Testes de gateway de pagamento: guia prático para desenvolvedores

Pagamentos com cartão são a única parte da sua aplicação em que um bug custa dinheiro de verdade. Testar no sandbox de um gateway de pagamento é a única forma segura de exercitar recusas, 3D Secure, reembolsos e webhooks — e fazer isso bem depende mais de disciplina do que de ferramentas.

Este guia cobre o fluxo de trabalho que funciona para a Stripe, a Adyen, a Braintree e a maioria dos outros gateways, além dos modos de falha que pegam as equipes de surpresa.

1. Separe as credenciais de teste e de produção

Cada gateway oferece um universo paralelo: chaves de API de teste, endpoints de teste e números de cartão de teste. Mantenha-os separados em todas as camadas:

• Arquivos .env e cofres de segredos diferentes, nunca uma única variável STRIPE_KEY.
• Uma falha imediata na inicialização se uma chave de teste chegar à produção ou se uma chave de produção for usada na CI.
• Um banner visível no staging para que ninguém duvide de qual ambiente está vendo.

A causa mais comum de "cobramos um cliente real em teste" é um merge de configuração que promoveu uma chave de produção sem ninguém perceber.

2. Use primeiro os cartões de teste do próprio gateway

Os números de teste do provedor estão ligados a comportamentos específicos que nenhum número gerado consegue reproduzir. A Stripe, por exemplo, associa cada número a um código de recusa:

A nossa referência de números de cartão de teste reúne os números oficiais da Stripe, da Adyen e da Braintree em uma única tabela. Use esses números para o comportamento do gateway e use o gerador de cartões quando precisar de números para um BIN, uma bandeira ou um volume específicos.

3. Teste as recusas como estados de primeira classe

Um pagamento recusado é um resultado normal, não um erro. Seu código deve ramificar pelo motivo da recusa, não apenas por "falhou":

• Recusas suaves (soft decline), como saldo insuficiente, devem oferecer uma nova tentativa.
• Recusas duras (hard decline), como cartão roubado ou conta inválida, não devem ser repetidas automaticamente.
• Falhas de autenticação devem retornar ao fluxo de 3D Secure.
• Erros de processamento devem ser repetidos com backoff.

Registre o código de erro do gateway, não apenas a mensagem, e guarde a resposta bruta para os tickets de suporte.

4. Simule o 3D Secure

Redirecionamentos, iframes e fluxos de desafio do 3DS são onde mora a maioria dos bugs de checkout. Teste pelo menos:

• Autenticação sem atrito (sem interação do usuário).
• O fluxo de desafio, incluindo um desafio que falhou e um cancelado.
• O botão voltar do navegador depois do redirecionamento.
• Navegadores internos de apps mobile.

A Stripe publica cartões de teste específicos para cada fluxo — veja o guia de testes de 3D Secure para a lista e o que cada cartão dispara.

5. Verifique webhooks, idempotência e ordenação

A resposta síncrona da API é só metade da história. O estado do dinheiro geralmente é definido por webhooks, então teste esse caminho com o mesmo cuidado que o checkout:

• Reenvie o mesmo evento de webhook duas vezes e verifique a idempotência. A maioria dos gateways tenta de novo quando a resposta não é 2xx, e eventos duplicados são garantidos em produção.
• Teste eventos fora de ordem (por exemplo, um reembolso que chega antes da captura).
• Valide as assinaturas dos webhooks e rejeite requisições sem assinatura.
• Faça os handlers serem rápidos: confirme o recebimento em poucos segundos e processe de forma assíncrona.
• As ferramentas de CLI stripe listen --forward-to e stripe trigger da Stripe facilitam o reenvio local; a Adyen e a Braintree oferecem simuladores de notificação equivalentes.

6. Coloque o sandbox na CI

Faça um smoke test do fluxo de pagamento a cada deploy, não apenas manualmente:

1. Crie um pagamento de teste com um cartão de sucesso.
2. Verifique o estado no banco de dados, o lançamento no razão e a notificação por e-mail.
3. Crie um pagamento recusado e verifique o erro exibido ao usuário.
4. Dispare o webhook do gateway e verifique a transição de estado.
5. Faça um reembolso e verifique o estorno.

Mantenha esses testes apenas no sandbox e marque-os para que rodem separadamente dos testes unitários rápidos.

7. Checklist de armadilhas comuns

• Misturar chaves de teste e de produção entre serviços (um clássico em arquiteturas de microsserviços).
• Fixar datas de validade no passado — use uma data bem no futuro para que os testes de "cartão vencido" sejam intencionais.
• Testar apenas o caminho feliz e esquecer o cancelamento do 3DS.
• Ignorar a verificação de assinatura dos webhooks porque "funciona localmente".
• Criar lógica de retentativa que repete recusas duras.
• Não testar moedas sem decimais, arredondamento e unidades de amount.
• Assumir que uma autorização bem-sucedida significa que o dinheiro foi liquidado — a captura ainda pode falhar depois.

Próximos passos

• Pegue os números oficiais da lista de números de cartão de teste.
• Gere dados de teste para qualquer BIN com o gerador de cartões ou enumere padrões com o gerador avançado.
• Valide números na sua suíte de testes com o guia do validador de Luhn.

Testar pagamentos não é glamouroso, mas é um dos hábitos com maior retorno para uma equipe: algumas horas no sandbox evitam com frequência incidentes que custam muito mais do que o tempo de engenharia.