Idempotency and pagination
Idempotency #
There is no idempotency header: the key is the id in the path. txid, idEnvio and the sub-account id are yours, with 26 to 35 alphanumeric characters; the refund id is yours too, with 1 to 35. Generate a ULID before calling and store it.
| Situation | Response |
|---|---|
| New id | 201 and the created resource. |
| Same id, same body | 200, the same resource and the header x-replayed: true. |
| Same id, different body | 409 (txid_duplicado, id_envio_duplicado, id_duplicado) when a field that identifies the request changes: on a charge, amount, debtor, ex.subconta and ex.splitConfig; on a payout, amount, tipo, payee document, subconta, exigirAprovacao and the presence of validadeSegundos; on a refund and on a sub-account, any field. Any other different field returns 200 with the resource already stored, unchanged. |
After a timeout or a 5xx, look up the resource by its id. If it exists, follow it. If it responds 404, repeat the call with the same id. Never generate a new id without knowing the outcome of the previous one: a payout repeated with another idEnvio pays twice.
Pagination #
The paginated listings (charges, refunds, payouts, transactions, the statement of the day and the webhook deliveries) use an opaque cursor.
{
"cobrancas": [],
"cursor": { "proximo": "MTc4OTcyMzIyMzc2NzE1NH5DT0Iw...", "temMais": true }
}
| Field | Description |
|---|---|
cursor.temMais |
true while there is another page. Rely on it, not on the size of the list. |
cursor.proximo |
Pass it in ?cursor= for the next page. Empty at the end. In the event feed, pass it in ?apos=: there it is never empty, and the one from the last page is the position to store to continue later. With ordem=recentes, the feed comes from the most recent to the oldest, and the cursor goes in ?antes=. |
limite |
Items per page, from 1 to 200. Default 50. Otherwise, 400 limite_invalido. |
The listings come from the most recent to the oldest; the event feed, from the oldest to the most recent.
Sub-accounts and split partners come whole in a single response, without a cursor. Disputes too, unless you pass limite or cursor: then they come by page.
The routes of the Central Bank of Brazil standard (GET /v2/cob, GET /v2/pix) use inicio, fim and paginacao.paginaAtual, as in the standard.
Correlation #
Send x-correlation-id with 8 to 64 ASCII characters without spaces. Every response returns it, including the response to the token request, an error repeats it in correlationId and the stored event carries the same value. Without it, we generate one.