Um produto, um cliente, um pagamento bem-sucedido. A demonstração termina com um visto verde. Em produção aparecem um segundo clique, uma conexão interrompida e uma notificação de pagamento que chega depois de o navegador fechar. O visto verde precisa de um ensaio mais exigente.
Um checkout coordena vários sistemas. O navegador, o banco de dados da loja, o provedor de pagamentos e o serviço de inventário podem discordar temporariamente. Prepare essa divergência em vez de assumir que cado pedido termina uma vez, pela ordem certa e enquanto o cliente está olhando.
Separe o pagamento da página de agradecimento
O regresso do navegador a uma página de sucesso não prova, por si só, que o pedido deva ser enviado. Use o processo de confirmação no servidor documentado pelo provedor de pagamentos e confirme o estado relevante, o valor, a moeda e a associação à pedido.
Separe os conceitos de pedido, tentativa de pagamento, reserva e envio. Um pagamento pode ser concluído enquanto a envio está atrasada. Uma tentativa falhada não significa necessariamente que o cliente desistiu. Um único campo booleano chamado “sucesso” tem dificuldade em representar estas situações.
Uma nova tentativa não pode tornar-se outra compra
Imagine que o cliente clica em Pagar, o pedido é concluído, mas a resposta nunca chega ao navegador. Clicar novamente pode ser uma reação perfeitamente razoável. O sistema precisa de distinguir a continuação da mesma operação de uma operação diferente.
A Stripe documenta chaves de idempotência para repetir pedidos compatíveis com segurança. Use um identificador estável para a mesma operação pretendida e respeite as regras do provedor sobre parâmetros e retenção. Isso não torna automaticamente idempotentes as escritas no seu banco de dados, os emails ou os movimentos de estoque.
Defina um identificador local da operação e imponha a unicidade necessária. A marcação de uma notificação como processada e a aplicação do seu efeito devem ser coordenadas: uma falha não pode deixar a alteração feita e o evento pronto para voltar a executá-la.
As notificações podem chegar tarde, repetidas ou fora de ordem
A documentação de webhooks da Stripe descreve entregas duplicadas e não garante a ordem dos eventos. Verifique as assinaturas pelo método documentado, preserve o corpo original do pedido quando exigido e consulte o estado autoritativo quando necessário. A ordem de chegada não é necessariamente a história do negócio.
Um exemplo: chega uma notificação antiga depois de um reembolso já ter sido registrado. Definir cegamente o pedido como “pago” pode substituir um estado mais recente. O processamento precisa de transições válidas e de uma estratégia de reconciliação, não apenas de confiar na última mensagem recebida.
Confirme rapidamente a receção após guardar a notificação de forma confiável e encaminhe o trabalho demorado para um processo adequado em segundo plano. Monitore falhas e repetições. Uma fila que ninguém acompanha transforma um erro recuperável numa acumulação invisível.
O estoque e os reembolsos merecem testes próprios
Teste dois clientes disputando a última unidade. Decida o que acontece quando uma reserva expira antes da confirmação do pagamento. Defina como a operação resolve um pagamento bem-sucedido quando não consegue fornecer o artigo. Não invente inventário nem deixe uma cobrança sem explicação.
Os reembolsos também são operações. Distinga o pedido de reembolso do resultado confirmado e considere reembolsos parciais, repetições e mensagens de falha. Devolver dinheiro não significa automaticamente que um artigo físico esteja pronto para voltar à venda; a inspeção e a política de inventário podem exigir outros passos.
Um ensaio que vale a pena fazer
- Clique duas vezes em Pagar e repita o mesmo pedido após simular um timeout.
- Feche o navegador antes de chegar a confirmação no servidor.
- Entregue o mesmo webhook de teste duas vezes e envie eventos relevantes fora de ordem.
- Interrompa o processamento entre o registro de um evento e a aplicação do seu efeito.
- Faça expirar a última reserva de estoque antes de uma confirmação de pagamento tardia.
- Peça um reembolso parcial, repita o pedido e simule uma falha do provedor.
- Desative temporariamente uma integração, restaure-a e reconcilie o trabalho em falta.
Use credenciais de teste e dados sintéticos. Para cada caso, registre a mensagem esperada para o cliente, o estado do pagamento, o movimento de inventário e a ação do operador. “Não há exceções nos logs” não serve como critério de aceitação se o cliente pagou duas vezes.
Desenhe também o tela de recuperação
Dê ao suporte rastreabilidade suficiente para relacionar o pedido com as tentativas de pagamento e as notificações, sem expor dados sensíveis desnecessários. Disponibilize ações controladas de repetição ou reconciliação, com histórico de auditoria. Editar diretamente o banco de dados não deve ser o procedimento habitual do checkout.
Um checkout confiável não é aquele onde nunca acontece uma falha. É aquele onde a falha não duplica silenciosamente uma cobrança, perde umo pedido ou deixa o cliente sem entender.
Fontes
Stripe: processamento de webhooks; Stripe: pedidos idempotentes. Consultadas em 17 de outubro de 2026. A Stripe é um exemplo de implementação; outros provedores têm os seus próprios contratos. Os cenários são testes propostos, não resultados de experiências com pagamentos em produção.