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 ou depois de verificar o status da cobrança pela API.