root@construct:~/logs/construindo-sistemas-de-pagamento-que-nao-perdem-dinheiro$
<-- voltar para /logs
2026-01-16//LOG

Construindo Sistemas de Pagamento Que Não Perdem Dinheiro

Quando liderei pagamentos num POS de restaurante, construí a infra de processamento de pagamento. Quando algo dá errado em pagamento, alguém perde dinheiro de verdade. Estas são as lições que aprendi em produção.

Todo pagamento precisa de chave de idempotência

Toda operação de pagamento precisa de chave de idempotência, mesmo que tu ache que teu sistema nunca vai retentar um request. A rede soluça, o cliente dá double tap, o load balancer dá timeout e tenta de novo. Sem idempotência no endpoint, tu vai processar cobrança duplicada.

A gente usava chave composta: ID do merchant + UUID gerado pelo client + tipo de operação. Ela era gravada antes de falar com o processador de pagamento. Se a gente via a mesma chave duas vezes, retornava o resultado cacheado da primeira tentativa. Isso evitava uma segunda cobrança.

Race condition vai te achar

Duas requests concorrentes conseguiam ler o mesmo saldo, verificar fundos suficientes e debitar. O merchant gastava mais do que tinha.

Resolvemos com locking pessimista no check de saldo: SELECT FOR UPDATE na row da conta, verifica fundos, debita, commit. Isso serializa pagamento concorrente pra mesma conta e fica um pouco mais lento. Eu aceito esse custo; em sistema de pagamento, corretude ganha de performance toda vez.

Mas esse era o race condition fácil. O difícil foi com transação concorrente no terminal de cartão. Dois POS, mesmo merchant, os dois batendo no processador ao mesmo tempo. O processador retornava sucesso pros dois, mas nosso webhook handler processava fora de ordem e a segunda transação sobrescrevia o status da primeira. A gente perdeu visibilidade de pagamento concluído.

Pra isso passamos a usar event sourcing nas mudanças de estado da transação. Cada atualização de status virou um evento append-only, e o estado atual era derivado do log na ordem do timestamp do processador, então um webhook atrasado não sobrescrevia mais um status mais novo. Nada era sobrescrito, e a trilha de auditoria ficava completa.

Transações duplicadas

Causa: a gente tinha mecanismo de retry de webhook. Quando o processador mandava confirmação de pagamento e a gente não confirmava (HTTP 200), eles retentavam. Normal. Só que nosso handler não checava se a transação já tinha sido registrada. Então cada retry criava um novo registro de transação no nosso sistema, e qualquer janela em que o endpoint deixava de confirmar, inclusive um deploy, transformava os retries enfileirados em lançamentos duplicados.

Detecção: os alertas de reconciliação de saldo pegaram. Revertemos manualmente cada duplicata, avisamos os merchants afetados e explicamos o que aconteceu.

O que mudou: antes de criar entrada nova, o handler passou a checar o ID de transação do processador contra nossos registros. Se já existia, confirmava e pulava. O fix foi pequeno, e dali em diante os webhook handlers eram testados com entrega duplicada antes de chegar em produção.

Reconciliação pega o que passou

Toda noite, rodávamos um job de reconciliação. Ele puxava as transações das últimas 24 horas no nosso sistema e no processador, comparava as duas listas e disparava alerta pra qualquer divergência.

Isso pegou bug que mais nada ia achar. Falha silenciosa onde a gente registrou pagamento mas o processador na real recusou. Edge case onde reembolso parcial se perdeu. Bug de timezone onde transação aparecia em dia diferente no nosso sistema e no processador.

Quase ninguém escreve sobre reconciliação, mas pra mim ela é a peça mais importante da infra de um sistema de pagamento. Builda antes de processar tua primeira transação real.

Recalcule o valor no servidor

O terminal POS mandava o valor a cobrar. A gente não confiava nele e recalculava no servidor a partir dos itens do pedido.

Cálculo de valor server-side a partir da fonte de verdade (o pedido no banco) é inegociável. Valor do terminal é só pra exibição.

Os algoritmos de um sistema de pagamento são diretos. A dificuldade é que cada edge case custa dinheiro de verdade. Numa plataforma de blog, uma race condition gera post duplicado. Num sistema de pagamento, alguém perde dinheiro. Isso muda como tu pensa sobre cada linha.

Pelo amor de Deus, testa teus webhook handlers com entrega duplicada antes de ir pra produção.

Construindo Sistemas de Pagamento Que Não Perdem Dinheiro | The Broad Way