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

# Modelo de status

> Status de cash-in, cash-out e refund-in, estados intermediários, terminalidade e ação do integrador.

## Cash-in (domínio)

Além de `PENDING`, `PAID`, `EXPIRED` e `FAILED`, o sistema pode transitar por estados **intermediários** ou **não conclusivos** quando o retorno do parceiro não é imediato ou há falha de rede.

| Status                    | Significado                                                               |
| ------------------------- | ------------------------------------------------------------------------- |
| `PENDING`                 | Aguardando pagamento ou confirmação.                                      |
| `PAID`                    | Recebimento **confirmado** (sucesso financeiro usual para “pedido pago”). |
| `EXPIRED`                 | QR/cobrança expirou sem pagamento.                                        |
| `FAILED`                  | Falha **definitiva** (conforme mapeamento do webhook do parceiro).        |
| `PROVIDER_RESULT_UNKNOWN` | Resposta **ambígua** (ex.: timeout); sujeito a **reconciliação**.         |
| `RECONCILIATION_REQUIRED` | Em análise após tentativas; ainda pode convergir a `PAID` ou `FAILED`.    |

Mapeamento **CashIn (webhook de parceiro) →** status interno de cash-in (documento de origem):

| `status` no webhook                        | Status interno cash-in |
| ------------------------------------------ | ---------------------- |
| `CONFIRMED`                                | `PAID`                 |
| `FAILED`, `CANCELLED`, `REJECTED`, `ERROR` | `FAILED`               |

**Integração prática:** trate **`PAID`** como sucesso de recebimento para liberar o pedido; monitore `PENDING` prolongado e estados **não terminais** ([boas práticas](/go-live/checklist)).

## Cash-out (domínio)

O fluxo completo envolve reserva, despacho e liquidação.

| Status                                      | Significado resumido                                         |
| ------------------------------------------- | ------------------------------------------------------------ |
| `CREATED` / `RESERVED` / `DISPATCH_PENDING` | Pipeline interno até aceite do parceiro.                     |
| `DISPATCHED`                                | Parceiro **aceitou** o envio; aguarda webhook final.         |
| `CONFIRMED`                                 | Transferência **confirmada** (término de sucesso usual).     |
| `FAILED`                                    | Falha **definitiva**; reserva liberada conforme regras.      |
| `RELEASED`                                  | Reserva liberada após falha.                                 |
| `PROVIDER_RESULT_UNKNOWN`                   | Resultado **ambíguo** na chamada ao parceiro.                |
| `RECONCILIATION_REQUIRED`                   | Requer intervenção ou **consulta de status**.                |
| `REVERSED`                                  | **Devolução** após confirmação (pós-`CONFIRMED`).            |
| `PENDING`                                   | **Legado**; mantido para compatibilidade com fluxos antigos. |

Mapeamento **CashOut (webhook de parceiro) →** status interno (origem):

| `status` no webhook | Status interno |
| ------------------- | -------------- |
| `CONFIRMED`         | `CONFIRMED`    |
| `FAILED`, …         | `FAILED`       |

A resposta imediata do `POST` pode refletir o estado no momento do commit (não necessariamente apenas a palavra `PENDING`).

## Refund-in (domínio)

| Status                    | Descrição                                                 |
| ------------------------- | --------------------------------------------------------- |
| `PENDING`                 | Solicitação aceita; aguarda webhook.                      |
| `CONFIRMED`               | Devolução **confirmada**.                                 |
| `FAILED`                  | Devolução **rejeitada**.                                  |
| `PROVIDER_RESULT_UNKNOWN` | Ambiguidade; a reconciliação pode aplicar resultado.      |
| `RECONCILIATION_REQUIRED` | Esgotadas tentativas automáticas **sem** conclusão clara. |

## Terminalidade (orientação prática)

* **Tendencialmente terminais de negócio:** `PAID`, `EXPIRED`, `FAILED` (cash-in); `CONFIRMED`, `FAILED`, `REVERSED` (cash-out); `CONFIRMED`, `FAILED` (refund) — ajuste conforme a sua política de `REVERSED` e conciliação.
* **Não trate como concluso:** `PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED` (e pipeline intermediário de cash-out) — use consultas, webhooks e [reconciliação](/ledger-and-reconciliation/reconciliation).

## Ver também

* Diagramas e sequências: [Ciclo de vida](/core-concepts/transaction-lifecycle)
* Guia operacional: [Reconciliar transações](/guides/reconcile-transactions)