Skip to main content

​
Visão geral do fluxo

​
Passo 1 — Criar o envio

curl -X POST https://api.clearpago.com.br/api/pix/cash-out \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-cashout-001" \
  -d '{
    "transaction": {
      "value": 500.00,
      "externalId": "saque-789",
      "description": "Pagamento Fornecedor ABC"
    },
    "recipient": {
      "name": "Maria Oliveira",
      "document": "987.654.321-00",
      "pixKey": "maria@email.com",
      "pixKeyType": "email"
    }
  }'
Resposta 201: 
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "CREATED",
  "externalId": "saque-789"
}
Persista o id imediatamente. Ele é necessário para monitoramento e reconciliação.

​
Tipos de chave Pix suportados

pixKeyTypeFormato
cpf123.456.789-00 ou 12345678900
cnpj00.000.000/0001-00 ou numérico
emailusuario@dominio.com
phone+5511999999999
evpUUID (chave aleatória)

​
Parâmetros importantes

CampoObrigatórioNotas
transaction.valueSimValor em BRL.
transaction.externalIdSimÚnico por operação. 409 em duplicata.
recipient.pixKeySimChave do destinatário.
recipient.pixKeyTypeSimTipo da chave (ver tabela acima).
recipient.documentNãoCPF/CNPJ do destinatário (recomendado para rastreio).

​
Passo 2 — Monitorar o pipeline

Após o 201, o cash-out passa por um pipeline interno. O status no POST reflete o estado no momento do commit — não é necessariamente PENDING.
StatusSignificado
CREATED / RESERVED / DISPATCH_PENDINGPipeline interno; aguardando despacho ao BaaS.
DISPATCHEDBaaS aceitou; aguardando confirmação final.
CONFIRMEDTransferência confirmada — estado de sucesso.
FAILEDFalha definitiva; reserva liberada.
PROVIDER_RESULT_UNKNOWNResposta ambígua; reconciliação em andamento.
RECONCILIATION_REQUIREDTentativas de reconciliação esgotadas; requer atenção.
REVERSEDRevertido pelo destinatário após confirmação.

​
Passo 3 — Receber o webhook

POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64 ECDSA P-256 SHA-256>

{
  "event_type": "pix_cash_out",
  "event": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "external_id": "saque-789",
    "status": "CONFIRMED",
    "value_cents": 50000,
    "end_to_end_id": "E07136847202504011200O7654ABCD12",
    "fee_amount_cents": 10,
    "confirmed_at": "2026-04-01T12:30:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
Sempre verifique a assinatura antes de processar. Responda 2xx rapidamente.

​
Passo 4 — Confirmar via GET (fall-back)

curl https://api.clearpago.com.br/api/pix/cash-out/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <seu_api_token>"
Use quando o webhook não chegou ou o status está em estado intermediário.

​
Estados ambíguos

Se o cash-out ficar em PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED:
  • Não cancele ou reenvie sem análise — o dinheiro pode ter saído.
  • Monitore a idade do estado com GET /api/pix/cash-out/{id}.
  • Aguarde a reconciliação automática. Se persistir, acione o suporte.
  • Veja o guia de reconciliação.

​
Reversão (cash-out reversal)

Um cash-out CONFIRMED pode ser revertido pelo destinatário. Nesse caso, você recebe pix_cash_out_reversal e o status vai para REVERSED. Veja Lidar com reversão de cash-out.

​
Reconciliação com o ledger

Após CONFIRMED, um lançamento de débito é criado no ledger. Após REVERSED, um crédito de reversão é criado. Consulte Ledger e reconciliação.

​
Referências