PUT /cob/{txid} (or POST /cob) with the amount and validity. The response carries the pixCopiaECola: show it (or its QR code) to the payer.
When the payer pays, the money lands in the balance right away and the charge becomes CONCLUIDA. With webhooks on, the receive notice arrives; without webhooks, call GET /cob/{txid} until the status is CONCLUIDA (the pix list carries the endToEndId).
Release the order only when the charge is CONCLUIDA. ATIVA means waiting for payment; REMOVIDA_PELO_PSP is an expired charge.
A Pix paid straight into an account key (GET /accounts/keys) has no charge: it shows up as CREDIT in GET /accounts/transactions and in the receive notice.
To check the money, use GET /accounts/balances (available) and GET /accounts/transactions (statement).
Sandbox (test environment)
Test the whole integration without moving real money. In the panel, under API, tap New key and choose Sandbox: the key is born with the sk_sbx_ prefix and a fake account holding R$ 10,000.00. Everything else matches production: the same base URL, the same token (POST /oauth/token with the sandbox key's Client ID and Client Secret), the same routes, the same fields and the same errors. Only the money is fake.
Sent Pix (POST /pix/payments/dict and /qrc): answers 202 already with the endToEndId and completes by itself in about 4 seconds (LIQUIDATED), with the transfer notice. The test fee is R$ 1.00.
Key falha@sandbox.test (EMAIL): the Pix is accepted and fails after about 4 seconds; the amount returns and the cashout notice arrives (CANCELED).
Key recusa@sandbox.test (EMAIL): refused immediately (400), nothing is debited.
Pix charge (PUT /cob/{txid}): stays ATIVA until you pay it with the sandbox command below; then it becomes CONCLUIDA, the balance goes up and the receive notice arrives. The pixCopiaECola of a sandbox charge can also be paid through POST /pix/payments/qrc.
Transfer between accounts (POST /internal-transfers): use document 111.444.777-35 (any name) as the test destination account.
Key lookup (GET /pix/keys/{key}) returns test data; naoexiste@sandbox.test answers 404.
Webhooks (POST /webhooks/{type}): apply only to the sandbox key and receive only test notices; they do not need to be enabled for the account.
Commands that play the part of the outside world (sandbox keys only; with a production key they answer 403):
Command
What it does
POST /sandbox/cob/{txid}/pay
Pays the charge: balance goes up, status CONCLUIDA, receive notice.
POST /sandbox/pix/receive
Simulates a Pix paid straight to your key. Body: { "amount": 25.50, "payer": "Someone" }.
POST /sandbox/pix/payments/{endToEndId}/complete
Speeds up the completion of a sent Pix (transfer notice).
POST /sandbox/pix/payments/{endToEndId}/fail
Forces a sent Pix to fail: the amount returns (cashout notice).
POST /sandbox/balance/topup
Adds fake balance. Body: { "amount": 500 }.
GET /sandbox/info
Lists these test keys and commands.
The sandbox is isolated: it does not use the real balance, does not go through the provider, and the endToEndIds it generates start with E99999999 (a bank that does not exist), so they are never mistaken for a real Pix. Test data is erased after 30 days. When everything works, create a production key and swap the Client ID and Client Secret: the code does not change.
API reference
Authentication
Get an access token
POST/oauth/token
Exchanges clientId and clientSecret for an access token (OAuth 2.0 client credentials). The token is valid for 1 hour; send it as Authorization: Bearer on every other route. Accepts JSON, a form body (client_id, client_secret, grant_type) or Authorization: Basic base64(clientId:clientSecret).
Request body
Field
Type
Description
clientIdrequired
string
The first 14 characters of your API key (e.g. sk_live_AbCdEf) or the key id.
clientSecretrequired
string
The full API key (sk_live_…).
grantTyperequired
string
Always client_credentials.
scope
string
Ignored: the token carries all of the key's permissions.
expiresAt is the expiry instant in Unix seconds.
The token stops working the moment its key is revoked.
Pix charges
Create an immediate charge with a txid
PUT/cob/{txid}
Creates a Pix charge (dynamic QR) with the txid you choose: 26 to 35 letters and digits. Repeating the PUT with the same txid returns the same charge. Each bank sets a minimum amount per charge (below it: 400 below_limit, with the minimum in the message).
Permission:cob.write → pix:write
Path parameters
Field
Type
Description
txidrequired
string
26 to 35 letters and digits.
Request body
Field
Type
Description
valor.originalrequired
string
Amount in BRL as a dot-decimal string ("49.90").
calendario.expiracao
integer
Validity in seconds, 60 to 2592000. Default 86400.
devedor.nome, devedor.cpf, devedor.cnpj
string
Who will pay (optional).
solicitacaoPagador
string
Text shown to the payer, up to 140 characters.
Create an immediate charge (generated txid)
POST/cob
Same as the PUT, but the bank generates the txid and returns it in the response.
Permission:cob.write → pix:write
Request body
Field
Type
Description
valor.originalrequired
string
Amount in BRL as a dot-decimal string ("49.90").
calendario.expiracao
integer
Validity in seconds, 60 to 2592000. Default 86400.
devedor, solicitacaoPagador
object | string
As in the PUT.
Get an immediate charge
GET/cob/{txid}
The charge state. When paid, status is CONCLUIDA and the pix list carries the endToEndId. When money arrives, always confirm with this call; do not rely on an external notice alone.
