Gateway Fallback — Pagar.Me
Sistema de fallback automático de pagamento que eliminou 100% da perda de vendas por indisponibilidade de gateway, orquestrando 3 projetos em stacks distintas.
Contexto
O fluxo de pagamento por cartão de crédito de uma plataforma EAD dependia exclusivamente de um único gateway. Quando esse provedor ficava indisponível — timeout, manutenção, erro de rede — o aluno simplesmente não conseguia pagar. A venda era perdida.
Para uma operação que processa centenas de transações diárias, cada minuto de indisponibilidade significava receita perdida e alunos frustrados.
Desafio
A solução precisava atravessar 3 projetos independentes, cada um com sua stack e domínio — do frontend até a integração bancária:
Interface do aluno — captura os dados do cartão com segurança e coordena a experiência de pagamento.
Cérebro da operação — decide quando acionar o fallback, confirma pagamentos e atualiza os sistemas internos (ERP, SAP).
Comunicação direta com o Pagar.Me — emite cobranças, recebe confirmações e garante que nenhuma transação seja duplicada.
Desafio técnico: Transformar um fluxo que dependia de um único provedor em um sistema resiliente com alternativa automática, sem que o aluno perceba qualquer mudança na experiência de pagamento.
Solução
O sistema detecta automaticamente quando o gateway primário está indisponível e redireciona a cobrança para um provedor alternativo — sem que o aluno perceba fricção.
Quando o caminho principal falha, o sistema automaticamente tokeniza o cartão via um provedor secundário e processa a cobrança de forma assíncrona — o aluno vê apenas "pagamento em processamento" e recebe a confirmação por e-mail.
Resultado
Impacto de Negócio
A implementação completa — do planejamento ao deploy — foi executada em 1 semana:
Planejamento estratégico
Blueprint técnico + decisões arquiteturais para os 3 projetos
Implementação
Estrutura funcional nas 3 stacks (NestJS, C#, PHP)
Testes e validação
Fluxo completo end-to-end, edge cases e deploy
- Zero perda de venda por indisponibilidade de gateway — fallback automático e transparente
- Menos de 3 segundos de latência adicional no caminho de fallback
- 3 projetos orquestrados em stacks completamente diferentes, entregues por um único desenvolvedor
- Código preparado para escalar — Boleto e PIX já implementados, prontos para ativação futura
Implementação Técnica
Camada 1 — API Billing (NestJS):
Módulo completo implementando a interface IFinancialInstitution com emissão, consulta, cancelamento e estorno. Webhook protegido por HMAC-SHA1. Idempotência garantida via code + idempotency-key no header.
Camada 2 — API Financeiro (C#): Use case dedicado que monta o payload tokenizado e delega ao Billing. O processamento assíncrono do webhook atualiza o status no AVA, baixa débitos (com retry de até 3 tentativas) e dispara integração SAP.
Camada 3 — EAD Frontend (PHP + JS): Tokenização sob demanda via SDK Pagar.Me — o cartão nunca trafega pelo servidor. Dados da negociação persistidos na sessão entre os dois requests. Detecção automática de bandeira pelo BIN.
- PCI Compliance — Tokenização exclusivamente no browser, apenas o hash criptografado trafega server-side
- Idempotência — Chave única por transação, prevenindo cobranças duplicadas
- Fallback inteligente — Classifica erros de infraestrutura (timeout, 5xx) vs. recusa de cartão
- Observabilidade — Tracing distribuído em todos os métodos públicos e privados
- Validação robusta — Validação em ambas as camadas com sanitização de documentos