O que costuma dar errado depois de dois anos rodando
A maioria dos probleminhas com sistema monetario 2 ano vem de uma coisa que ninguém te avisa na implantação: os microajustes no gateway de pagamento vão se acumulando e a API que você integrou em 2023 começa a retornar códigos de erro que não existiam no manual. Não é bug. É o provedor mudando o schema de resposta sem avisar direito, só solta uma nota de release de três linhas e pronto. Se você não roda um health check automático a cada 72 horas, você fica descobrindo por cliente que reclama no WhatsApp.
Na prática, como isso se manifesta no dia a dia
Em meu caso específico, o que acontecia era mais insidioso do que parece. O sistema de checkout continuava processando, sim, mas a reconciliação diária entre o relatório do gateway e o extrato do banco começava a divergir em transações de R$ 0,01 a R$ 0,03. Anota: não era falha de pagamento. Era o arredondamento que o gateway fazia em frações de centavo que, multiplicado por 4.000 a 6.000 transações mensais, virava uma diferença de R$ 80 a R$ 140 no fechamento. Levei uns quatro meses pra perceber que o problema não era no banco nem no meu código, era no formato do XML de conciliação que o gateway trocou no mês 14 de operação. A workaround que usei, que ainda está no ar, foi parar de confiar no relatório deles e construir uma segunda conciliação cruzando o webhook de "payment.succeeded" com o SFTP bancário. Tomou umas 12 horas de trabalho num fim de semana, mas cortou a tarefa de revisão manual de cerca de 90 minutos por semana pra uns 10, porque agora só preciso olhar os itens que não casaram.
👉 Clique no botão abaixo para saber mais sobre o assunto!
O ponto cego que quase todo mundo ignora
Se o seu sistema monetário tem menos de dois anos de vida, o problema real não é técnico, é de documentação. Você integra, funciona, e nunca mais toca naquele código. Então quando a operadora muda um campo de "status" pra "state", ou troca o timezone do relatório de UTC-3 pra UTC-0, o break é silencioso. A transação passa, o dinheiro vai, mas o campo de referência que você usa pra matchear com o ERP vem vazio por três semanas até alguém notar que o relatório de vendas do mês tá com 8% das linhas sem link pro produto. Um detalhe que pega muita gente: a regra de idempotência do gateway. Se você não está mandando um ID único de requisição em cada tentativa de charge, a gente já viu caso de duplicidade que só apareceu quando o cliente reiniciou o celular no meio do redirect. Não foi o gateway que cobrou duas vezes. Foi o seu backend que, por não ter implementado a chave de idempotência de forma idempotente (sim, existe esse termo), processou a mesma order_id duas vezes porque a sessão HTTP caiu e ele reenviou. A checagem de duplicidade que eu faço agora é por (order_id + timestamp do webhook com tolerância de 5s). Antes era só order_id, e era insuficiente.
Quando vale a pena trocar e quando não vale
Se os seus probleminhas com sistema monetario 2 ano são só de manutenção passiva — atualizar SDK, ler changelog, ajustar o parser de XML —, não troque. O custo de re-onboarding numa operadora nova, refazer a compliance da PCI-DSS no seu lado, migrar o histórico de reconciliação de 24 meses, toma de 3 a 5 semanas de trabalho dedicado, independente de tamanho da equipe. Não compensa por causa de uma divergência de centavos. On complica de verdade e talvez valha a migração: quando o gateway passa a cobrar uma taxa por tentativa de charge recusada (e não só pela aprovada). Aí a economia de 2-3 meses paga a migração inteira. Eu mudei nesses termos pro Adyen porque a operadora anterior tinha aplicado isso em janeiro do segundo ano e meu volume de recusas ia de 4% pra 7% numa mudança de sazonalidade. A conta fechou em oito meses.
O que ninguém fala sobre o suporte
O suporte técnico desses gateways, na prática, resolve em dois níveis: tickets de "não processa nada" e tickets de "processa mas não reconcilia". O segundo tipo é onde o problema mora e onde a fila espera de 72 a 96 horas vira rotina. Não é que eles sejam incompetentes. É que o time que atende integração e o time que atende operação bancária são separados e a transição entre um e outro perde contexto. O que faz diferença é chegar no ticket com o ID exato da transação, o snapshot do webhook em JSON, e o print do extrato bancário no mesmo dia. Sem isso, eles mandam o formulário genérico e você perde uma semana. Se o volume for acima de uns 20 mil transações mensais, considere ter um engineer dedicado 20% do tempo só pra monitorar os webhooks e os logs de erro do parser. Menos que isso, o custo fixo não se justifica e um script cron que roda a cada 6 horas comparando contagens de eventos chega a ser suficiente pra detectar qualquer drift antes de virar prejuízo real no fechamento contábil.
