09/06/2026 · Equipe GálagoTEF
Erros comuns ao integrar pagamento e como evitar
Integrar pagamento parece simples quando tudo dá certo: envia o valor, recebe “aprovado”, pronto. Os problemas aparecem nas bordas — timeout, rede caindo, evento repetido, credencial vazando. Este artigo reúne os erros mais comuns ao integrar pagamento e TEF no PDV, e como evitar cada um antes que virem prejuízo.
1. Não tratar timeout como venda em aberto
O erro mais caro. Quando seu sistema envia a cobrança e não recebe resposta a tempo, a transação pode ter sido aprovada mesmo assim. Tratar isso como “falhou, tenta de novo” gera cobrança dupla no cliente.
Como evitar: trate timeout como estado indeterminado. Antes de reenviar, consulte o status daquela transação. Se já foi aprovada, use o resultado existente. Nunca assuma que ausência de resposta significa que nada aconteceu.
2. Ignorar idempotência
Ligado ao anterior: o operador aperta duas vezes, a rede oscila, o app reenvia. Sem controle, cada envio vira uma venda.
Como evitar: envie uma chave de idempotência única por venda. O hub retorna o resultado da transação original em vez de criar outra. Esse é o mecanismo que separa uma integração amadora de uma pronta para dinheiro real — aprofunde em idempotência em pagamentos.
3. Confiar só no “OK” da tela e não persistir NSU
Muita integração mostra “aprovado” para o operador mas não grava NSU e código de autorização amarrados à venda. Na hora de conciliar ou estornar, falta a chave que identifica a transação na adquirente.
Como evitar: persista NSU, código de autorização, bandeira, modalidade e valor no momento da aprovação. Sem isso, conciliação vira garimpo e estorno vira impossível. Veja o que cada campo significa em NSU e código de autorização.
4. Webhook sem validação de assinatura nem idempotência
Consumir webhook confiando cegamente no payload é abrir a porta para eventos forjados. E tratar cada chamada como única gera processamento duplicado quando o mesmo evento chega mais de uma vez (o que é normal).
Como evitar:
- Valide a assinatura de cada webhook contra o segredo compartilhado.
- Seja idempotente no consumo: o mesmo evento não pode confirmar a venda duas vezes.
- Responda rápido (2xx) e processe de forma assíncrona se necessário.
- Tenha um plano B por polling caso o webhook não chegue.
5. Testar só o caminho feliz
Passar um cartão em homologação, ver aprovado e ir para produção. Aí, no primeiro cartão negado ou na primeira queda de rede, o sistema trava.
Como evitar: cubra negação, timeout, cancelamento, estorno e reenvio em homologação. O guia como testar uma integração de TEF em homologação detalha os cenários.
6. Deixar credencial no código
Chaves de API, tokens e segredos commitados no repositório ou embutidos no binário. Uma vez vazados, comprometem todos os pagamentos.
Como evitar: mantenha segredos em variáveis de ambiente ou cofre (Secrets Manager). Separe credenciais de homologação e produção. Rotacione se houver suspeita de vazamento.
7. Não isolar dados entre empresas
Em sistemas multiempresa, misturar transações de tenants diferentes é falha grave de segurança e de conciliação — uma empresa enxergando ou afetando a cobrança de outra.
Como evitar: todo registro carrega o identificador da empresa, e toda consulta filtra por ele. Em pagamento, isolamento é requisito de dia 1, não backlog.
8. Não planejar estorno e cancelamento
Cancelamento (mesma data, antes da liquidação) e estorno (depois) têm regras diferentes e prazos diferentes. Integrações que só pensam em “cobrar” descobrem tarde que não sabem desfazer.
Como evitar: implemente e teste os dois fluxos desde o início, guardando a referência da transação original.
Resumo dos erros e antídotos
- Timeout tratado como falha → consulte status antes de reenviar.
- Sem idempotência → chave única por venda.
- NSU não persistido → grave a chave na aprovação.
- Webhook sem assinatura → valide e seja idempotente no consumo.
- Só caminho feliz → homologue os cenários de erro.
- Credencial exposta → cofre de segredos.
- Dados misturados → filtre por empresa sempre.
- Sem estorno/cancelamento → implemente cedo.
A maioria desses erros desaparece quando você integra por um hub de TEF com API única, idempotência nativa e status por webhook e polling. Consulte a documentação da API para ver como cada proteção já vem pronta.
Evite retrabalho e cobrança duplicada desde a primeira venda: integre por uma API única no painel do GálagoTEF e teste todos os cenários antes de ir para produção.