Recursos · 47
Pagamentos incertos: recuperar o checkout sem pedidos duplicados
Conciliar atrasos de rede, devoluções do navegador, notificações e estado do negócio em vez de tratar qualquer sinal isolado como suficiente.
Atualizado · 4 min
O que este guia ajuda a alcançar
- Tentativa, pagamento e pedido separados.
- Lidar com devoluções atrasadas ou ausentes.
- Eliminar notificações e solicitações duplicadas.
- Explicar incertezas sem pedir aos usuários que paguem novamente.
Verificação rápida
- Qual fonte confirma o pagamento?
- Fechar o navegador altera o estado da operação?
- Um evento repetido prepara dois pedidos?
- As assinaturas de eventos são verificadas?
- Como o suporte encontra uma operação incerta?
Método passo a passo
- 1
Definir os estados.
Separar carrinho, tentativa, autorização, pagamento confirmado, pedido e reembolso. Escrever transições, fonte autorizada e ações permitidas. Seguir o provedor e os métodos de pagamento reais; nem todos os métodos confirmam imediatamente.
Entregável: diagrama de estados e contrato comercial.
- 2
Identificar a operação.
Conectar uma tentativa a um pedido e aos identificadores do provedor. Usar a regra de idempotência documentada para repetição da mesma operação. Uma nova finalidade ou parâmetros alterados exigem uma decisão explícita em vez da reutilização cega de chaves.
Entregável: identidade estável e regras de recuperação.
- 3
Lidar com o retorno do navegador.
Exibir o estado de uma verificação do lado do servidor apropriada para o provedor. Um redirecionamento para uma página de sucesso por si só não é prova de pagamento. Abranger navegador fechado, retorno ausente, autenticação interrompida e rede lenta.
Entregável: fluxo de retorno e mensagens por estado.
- 4
Verificar notificações
Verificar a autenticidade de acordo com a documentação do provedor, registrar a identidade do evento e lidar com repetições sem efeitos duplicados. Os eventos podem estar atrasados ou fora de ordem. Quando necessário, recuperar o objeto de referência antes de uma transição irreversível.
Entregável: manipulador testado e rastreamentos sem dados bancários.
- 5
Conciliar discrepâncias
Comparar operações, pedidos e cumprimento de obrigações do provedor. Isolar pagamentos sem pedido, pedidos sem confirmação, processamento duplo e reembolsos não propagados. Atribuir um responsável e um procedimento a cada discrepância; não repetir automaticamente uma cobrança incerta.
Entregável: fila de conciliação e decisões.
- 6
Testar recuperação completa
No modo de teste do provedor, reproduzir tempo limite, duplicado, evento atrasado, pedido invertido e devolução ausente. Verificar uma transição comercial, corrigir informações do cliente e visibilidade do suporte. Os detalhes de idempotência diferem entre os provedores.
Entregável: evidências de não duplicação e critérios de implantação.
Exemplo prático fictício
Situação ilustrativa
Situação ilustrativa: o pagamento é bem-sucedido, mas o cliente perde a conexão antes da confirmação e duas notificações chegam posteriormente.
Decisão e evidências esperadas
Um pedido é confirmado. A recuperação exibe o estado verificado e o suporte pode conciliar a referência sem solicitar dados bancários.
Distinguir os mecanismos
| Mecanismo | Finalidade | Verificação ou limitação |
|---|---|---|
| Retorno do navegador | Informar e retomar a interface | Pode estar ausente ou interrompido |
| Webhook verificado | Receber uma alteração de estado do provedor | Pode ser repetido, atrasado ou fora de ordem |
| Conciliação do servidor | Comparar o estado do pagamento e do pedido | Necessita de uma regra de resolução de discrepâncias |
Indicadores de gestão
| Indicador | O que mede | Primeira ação |
|---|---|---|
| Estados incertos | Operações não resolvidas dentro do atraso pretendido | Verificar o estado de referência |
| Efeitos duplicados | Pedidos ou processamentos realizados duas vezes | Corrigir a deduplicação de negócios |
| Lacunas fechadas | Casos reconciliados com decisão e evidências | Lidar com os casos mais antigos e críticos |
Erros comuns
- Confirmação apenas a partir de uma URL de sucesso
- Tratar o tempo limite como falha de pagamento
- Presumir que os eventos chegam em Pedido
- Repetir uma cobrança antes de verificar
Perguntas frequentes
Um tempo limite significa falha?
Não. Significa que a resposta não foi recebida dentro do prazo. Verifique o estado da operação antes de criar outra.
A idempotência do provedor é suficiente?
Não. A criação, o processamento e as notificações de pedidos também devem tolerar o processamento repetido sem efeitos comerciais duplicados.
O que deve ser dito ao usuário?
Explique que a verificação está em andamento, forneça uma referência segura e uma maneira de recuperar o status. Evite solicitar outro pagamento enquanto o anterior estiver incerto.
Que provas guardar para uma verificação útil?
Guardar identificadores não sensíveis, estados e prova de um único efeito. Associar novas tentativas ao contrato API, não apenas ao timeout.
Webhooks: assinaturas e reenvio
As notas detalhadas desta edição estão disponíveis em inglês.
A payment notification does not close reconciliation by itself
Authenticate each webhook, bind it to the right account and compare its effect with authorised server state. A repeated event must not repeat an initial activation; missing events must remain detectable.
- Separate notification identity from the operation to perform.
- Test overlapping manual resend and automatic retry.
- Retain uncertainty after an unknown external result and check the source before retrying.
See webhook signatures, digests and the ten cases →
Sources reviewed on · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries
Precisão dos montantes API e unidades exatas
As notas detalhadas desta edição estão disponíveis em inglês.
Separate exact conversion from payment confirmation
An interface can display the correct price while preparing an incorrect provider integer. Acceptance must reconcile the server amount with the operation contract, then check confirmed state without mistaking arithmetic for completed payment.
- Test zero-, two- and three-decimal currencies.
- Include a case where step cannot be inferred from decimals.
- Retain an exact reference before localised formatting.
Check a unit in the workshop →
Adyen · Currency codes and minor units · Provider documentation · reviewed 2026-11-06
Stripe · Supported currencies and special cases · Provider documentation · reviewed 2026-11-06
Referências oficiais
As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.
Referências consultadas em .
- Stripe — Payment status updates
- Stripe — Webhooks
- Stripe — Idempotent requests
- Stripe · Manage webhook endpoints
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- Adyen · Currency codes and minor units
- Stripe · Supported currencies and special cases
