> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lidar com reversão de cash-out

> O que é reversão de cash-out, como o webhook chega, impacto no ledger e como o sistema integrador deve reagir.

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

```http theme={null}
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. |

<Warning>
  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.
</Warning>

## 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](/core-concepts/ledger-and-balance) para detalhes.

## O que fazer ao receber o evento

<Steps>
  <Step title="Validar a assinatura">
    Sempre [verifique a assinatura](/guides/verify-webhook-signatures) (`Digital-Signature`) antes de qualquer ação.
  </Step>

  <Step title="Responder 2xx rapidamente">
    Responda `200` ou `204` imediatamente. Processamento longo deve ir para uma fila.
  </Step>

  <Step title="Verificar idempotência">
    Chave: `event_type: pix_cash_out_reversal` + `event.id` (UUID do cash-out). Evita processar a reversão duas vezes.
  </Step>

  <Step title="Atualizar o status interno">
    Marque o cash-out como `REVERSED` na sua base de dados.
  </Step>

  <Step title="Ajustar registros financeiros">
    Realize o crédito correspondente no seu sistema de controle financeiro (ERP, planilha, etc.).
  </Step>

  <Step title="Notificar equipes se necessário">
    Dependendo do impacto operacional, notifique finanças, operações ou o usuário afetado.
  </Step>
</Steps>

## Quando o cash-out mostra REVERSED no GET

Se por qualquer motivo você perdeu o webhook, a consulta direta mostra o estado atual:

```bash theme={null}
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. |

## Referências

* [Modelo de status (cash-out)](/core-concepts/status-model)
* [Referência de eventos de webhook](/webhooks/webhook-event-reference)
* [Ledger e saldo](/core-concepts/ledger-and-balance)
* [Verificar assinaturas](/guides/verify-webhook-signatures)