Get payout

Returns the payout by its idEnvio, with the current status.

GET /v2/ex/pix/{idEnvio}

Scope: ex.pix.send.read.

GET /v2/ex/pix/SAQ01J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000003",
  "status": "EM_PROCESSAMENTO",
  "tipo": "SAQUE",
  "valor": "300.00",
  "solicitadoEm": "2026-09-18T12:00:00Z",
  "prazoRegulatorio": "2026-09-18T14:00:00Z",
  "favorecido": { "chave": "12345678909", "cpf": "12345678909" },
  "referenciaExterna": "saque-778812",
  "infoPagador": "Saque pedido 778812",
  "origem": "API",
  "sla": { "estouradoNaEntrada": false, "restanteSegundos": 7199 }
}

origem is API when the payout came from your integration, PAINEL when someone on your team sent it through the dashboard, to a registered payee, and BACKOFFICE when the institution made it at your request. With PAINEL, origemLogin carries the login of the person who sent it.

A sending through the dashboard, or by the institution, above the maximum amount of each Pix arrives as several payouts of equal amounts, 2 seconds apart. The first carries the idEnvio of the sending, and the others the same idEnvio with P002, P003 and so on at the end. Each one has its own endToEndId, its own fee and its own webhook notices. The payouts your integration creates are not split into several payouts.

When the Pix times out in the SPI (code AB03: the receiving bank did not answer in time, and the Pix did not go out), on some accounts the payout does not end right away. It is sent again a few times, with a wait that doubles at each attempt, and stays EM_PROCESSAMENTO in between. Each attempt has a different endToEndId: the one in the payout.realizado notice is the one that counts, and a query by the endToEndId of an earlier attempt also returns the payout. The payout.nao_realizado notice with AB03 only arrives after the last attempt. The same happens, on some accounts, when the payment institution refuses the sending for a temporary reason: the payout is sent again the same way, and the payout.nao_realizado notice (with MS03) only arrives after the last attempt. When it answers that it is unavailable, the payout waits: it is sent again once, a few minutes later or when it comes back, and the payout.nao_realizado notice (with MS03) arrives if it is refused again, or if it does not come back in time. And when it refuses for lack of balance, in its own account or at the bank it sends the Pix through, the payout waits for the balance: it is sent again every minute, and the payout.nao_realizado notice with AM04 only arrives if the balance does not come back in time.

When there is more than one account for your payouts, a payout that the institution refuses is sent through the next one before it comes back as not completed, with the same idEnvio and a different endToEndId, and it stays EM_PROCESSAMENTO in between. The payout.nao_realizado notice only arrives after all of them, with the reason of the last one.

All these new attempts, including the move to another account, only happen in the first few minutes after the payout arrives. After that deadline, a refusal ends the payout, and the payout.nao_realizado notice arrives right away.

In some accounts the institution splits a payout above a limit into several equal Pix, one after the other. For your integration it remains a single payout, with the usual idEnvio, valor and notices, and the endToEndId of the payout is the one of the first Pix. Only in that payout the response carries valorRealizado and pix:

To know how much reached the payee, read valorRealizado, and not only status and valor. If the first Pix does not go out, the payout ends NAO_REALIZADO with its motivo, like an ordinary payout. Looking up any endToEndId from pix returns the payout.

The fee is charged per Pix, on the amount of each one: the available balance must cover the payout amount plus one fee per Pix, and the statement shows one fee line for each Pix. When the institution agreed with you on a single fee per payout, the payout pays the fee of one payout on the amount that went out, shared among the Pix: with a fixed fee the first Pix pays it and the others have no fee line in the statement.

A payout that waited for approval carries aprovacao (regras, expiraEm and, once decided, desfecho, decididaEm, decididaPor and motivo), and a request with exigirAprovacao carries the echoed exigirAprovacao equal to true. While it waits, and if it is not approved, it does not carry endToEndId. When the institution approves it at your request, or cancels the payout, decididaPor comes as instituicao, with the motivo. A payout created with validadeSegundos carries enviarAte, the deadline for it to go out.

A payee that is a legal entity comes with cnpj instead of cpf. Accept both when reading, even if your integration only sends CPF: a payout sent through the dashboard may be to a legal entity.

A settled payout carries liquidadoEm and sla.cumprido:

{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "status": "REALIZADO",
  "liquidadoEm": "2026-09-18T12:00:09Z",
  "sla": { "cumprido": true, "estouradoNaEntrada": false }
}

When the institution that sends the Pix reports who received it, the settled payout carries recebedor, with nome, documento, ispb, banco (the name of the institution where it was received), bancoNomeCompleto, bancoCodigo (the three digit bank code, such as 260), bancoCnpj (the CNPJ of the institution, without mask), agencia, conta and tipoConta. The name, the code and the CNPJ come from the participant lists of the Central Bank of Brazil, and when the institution reports only the bank name, the ispb is taken from the list by the name. Any field may be missing, and the document may come with part of the digits hidden. Without that information the field does not come: it is never the payee of the request.

The bank of the payee may return a payout already completed, in full or in part. The payout remains REALIZADO, with its amount, and starts carrying valorDevolvido, the sum of what came back. Each return arrives through the event payout.devolucao_recebida and enters the statement as a DEVOLUCAO_DE_SAQUE line.

The query also carries devolucoes, one line per return, from the oldest to the newest:

The payout fee does not come back. The list does not carry devolucoes: it carries valorDevolvido.

A completed payout carries tarifa, the fee it paid, the same as the TARIFA line of the statement. The fee is charged at settlement: a payout in progress, a payout not completed and a payout with a zero fee do not carry it.

A NAO_REALIZADO payout carries motivo with codigo, classe and descricao:

GET /v2/ex/pix/SAQ02J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "idEnvio": "SAQ02J1ZK7M9QW3ERT5TY6UI8O",
  "status": "NAO_REALIZADO",
  "tipo": "SAQUE",
  "valor": "20.00",
  "liquidadoEm": "2026-09-18T11:00:09Z",
  "motivo": {
    "codigo": "AC03",
    "classe": "CORRIGIVEL",
    "descricao": "Agência/conta do usuário recebedor inexistente ou inválida."
  }
}

classe is CORRIGIVEL when another key or account solves it, RETRYAVEL when the same request may go through later and TERMINAL when it is not to be repeated.

descricao is a short sentence for whoever serves your customer, written by us: the meaning of the code, or the cause when the code is not enough. Decide by the codigo and the classe, never by the sentence. It may be missing on an old payout.

MS03 is a rejection without a reason we can pass on: the institution that sends the Pix rejected it without a code, the enviarAte deadline expired, the approval expired or was cancelled, support gave up on a payout that did not go out, the amount is above the maximum per payout Pix of the account and the payout did not go out, or the account started sending only to the key that is the document of the payee and the payout, to another key, had not been sent yet. It is not repeated with the same idEnvio; a new idEnvio may be tried. When the descricao states the maximum per Pix, the new payout goes in Pix of up to that maximum: above it the response is 422 valor_acima_do_maximo. When the descricao says the account only sends to the key that is the CPF or CNPJ of the payee, the new payout goes to that key: another key responds 422 chave_exige_documento. MS02 is the rejection by your company in the approval.

Timeline #

GET /v2/ex/pix/{idEnvio}?historico=true carries historico, the timeline of the payout, with the notice of each step to your webhook. Any value other than true or false answers 400 filtro_invalido.

historico.passos comes in time order. Each step has passo and em and, depending on the step, valor, rtrId, parte, motivo and tipo:

The step that generated a notice to your webhook carries aviso:

With historico.avisosApurados false, the notices were not read now, and the steps come without aviso.

Resend the notice of a step #

POST /v2/ex/pix/{idEnvio}/avisos/{eventoId}/reenvio

Scope: ex.webhook.write. No body.

Sends again to your webhook the notice of a step with reenviavel equal to true. Answers 202 with idReenvio and eventoId, and the request appears in the list of webhook resends.

By endToEndId #

GET /v2/ex/pix/e2e/{e2eId}

GET /v2/ex/pix/e2e/E12345678202609181200000000000003
→ 200
{
  "idEnvio": "SAQ01J1ZK7M9QW3ERT5TY6UI8O",
  "endToEndId": "E12345678202609181200000000000003",
  "status": "EM_PROCESSAMENTO"
}

Receipt #

GET /v2/ex/comprovantes/{idEnvio} returns the PDF receipt of a REALIZADO payout. Before the outcome, and for a NAO_REALIZADO payout, it responds 422 saque_nao_liquidado.

For a payout split into several Pix, the receipt shows the amount that went out and the list of the Pix, with the amount, the status and the endToEndId of each completed Pix. When less than requested went out, it also states the requested amount and what returned to the balance.

Errors #