Por que pagamentos com stablecoins precisam de confirmações e validade
Uma transação aparecer na blockchain não significa que o pedido comercial deva ser finalizado imediatamente. O gateway ainda precisa tratar confirmações, validade, notificações repetidas e transferências enviadas depois do checkout expirar.
Confirmações controlam a certeza on-chain
Quando um nó observa uma transação pela primeira vez, ela normalmente ainda está pendente. Aguardar uma profundidade adequada reduz riscos de bifurcações temporárias, diferenças entre nós ou mudança de estado. A quantidade deve considerar rede, valor e velocidade de entrega.
A validade controla a consistência comercial
O prazo limita a janela de uma cotação, reserva ou recarga, mas não impede uma transferência na rede. Se o cliente pagar depois, o sistema deve detectar o movimento e encaminhá-lo para pagamento atrasado ou exceção.
Separe claramente os estados
- `pending`: pedido criado sem transferência válida
- `confirming`: transferência detectada aguardando confirmações
- `paid`: valor e confirmações atendidos
- `expired`: prazo encerrado antes da detecção do pagamento
- `exception`: valor, moeda, rede ou horário precisam de revisão
Callbacks devem ser idempotentes
Retentativas podem entregar o mesmo evento mais de uma vez. O comerciante deve deduplicar por pedido e evento; o gateway deve guardar resultados, tentativas e última resposta para impedir créditos duplicados.
Padrão de implementação mais seguro
Fixe moeda, rede, valor e validade ao criar o pedido. Registre o hash assim que detectar a transferência e marque como pago somente após as confirmações. Pagamentos menores, maiores, na moeda errada ou atrasados devem seguir uma revisão independente.