Guia de Cash Out (PIX Out)
Este guia explica passo a passo como realizar transferências PIX (cash out) com consulta prévia de chave. O pagamento de boleto, que é o outro cash out da API, está em Boleto Pay. Para pagar dezenas ou milhares de PIX a partir de um arquivo, com conferência e aceite antes do débito, veja PIX em lote.
Visão Geral
O Cash Out permite enviar dinheiro via PIX para qualquer chave cadastrada no sistema PIX brasileiro. O fluxo recomendado é:
- Consultar a chave - Validar e obter os dados do destinatário
- Confirmar os dados - Exibir para o usuário para confirmação
- Executar a transferência - Enviar o PIX
Fluxo de Integração
Tipos de Chave PIX
Passo 1: Consultar a Chave PIX (Opcional mas Recomendado)
Antes de transferir, consulte a chave para validar o destinatário e exibir os dados para confirmação do usuário:
A API consulta a chave automaticamente durante a transferência — a consulta prévia é opcional, mas melhora a experiência do usuário. O resultado fica em cache por 24 h (use ?noCache=true para forçar uma consulta nova ao DICT) e consome cota de consultas conforme as políticas do tenant. O consumo de DICT é medido em tempo real e acompanhado pela CorpX: antes de integrar, leia Consultas de chave PIX.
O que a transferência devolve
A resposta da transferência não repete os dados do destinatário: ela traz o desfecho da operação (status, paymentId, endToEndId). Nome e documento de quem recebeu aparecem no extrato e no lookup do pagamento.
Passo 2: Executar a Transferência
Execute a transferência PIX via chave:
Request
Parâmetros do Body
A conta de origem vem do path ({accountId}) e a moeda é sempre BRL — nenhum dos dois é enviado no body.
Resposta de Sucesso
O status HTTP reflete o desfecho: 200 (COMPLETED), 422 (FAILED),
202 (TIMEOUT/PENDING — indeterminado; confira o extrato antes de
reenviar).
Rejeições imediatas do liquidante (antifraude ou saldo insuficiente na
liquidação) retornam 422 FAILED na hora, com errorCode
(partner_rejected / insufficient_funds) e errorReason preenchidos.
Transferências retidas no banco liquidante aparecem como
PENDING_APPROVAL nas consultas e aguardam o desfecho por até ~25 minutos
antes de marcar TIMEOUT; o resultado chega pelos webhooks
pix.out.completed / pix.out.failed / pix.out.timeout.
Nesse estado a consulta e o pix.out.timeout trazem hold
(owner: "partner" + reason) e o estado bruto em
partnerStatus/partnerStatusId. PENDING_APPROVAL nunca significa
aprovação pendente do seu lado ou do nosso: a decisão é do liquidante.
E TIMEOUT não é o fim — seguimos consultando por até 7 dias e, se ele
liquidar ou recusar, você recebe pix.out.completed / pix.out.failed
com late: true e o mesmo paymentId.
Resposta de Erro
Timeout no fluxo síncrono
Se o liquidante não confirmar dentro da janela, a API responde 202 com
status: "TIMEOUT" e um campo warning — não existe 207. O PIX pode ter
sido enviado: consulte o extrato ou o lookup do pagamento antes de reenviar.
O desfecho tardio chega por webhook (pix.out.completed / pix.out.failed).
Fluxo assíncrono (recomendado para alto volume)
Use POST /v1/accounts/{accountId}/pix/out/async para agendar o pagamento e receber 202 imediato:
Resposta:
A resposta 202 inclui o header Location apontando para
/v1/accounts/{accountId}/payments/{identifier} — um alias mantido por
compatibilidade, que responde com headers Deprecation. A rota canônica de
consulta é GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=.
O resultado final (sucesso/falha) é entregue por webhook e também pode ser
consultado por identifier/paymentId. Para não consultar essa rota em
laço, passe waitForFinalStatus — a chamada segura a conexão até o
desfecho. Ver Esperar o desfecho em vez de fazer polling.
Passo 3: Consultar Status da Transferência
Após executar uma transferência, você pode consultar seu status usando o ID E2E:
Request
Parâmetros de Query
*Pelo menos um dos dois (endToEndId ou identifier) é obrigatório. O accountId vai no path, não na query.
Resposta de Sucesso (200 OK)
Esta rota responde no mesmo envelope do extrato (items[]), com 0 ou 1
item. Os horários (timestamp) saem em horário de Brasília (-03:00).
Transação inexistente não é 404: vem 200 com items: [].
Para receber um único objeto (em vez do envelope items[]), use
GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=... (ou
?endToEnd=...).
Esperar o desfecho em vez de fazer polling
O parâmetro waitForFinalStatus substitui o laço de consultas que o
integrador faria no lookup de pagamento
(GET /v1/accounts/{accountId}/pix/payments/lookup). Só essa rota aceita o
parâmetro; a /pix/transactions do exemplo acima o ignora. Em vez de chamar
o lookup a cada poucos segundos, chame uma vez com waitForFinalStatus
(segundos, no máximo 10). A API segura a conexão e consulta o liquidante até
o pagamento chegar a COMPLETED, FAILED ou REVERSED, ou até o prazo
acabar. A primeira consulta sai 1 s depois da chamada, dentro do prazo: logo
depois do POST o liquidante costuma ainda não ter o pagamento.
O shape da resposta não muda. Acima de 10 vale 10, e o header
X-Wait-Seconds devolve o prazo aplicado (não o tempo que a chamada levou).
Sem o parâmetro, ou com 0, a rota responde na hora, como antes.
Quando o prazo acaba antes do desfecho:
- Se o pagamento foi lido ao menos uma vez, a resposta é
200com o último estado (PROCESSING,PENDING_APPROVAL…). Não é erro: chame de novo ou aguarde o webhook. - Se o pagamento nunca foi lido, a resposta é a da última consulta:
404 not_foundquando o liquidante não o encontrou, ou o erro do liquidante quando ela falhou. Logo depois de umPOST .../pix/out/async, o404quer dizer que o liquidante ainda não registrou o pagamento — ou que oidentifierestá errado.
Se o liquidante não encontra o pagamento, mas ele já tem desfecho na CorpX
(concluído, recusado antes de chegar ao liquidante ou devolvido), a resposta
é 200 com esse status, com ou sem waitForFinalStatus. Com o pagamento em
andamento, o 404 continua querendo dizer que o liquidante ainda não o
registrou.
Na recusa (FAILED), o lookup traz errorCode com o mesmo código do webhook
pix.out.failed (insufficient_funds, limit_exceeded_transaction,
limit_exceeded_daily, partner_rejected…) e o motivo em errorMessage.
Decida pelo código, não pelo texto: é ele que separa falta de saldo de limite
estourado na mensagem que você mostra ao seu cliente.
Uma recusa definitiva do liquidante (4xx, fora 408 e 429) volta na hora,
sem esperar o prazo. Só falha transitória (5xx, 408, 429, timeout) é
repetida.
A resposta pode chegar alguns segundos depois do prazo: uma consulta ao
liquidante que já tinha começado quando o prazo acabou termina antes da
resposta (até 5 s). Configure o timeout do seu cliente HTTP em pelo menos
waitForFinalStatus + 10 s — 20 s para waitForFinalStatus=10.
O webhook continua sendo o caminho autoritativo. O waitForFinalStatus é
para quem precisa do desfecho na mesma chamada.
Status Possíveis
Fluxo de estados
- O resultado final chega pelos webhooks
pix.out.completed/pix.out.failed. Em caso deTIMEOUT, a API também emitepix.out.timeout(estado indeterminado — confira o extrato; umcompleted/failedtardio ainda pode chegar depois, comlate: truee o mesmopaymentId). - Reenvio com a mesma
Idempotency-Keydevolve o desfecho registrado e não executa o pagamento de novo: emFAILED, a mesma recusa; emTIMEOUT, o estado indeterminado. Para tentar de novo depois de umFAILED, useIdempotency-Keynova eidentifiernovo. Depois de umTIMEOUT, confira o extrato antes: com chave nova você pode duplicar o envio. Detalhes em Idempotência.
Sempre salve o identifier das transferências e consulte o status por ele — é o ID que você define, estável e disponível desde a criação (o endToEndId só existe após a liquidação).
Exemplo Completo: Script de Cash Out
Consultar QR Code (Decode)
Antes de pagar, você pode decodificar o QR Code para exibir os dados do beneficiário ao usuário:
Resposta (QR dinâmico imediato):
Para QR de cobrança com vencimento (dynamic-due-date), o response
inclui também os componentes do valor (discount, deduction,
interest, penalty), originalAmount (valor de face antes dos
ajustes), dueDate, paymentDeadline e payeeTradeName (nome
fantasia da PJ). Veja o exemplo correspondente no OpenAPI.
Você pode reutilizar decodeId no body do POST /pix/out/qr-code/async
para pular um segundo decode na hora do pagamento.
Após confirmar, use o endpoint de pagamento abaixo para executar.
Pagar QR Code (PIX Out via EMV)
Se você possui um código EMV (QR Code copia e cola), use o endpoint assíncrono (canônico):
Fluxo assíncrono (recomendado)
POST /v1/accounts/{accountId}/pix/out/qr-code/async — resposta 202 imediata:
Resposta:
A resposta 202 inclui o header Location apontando para o lookup do
pagamento. O resultado final (sucesso/falha/timeout) chega por webhook
(pix.out.completed, pix.out.failed, pix.out.timeout) e também pode
ser consultado por identifier/paymentId.
Endpoint síncrono (deprecated)
POST /v1/accounts/{accountId}/pix/out/qr-code (sync) está deprecated.
Continue funcionando por compatibilidade e devolve headers Deprecation,
Sunset e Link (sunset previsto: 2026-11-21). Migre para
/pix/out/qr-code/async.
Webhook de Transferência
Após a transferência, você receberá um webhook no envelope canônico
(id, type, occurredAt, schemaVersion, data):
O evento equivalente de falha é pix.out.failed (com error no data) e o
de estado indeterminado é pix.out.timeout. A referência completa dos campos
está em Webhooks.
BigPix (descontinuado)
O limite de R$ 15.000 por transação foi removido — POST /v1/accounts/{accountId}/pix/out
agora aceita qualquer valor em uma única transação. O BigPix (que dividia valores
grandes em múltiplos PIX) não é mais necessário e está descontinuado.
Os endpoints /pix/out/bigpix e /pix/out/bank-account/bigpix continuam funcionais
por retrocompatibilidade, mas retornam o header Deprecation: true. Migre para
POST /pix/out (ou /pix/out/bank-account). A data de remoção definitiva será
anunciada no changelog com antecedência.
Erros Comuns
A lista completa com mensagens e semântica está em Erros.
Reenviar a mesma Idempotency-Key em PIX out não devolve 409: a API
retorna o resultado já registrado, inclusive quando ele é uma recusa
(FAILED).
Boas Práticas
- Sempre consulte a chave antes de transferir para validar o destinatário
- Confirme com o usuário os dados antes de executar
- Use uma Idempotency Key única por transferência — e reutilize a mesma chave ao repetir a requisição, nunca uma nova
- Salve o E2E para rastreamento e suporte
- Configure webhooks para receber confirmações assíncronas
- Implemente retry com exponential backoff para falhas temporárias
Limites
O valor é limitado pelo teto da conta. A leitura, as janelas e o pedido
de aumento estão no guia de limites.
GET .../pix/limits está deprecated.
Próximos Passos
- Guia de Devolução - Estornar transferências recebidas
- Webhooks - Configurar notificações
- Erros - Lista completa de códigos de erro