# Ciclo de vida da cobrança

Uma cobrança percorre o caminho da criação até ser fechada ou expirar. Esta seção descreve os estados em que ela pode ficar, como se move entre eles e o que o lojista pode fazer em cada etapa.

## Status da cobrança

| Status    | Valor na API | Descrição                                                                      | Entra na busca de pagamentos         |
| --------- | ---------- | ------------------------------------------------------------------------------ | ------------------------------------ |
| Em aberto | `unpaid`   | A cobrança foi emitida, o prazo de pagamento não passou, nenhum pagamento recebido | Sim                                  |
| Paga      | `paid`     | Um pagamento foi encontrado e vinculado à cobrança                             | Não                                  |
| Expirada  | `expired`  | O prazo de pagamento passou, nenhum pagamento recebido                         | Sim, por mais uma hora após a expiração |
| Cancelada | `canceled` | A cobrança foi cancelada pelo lojista manualmente ou pela API                  | Não                                  |

## Transições de status

* **Criação da cobrança.** A cobrança recebe imediatamente o status Em aberto.
* **Em aberto → Paga.** Chegou um pagamento no valor exato da cobrança, ou o lojista vinculou um pagamento manualmente.
* **Em aberto → Expirada.** O prazo de pagamento passou sem nenhum pagamento recebido.
* **Em aberto → Cancelada.** O lojista cancelou a cobrança.
* **Expirada → Paga.** O pagamento chegou dentro de uma hora após a expiração e foi encontrado automaticamente, ou o lojista o vinculou manualmente.
* **Cancelada.** Um estado final; não há caminho de volta.

Uma cobrança no status Paga também não muda de estado — não pode ser paga de novo nem cancelada.

## Prazo de pagamento

O prazo é definido na criação da cobrança e vai de 30 minutos a 12 horas. Valores permitidos: 30 minutos, 1 hora, 3 horas, 6 horas, 12 horas.

Até o prazo, o cliente vê o formulário de pagamento e pode pagar a cobrança. Depois da expiração, a cobrança passa a Expirada e o formulário de pagamento deixa de oferecer o pagamento.

Os dois extremos têm seu preço. Um prazo curto é arriscado em redes lentas — o cliente pode não conseguir a tempo. Um longo amplia a diferença entre a cotação na criação da cobrança e a cotação no pagamento.

## Janela de busca de pagamentos

A busca de pagamentos continua por mais uma hora depois do prazo de pagamento — para levar em conta redes lentas, em que uma transação pode ser confirmada depois de a cobrança já ter expirado formalmente. Durante todo esse tempo o cliente vê a cobrança como expirada, mas, quando chega um pagamento no valor certo, ela passa automaticamente a Paga, com todas as notificações.

Daí a regra para integradores: não rejeite uma notificação de pagamento porque o prazo passou — essa verificação corta uma parte dos pagamentos reais.

## Cancelamento de uma cobrança

Você pode cancelar uma cobrança se ela contiver um erro. O cancelamento exige duas condições:

* A cobrança não está paga — isto é, está no status Em aberto
* Ninguém abriu a página de pagamento da cobrança; o contador de visualizações está em zero

A segunda condição protege contra o cancelamento de uma cobrança que o cliente já viu e possivelmente começou a pagar.

O cancelamento é irreversível. Uma cobrança cancelada é excluída da busca de pagamentos, e um pagamento não pode ser vinculado a ela nem manualmente. Se o pagamento for provável, espere o prazo passar em vez de cancelar — uma cobrança expirada ainda pode ser fechada com um pagamento.

## O que fica travado na criação e o que é recalculado no pagamento

Na criação da cobrança, o serviço converte o valor em fiat para cripto pela cotação atual e trava os valores resultantes para a cobrança. São esses os valores que o cliente vê, e são eles que o serviço procura on-chain. A cotação não os afeta mais: não importa quanto tempo passe, o cliente paga exatamente o valor travado.

No momento do pagamento, os valores contábeis são recalculados:

| Campo               | O que acontece                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `amountFiat`        | O valor original da cobrança em moeda fiat. Nunca muda                                             |
| `amountFiatUSD`     | Sobrescrito com o valor efetivamente recebido, convertido para USD pela cotação do momento do pagamento |
| `commissionFiatUSD` | Recalculado a partir do novo valor de `amountFiatUSD` pela taxa do projeto                         |

Por causa do movimento da cotação, esses valores podem diferir dos originais mesmo quando o pagamento é exato. Para conciliar com o pedido na sua loja, use `amountFiat` — o único valor que permanece inalterado.

## Notificações ao longo da vida da cobrança

As notificações são configuradas por projeto. Uma cobrança tem duas:

* **Pagamento recebido (Incoming payment).** Enviada para o e-mail e o Telegram quando qualquer transação recebida é detectada na sua carteira, tenha ela sido vinculada a uma cobrança ou não.
* **Cobrança paga (Invoice paid).** Enviada para o e-mail, o Telegram e a Webhook URL no momento em que a cobrança passa a Paga — tanto na vinculação automática quanto na manual.

Disso resulta uma regra simples de diagnóstico: se chegou uma notificação de pagamento recebido mas nenhuma notificação de cobrança paga veio em seguida, o pagamento não foi vinculado por divergência de valores e precisa de tratamento manual.

## Retorno do cliente ao site da loja

Nas configurações do projeto, você pode definir duas URLs para as quais o cliente retorna da página de pagamento:

* **URL de sucesso (Successful URL)** — redirecionamento automático depois que a cobrança é paga
* **URL de falha (Unsuccessful URL)** — redirecionamento automático quando uma cobrança expirada ou cancelada é aberta

Cada URL é ativada separadamente. Se uma URL não estiver definida, o cliente permanece na página de pagamento e vê o status da cobrança.

O parâmetro `uid` — o identificador da cobrança para o cliente — é acrescentado à URL: `https://example.com/order/success?uid=AFhygKX21ecd`. A loja o usa para encontrar o pedido e mostrar ao cliente a sua própria página.

Chegar a essas URLs não confirma o pagamento — o cliente pode abrir o link manualmente. Entregue os pedidos com base no [webhook](./webhook-url/index.md) ou depois de [verificar o status da cobrança](./api/index.md) pela API.