Criar uma cobrança.

Cria uma cobrança usando um meio de pagamento tokenizado, PIX ou boleto. Para cobranças no cartão, use capture_method=automatic para pagar na hora ou capture_method=manual para autorizar agora e capturar depois. Para PIX e boleto os artefatos de pagamento voltam de forma SÍNCRONA nesta resposta: uma cobrança PIX traz um objeto `pix` no topo com a imagem do QR Code (`qr_code`) e o copia-e-cola (`qr_code_text`); uma cobrança de boleto traz um objeto `boleto` no topo com o código de barras, a linha digitável e a URL do PDF. Os mesmos artefatos também chegam no webhook `charge.created` e no GET /charges/{id}, então dá para reconciliar por qualquer um dos três canais.

Cria uma cobrança usando um meio de pagamento tokenizado, PIX ou boleto. Para cobranças no cartão, use capture_method=automatic para pagar na hora ou capture_method=manual para autorizar agora e capturar depois. Para PIX e boleto os artefatos de pagamento voltam de forma SÍNCRONA nesta resposta: uma cobrança PIX traz um objeto pix no topo com a imagem do QR Code (qr_code) e o copia-e-cola (qr_code_text); uma cobrança de boleto traz um objeto boleto no topo com o código de barras, a linha digitável e a URL do PDF. Os mesmos artefatos também chegam no webhook charge.created e no GET /charges/{id}, então dá para reconciliar por qualquer um dos três canais.

Autorização

ApiKeyAuth

AutorizaçãoBearer <token>

Em: header

Parâmetros de cabeçalho

Idempotency-Key?string

Tamanho1 <= length <= 255

Corpo da requisição

application/json

Definições TypeScript

Use o tipo request body em TypeScript.

amount*integer

Amount in the minor unit of currency (USD 5.00 -> 500). CLP has no minor unit, so 500 CLP -> 500.

Intervalo1 <= value

currency?string

Currency of amount. Defaults to BRL. A currency other than BRL must be enabled for your account (currency_not_supported otherwise), accepts CARD ONLY and requires installments: 1.

Padrão"BRL"

Value in

"BRL"
"USD"
"EUR"
"GBP"
"CHF"
"CAD"
"MXN"
"ARS"
"CLP"
"COP"
"PEN"

payment_method*string

Value in

"CREDIT_CARD"
"DEBIT_CARD"
"PIX"
"BOLETO"

capture_method?string

Padrão"automatic"

Value in

"automatic"
"manual"

installments?integer

Required for CREDIT_CARD and DEBIT_CARD. Send 1 for one-time card payments. Each installment must be at least R$ 5,00, so a count the amount cannot support is refused with validation_error (a R$ 1,00 charge only accepts 1). Simulate with GET /v1/installments to get the counts this amount allows.

Intervalo1 <= value <= 24

card_token?string

Match^tok_[A-Za-z0-9_\-]+$

buyer*

Buyer identity. document and phone are required when currency is BRL and optional otherwise. For every optional field here, a blank value counts as not provided: null, an empty string and an absent key are equivalent (document, phone, ip, address.street_number, address.district, address.line_2).

pix?

boleto?

split?array<>

Optional split of the charge to other sellers of the same whitelabel. Recipients are carved out of the charge amount; the remainder stays with the charge's own seller through the normal fee/receivable flow. All items must use the same allocation mode (amount_cents or percentage_bps).

Items1 <= items <= 10

split_rule_id?string

Optional reference to a reusable SplitRule template by public id. The template's recipients are materialized into the same split[] shape at charge-creation time and frozen on the charge, so later edits to the template never affect this charge. Mutually exclusive with inline split.

Match^spr_[A-Za-z0-9]+$

risk_session_id?string

Required for every new checkout integration: the RISK-020 browser session must belong to the same whitelabel, seller and environment and must not be expired. The server temporarily accepts omission only for legacy compatibility; it is observational and does not change authorization.

Match^rks_[A-Za-z0-9_-]+$

metadata?

schedule?

Scheduled card charge (SCHED-CARD). When present, the charge is created with status scheduled and is executed against the acquirer on execute_at by a background job — it is NOT authorized on this request. Exception (SCHED-NOW): an execute_at within 60 seconds of now — before or after — is a request to charge NOW, so the charge is executed on this very request and the response already carries the final status (paid/refused), not scheduled. Card and BRL only, automatic capture. 3-D Secure does NOT run for a scheduled charge (merchant-initiated, no cardholder present). Because it bypasses 3-D Secure, creating a scheduled charge REQUIRES the charges:schedule capability on the API key — a sensitive capability granted only by an admin or compliance role. A key without it receives a 403 permission_error (insufficient_permissions).

reservation?

Hospitality reservation behind this sale (HOSP-100). Additive and optional: a charge without it behaves exactly as before. Requires the seller to be enabled for hospitality — otherwise the request is rejected with reservation_not_supported (422). check_in and check_out are BOTH required: the white label can switch the release anchor between check-in and check-out at any time, and a reservation captured without a check-out would silently break that rule. channel must be a channel code from the white label's reservation-channel catalog (unknown_reservation_channel, 422, returns the valid codes in details.valid_channels). A check-in too far in the future is rejected with reservation_horizon_exceeded (422). status, rate_type and guarantee_nights are INFORMATIONAL: the platform never derives a refund from them — a cancellation is always issued through the normal refund endpoint.

Corpo da resposta

`application/json`

curl -X POST "https://example.com/charges" \  -H "Idempotency-Key: order_123_attempt_1" \  -H "Content-Type: application/json" \  -d '{    "amount": 10990,    "currency": "BRL",    "payment_method": "CREDIT_CARD",    "capture_method": "automatic",    "card_token": "tok_xxx",    "installments": 1,    "buyer": {      "name": "Ada Lovelace",      "email": "ada@example.com",      "phone": "+55 11 99999-0000",      "document": "935.411.347-80",      "ip": "203.0.113.10",      "address": {        "line_1": "Av. Paulista, 1000",        "zip_code": "01310-100",        "city": "Sao Paulo",        "state": "SP",        "country": "BR"      }    },    "metadata": {      "order_id": "order_123"    }  }'

{  "id": "ch_3n8Xa2b1c0",  "object": "charge",  "status": "pending",  "amount_cents": 10990,  "currency": "BRL",  "payment_method": "pix",  "capture_method": "automatic",  "captured": false,  "installments": null,  "buyer": {    "name": "Ada Lovelace",    "email": "ada@example.com",    "phone": "+55 11 99999-0000",    "document": "935.411.347-80",    "document_type": "cpf",    "ip": null,    "address": {      "line_1": "Av. Paulista, 1000",      "line_2": null,      "zip_code": "01310-100",      "city": "Sao Paulo",      "state": "SP",      "country": "BR"    }  },  "pix": {    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",    "qr_code_text": "00020126580014br.gov.bcb.pix0136...5204000053039865802BR6009SAO PAULO62070503***6304AB12",    "expires_at": "2026-08-25T18:00:00.000Z"  },  "metadata": {    "order_id": "order_123"  },  "paid_at": null,  "created_at": "2026-08-25T17:00:00.000Z",  "updated_at": "2026-08-25T17:00:00.000Z",  "request_id": "req_9f8e7d6c"}

Criar uma cobrança.

Autorização

Parâmetros de cabeçalho

Corpo da requisição

Corpo da resposta

201application/json

401application/json

403application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`