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 polling da maquininha?
- Qual a diferença entre o "Adquirente" e a "Integração"?
- Onde fica o ZPL do comprovante?
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 → 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 uma integração configurada. O sistema usa essa integração para decidir o fluxo:
- Tipo de pagamento crédito/débito → vai para PayGo (se a integração da conta for PayGo).
- Tipo de pagamento Pix → vai para PayGo, StarkBank ou Pagar.me dependendo da integração configurada.
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?
| Id | Status | Cor | Significado |
|---|---|---|---|
| 1 | Pendente | Amarelo (#faad14) | Recém-criada, ainda não enviada ao gateway. |
| 2 | Em pagamento | Azul claro (#66BDE2) | Enviada para maquininha/QR Code emitido — aguardando cliente operar. |
| 3 | Creditado | Verde (#18AA8C) | Sucesso — pagamento aprovado pelo adquirente. |
| 4 | Expirado | Cinza (#B2BBC0) | Não houve resposta da maquininha em 15s OU cliente não pagou o Pix dentro do prazo. |
| 5 | Cancelamento iniciado | Laranja (#F8AC5A) | Cancelamento solicitado no gateway, aguardando confirmação. |
| 6 | Em cancelamento | Rosa (#F9A4A4) | Cancelamento em processamento na maquininha (cliente pode estar interagindo). |
| 7 | Cancelado | Vermelho (#FF7373) | Cancelamento concluído com sucesso. |
| 8 | Pagamento recusado | Vermelho escuro (#cf1322) | Cartão recusado, saldo insuficiente, fraude detectada etc. |
Status 1, 2, 5, 6 são intermediários — a transação ainda está "viva". Status 3, 4, 7, 8 são finais. Em geral só Creditado (3) 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 (AuthId) | 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 (PaymentSystemName) | 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 não há impressora padrão, abre a janela do Print Service para o operador escolher.
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 (Receipt = null E ReceiptBuyer = null). 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 pelo polling do
GET(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 (
3) — transação aprovada, agora você quer estornar. - Em cancelamento (
6) — cancelamento iniciado mas ainda não finalizou (retentativa).
Outros status não permitem cancelar:
- Pendente (
1), Em pagamento (2) — ainda não há o que cancelar. - Expirado (
4), Pagamento recusado (8) — não houve cobrança efetiva. - Cancelamento iniciado (
5), Cancelado (7) — 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).
- Modal Cancelar Transação TEF abre, mostrando a transação selecionada.
- Digite a SENHA TÉCNICA DO TEF (
TEFCancelingPassword) — 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 CancelPix do Pagar.me e status vira Cancelado (7) 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 id da transação fica registrado em FailedCanceledTransaction no estado da tela para você poder repetir a operação ou contatar o suporte com o id 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?
Sim — o modal tem um botão Cancelar (no canto, dentro do diálogo) que aborta o polling via AbortController. Quando você aborta:
- A requisição em curso é cancelada client-side.
- A mensagem Requisição cancelada pelo usuário aparece.
- O status na maquininha pode continuar evoluindo (você abortou apenas o polling local; o cancelamento real pode ter prosseguido).
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 ciclo do servidor faz até 60 tentativas (≈ 60 segundos). A frente do PDV, por sua vez, repete a consulta a cada 2 segundos, com timeout total de 180 segundos — então, mesmo quando o servidor termina um ciclo sem resposta, a frente continua perguntando para cobrir vendas mais lentas. O usuário vê a mensagem "Aguarde ou digite o número do cartão..." durante essa espera.
Em ambientes de teste do desenvolvedor, o sistema simula sucesso após 3 tentativas para facilitar testes sem maquininha física.
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 Configurações → Contas Bancárias). Define qual gateway o sistema fala. |
| 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.
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.
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.