Lidar com reversão de cash-out

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

Campo	Valor	Notas
`event.id`	UUID do cash-out revertido	Não é um novo UUID.
`event.external_id`	`externalId` do cash-out	Igual ao enviado na criação.
`event.status`	`REVERSED`	Status final do cash-out.
`event.value_cents`	Valor revertido em centavos	Normalmente 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:

Evento	Lançamento
Cash-out `CONFIRMED`	Débito no ledger
Cash-out `REVERSED`	Cré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

Validar a assinatura

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

Responder 2xx rapidamente

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

Verificar idempotência

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

Atualizar o status interno

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

Ajustar registros financeiros

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

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

Área	Ação
Financeiro / ERP	Registrar crédito correspondente ao valor revertido.
Operações	Investigar a causa da reversão se não for esperada.
Suporte	Notificar usuário afetado, se aplicável.
Auditoria	Correlacionar `end_to_end_id` da reversão com os registros do BaaS.

Início

Introdução

Conceitos

Guias

Referência de API

Webhooks

Ledger e Reconciliação

Erros

Go-live

FAQ

Lidar com reversão de cash-out

O que é reversão de cash-out

Webhook recebido

Semântica dos campos

Impacto no ledger

O que fazer ao receber o evento

Quando o cash-out mostra REVERSED no GET

Impacto operacional

Referências

​O que é reversão de cash-out

​Webhook recebido

​Semântica dos campos

​Impacto no ledger

​O que fazer ao receber o evento

​Quando o cash-out mostra REVERSED no GET

​Impacto operacional

​Referências

O que é reversão de cash-out

Webhook recebido

Semântica dos campos

Impacto no ledger

O que fazer ao receber o evento

Quando o cash-out mostra REVERSED no GET

Impacto operacional

Referências