Integrar gateway de pagamento é uma daquelas tarefas que parecem simples na documentação e revelam sua complexidade real assim que um pagamento falha, atrasa ou é estornado. Depois de várias integrações, aprendi que o código do "pagamento aprovado" é o mais fácil de escrever — e o menos importante.
O que realmente exige cuidado
Webhooks que chegam fora de ordem, pagamentos duplicados por retry do gateway, estados intermediários (pendente, em análise, estornado parcialmente) — é aí que a maioria das integrações mal feitas quebra. Trato cada notificação de pagamento como um evento idempotente: processar a mesma notificação duas vezes não pode gerar dois cobranças ou duas liberações de acesso.
Um caso real: um gateway pode reenviar o mesmo webhook de confirmação várias vezes até receber uma resposta HTTP de sucesso — se a minha aplicação não verificar se aquele pagamento já foi processado antes de liberar o acesso, um único pagamento pode gerar liberações duplicadas ou notificações repetidas ao cliente. A solução é simples: guardar o identificador único da transação e verificar, antes de processar, se ele já foi visto.
Como isolo essa complexidade
Uso a mesma lógica da Arquitetura Hexagonal aqui: a regra de negócio ("liberar acesso quando o pagamento for confirmado") não conhece detalhe de qual gateway está por trás. Um adaptador traduz o webhook específico do provedor para um evento genérico de domínio. Trocar de gateway, quando precisa acontecer, vira um problema de adaptador — não de reescrever regra de negócio, o mesmo princípio que detalhei em Arquitetura Hexagonal na prática.
Processamento assíncrono como padrão
Nunca processo webhook de pagamento de forma síncrona na própria requisição que o gateway envia. Recebo o evento, valido a assinatura, e jogo o processamento real para uma fila — a mesma disciplina que aplico para qualquer tarefa que não precisa travar uma resposta, como descrevo em Jobs e Queues. Isso evita timeout do lado do gateway e me dá espaço para reprocessar em caso de falha.
