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 Pagamento de Boleto no fim desta página.

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

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"

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.

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}"
}

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.

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

*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).

{
  "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": "123***01",
        "bankCode": "001"
      }
    }
  ],
  "fetchedAt": "2026-01-28T18:00:05Z"
}

Status Possíveis

Fluxo de estados

• 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 depende do desfecho anterior: se o pagamento terminou em FAILED, a chave é liberada e a nova requisição reexecuta o pagamento (desde v2.43.3); se terminou em TIMEOUT, o reenvio não acontece — o estado é indeterminado e a API devolve o resultado registrado. Com uma chave nova, você pode duplicar o envio. Detalhes em Idempotência.

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)

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)

Pagamento de Boleto

Boleto é o outro cash out disponível na v2 (na v1 esses endpoints respondiam 503). São três rotas: uma para ler o boleto antes de pagar, uma para pagar e uma para consultar o resultado.

Passo 1: Preview (ler o boleto)

Resolve a linha digitável no parceiro e devolve 200 com os dados do título (beneficiário, pagador, valores, vencimento) para você exibir antes de debitar.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/preview" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{ "line": "34191790010104351004791020150008291070026000" }'

O campo canônico é line; barcode é aceito como alias. Boleto não encontrado no parceiro devolve 404 not_found.

{
  "type": "boleto-payment",
  "bank": "Itaú Unibanco S.A.",
  "bankCode": "341",
  "receiverName": "FORNECEDOR EXEMPLO LTDA",
  "receiverTaxId": "12345678000190",
  "dueDate": "2026-08-10",
  "amount": 1430.63,
  "discountAmount": 0,
  "interestAmount": 3.29,
  "fineAmount": 28.61,
  "totalUpdated": 1462.53,
  "status": "PAYABLE"
}

Passo 2: Pagar

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/pay" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "line": "34191790010104351004791020150008291070026000",
       "amount": 1462.53,
       "taxId": "12345678000199",
       "description": "Fornecedor ACME"
     }'

Valor divergente volta como boleto_amount_mismatch (422), e a mensagem traz o valor que o liquidante espera — refaça o preview e reenvie com ele.

A resposta é sempre 202, nunca 200: o pagamento roda de forma assíncrona e o corpo traz paymentId (= boletoId, no formato bol_{uuid}), status: "PROCESSING" e um header Location apontando para a consulta de status.

{
  "paymentId": "bol_aabbccdd-...",
  "boletoId": "bol_aabbccdd-...",
  "idempotencyKey": "...",
  "amount": 250.00,
  "status": "PROCESSING"
}

O boletoId é derivado de (accountId, Idempotency-Key), então repetir a requisição com a mesma chave devolve o mesmo paymentId e reaproveita a execução em curso — sem débito duplicado.

Passo 3: Consultar o resultado

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/payments/bol_aabbccdd-..." \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Aceita tanto o paymentId canônico (bol_...) quanto a referência do parceiro. Enquanto o parceiro ainda não devolveu a referência, a rota responde 200 com o último status local conhecido (PROCESSING) em vez de erro.

O desfecho também chega por webhook: boleto.paid e boleto.failed (ver Webhooks). A compensação de um boleto pode levar horas — até o dia útil seguinte — então trate PROCESSING como estado normal e prolongado, não como falha.

Erros Comuns

A lista completa com mensagens e semântica está em Erros.

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

Não há mais limite fixo por transação — o valor é limitado apenas pelos limites operacionais da conta (consulte GET /v1/accounts/{accountId}/pix/limits).

Próximos Passos

• Guia de Devolução - Estornar transferências recebidas
• Webhooks - Configurar notificações
• Erros - Lista completa de códigos de erro