04/06/2026 · Equipe GálagoTEF

Como testar uma integração de TEF em homologação

Colocar TEF em produção sem testar direito é pedir para descobrir bugs com dinheiro de cliente real na frente. Homologação é o ambiente onde você exercita a integração sem mover dinheiro de verdade, valida os fluxos felizes e — principalmente — os de erro. Este guia mostra como estruturar os testes de uma integração de TEF em homologação antes de liberar para o caixa.

O que é o ambiente de homologação

Homologação (ou sandbox) é uma réplica do ambiente de produção que responde como a administradora responderia, mas sem debitar cartões reais nem creditar sua conta. Você recebe credenciais de teste separadas das de produção e, geralmente, cartões de teste e valores especiais que disparam respostas controladas (aprovado, negado, timeout).

A regra de ouro: credencial de homologação nunca vai para produção, e vice-versa. Mantenha as duas em variáveis de ambiente ou cofre de segredos, nunca no código.

Cenários que você precisa cobrir

O erro clássico é testar só o caminho feliz — passar um cartão, ver “aprovado” e achar que acabou. Uma integração de pagamento robusta trata muito mais que isso. Cubra ao menos:

• Aprovação em cada modalidade: débito, crédito à vista, crédito parcelado e PIX (e voucher, se aceitar).
• Negação por saldo/limite, cartão inválido e senha incorreta.
• Timeout e queda de rede no meio da transação — o caso mais perigoso.
• Cancelamento da venda no mesmo dia.
• Estorno de uma transação já confirmada.
• Reenvio da mesma cobrança (idempotência) — não pode gerar venda duplicada.
• Comprovante: NSU e código de autorização chegando e sendo gravados corretamente.

O cenário de timeout merece atenção redobrada. Se o aparelho aprovou mas seu sistema não recebeu a resposta, você pode ter cobrado o cliente sem registrar a venda. É exatamente para isso que existe idempotência em pagamentos: reenviar com a mesma chave retorna o resultado da transação original em vez de criar outra.

Como testar status: polling e webhook

Transações de POS-comanda não são instantâneas — o hub cria o pagamento e você acompanha o status até a confirmação. Há dois mecanismos, e o ideal é validar os dois em homologação:

1. Polling. Seu sistema consulta o status periodicamente (por exemplo, a cada poucos segundos) até chegar a um estado final: confirmada, negada ou cancelada.
2. Webhook. O hub chama uma URL sua assim que o status muda, evitando ficar perguntando.

Em homologação, teste receber o webhook, validar a assinatura e ser idempotente no consumo — o mesmo evento pode chegar mais de uma vez. Se quiser aprofundar, veja webhooks de pagamento.

Boas práticas durante os testes

Alguns cuidados evitam que a homologação passe uma falsa sensação de segurança:

• Registre tudo (log). Guarde payload enviado, resposta, NSU, autorização e horário. Sem log, um bug em produção vira mistério.
• Teste com valores de borda. R$ 0,01, valores altos, parcelamento no máximo permitido.
• Simule o operador errando. Cancelar no meio, tirar o cartão cedo, apertar o botão duas vezes.
• Meça o tempo de resposta. Se a homologação já está lenta, produção com fila será pior.
• Valide a conciliação. Rode um “fechamento” com as transações de teste e confira se tudo bate.

Checklist antes de ir para produção

Antes de trocar as credenciais e liberar o caixa, confirme:

• Todas as modalidades aprovam e negam como esperado.
• Timeout e queda de rede não geram cobrança duplicada.
• Estorno e cancelamento funcionam e refletem no seu sistema.
• Webhook valida assinatura e trata evento repetido.
• NSU e autorização são gravados e amarrados à venda.
• Credenciais de produção estão em cofre de segredos, não no código.
• Existe uma maquininha ou fluxo de contingência caso a integração caia.

Passar por essa lista é o mínimo. Para uma visão mais ampla do que verificar antes de subir, o guia erros comuns ao integrar pagamento complementa bem este.

Testando com o GálagoTEF

No GálagoTEF, você recebe credenciais de teste por empresa e pode exercitar todo o ciclo — criar, acompanhar por polling ou webhook, confirmar, estornar e cancelar — antes de virar a chave para produção. A documentação da API traz os cartões de teste e os status normalizados de cada resposta.

Comece a homologar sua integração hoje: crie um ambiente de testes no painel do GálagoTEF e valide cada cenário antes de aceitar o primeiro cartão real.

← Voltar ao blog