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

# Ciclo de vida das operações

> Grandes fluxos: cash-in, cash-out, refund-in, reversão, como os eventos chegam e reação do integrador.

## Cash-in (recebimento)

1. `POST /api/pix/cash-in` → geralmente `PENDING` e eventualmente `pixCode` (EMV).
2. O pagador liquida no parceiro.
3. O parceiro chama a clearpago em `POST /api/webhooks/pix/cash-in` (você **não** expõe este endpoint). Workers aplicam estados, **ledger** e **outbox** de notificação.
4. Seu endpoint recebe `POST` com `event_type: pix_cash_in` (assinado). Consulte o detalhe com `GET /api/pix/cash-in/{id}` em caso de dúvida.
5. Trate `PAID` como sucesso financeiro usual para “liberar” o pedido; respeitando a política interna (ver [status](/core-concepts/status-model)).

## Cash-out (por chave ou QR)

1. `POST /api/pix/cash-out` ou `POST /api/pix/cash-out-qrcode` → **reserva** e encadeamento (outbox/despacho).
2. O despacho fala com o BaaS; respostas **ambíguas** (timeout, 5xx, EOF) podem levar a **reconciliação** sem liberar reserva indevidamente.
3. Webhook do parceiro em `POST /api/webhooks/pix/cash-out` (interno) atualiza estados; seu sistema recebe `pix_cash_out` quando aplicável.
4. Confirmação de transferência: status terminal típico **`CONFIRMED`** no domínio documentado, após o pipeline (incluindo `DISPATCHED` conforme o caso). Veja [envio por chave](/guides/send-pix-cash-out-key).

## Refund-in (devolução do recebimento)

1. Sobre cash-in `PAID`, `POST /api/pix/refund-in/{id}` com `{id}` = UUID do **cash-in**.
2. Prazo: até **89 dias** após o recebimento. Parciais múltiplos permitidos; somas competem por teto.
3. Webhook de parceiro com `CashInReversal` amarra o resultado; seu comerciante recebe `pix_cash_in_reversal` com **semântica de IDs específica** (ver [referência de webhooks](/webhooks/webhook-event-reference)).

## Reversão de cash-out (devolução pelo destinatário)

1. Ocorre após envio `CONFIRMED` quando o parceiro emite `CashOutReversal`.
2. O cash-out vai a **`REVERSED`**; há **crédito** no ledger.
3. Seu comerciante recebe `pix_cash_out_reversal` com `event.id` = UUID do **cash-out**; monitore `value_cents` (fallback documentado no código de origem se metadados incompletos). Ver [guia](/guides/handle-cash-out-reversal).

## Como “os eventos chegam”

* **BaaS → clearpago:** webhooks internos (HMAC/timestamp, etc.); assíncrono.
* **clearpago → comerciante:** `Digital-Signature` (ECDSA) no corpo JSON; responda **2xx** rápido.
* **Reconciliação:** preenche lacunas quando webhooks atrasam ou a rede foi ambígua.

## O que o sistema integrador deve fazer

* Persistir `id` e `externalId` cedo.
* Tornar handlers de webhook **idempotentes** (mesmo evento + mesma transição pode repetir).
* Monitorar estados **não terminais** antigos e alinhar com [reconciliação operacional](/guides/reconcile-transactions).