Transações TEF
A tela de Transações TEF mostra o histórico de pagamentos feitos no PDV — cartão de crédito, débito (via maquininha PayGo/ControlPay) e Pix (via Stark Bank ou Pagar.me). Cada linha é uma tentativa de cobrança com seu status (Pendente → Em pagamento → Creditado, ou Expirado / Pagamento recusado), valor, TID retornado pela operadora, código de autorização, adquirente real (Cielo, Rede, Stone etc.), bandeira do cartão e últimos 4 dígitos. É a tela de auditoria das transações que aconteceram na frente de caixa, separada do extrato bancário e da venda em si.
A tela tem um modo de visualização único, em lista, com 2 ações por linha: Imprimir (via cliente ou via estabelecimento — quando a maquininha retornou o ZPL) e Cancelar Transação (só para status Creditado ou Em cancelamento). O cancelamento exige a senha técnica do TEF e faz polling síncrono na maquininha por até 180 segundos, durante o qual o operador pode precisar interagir com o PIN PAD para digitar o número do cartão original.
A tela não cria novas transações — a criação acontece dentro do PDV quando o operador fecha um pedido com cartão/Pix. Esta tela é apenas para consulta e cancelamento posterior.
Índice
Conceito
- O que é a tela de Transações TEF?
- O que é TEF?
- Quais integrações de pagamento o idworks suporta?
- Quais os 8 status possíveis de uma transação?
- Qual a diferença entre TID, código de autorização, adquirente e bandeira?
- O que é o "terminal TEF"?
Visualização
- Como filtrar a lista de transações?
- Como exportar a lista para Excel?
- Como abrir o pedido vinculado a uma transação?
- O que mostra a coluna Status Pagamento em cores?
Impressão de comprovantes
- Como imprimir a via do estabelecimento?
- Como imprimir a via do cliente?
- Por que o botão de imprimir está desabilitado?
Cancelamento
- Quando posso cancelar uma transação?
- Como cancelar uma transação TEF (cartão)?
- Por que precisa da senha técnica do TEF?
- Por que o cancelamento demora?
- Posso cancelar uma cobrança Pix?
- O que aparece quando o cancelamento falha?
- Posso fechar a janela durante o cancelamento?
Regras de negócio
- Como o pedido fica vinculado à transação?
- Como funciona o acompanhamento da maquininha?
- Qual a diferença entre o "Adquirente" e a "Integração"?
- Onde fica o ZPL do comprovante?
Boas práticas
Referência rápida
O que é a tela de Transações TEF?
É a tela onde você consulta todas as cobranças feitas pelo PDV via maquininha ou Pix — uma por operação. Cada transação tem um ciclo de vida que começa em Pendente, vai para Em pagamento (aguardando o cliente operar a maquininha ou pagar o Pix) e termina em Creditado (sucesso), Pagamento recusado (cartão recusado) ou Expirado (cliente não pagou no tempo configurado). Algumas transações Creditadas podem ser canceladas depois (status terminal: Cancelado).
📍 Onde: menu lateral → Frente de caixa (PDV) → Transações TEF.
O que é TEF?
TEF = Transferência Eletrônica de Fundos. É o protocolo de comunicação entre o sistema de gestão (idworks) e a maquininha de cartão (PIN PAD) instalada no caixa. Em vez de o operador digitar o valor manualmente na maquininha, o sistema manda a venda direto para a maquininha junto com o valor, e a maquininha só pede para o cliente passar o cartão e inserir senha.
Vantagens do TEF:
- Sem digitação manual → sem erro de digitação (valor errado).
- O resultado (aprovado/recusado, TID, autorização) volta automaticamente para o sistema, atualizando o pedido.
- Comprovantes ficam armazenados no sistema (não dependem do papel da maquininha).
No idworks, o TEF é feito via integração com a PayGo (gateway da ControlPay) — a maquininha física pode ser de qualquer adquirente (Cielo, Rede, Stone etc.), o que importa é estar homologada com a PayGo.
Quais integrações de pagamento o idworks suporta?
A tabela de integrações em Configurações → Integrações define qual gateway é usado em cada caixa. Hoje o PDV suporta:
| Integração | Tipo | Suporte no PDV |
|---|---|---|
PayGo / ControlPay (17) | TEF (maquininha) | Crédito, Débito e Pix via PIN PAD físico. |
Stark Bank (131) | Pix | Geração de QR Code dinâmico (expira após 1h). Não suporta cancelamento. |
Pagar.me (13) | Pix | Geração de QR Code. Suporta cancelamento. |
Cada conta bancária do caixa tem dois slots de integração configurados em separado, em Financeiro → Contas Bancárias:
| Slot | Quando é usado | Integrações típicas |
|---|---|---|
| Integração de Pagamento | Cobranças de crédito e débito (categorias 22 e 23). | PayGo / ControlPay. |
| Integração Pix | Cobranças de Pix (categoria 24). | Stark Bank, Pagar.me ou PayGo (Pix via PIN PAD). |
O sistema escolhe automaticamente o slot pela categoria do tipo de pagamento: se for crédito/débito, usa o slot Integração de Pagamento; se for Pix, usa o slot Integração Pix. Assim você pode ter, no mesmo caixa, maquininha PayGo para cartão e Pix da Stark Bank ou Pagar.me — sem precisar de contas bancárias separadas.
Outras integrações (boleto, depósito etc.) não passam pelo TEF — viram contas a pagar/receber diretamente, sem registro de transação TEF.
Quais os 8 status possíveis de uma transação?
| Status | Significado |
|---|---|
| Pendente | Amarelo. Recém-criada, ainda não enviada ao gateway. |
| Em pagamento | Azul claro. Enviada para maquininha/QR Code emitido — aguardando cliente operar. |
| Creditado | Verde. Sucesso — pagamento aprovado pelo adquirente. |
| Expirado | Cinza. Não houve resposta da maquininha em 15s OU cliente não pagou o Pix dentro do prazo. |
| Cancelamento iniciado | Laranja. Cancelamento solicitado no gateway, aguardando confirmação. |
| Em cancelamento | Rosa. Cancelamento em processamento na maquininha (cliente pode estar interagindo). |
| Cancelado | Vermelho. Cancelamento concluído com sucesso. |
| Pagamento recusado | Vermelho escuro. Cartão recusado, saldo insuficiente, fraude detectada etc. |
Os status Pendente, Em pagamento, Cancelamento iniciado e Em cancelamento são intermediários — a transação ainda está "viva". Creditado, Expirado, Cancelado e Pagamento recusado são finais. Em geral só Creditado vira venda válida; os demais ficam apenas como histórico de tentativa.
Qual a diferença entre TID, código de autorização, adquirente e bandeira?
| Campo | O que é | Quem fornece |
|---|---|---|
| TID (Transaction ID / NSU) | Identificador único da transação no adquirente. Usado para conciliação bancária com o extrato da maquininha. | Adquirente (Cielo, Rede etc.). |
| Código de Autorização | Código de aprovação emitido pelo emissor do cartão (banco do cliente). | Banco emissor (via adquirente). |
| Adquirente | A operadora da maquininha que processou a transação (Cielo, Rede, Stone, Getnet, SafraPay etc.). | Retornado pela maquininha. |
| Bandeira | A bandeira do cartão usado (Visa, Master, Elo, Hipercard, American Express, "Pix" etc.). | Retornado pela maquininha. |
O TID é o campo mais importante para o financeiro — é por ele que você concilia a venda na tela de Conciliação Adquirente com o que aparece no extrato da operadora.
O que é o "terminal TEF"?
É o código PayGo da maquininha física instalada no caixa. Configurado no cadastro da conta bancária quando a integração é PayGo. Cada caixa do PDV (cada conta bancária do tipo "caixa") tem um terminal TEF associado — quando o operador faz uma venda nesse caixa, o sistema manda para aquela maquininha específica.
Por isso, se você tem 3 caixas físicos com 3 maquininhas, precisa configurar 3 contas bancárias com 3 códigos de terminal diferentes (um por maquininha). O token da integração PayGo é único da empresa — é como uma chave de identificação.
Como filtrar a lista de transações?
Abra o painel de filtros (botão de funil no topo direito). Filtros disponíveis:
| Filtro | O que filtra |
|---|---|
| Conta | Empresa do grupo (multi-account). |
| Data Transação | Intervalo da data de criação da transação. |
| Data Cancelamento | Intervalo da data de cancelamento (preenchido apenas em transações canceladas). |
| Empresa | Empresa faturadora vinculada à conta bancária do caixa. |
| Banco | Caixa/maquininha específica. |
| Cód. Autorização | Busca exata pelo código de autorização da transação. |
| TID | Busca exata pelo TID retornado pelo adquirente. |
| Cód. Terminal TEF | Filtra pelo código da maquininha (ID PayGo). |
| Status Pagamento | Filtra por um dos 8 status. |
Combine à vontade. Em seguida, Buscar. Para resetar, Limpar. Além dos filtros, cada coluna tem busca interna (lupa do cabeçalho).
Você precisa selecionar pelo menos um filtro para a lista carregar (a tela mostra o aviso "Por favor, selecione pelo menos um filtro para visualizar os resultados.").
Como exportar a lista para Excel?
Botão Mais Ações no topo direito → opção com ícone de download. O arquivo .xlsx é gerado com os dados visíveis (respeita os filtros aplicados) e baixado direto.
O export usa a mesma rotina das outras telas de listagem do idworks.
Como abrir o pedido vinculado a uma transação?
A coluna Cód. pedido mostra o id do pedido com um ícone de olho. Clique para abrir o pedido em uma nova aba (atalho preserva a tela de transações aberta).
O vínculo é feito por um identificador único da tentativa de pagamento (gerado no momento em que o operador inicia o pagamento). Quando a venda é fechada, o pedido é gravado com esse mesmo identificador. Se a transação não chegou a virar pedido (ex.: status Expirado), o campo Cód. pedido fica vazio.
O que mostra a coluna Status Pagamento em cores?
Cada um dos 8 status tem uma cor para sinalização rápida na lista — veja a tabela em Quais os 8 status possíveis de uma transação?.
O verde (Creditado) é o que você espera ver na maioria das linhas. Vermelhos (Cancelado, Pagamento recusado) precisam de atenção — alguém pode ter cancelado uma venda boa por engano, ou o cliente teve cartão recusado várias vezes (suspeita de fraude).
Como imprimir a via do estabelecimento?
Na linha da transação, clique no botão de impressora → escolha Via Estabelecimento no dropdown.
O sistema envia o comprovante em ZPL (linguagem de impressão Zebra) para a impressora padrão configurada na empresa (em Configurações → Parametrizações). Se nenhuma impressora padrão estiver configurada, o sistema imprime na impressora padrão do computador.
O comprovante vem da maquininha — só transações Creditadas via PayGo têm essa via. Pix StarkBank/Pagar.me não geram comprovante no formato ZPL.
Como imprimir a via do cliente?
Mesma rotina: ícone de impressora → Via Cliente. O sistema usa o comprovante destinado ao cliente armazenado na transação.
A via do cliente costuma ser mais curta que a do estabelecimento (sem dados como assinatura, declaração jurada etc.). É a via que o cliente leva para casa.
Por que o botão de imprimir está desabilitado?
Quando a transação não tem comprovante ZPL armazenado (nem a via do estabelecimento, nem a do comprador). Acontece principalmente nesses casos:
- Transação Pix (Stark Bank, Pagar.me) — pagamento via Pix não gera comprovante ZPL.
- Transação que não foi Creditada — Expirado, Pendente, Pagamento recusado não têm comprovante.
- Transação antiga anterior à integração com a captura de ZPL.
- Falha na captura do ZPL pela consulta automática (rede instável durante a aprovação).
Nesses casos, o comprovante físico precisa ser obtido pelo papel da maquininha (no caso PayGo) ou pelo comprovante Pix do banco do cliente.
Quando posso cancelar uma transação?
Apenas em 2 status:
- Creditado — transação aprovada, agora você quer estornar.
- Em cancelamento — cancelamento iniciado mas ainda não finalizou (retentativa).
Outros status não permitem cancelar:
- Pendente, Em pagamento — ainda não há o que cancelar.
- Expirado, Pagamento recusado — não houve cobrança efetiva.
- Cancelamento iniciado, Cancelado — já está no fluxo de cancelamento ou cancelada.
Tentar cancelar fora desses casos retorna Transação não esta aprovada. O cancelamento é permitido apenas em transações autorizadas.
Como cancelar uma transação TEF (cartão)?
- Na linha, clique no ícone de Cancelar Transação (símbolo de "proibido"/Stop).
- A janela Cancelar transações TEF abre, mostrando a transação selecionada.
- Digite a senha do TEF no campo Senha master — fornecida pela PayGo no momento da contratação.
- Confirme em Cancelar essa transação?.
- Mensagem Processando o cancelamento... aparece.
- Quando a maquininha responder com "Em cancelamento", a mensagem muda para Aguarde ou digite o número do cartão... — neste ponto o cliente precisa passar o cartão original (alguns adquirentes exigem) ou digitar os 4 últimos dígitos.
- O sistema verifica a maquininha a cada 2 segundos por até 180 segundos no total.
- Resultado:
- Sucesso → notificação "Transação cancelada com sucesso!" + atualização do status na lista.
- Falha → bloco vermelho com mensagem do adquirente, valor, tipo de pagamento e motivo.
- Timeout → "Tempo limite excedido. Cancelamento não confirmado." (o status final pode chegar depois via reconciliação).
Pré-requisito: privilégio Deletar Transação TEF.
Por que precisa da senha técnica do TEF?
A senha técnica é uma proteção da maquininha PayGo: sem ela, qualquer pessoa com acesso ao sistema poderia estornar vendas livremente. A senha é fornecida pela PayGo no momento da contratação e deve ficar com o gerente da loja — operadores comuns não têm.
Quando a senha é incorreta, a PayGo retorna a mensagem direta e o cancelamento não é processado.
Por que o cancelamento demora?
O cancelamento TEF tem 3 etapas, cada uma síncrona:
- Envio do comando (até alguns segundos) — sistema → PayGo → maquininha física.
- Espera pela ação do cliente (variável — pode ser 0 ou vários minutos) — alguns adquirentes exigem que o cliente passe o cartão original ou digite os últimos 4 dígitos na maquininha.
- Verificação periódica (até 180 segundos no total) — sistema consulta a maquininha a cada 2 segundos.
Total: pode levar de 3 segundos (caso simples, cancelamento direto) a 3 minutos (caso o cliente precise operar a maquininha). A interface mostra mensagens dinâmicas para o operador entender o que está acontecendo:
- "Processando o cancelamento..." (etapas 1)
- "Aguarde ou digite o número do cartão..." (etapas 2 e 3, quando a maquininha já respondeu "Em cancelamento")
O tempo limite da verificação é de 180 segundos. Se passar disso, a mensagem Tempo limite excedido ao consultar o status do cancelamento TEF aparece e o status na lista pode demorar para sincronizar.
Posso cancelar uma cobrança Pix?
Depende da integração:
| Integração | Cancelamento via tela? |
|---|---|
| PayGo / ControlPay (Pix via PIN PAD) | Sim — passa pelo mesmo fluxo TEF com senha técnica. |
| Stark Bank | Não. O QR Code Pix do Stark Bank apenas expira após o tempo configurado (default 3600s = 1h). Retorna a mensagem Não é possível cancelar uma cobrança Pix. O QR Code apenas expira após o tempo configurado. |
| Pagar.me | Sim — chama o cancelamento Pix do Pagar.me e o status vira Cancelado imediatamente. Não precisa de senha técnica. |
Para Pix já recebido (status Creditado), o cancelamento na tela registra a anulação no gateway mas não dispara devolução automática — a devolução do valor ao cliente é uma operação financeira separada (TED, PIX outbound) que precisa ser feita pelo Internet Banking.
O que aparece quando o cancelamento falha?
Quando o gateway retorna falha durante o cancelamento, a tela mostra um bloco vermelho no modal com:
- Cancelamento TEF não foi concluído.
- Valor: R$
- Tipo de pagamento: <categoria do cartão>
- Motivo:
(ou "Motivo não informado.")
O identificador da transação fica disponível na tela para você poder repetir a operação ou contatar o suporte com o número em mãos.
Mensagens comuns de falha do adquirente:
- "Cartão não corresponde ao original" — cliente passou cartão diferente.
- "Transação não localizada na maquininha" — TID/intenção de venda já saiu do buffer da maquininha (tempo limite).
- "Senha técnica inválida" — senha digitada incorretamente.
- "Conexão com PIN PAD perdida" — maquininha desconectada do computador.
Posso fechar a janela durante o cancelamento?
Nesta tela, o acompanhamento do cancelamento roda até concluir ou atingir o tempo limite (cerca de 180 segundos) — não há um botão para abortar o acompanhamento no meio. Se você fechar a janela antes do fim:
- O acompanhamento na tela é encerrado, mas o cancelamento real na maquininha pode continuar evoluindo (você interrompeu apenas a visualização).
- Para conferir o status real depois, recarregue a lista (botão de reload da tabela) — o status atualizado pelo sistema será refletido.
Como o pedido fica vinculado à transação?
O sistema usa um identificador único da tentativa de pagamento que liga a transação ao pedido final. Funciona assim:
- No PDV, quando o operador clica em "Pagar com Cartão", o sistema gera o identificador e cria a transação TEF com ele.
- O cliente passa o cartão / paga o Pix.
- Quando aprovado, o pedido é fechado e gravado com o mesmo identificador.
- A lista da tela usa esse identificador para casar a transação com o pedido e mostrar a coluna Cód. pedido.
Se a transação expira ou é recusada, não há pedido fechado para casar — o pedido nunca é criado, mas a tentativa fica registrada em Transações TEF para auditoria.
Como funciona o acompanhamento da maquininha?
Enquanto o cliente está pagando, o sistema consulta o adquirente repetidamente para saber se a transação foi aprovada:
- PayGo / ControlPay: consulta a cada 1 segundo.
- Stark Bank: consulta a cada 1 segundo.
- Pagar.me: consulta a cada 1 segundo.
Cada consulta do servidor fica aberta fazendo até 60 tentativas (≈ 60 segundos) antes de responder. Quando o servidor retorna sem resposta definitiva, a frente do PDV reabre a consulta para cobrir vendas mais lentas, até um tempo limite de cerca de 90 segundos no total. O usuário vê a mensagem "Aguarde ou digite o número do cartão..." durante essa espera.
Qual a diferença entre o "Adquirente" e a "Integração"?
| Conceito | Exemplos | Onde é configurado |
|---|---|---|
| Integração | PayGo, Stark Bank, Pagar.me | Cadastro da conta bancária do caixa (em Financeiro → Contas Bancárias). A conta tem dois slots: Integração de Pagamento (cartão de crédito/débito) e Integração Pix (cobranças Pix). O sistema escolhe o slot pela categoria do tipo de pagamento. |
| Adquirente | Cielo, Rede, Stone, Getnet, SafraPay | Vem da resposta da maquininha — não é configurado no idworks. Define qual operadora processou a transação. |
A PayGo é uma agnóstica: ela faz a ponte entre o idworks e qualquer maquininha homologada, independente do adquirente. Ou seja, você pode ter um caixa com integração PayGo e maquininhas de Cielo + Rede rodando no mesmo terminal — o adquirente real só é identificado depois que a transação processa.
Configurar a Integração Pix separadamente é o que permite ter Pix em um gateway diferente do cartão (ex.: cartão pela PayGo, Pix pela Pagar.me) no mesmo caixa.
Onde fica o ZPL do comprovante?
A maquininha PayGo devolve o comprovante já em ZPL (linguagem de impressão Zebra). O sistema guarda dois comprovantes para cada transação:
- Via do estabelecimento — usada pela loja.
- Via do cliente — entregue ao cliente.
Quando você imprime o comprovante pela tela, o sistema entrega o ZPL pronto para a impressora térmica Zebra. Pix (Stark Bank, Pagar.me) não gera comprovante ZPL — o Pix gera apenas QR Code, não comprovante impresso.
Boas práticas para o cancelamento e a conferência
Cancelamento de cartão mexe com dinheiro do cliente e da loja — alguns cuidados evitam estorno indevido e cliente sem o dinheiro de volta. Dicas que valem a atenção:
- Deixe a senha técnica da maquininha com o gerente. Sem ela ninguém cancela uma venda — é a proteção contra estorno indevido. Operador comum não deve tê-la; ela fica com quem responde pela loja.
- Lembre que cancelar a transação não devolve o dinheiro sozinho. O cancelamento anula a cobrança no adquirente, mas a devolução ao cliente (especialmente no Pix já recebido) é uma operação financeira à parte — TED/Pix pelo banco. Combine o estorno antes de dar a venda como resolvida.
- Não feche a janela no meio do cancelamento. O acompanhamento roda até concluir ou atingir o tempo limite; se você fechar antes, perde a visão mas a maquininha pode continuar processando. Para saber o resultado real, recarregue a lista depois.
- Confira pelo TID na conciliação adquirente. O TID é o número que casa a venda com o extrato da operadora. Use o filtro por TID para localizar uma transação específica e fechar o que entrou na maquininha contra o que o banco creditou.
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar Transações TEF | Acesso à tela e à lista. Sem isso, a tela não aparece no menu. |
| Deletar Transação TEF | Botão de cancelar transação. Sem isso, o ícone aparece desabilitado para o operador. |
Não há privilégio separado para imprimir — quem visualiza pode imprimir (desde que o ZPL exista). A criação de transações é feita dentro do PDV (Frente de Caixa), com privilégios próprios da tela do PDV — não passa por essa tela.