Skip to main content

​
O que é reversão de cash-out

Uma reversão de cash-out ocorre quando um Pix enviado (CONFIRMED) é devolvido pelo destinatário — seja de forma voluntária ou por ação do BaaS/BACEN. O cash-out transita para o status REVERSED e o valor retorna ao saldo disponível via crédito no ledger. Este evento não é iniciado pelo seu sistema. Ele é originado externamente (destinatário ou BaaS) e chega através do pipeline de notificações da ClearPago.

​
Webhook recebido

Quando uma reversão é processada, você recebe: 
POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64 ECDSA P-256 SHA-256>

{
  "event_type": "pix_cash_out_reversal",
  "event": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "external_id": "saque-789",
    "status": "REVERSED",
    "value_cents": 50000,
    "end_to_end_id": "D07136847202504021600O9999ABCD99",
    "fee_amount_cents": 0,
    "confirmed_at": "2026-04-02T09:05:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}

​
Semântica dos campos

CampoValorNotas
event.idUUID do cash-out revertidoNão é um novo UUID.
event.external_idexternalId do cash-outIgual ao enviado na criação.
event.statusREVERSEDStatus final do cash-out.
event.value_centsValor revertido em centavosNormalmente o valor total do cash-out.
Monitore o campo value_cents. Em casos de metadados incompletos do BaaS, o fallback de valor pode ser aplicado pela plataforma. Consulte GET /api/pix/cash-out/{id} para confirmar o valor exato.

​
Impacto no ledger

Após a reversão, um lançamento de crédito é criado no ledger:
EventoLançamento
Cash-out CONFIRMEDDébito no ledger
Cash-out REVERSEDCrédito no ledger (reversão do débito)
O crédito retorna ao saldo disponível. Consulte Ledger e saldo para detalhes.

​
O que fazer ao receber o evento

1

Validar a assinatura

Sempre verifique a assinatura (Digital-Signature) antes de qualquer ação.
2

Responder 2xx rapidamente

Responda 200 ou 204 imediatamente. Processamento longo deve ir para uma fila.
3

Verificar idempotência

Chave: event_type: pix_cash_out_reversal + event.id (UUID do cash-out). Evita processar a reversão duas vezes.
4

Atualizar o status interno

Marque o cash-out como REVERSED na sua base de dados.
5

Ajustar registros financeiros

Realize o crédito correspondente no seu sistema de controle financeiro (ERP, planilha, etc.).
6

Notificar equipes se necessário

Dependendo do impacto operacional, notifique finanças, operações ou o usuário afetado.

​
Quando o cash-out mostra REVERSED no GET

Se por qualquer motivo você perdeu o webhook, a consulta direta mostra o estado atual: 
curl https://api.clearpago.com.br/api/pix/cash-out/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <seu_api_token>"
Se status for REVERSED, a reversão já foi processada e o crédito já foi aplicado no ledger.

​
Impacto operacional

ÁreaAção
Financeiro / ERPRegistrar crédito correspondente ao valor revertido.
OperaçõesInvestigar a causa da reversão se não for esperada.
SuporteNotificar usuário afetado, se aplicável.
AuditoriaCorrelacionar end_to_end_id da reversão com os registros do BaaS.

​
Referências