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

# Status das transações

> Estados possíveis de um pagamento e o que fazer em cada um.

## Estados do pagamento

| Status       | Valor numérico | Descrição                                                          |
| ------------ | -------------- | ------------------------------------------------------------------ |
| `pending`    | `1`            | Criado e aguardando processamento pelo gateway                     |
| `authorized` | `2`            | Pré-autorizado — valor reservado no cartão, aguardando captura     |
| `approved`   | `3`            | Aprovado — cobrança efetivada ou PIX confirmado                    |
| `failed`     | `4`            | Falhou após todas as tentativas configuradas                       |
| `refunded`   | `5`            | Estornado após aprovação                                           |
| `cancelled`  | `6`            | Pré-autorização cancelada — valor liberado no cartão               |
| `processing` | —              | Estado transitório: resposta assíncrona (`202`) ainda em andamento |

<Info>
  O estado `processing` não existe no banco de dados — ele é retornado apenas na resposta HTTP `202` quando o gateway não respondeu dentro do `time_to_wait_sync`. O estado persistido permanece `pending` até a resolução.
</Info>

## O que fazer em cada estado

| Status       | Ação recomendada                                                                                                                 |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `pending`    | Aguarde o webhook de `approved` ou `failed`                                                                                      |
| `processing` | Armazene o `transaction_id` e aguarde o webhook                                                                                  |
| `authorized` | [Capture](/payments#capturar) quando confirmar o pedido, ou [cancele](/payments#cancelar-a-pré-autorização) para liberar o valor |
| `approved`   | Libere o produto/serviço ao cliente                                                                                              |
| `failed`     | Ofereça nova tentativa ao cliente com nova `Idempotency-Key`                                                                     |
| `refunded`   | Confirme o estorno ao cliente; atualize seu sistema de pedidos                                                                   |
| `cancelled`  | A reserva foi desfeita; nada foi cobrado do cliente                                                                              |

<Warning>
  `authorized` **não** é um estado final: o valor está apenas reservado. Se você não capturar, o gateway libera a reserva sozinho depois de alguns dias e a venda se perde.
</Warning>

## Estados finais

Use o helper do pacote `@plugtopay/api-client` para distinguir estados que não mudarão mais:

```typescript theme={null}
import { isFinalPaymentStatus } from '@plugtopay/api-client'

if (isFinalPaymentStatus(payment.status)) {
  // approved, failed, refunded ou cancelled — pode encerrar o polling
}
```

`authorized` não conta como final: a transação ainda espera uma captura ou um cancelamento.

## Mapeamento de múltiplas tentativas

Quando há fallback entre gateways, cada tentativa fica registrada em `transactions[]` com seu próprio `status`. O `status` raiz do `PaymentResource` reflete **o resultado final** após todas as tentativas:

```json theme={null}
{
  "status": "approved",
  "transactions": [
    { "attempt": 1, "gateway": "safe2pay", "status": "failed", "response_code": "51" },
    { "attempt": 2, "gateway": "pagarme",  "status": "approved", "response_code": "00" }
  ]
}
```