Consultar saque

Devolve o saque pelo idEnvio, com o status atual.

GET /v2/ex/pix/{idEnvio}

Escopo: 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 é API quando o saque veio da sua integração, PAINEL quando alguém da sua equipe o enviou pelo painel, a um favorecido cadastrado, e BACKOFFICE quando a instituição o fez a seu pedido. No PAINEL, origemLogin traz o login de quem enviou.

Um envio pelo painel, ou da instituição, acima do valor máximo de cada Pix chega como vários saques de valores iguais, com 2 segundos entre eles. O primeiro leva o idEnvio do envio, e os outros o mesmo idEnvio com P002, P003 e assim por diante no fim. Cada um tem o seu endToEndId, a sua tarifa e os seus avisos de webhook. Os saques que a sua integração cria não se dividem em vários saques.

Quando o Pix expira por tempo no SPI (código AB03: o banco de quem recebe não respondeu a tempo, e o Pix não saiu), em algumas contas o saque não termina na hora. Ele é enviado de novo algumas vezes, com uma espera que dobra a cada tentativa, e segue EM_PROCESSAMENTO nesse meio. Cada tentativa tem outro endToEndId: vale o do aviso payout.realizado, e a consulta pelo endToEndId de uma tentativa de antes também devolve o saque. O aviso payout.nao_realizado com AB03 só chega depois da última tentativa. O mesmo acontece, em algumas contas, quando a instituição de pagamento recusa o envio por um motivo passageiro: o saque é enviado de novo da mesma forma, e o aviso payout.nao_realizado (com MS03) só chega depois da última tentativa. Quando ela responde que está indisponível, o saque espera: é enviado de novo uma vez, alguns minutos depois ou quando ela voltar, e o aviso payout.nao_realizado (com MS03) chega se for recusado de novo, ou se ela não voltar a tempo. E quando ela recusa por falta de saldo, na conta dela ou no banco por onde ela envia o Pix, o saque espera o saldo: é enviado de novo a cada minuto, e o aviso payout.nao_realizado com AM04 só chega se o saldo não voltar a tempo.

Quando há mais de uma conta para os seus saques, o saque que a instituição recusa é enviado pela próxima antes de voltar como não realizado, com o mesmo idEnvio e outro endToEndId, e segue EM_PROCESSAMENTO nesse meio. O aviso payout.nao_realizado só chega depois de todas, com o motivo da última.

Todas essas novas tentativas, inclusive a passagem para outra conta, acontecem só nos primeiros minutos depois de o saque chegar. Passado esse prazo, a recusa encerra o saque, e o aviso payout.nao_realizado chega na hora.

Em algumas contas a instituição divide o saque acima de um limite em vários Pix iguais, um depois do outro. Para a sua integração ele continua um saque só, com o idEnvio, o valor e os avisos de sempre, e o endToEndId do saque é o do primeiro Pix. Só nesse saque a resposta traz valorRealizado e pix:

Para saber quanto chegou ao favorecido, leia valorRealizado, e não só status e valor. Se o primeiro Pix não sai, o saque termina NAO_REALIZADO com o motivo dele, como um saque comum. A consulta por qualquer endToEndId de pix devolve o saque.

A tarifa é cobrada por Pix, sobre o valor de cada um: o saldo disponível precisa cobrir o valor do saque e uma tarifa por Pix, e o extrato traz uma linha de tarifa para cada Pix. Quando a instituição combinou com você uma tarifa só por saque, o saque paga a tarifa de um saque sobre o valor que saiu, repartida entre os Pix: na tarifa fixa o primeiro Pix paga e os outros não têm linha de tarifa no extrato.

Um saque que esperou aprovação traz aprovacao (regras, expiraEm e, decidido, desfecho, decididaEm, decididaPor e motivo), e o pedido com exigirAprovacao traz o eco exigirAprovacao igual a true. Enquanto espera, e se não for aprovado, ele não traz endToEndId. Quando a instituição aprova a seu pedido, ou cancela o saque, decididaPor vem instituicao, com o motivo. O saque criado com validadeSegundos traz enviarAte, o prazo para sair.

O favorecido pessoa jurídica vem com cnpj no lugar de cpf. Aceite os dois ao ler, mesmo que a sua integração só mande CPF: um saque enviado pelo painel pode ser para pessoa jurídica.

Um saque liquidado traz liquidadoEm e sla.cumprido:

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

Quando a instituição que envia o Pix informa quem o recebeu, o saque liquidado traz recebedor, com nome, documento, ispb, banco (o nome da instituição de quem recebeu), bancoNomeCompleto, bancoCodigo (o código de três dígitos do banco, como 260), bancoCnpj (o CNPJ da instituição, sem máscara), agencia, conta e tipoConta. O nome, o código e o CNPJ vêm das listas de participantes do Banco Central, e quando a instituição informa só o nome do banco, o ispb sai da lista pelo nome. Cada campo pode faltar, e o documento pode vir com parte dos dígitos escondida. Sem a informação o campo não vem: ele nunca é o favorecido do pedido.

O banco do favorecido pode devolver um saque já realizado, no todo ou em parte. O saque continua REALIZADO, com o valor dele, e passa a trazer valorDevolvido, a soma do que voltou. Cada volta chega pelo evento payout.devolucao_recebida e entra no extrato como uma linha DEVOLUCAO_DE_SAQUE.

A consulta traz também devolucoes, uma linha por volta, da mais velha para a mais nova:

A tarifa do saque não volta. A listagem não traz devolucoes: ela traz valorDevolvido.

O saque liquidado traz tarifa, a tarifa que ele pagou, a mesma da linha TARIFA do extrato. Ela é cobrada na liquidação: o saque em curso, o não realizado e o de tarifa zero não a trazem.

Um saque NAO_REALIZADO traz motivo com codigo, classe e 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 é CORRIGIVEL quando outra chave ou conta resolve, RETRYAVEL quando o mesmo pedido pode passar mais tarde e TERMINAL quando não se repete.

descricao é uma frase curta para quem atende o seu cliente, escrita por nós: o significado do código, ou a causa quando o código não basta. Decida pelo codigo e pela classe, nunca pela frase. Ela pode faltar num saque antigo.

MS03 é a recusa sem um motivo que possamos repassar: a instituição que envia o Pix recusou sem código, o prazo de enviarAte venceu, a aprovação expirou ou foi cancelada, o suporte desistiu de um saque que não saiu, o valor passa do máximo por Pix de saque da conta e o saque não saiu, ou a conta passou a enviar só para a chave que é o documento do favorecido e o saque, para outra chave, ainda não tinha sido enviado. Não se repete com o mesmo idEnvio; um novo idEnvio pode ser tentado. Quando a descricao diz o máximo por Pix, o novo saque vai em Pix de até esse máximo: acima dele responde 422 valor_acima_do_maximo. Quando a descricao diz que a conta só envia para a chave que é o CPF ou o CNPJ do favorecido, o novo saque vai para essa chave: outra responde 422 chave_exige_documento. MS02 é a recusa da sua empresa na aprovação.

Linha do tempo #

GET /v2/ex/pix/{idEnvio}?historico=true traz historico, a linha do tempo do saque, com o aviso de cada passo ao seu webhook. Outro valor que true ou false responde 400 filtro_invalido.

historico.passos vem na ordem do tempo. Cada passo tem passo e em e, conforme o passo, valor, rtrId, parte, motivo e tipo:

O passo que gerou um aviso ao seu webhook traz aviso:

Com historico.avisosApurados falso, os avisos não foram lidos agora, e os passos vêm sem aviso.

Reenviar o aviso de um passo #

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

Escopo: ex.webhook.write. Sem corpo.

Manda de novo ao seu webhook o aviso de um passo com reenviavel igual a true. Responde 202 com idReenvio e eventoId, e o pedido aparece na lista dos reenvios do webhook.

Pelo endToEndId #

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

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

Comprovante #

GET /v2/ex/comprovantes/{idEnvio} devolve o comprovante em PDF de um saque REALIZADO. Antes do desfecho, e no saque NAO_REALIZADO, responde 422 saque_nao_liquidado.

No saque dividido em vários Pix, o comprovante traz o valor que saiu e a lista dos Pix, com o valor, a situação e o endToEndId de cada Pix realizado. Quando saiu menos que o pedido, ele diz também o valor pedido e o que voltou ao saldo.

Erros #