Skip to navigation

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 é:

  1. Consultar a chave - Validar e obter os dados do destinatário
  2. Confirmar os dados - Exibir para o usuário para confirmação
  3. Executar a transferência - Enviar o PIX

Fluxo de Integração

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Consultar │ │ Confirmar │ │ Executar │
│ Chave │ ───► │ Dados │ ───► │ Transferência│
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
Nome, Banco, Usuário E2E gerado,
Conta, CPF/CNPJ Confirma Webhook enviado

Tipos de Chave PIX

TipoFormatoExemplo
CPF11 dígitos12345678901
CNPJ14 dígitos12345678000199
EMAILE-mail válidojoao@email.com
PHONE+55 + DDD + número+5511999998888
EVPUUID123e4567-e89b-12d3-a456-426614174000

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:

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/12345678901" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

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

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-order-12345" \
-d '{
"amount": 100.00,
"keyType": "CPF",
"key": "12345678901",
"description": "Service payment",
"identifier": "order-12345"
}'

Parâmetros do Body

A conta de origem vem do path ({accountId}) e a moeda é sempre BRL — nenhum dos dois é enviado no body.

CampoTipoObrigatórioDescrição
amountnumberSimValor em BRL (ex.: 100.00)
keyTypestringSimTipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP
keystringSimChave PIX do destinatário
descriptionstringNãoDescrição da transferência (máximo 140 caracteres)
identifierstringNãoIdentificador fornecido pelo integrador para rastreamento e conciliação. Aparece no extrato quando o pagamento é conciliado.

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.

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"transactionId": "txn-abc123-def456",
"endToEndId": "E12345678202301011234abcdefghijkl",
"status": "COMPLETED",
"completedAt": "2026-01-28T15:00:02Z",
"identifier": "order-12345",
"workflowId": "pix-out-{accountId}-{identifier}"
}
CampoDescrição
paymentIdID interno da intenção de pagamento (rastreio/conciliação)
transactionIdID da transação
endToEndIdID E2E BACEN (presente após liquidar)
statusCOMPLETED, FAILED, TIMEOUT, PENDING, PROCESSING
errorCode / errorReasonpreenchidos quando FAILED

Resposta de Erro

{
"errorCode": "insufficient_funds",
"message": "Saldo insuficiente na conta do liquidante para concluir a operação."
}

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:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/async" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-order-async-12345" \
-d '{
"amount": 100.00,
"keyType": "CPF",
"key": "12345678901",
"description": "Service payment",
"identifier": "order-12345-async"
}'

Resposta:

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"workflowId": "pix-out-{accountId}-{identifier}",
"runId": "b7c1f0e2-...",
"idempotencyKey": "transfer-order-async-12345",
"identifier": "order-12345-async",
"status": "ACCEPTED"
}

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

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/transactions?endToEndId=E12345678202301011234abcdefghijkl" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

Parâmetros de Query

ParâmetroTipoObrigatórioDescrição
endToEndIdstringSim*ID E2E da transação
identifierstringSim*Identificador da cobrança ou referência

*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: [].

{
"accountId": "{accountId}",
"source": "live",
"page": 0,
"size": 1,
"totalElements": 1,
"totalPages": 1,
"hasNext": false,
"items": [
{
"partnerId": "a697b489-681a-451c-a043-d4ae65be8c80",
"endToEndId": "E12345678202301011234abcdefghijkl",
"direction": "OUT",
"transactionType": "D",
"operation": "PIX",
"status": "COMPLETED",
"amount": -100.00,
"currency": "BRL",
"description": "PIX - MARIA DA SILVA",
"identifier": "order-12345",
"timestamp": "2026-01-28T15:00:00-03:00",
"counterParty": {
"name": "MARIA DA SILVA",
"document": "12345678900",
"bankCode": "001"
}
}
],
"fetchedAt": "2026-01-28T18:00:05Z"
}

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.

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/payments/lookup?identifier=order-12345&waitForFinalStatus=10" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

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 é 200 com 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_found quando o liquidante não o encontrou, ou o erro do liquidante quando ela falhou. Logo depois de um POST .../pix/out/async, o 404 quer dizer que o liquidante ainda não registrou o pagamento — ou que o identifier está 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

StatusDescrição
COMPLETEDLiquidada com sucesso
PROCESSINGEm processamento no parceiro
PENDING_APPROVALRetida dentro do banco liquidante (fila de autorização interna dele ou análise de risco). Leia hold.owner / hold.reason — não há aprovação pendente do seu lado nem do nosso
FAILEDFalhou / rejeitada
REVERSEDEstornada / devolvida
UNKNOWNStatus do parceiro fora do mapeamento

Fluxo de estados

Aprovado Rejeitado Saldo insuficiente Em análise Aprovada Cancelada Sem confirmaçãona janela Sem desfechoem ~25 min Liquidante decideem até 7 dias Cliente envia PIXPOST /pix/out Avaliação derisco e saldo <code>PROCESSING</code> Liquidação BACEN <code>COMPLETED</code> · HTTP 200Webhook <code>pix.out.completed</code> <code>FAILED</code> · HTTP 422<code>errorCode</code> + <code>errorReason</code>Webhook <code>pix.out.failed</code> <code>PENDING_APPROVAL</code> · HTTP 202 <code>TIMEOUT</code> · HTTP 202Consulte GET /paymentsantes de reenviar <code>COMPLETED</code>/<code>FAILED</code> tardioWebhook com <code>late: true</code>
  • O resultado final chega pelos webhooks pix.out.completed / pix.out.failed. Em caso de TIMEOUT, a API também emite pix.out.timeout (estado indeterminado — confira o extrato; um completed/failed tardio ainda pode chegar depois, com late: true e o mesmo paymentId).
  • Reenvio com a mesma Idempotency-Key devolve o desfecho registrado e não executa o pagamento de novo: em FAILED, a mesma recusa; em TIMEOUT, o estado indeterminado. Para tentar de novo depois de um FAILED, use Idempotency-Key nova e identifier novo. Depois de um TIMEOUT, 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

#!/bin/bash
# Configuration
API_URL="https://tenant.api.corpx.com"
TOKEN="your_token_here"
TENANT_ID="tenant-suaempresa"
ACCOUNT_ID="your_account"
# Transfer details
PIX_KEY="12345678901"
PIX_KEY_TYPE="CPF"
AMOUNT=100.00
echo "=== PIX CASH OUT ==="
echo ""
echo "PIX Key: $PIX_KEY ($PIX_KEY_TYPE)"
echo "Amount: R$ $AMOUNT"
echo ""
# 1. Confirm (in production, wait for user confirmation)
read -p "Confirm transfer? (y/n): " confirm
if [ "$confirm" != "y" ]; then
echo "Transfer cancelled"
exit 0
fi
# 2. Execute transfer
echo ""
echo "Executing transfer..."
IDEMPOTENCY_KEY="cashout-$(date +%s)-$RANDOM"
transfer_response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/out" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d "{
\"amount\": $AMOUNT,
\"keyType\": \"$PIX_KEY_TYPE\",
\"key\": \"$PIX_KEY\",
\"description\": \"Transfer via script\"
}")
# Check result
STATUS=$(echo "$transfer_response" | jq -r '.status')
E2E=$(echo "$transfer_response" | jq -r '.endToEndId')
if [ "$STATUS" = "COMPLETED" ]; then
echo ""
echo "=== TRANSFER COMPLETED ==="
echo "Status: $STATUS"
echo "E2E: $E2E"
echo "$transfer_response" | jq
else
echo ""
echo "=== RESULT ==="
echo "$transfer_response" | jq
fi

Consultar QR Code (Decode)

Antes de pagar, você pode decodificar o QR Code para exibir os dados do beneficiário ao usuário:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/decode" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Content-Type: application/json" \
-d '{
"emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
}'

Resposta (QR dinâmico imediato):

{
"key": "123e4567-e89b-12d3-a456-426614174000",
"amount": 150.00,
"originalAmount": 150.00,
"identifier": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
"decodeId": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
"qrCodeType": "dynamic-immediate",
"qrCodeTypeId": 1,
"allowChange": false,
"description": "Compra online",
"payeeName": "EMPRESA EXEMPLO LTDA",
"payeeDocument": "12345678000190",
"bankIspb": "50871921",
"bankBranch": "0001",
"bankAccount": "123456-7",
"accountType": "CHECKING"
}

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:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/async" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pay-qr-async-12345" \
-d '{
"emv": "00020126580014br.gov.bcb.pix...",
"amount": 150.00,
"description": "QR Code payment",
"identifier": "pay-qr-async-12345"
}'

Resposta:

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"workflowId": "pix-out-{accountId}-{identifier}",
"runId": "b7c1f0e2-...",
"idempotencyKey": "pay-qr-async-12345",
"identifier": "pay-qr-async-12345",
"status": "ACCEPTED"
}

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)

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):

{
"id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.out.completed",
"occurredAt": "2026-09-16T20:58:46.258668746Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-suaempresa",
"accountId": "{accountId}",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-suaempresa",
"accountId": "{accountId}",
"status": "SUCCESS",
"endToEnd": "E36741675202601281500001234567",
"transactionId": "162982-pix",
"amount": 100.00,
"currency": "BRL",
"description": "Pagamento fornecedor",
"identifier": "order-12345",
"originalTransactionId": "",
"initiatedAt": "2026-09-16T20:58:42.646763686Z",
"completedAt": "2026-09-16T20:58:46.258668746Z",
"key": {
"type": "CPF",
"key": "12345678901"
},
"payee": {
"name": "MARIA DA SILVA",
"document": "12345678901",
"bankCode": "001",
"bankIspb": "00000000",
"branch": "0001",
"accountNumber": "12345678"
}
}
}

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)

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

ErroHTTPCausaSolução
key_not_found404Chave PIX não existe no DICTVerifique a chave e seu tipo
invalid_pix_key422Chave malformada ou incompatível com o tipo informadoUse: CPF, CNPJ, EMAIL, PHONE, EVP
insufficient_funds422Saldo insuficiente apurado pelo liquidanteVerifique o saldo da conta
limit_exceeded_daily / limit_exceeded_nightly / limit_exceeded_monthly / limit_exceeded_transaction422Limite da conta excedido na janela indicadaAguarde a virada da janela ou solicite aumento
partner_rejected422Recusa do liquidante por risco/antifraudeVeja o bloco partner com o motivo
policy_denied422Uma regra de política do tenant/conta recusou a transferênciaVeja violations no corpo e ajuste a regra no painel — Políticas e Regras

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

  1. Sempre consulte a chave antes de transferir para validar o destinatário
  2. Confirme com o usuário os dados antes de executar
  3. Use uma Idempotency Key única por transferência — e reutilize a mesma chave ao repetir a requisição, nunca uma nova
  4. Salve o E2E para rastreamento e suporte
  5. Configure webhooks para receber confirmações assíncronas
  6. 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