Enviar Pix por chave (Cash-out)

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

`pixKeyType`	Formato
`cpf`	`123.456.789-00` ou `12345678900`
`cnpj`	`00.000.000/0001-00` ou numérico
`email`	`usuario@dominio.com`
`phone`	`+5511999999999`
`evp`	UUID (chave aleatória)

Parâmetros importantes

Campo	Obrigatório	Notas
`transaction.value`	Sim	Valor em BRL.
`transaction.externalId`	Sim	Único por operação. `409` em duplicata.
`recipient.pixKey`	Sim	Chave do destinatário.
`recipient.pixKeyType`	Sim	Tipo da chave (ver tabela acima).
`recipient.document`	Não	CPF/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.

Status	Significado
`CREATED` / `RESERVED` / `DISPATCH_PENDING`	Pipeline interno; aguardando despacho ao BaaS.
`DISPATCHED`	BaaS aceitou; aguardando confirmação final.
`CONFIRMED`	Transferência confirmada — estado de sucesso.
`FAILED`	Falha definitiva; reserva liberada.
`PROVIDER_RESULT_UNKNOWN`	Resposta ambígua; reconciliação em andamento.
`RECONCILIATION_REQUIRED`	Tentativas de reconciliação esgotadas; requer atenção.
`REVERSED`	Revertido 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.

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Enviar Pix por chave (Cash-out)

Visão geral do fluxo

Passo 1 — Criar o envio

Tipos de chave Pix suportados

Parâmetros importantes

Passo 2 — Monitorar o pipeline

Passo 3 — Receber o webhook

Passo 4 — Confirmar via GET (fall-back)

Estados ambíguos

Reversão (cash-out reversal)

Reconciliação com o ledger

Referências

​Visão geral do fluxo

​Passo 1 — Criar o envio

​Tipos de chave Pix suportados

​Parâmetros importantes

​Passo 2 — Monitorar o pipeline

​Passo 3 — Receber o webhook

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

​Estados ambíguos

​Reversão (cash-out reversal)

​Reconciliação com o ledger

​Referências

Visão geral do fluxo

Passo 1 — Criar o envio

Tipos de chave Pix suportados

Parâmetros importantes

Passo 2 — Monitorar o pipeline

Passo 3 — Receber o webhook

Passo 4 — Confirmar via GET (fall-back)

Estados ambíguos

Reversão (cash-out reversal)

Reconciliação com o ledger

Referências