O contexto
Em uma plataforma de checkout, cada requisição carrega dinheiro. Isso muda completamente o cálculo de engenharia: um sistema comum pode tolerar um erro ocasional e reprocessar depois. Um sistema de pagamento não pode cobrar duas vezes, não pode perder uma confirmação e não pode ficar fora do ar no pico de venda do cliente.
O trabalho foi contribuir com a arquitetura de backend dessa plataforma — construindo e mantendo as APIs REST de processamento de transações e as integrações com merchants e gateways de pagamento externos.
O desafio técnico
Três problemas dominam qualquer plataforma de pagamento:
Falha parcial de terceiros. O gateway responde em 30 segundos, ou não responde. A transação foi criada do lado dele ou não? Sem uma resposta confiável, a plataforma precisa decidir entre arriscar cobrar duas vezes ou arriscar não cobrar.
Eventos duplicados e fora de ordem. Webhooks de gateway não garantem entrega única nem ordenação. O evento de captura pode chegar antes do evento de autorização.
Rastreabilidade obrigatória. Quando o merchant abre um chamado sobre uma transação específica, a resposta precisa vir em minutos e com histórico completo — não depois de alguém vasculhar log bruto.
O que foi feito
Idempotência como requisito de arquitetura. Toda operação com efeito financeiro aceita chave de idempotência. Um retry do gateway ou do merchant devolve o resultado original em vez de executar novamente. Isso transforma retry — que é inevitável — de risco em mecanismo de segurança.
Separação entre recepção e processamento. Webhooks são validados, persistidos e respondidos imediatamente. O processamento acontece em worker separado, com retry controlado e fila para os eventos que falharam de forma definitiva. O gateway nunca fica esperando a regra de negócio rodar.
Máquina de estados explícita da transação. Cada transição de status é validada contra o estado atual. Um evento fora de ordem não corrompe o registro — ele é reconhecido, registrado e tratado conforme a transição permitida.
Log estruturado com identificador de correlação. Cada transação carrega um identificador que atravessa toda a cadeia, incluindo as chamadas ao gateway externo. Consultar o histórico completo de uma transação passou a ser uma busca, não uma investigação.
O aprendizado que levamos para outros projetos
Sistemas financeiros ensinam a projetar para a falha em vez de para o sucesso. Essa postura — perguntar primeiro “o que acontece quando isso der errado?” — é aplicada hoje em todas as integrações que construímos, mesmo quando não há dinheiro envolvido.