Estados de pagamento acabam em chamados de suporte, exportações financeiras e e-mails para clientes. Se um estado não pode ser explicado em uma frase, ele será mal interpretado — geralmente no pior momento.
Uma única autoridade para as transições
Toda transição é decidida em um só lugar: a máquina de estados do gateway. Os workers em segundo plano nunca gravam um status diretamente. Eles registram evidências (uma observação, um novo topo da cadeia, uma expiração) e pedem à máquina de estados que reavalie. A máquina bloqueia a linha do pagamento, calcula o estado de destino a partir das evidências e aplica a transição somente se ela for permitida. Cada mudança grava um evento de estado e uma mensagem de outbox na mesma transação do banco de dados.
O caminho feliz
created → awaiting_payment → detected → confirming → confirmed
A maioria dos pagamentos só passa por esses cinco estados. Cada um tem uma descrição em linguagem simples que aparece no painel, no checkout e na documentação da API.
As exceções honestas
Os demais estados existem porque a realidade é bagunçada:
| Estado | Significado simples |
|---|---|
underpaid |
Chegou e foi confirmado menos do que o valor cotado. |
overpaid |
Chegou mais do que o cotado. O pedido pode ser entregue; o excedente exige uma decisão. |
expired |
A cotação expirou antes que qualquer coisa fosse observada. |
late_payment |
Algo chegou depois da expiração. Fica registrado, nunca é creditado silenciosamente. |
reorged |
Um bloco com este pagamento foi substituído. Não entregue até que ele seja confirmado de novo. |
manual_review |
Retido para uma decisão documentada. |
resolved |
Uma pessoa resolveu, com um motivo que fica registrado. |
failed / canceled |
Encerrado por um motivo validado, ou pelo lojista antes do pagamento. |
Nenhum significado só pela cor
Cada estado tem um rótulo, um ícone e uma frase de explicação, para que seja lido da mesma forma com ou sem cor, animação ou visão. O mesmo vocabulário é compartilhado por todas as interfaces do FeitPay, então um status significa a mesma coisa em todo lugar.