10/05/2026 · Equipe GálagoTEF
API de pagamento: o que avaliar antes de integrar
Escolher uma API de pagamento é uma decisão que você carrega por anos: migrar depois custa caro. Antes de escrever a primeira linha de integração, vale avaliar critérios técnicos que separam uma API sólida de uma que vai gerar suporte, retrabalho e, no pior caso, venda duplicada. Este é o checklist que usamos.
Documentação e ambiente de testes
Uma boa API começa por uma boa documentação. Avalie se ela é clara, com exemplos de requisição e resposta, códigos de erro descritos e o ciclo de vida da transação bem explicado. Igualmente importante é existir um ambiente de homologação (sandbox) onde você testa sem mover dinheiro real. Integrar direto em produção é receita para acidente. Veja como conduzir esses testes em testar uma integração de TEF em homologação.
Idempotência: o item inegociável
Redes falham. Se seu sistema envia uma cobrança, sofre um timeout e reenvia, a API precisa reconhecer que é a mesma cobrança e não criar uma segunda. Isso se chama idempotência e costuma ser implementado com uma chave única (idempotency key) por transação. Sem isso, você corre risco real de cobrar o cliente duas vezes. É tão central que dedicamos um artigo inteiro a idempotência em pagamentos.
Modelo de status e confirmação
Pagamento é assíncrono: entre “criei a cobrança” e “o dinheiro entrou” existem estados intermediários. Avalie:
- Quais status a API expõe e se eles são claros (pendente, confirmada, negada, cancelada, estornada).
- Se há webhook para ser avisado quando o status muda.
- Se há polling (consulta de status) como alternativa ou complemento.
- Qual o comportamento em caso de timeout no meio da transação.
O ideal é suportar webhook e polling juntos. Aprofundamos em webhooks de pagamento: como usar para confirmar vendas.
Estorno, cancelamento e reversão
Toda venda pode precisar ser desfeita. Verifique se a API oferece caminhos claros para cancelar uma transação ainda não liquidada e para estornar uma já concluída, e se esses caminhos também são idempotentes. Uma API que só sabe cobrar, mas não sabe reverter, vai te obrigar a gambiarras.
Segurança e conformidade
Pagamento lida com dados sensíveis e dinheiro, então segurança não é opcional:
- Autenticação forte: tokens de API (Bearer/JWT), rotação de chaves e escopo por consumidor.
- HTTPS obrigatório em todas as chamadas.
- Webhooks assinados: assinatura por segredo compartilhado para você validar que a notificação é legítima.
- Conformidade PCI e LGPD: a plataforma deve tratar dados de cartão e dados pessoais dentro das normas.
Isolamento e multiempresa
Se você vai atender vários lojistas com a mesma integração, a API precisa isolar dados por empresa (tenant). Cada consumidor deve enxergar apenas suas transações, com token próprio e sem risco de vazamento entre contas. Isso é especialmente crítico em pagamento, onde um cruzamento indevido é incidente grave.
Flexibilidade de administradoras
Pergunte-se: e se eu precisar de outra administradora de TEF amanhã? Uma API amarrada a um único provedor te obriga a reintegrar do zero. Um hub de TEF expõe um contrato neutro e traduz para cada administradora por baixo, então adicionar uma nova é problema da plataforma, não seu. Entenda o modelo em por que usar um hub de TEF em vez de integrar direto.
Checklist rápido
- Documentação clara e sandbox disponível
- Idempotência por chave única
- Status bem definidos, com webhook e polling
- Estorno e cancelamento idempotentes
- Autenticação forte, HTTPS e webhooks assinados
- Conformidade PCI e LGPD
- Isolamento por empresa
- Suporte a mais de uma administradora
Decida com critério, integre uma vez
A melhor API não é a que tem mais recursos na página de marketing, e sim a que trata os casos difíceis (timeout, reenvio, reversão) com clareza. Avaliar esses pontos antes economiza meses de suporte depois.
O GálagoTEF foi desenhado com idempotência, webhooks assinados e isolamento por empresa como requisitos de dia um. Consulte a documentação da API e comece sua integração em app.galagotef.com.br.