01/07/2026 · Equipe GálagoTEF

Elgin TEF: visão geral para integradores

Se você vai integrar pagamento em maquininha usando a Elgin TEF, este guia dá a visão geral que todo integrador precisa antes de escrever a primeira linha: como é o fluxo de uma transação, como se acompanha o status e o que muda em relação a um TEF tradicional de balcão. O foco é a linha Elgin TEF HUB / POS Comandas, voltada a POS-comanda com comunicação REST sobre HTTPS.

O que é a Elgin TEF HUB / POS Comandas

A Elgin é uma das administradoras de TEF disponíveis no mercado brasileiro. A linha POS Comandas expõe uma API REST em JSON, autenticada por token, na qual o seu sistema cria uma cobrança e a maquininha (o POS) executa a transação com o portador do cartão. É um modelo pensado para restaurantes, bares e varejo com múltiplos terminais, onde a comanda ou o caixa dispara a cobrança para uma maquininha específica.

Diferente de um TEF discado antigo, aqui não há middleware pesado no balcão: a comunicação é HTTP, o que facilita integrar sistemas web, desktop e mobile ao mesmo backend.

O fluxo de uma transação

O ciclo de vida de um pagamento na Elgin segue um padrão que vale memorizar:

1. Autenticação — você obtém um token (Bearer JWT) e o envia no header das chamadas.
2. Criação do pagamento — um POST /Pagamento com valor, modalidade e o POS de destino.
3. Acompanhamento por polling — enquanto o cliente passa o cartão, você consulta o status periodicamente (a cada poucos segundos).
4. Confirmação — quando o status indica transação confirmada, a venda está aprovada.
5. Estorno ou cancelamento — se necessário, você dispara a operação inversa.

Modalidades suportadas

A modalidade é informada na criação da cobrança. Os valores comuns são:

• 1 — Débito
• 2 — Crédito
• 3 — PIX
• 4 — Voucher (vale-refeição/alimentação)

Para crédito, ainda há a distinção entre à vista e parcelado, que impacta taxa e prazo de recebimento — vale revisar como o parcelado loja se diferencia do parcelado emissor antes de fixar as regras do seu PDV.

Polling de status

Como a transação é assíncrona (depende do cliente inserir o cartão e digitar a senha na maquininha), você não recebe o resultado na resposta do POST. Em vez disso, consulta o status em intervalos regulares — tipicamente a cada 3 segundos — até chegar a um estado terminal, como Confirmada. Cada estado numérico da Elgin deve ser mapeado para um status normalizado no seu sistema (pendente, confirmada, negada, cancelada), para não espalhar códigos da administradora pela sua aplicação.

Dois cuidados importantes no polling:

• Timeout e limite de tentativas — defina um teto de tempo; se o cliente desistir, a transação fica pendente e precisa de tratamento.
• Idempotência — nunca recrie a cobrança a cada retentativa. Use uma chave única por transação para não gerar venda duplicada. O tema é tão central que vale ler sobre idempotência em pagamentos.

Webhook: alternativa ao polling

Além do polling, a Elgin oferece notificação por webhook: seu backend expõe um endpoint (registrado no cadastro do estabelecimento) e recebe a mudança de status ativamente. Na prática, vale usar os dois — webhook para reagir rápido e polling como rede de segurança, caso uma notificação se perca. Se você ainda não trabalha com esse padrão, o guia de webhooks de pagamento explica como confirmar vendas com segurança.

O que o integrador precisa cuidar

Integrar Elgin diretamente é viável, mas concentra responsabilidades no seu código:

• Gerenciar e renovar o token JWT.
• Implementar polling e webhook, com deduplicação de eventos.
• Mapear estados numéricos para status de negócio.
• Garantir idempotência e isolamento por estabelecimento.
• Guardar NSU, código de autorização e comprovante para conciliação.

Cada uma dessas peças precisa ser testada em homologação antes de ir a produção — algo que o roteiro de testar integração de TEF em homologação cobre passo a passo.

Integrar direto ou por um hub?

Nada impede integrar a Elgin diretamente. Mas se você atende vários clientes, opera múltiplos POS ou quer estar pronto para uma segunda administradora amanhã, um hub de TEF abstrai tudo isso: você fala uma API única e o hub cuida do dialeto da Elgin — token, polling, webhook, modalidades e idempotência. O GálagoTEF nasceu exatamente assim, com a Elgin como primeira administradora e a arquitetura pronta para as próximas.

Quer integrar sem carregar o peso do protocolo? Veja a documentação da API do GálagoTEF ou crie sua conta no painel e comece a testar em homologação hoje.

← Voltar ao blog