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.

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

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

Tipos de Chave PIX

Tipo	Formato	Exemplo
`CPF`	11 dígitos	`12345678901`
`CNPJ`	14 dígitos	`12345678000199`
`EMAIL`	E-mail válido	`joao@email.com`
`PHONE`	+55 + DDD + número	`+5511999998888`
`EVP`	UUID	`123e4567-e89b-12d3-a456-426614174000`

Passo 1: Consultar a Chave PIX (Opcional mas Recomendado)

Antes de transferir, você pode consultar a chave para validar e obter os dados do destinatário. A resposta de preview é retornada ao fazer a transferência, mas uma consulta prévia permite exibir os dados para confirmação do usuário.

informação

A API realiza automaticamente a consulta da chave durante a transferência. A consulta prévia é opcional, mas recomendada para uma melhor experiência do usuário.

Dados Retornados na Transferência

Ao executar a transferência (próximo passo), a resposta inclui os dados do destinatário:

{
  "transactionId": "txn_xyz789abc123",
  "status": "APPROVED",
  "endToEndId": "E36741675202601281500001234567",
  "amount": 100.00,
  "currency": "BRL"
}

Campo	Descrição
`transactionId`	ID interno da transação
`status`	Status: `APPROVED`, `PENDING`, `REJECTED`, `PROCESSING`
`endToEndId`	ID E2E para rastreamento no BACEN

Passo 2: Executar a Transferência

Execute a transferência PIX via chave:

Request

curl -X POST "https://api.corpxapi.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 '{
    "accountId": "{accountId}",
    "amount": 100.00,
    "currency": "BRL",
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345"
  }'

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	UUID da conta de origem
`amount`	number	Sim	Valor em BRL (ex.: 100.00)
`currency`	string	Sim	Sempre `BRL`
`keyType`	string	Sim	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`key`	string	Sim	Chave PIX do destinatário
`description`	string	Não	Descrição da transferência (máximo 140 caracteres)
`identifier`	string	Não	Identificador fornecido pelo integrador para rastreamento e conciliação. Aparece no extrato quando o pagamento é conciliado.

Resposta de Sucesso (202 Accepted)

{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "amount": 100.00,
  "currency": "BRL"
}

Campo	Descrição
`transactionId`	ID interno da transação
`status`	`APPROVED`, `PENDING`, `REJECTED`, `PROCESSING`
`endToEndId`	ID E2E para rastreamento no BACEN

Resposta de Erro

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

Timeout e Rate Limit no fluxo síncrono

Timeout do parceiro (207 partner_timeout): o PIX pode ter sido enviado; consulte extrato/status do pagamento antes de reenviar.
Rate limit por conta (429 rate_limit_exceeded): o endpoint síncrono aplica limite por conta (default atual 100 req/min, customizável por policy) e retorna currentRateLimit + scope no erro.
Planejado para os próximos dias: o default das requisições síncronas será ajustado para 10 req/min.

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://api.corpxapi.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 '{
    "accountId": "{accountId}",
    "amount": 100.00,
    "currency": "BRL",
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345-async"
  }'

Resposta:

{
  "paymentId": "2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "status": "SCHEDULED",
  "scheduled": true
}

O resultado final (sucesso/falha) é entregue por webhook e também pode ser consultado por 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://api.corpxapi.com/v1/accounts/{accountId}/pix/transactions?endToEndId=E12345678202301011234abcdefghijkl" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	UUID da conta
`endToEndId`	string	Sim*	ID E2E da transação
`identifier`	string	Sim*	Identificador da cobrança ou referência

*Pelo menos um dos dois (endToEndId ou identifier) é obrigatório.

Resposta de Sucesso (200 OK)

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -100.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2026-01-28T15:00:00Z",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 9900.00
}

Status Possíveis

Status	Descrição
`COMPLETED`	Transação concluída com sucesso
`REVERSED`	Transação estornada
`PENDING`	Aguardando processamento
`FAILED`	Transação falhou

dica

Sempre salve o endToEndId das transferências para poder consultar o status posteriormente.

Exemplo Completo: Script de Cash Out

#!/bin/bash

# Configuration
API_URL="https://api.corpxapi.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 "{
    \"accountId\": \"$ACCOUNT_ID\",
    \"amount\": $AMOUNT,
    \"currency\": \"BRL\",
    \"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" = "APPROVED" ]; then
  echo ""
  echo "=== TRANSFER APPROVED ==="
  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://api.corpxapi.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:

{
  "amount": 150.00,
  "allowChange": false,
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "beneficiaryName": "EMPRESA EXEMPLO LTDA",
  "beneficiaryType": "LEGAL_PERSON",
  "document": "12345678000190",
  "bankIspb": "12345678",
  "bankAccount": "123456",
  "bankBranch": "0001",
  "accountType": "CHECKING",
  "discount": 0
}

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 específico:

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

Para QR Codes estáticos sem valor definido, inclua o campo amount:

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

Webhook de Transferência

Após a transferência, você receberá um webhook:

{
  "event": "pix.out.completed",
  "timestamp": "2026-01-28T15:00:02Z",
  "data": {
    "transactionId": "txn_xyz789abc123",
    "status": "COMPLETED",
    "value": 100.00,
    "endToEndId": "E36741675202601281500001234567",
    "recipient": {
      "name": "MARIA DA SILVA",
      "document": "12345678901"
    }
  }
}

BigPix (Transferências de alto valor)

Para transferências acima do limite individual (R$15.000 por padrão), use o endpoint BigPix:

Importante: BigPix agora é sempre assíncrono.
POST /v1/accounts/{accountId}/pix/out/bigpix agenda o processamento (mesmo comportamento do /pix/out/async) e retorna 202 com paymentId.

Erros Comuns

Erro	Causa	Solução
`key_not_found`	Chave PIX não existe	Verifique a chave e seu tipo
`insufficient_balance`	Saldo insuficiente	Verifique o saldo da conta
`invalid_key_type`	Tipo de chave inválido	Use: CPF, CNPJ, EMAIL, PHONE, EVP
`transfer_limit_exceeded`	Limite diário excedido	Aguarde ou solicite aumento
`409 Conflict`	Idempotency Key duplicada	Use uma chave diferente

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

Tipo	Limite Padrão
Por transação	R$ 50.000,00
Diário	R$ 100.000,00
Mensal	Sem limite

informação

Os limites podem ser personalizados. Entre em contato com o suporte para mais informações.

Próximos Passos

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

Visão Geral​

Fluxo de Integração​

Tipos de Chave PIX​

Passo 1: Consultar a Chave PIX (Opcional mas Recomendado)​

Dados Retornados na Transferência​

Passo 2: Executar a Transferência​

Request​

Parâmetros do Body​

Resposta de Sucesso (202 Accepted)​

Resposta de Erro​

Timeout e Rate Limit no fluxo síncrono​

Fluxo assíncrono (recomendado para alto volume)​

Passo 3: Consultar Status da Transferência​

Request​

Parâmetros de Query​

Resposta de Sucesso (200 OK)​

Status Possíveis​

Exemplo Completo: Script de Cash Out​

Consultar QR Code (Decode)​

Pagar QR Code (PIX Out via EMV)​

Webhook de Transferência​

BigPix (Transferências de alto valor)​

Erros Comuns​

Boas Práticas​

Limites​

Próximos Passos​

Visão Geral

Fluxo de Integração

Tipos de Chave PIX

Passo 1: Consultar a Chave PIX (Opcional mas Recomendado)

Dados Retornados na Transferência

Passo 2: Executar a Transferência

Request

Parâmetros do Body

Resposta de Sucesso (202 Accepted)

Resposta de Erro

Timeout e Rate Limit no fluxo síncrono

Fluxo assíncrono (recomendado para alto volume)

Passo 3: Consultar Status da Transferência

Request

Parâmetros de Query

Resposta de Sucesso (200 OK)

Status Possíveis

Exemplo Completo: Script de Cash Out

Consultar QR Code (Decode)

Pagar QR Code (PIX Out via EMV)

Webhook de Transferência

BigPix (Transferências de alto valor)

Erros Comuns

Boas Práticas

Limites

Próximos Passos