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

Laboratório de análise fictício vazio: três blocos de latão, mostrador vazio, folhas e pasta bordô Ilustração editorial gerada com IA

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. 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. 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. 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. 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. 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. 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

MecanismoFinalidadeVerificação ou limitação
Retorno do navegadorInformar e retomar a interfacePode estar ausente ou interrompido
Webhook verificadoReceber uma alteração de estado do provedorPode ser repetido, atrasado ou fora de ordem
Conciliação do servidorComparar o estado do pagamento e do pedidoNecessita de uma regra de resolução de discrepâncias

Indicadores de gestão

IndicadorO que medePrimeira ação
Estados incertosOperações não resolvidas dentro do atraso pretendidoVerificar o estado de referência
Efeitos duplicadosPedidos ou processamentos realizados duas vezesCorrigir a deduplicação de negócios
Lacunas fechadasCasos reconciliados com decisão e evidênciasLidar 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 .