API de pagamento: gerir pedidos repetidos e respostas incertas

Identifique a intenção antes do pedido

Crie uma referência interna para a tentativa de pagar uma encomenda concreta. Associe-lhe montante, moeda e versão da encomenda. Um novo envio provocado por falta de resposta pertence à mesma intenção; uma alteração acordada do valor pode exigir outra tentativa. Esta distinção deve existir no servidor e não apenas no estado do botão do navegador.

Considere uma reserva de alojamento cujo preço foi confirmado. Se o cliente carregar duas vezes, a aplicação deve reconhecer a mesma ação. Se posteriormente acrescentar um serviço, a decisão sobre uma nova cobrança é diferente. Um identificador baseado apenas no cliente ou na data não descreve suficientemente estes casos e pode juntar operações que deveriam permanecer separadas.

Ferramentas de desenvolvimento

Verifique o contrato da API utilizada

Cada interface define a forma de criar operações, consultar estados e tratar repetições. A documentação PaymentIntents da Stripe descreve o seu próprio modelo de pagamento. Não copie nomes de campos ou pressupostos desse modelo para outra API sem verificar o respetivo contrato. A existência de um conector não garante que todas as funcionalidades sejam expostas da mesma maneira.

Quando utiliza OrsunPay, identifique a fronteira entre a aplicação, o software de orquestração e o prestador. Registe quem guarda cada identificador e qual a fonte autorizada para cada estado. As contas e contratos dos prestadores continuam a pertencer ao comerciante; a cobrança do software é separada. Uma arquitetura clara facilita a investigação de falhas em qualquer dessas fronteiras.

Webhooks de pagamento

Trate o tempo limite como incerteza

Uma recusa explícita e a ausência de resposta são resultados diferentes. Depois de um tempo limite, o prestador pode ter aceitado a operação. Consulte a tentativa existente ou utilize a repetição segura prevista pela interface antes de criar outra operação. Não transforme o desejo de dar uma resposta rápida numa segunda cobrança potencial.

Na interface, apresente uma mensagem que explique a verificação em curso e forneça uma referência. Defina uma rotina para casos que permanecem pendentes. O prazo de intervenção pertence ao seu processo operacional e não constitui uma garantia de processamento do fornecedor. A equipa deve saber onde consultar o estado e quem tem autorização para executar qualquer correção.

Faça os eventos convergirem no mesmo registo

Uma confirmação por webhook pode chegar antes ou depois da resposta síncrona. Ambos os caminhos devem atualizar a mesma tentativa com regras de transição coerentes. Verifique a autenticidade do evento, a conta, o montante e a moeda. Uma mensagem repetida não pode voltar a executar a encomenda nem reverter um resultado definitivo sem fundamento.

A documentação Stripe sobre webhooks explica a receção de eventos do prestador. Os eventos da OrsunPay têm o seu próprio protocolo, incluindo assinatura HMAC; não são intercambiáveis com os da Stripe. Se receber diretamente de várias origens, mantenha configurações separadas e aplique a verificação correta a cada uma. Uma aparência semelhante do conteúdo não prova a identidade da origem.

Teste concorrência e recuperação

Os testes devem incluir dois pedidos simultâneos para a mesma intenção. Proteja a criação e as alterações críticas no armazenamento, para que processos paralelos não decidam ambos que ainda não existe operação. A escolha técnica depende da arquitetura, mas o resultado esperado é sempre uma ação comercial coerente e uma história que possa ser consultada.

• Repita um pedido sem alterar a intenção nem os parâmetros.
• Simule uma resposta perdida após a aceitação externa.
• Receba o webhook antes da resposta ao pedido inicial.
• Recupere a entrega de um serviço sem repetir o pagamento.

Mantenha uma pista operacional útil

Guarde as ligações entre encomenda, tentativa interna e referência do prestador. Evite eliminar tentativas falhadas apenas para simplificar o ecrã; elas ajudam a explicar a sequência ao apoio ao cliente. Os registos devem conter dados suficientes para investigação, sem segredos de autenticação ou informação de cartão desnecessária.

Reveja regularmente operações de estado desconhecido e documente qualquer intervenção. Não presuma cascata automática entre prestadores ou encaminhamento por custo na OrsunPay atual. Primeiro assegure um comportamento previsível numa integração, depois avalie a expansão. A qualidade de uma API em produção mede-se também pela capacidade de recuperar uma falha sem criar uma nova ambiguidade financeira.

Fontes

• Stripe — Objetos PaymentIntent
• Stripe — Notificações webhook