Homologação TEF PayGo — Guia do Membro

Etapa 01

O que a PayGo certifica — e por que a homologação é sua

A PayGo não certifica “o sistema”. Ela certifica uma automação comercial identificada por três dados, e os três saem da sua instalação:

O que a PayGo registra	De onde o ERP tira
Software house (nome + CNPJ)	Configurações › SoftHouse — campos Razão e CNPJ
Nome da automação	Configurações › Terminais › aba TEF/POS — Nome Aplicação
Versão da automação	Configurações › Terminais › aba TEF/POS — Versão

Como cada membro revende o sistema com a marca dele, esses três campos são diferentes em cada instalação — e por isso cada membro roda a própria certificação. O que você herda não é o certificado: é o comportamento do código, que já foi auditado e aprovado nos passos em que quase todo mundo tropeça.

Já resolvido no código

Em agosto de 2026 a PayGo reprovou três vezes o passo 51 (desfazimento por queda de energia) e duas vezes os passos 31/32 (confirmação manual) numa automação nossa. Os dois foram corrigidos e o passo 51 foi aprovado pela PayGo em 17/08/2026 — com a resposta textual “o passo 51 está correto”. O conserto está na 7.4.4 em diante. Você não precisa refazer esse trabalho; precisa não desfazê-lo (veja a etapa 07).

Como o ERP conversa com a PayGo

O caminho é TEF dedicado: o ERP usa o componente ACBrTEFAPI, que por sua vez carrega a PGWebLib.dll instalada na máquina. Não há servidor intermediário, não há “gerenciador padrão” rodando à parte — o PIN-pad fala com o executável do caixa.

Uma consequência prática: o ambiente (teste ou produção) é decidido pela DLL que estiver instalada, não por uma opção no ERP. A biblioteca de certificação só fala com o sandbox; a de produção só fala com produção. Trocar de ambiente é trocar o arquivo.

Etapa 02

Abrir o processo na PayGo

Prazo típico de análise depois que você envia os testes: 5 dias úteis. Comece por aqui antes de mexer em qualquer configuração — o ponto de captura de sandbox é o item de maior espera.

Abra o chamado no portal de desenvolvedores. É um Jira Service Desk: dev.proj.setis.com.br › portal 16, opção “Enviar uma solicitação ou incidente”. Diga que é integração PGWebLib para Windows e informe os dados da sua empresa (razão social e CNPJ da software house, nome e versão da automação).
Peça o kit de integração e o roteiro de testes. O kit traz a biblioteca de certificação (o arquivo tem o sufixo _CERT) e a planilha de testes. Exemplos de código em várias linguagens ficam no GitHub da PayGo — você não vai precisar deles, o ACBr já cobre a integração.
Receba o ponto de captura (PdC) de sandbox e as credenciais dos três autorizadores simulados: C6PAY (sub-adquirente), REDE (adquirente) e PIX C6 BANK (Pix e carteira digital). A PayGo só libera PdC de teste no ambiente sandbox.
Rode a planilha inteira na máquina de teste (etapas 03 a 07 deste guia).
Devolva no mesmo chamado a planilha preenchida e os logs da PGWebLib do dia dos testes.
Analise o retorno. Aprovado, você recebe o certificado de aptidão para produção. Reprovado, a PayGo aponta os passos e você refaz só aqueles.

Atalho que vale usar

O Projeto ACBr é parceiro da PayGo e faz a ponte: preenchendo o cadastro do TEF ACBr PayGo no site deles, a PayGo entra em contato para gerar o seu PdC, e o suporte do ACBr acompanha a homologação. É o mesmo processo, com alguém do lado de cá que já viu esses logs antes.

Etapa 03

Preparar a máquina de teste

PIN-pad

Modelo homologado pela PayGo, ligado pelo cabo USB original do equipamento. A nossa certificação foi feita com um Gertec PPC-930.
A porta virtual precisa estar entre COM1 e COM32 — acima disso a biblioteca não detecta. Se o Windows atribuiu COM47, mude no Gerenciador de Dispositivos para o número livre mais baixo.
O ERP passa a porta como AUTO: a biblioteca varre as portas sozinha. Não há campo de porta do PIN-pad para preencher.

Biblioteca

Copie a PGWebLib.dll de certificação para a pasta do executável (C:\Sistema na instalação padrão), ou aponte a variável de ambiente PathPGWebLib para o caminho completo do arquivo.
O ERP é compilado em 32 bits — use a DLL x86. A de 64 bits carrega pela variável PathPGWebLib_x64 e não serve aqui.
A pasta de trabalho é criada sozinha em C:\Sistema\tef\PGWeb\. É lá que ficam os arquivos de transação e os logs que a PayGo vai pedir.

Rede

Ambiente	Servidor de transação
Sandbox / certificação	`pos-transac-sb.tpgweb.io` `31735`
Produção	`pos-transac.pgweb.io` `31735`

Em cliente com firewall ou proxy fechado, libere as portas 17500, 31732–31735 e 13160 para os servidores PayGo Web, mais sandbox.controlpay.com.br (80/443) no ambiente de testes. O canal exige TLS 1.2 no mínimo — máquina antiga com TLS desabilitado não conecta e o erro não diz isso.

Impressora

O comprovante do TEF sai pela impressora ESC/POS do terminal — a mesma configurada em Configurações › Terminais › aba Configurações › ESC/POS. Deixe-a funcionando antes de começar: vários passos da planilha pedem a via impressa, e sem impressora o teste roda mas não produz evidência.

Etapa 04

Instalar o ponto de captura

O PdC é instalado por dentro do próprio ERP, pela função administrativa da PayGo. Não existe programa separado para isso no TEF dedicado.

Abra Configurações › Terminais, escolha o terminal e vá na aba TEF/POS.
Marque Usa TEF e escolha Gerenciador TEF = tefApiPayGoWeb. Grave (F10).
Clique em Testar TEF. O ERP inicializa a biblioteca e abre o menu administrativo da PayGo na tela.
Escolha Instalação e responda o que for pedido:

Campo	Valor
Senha técnica	`314159`
Número do ponto de captura	o que a PayGo enviou no chamado
Endereço do servidor	`pos-transac-sb.tpgweb.io`
Porta	`31735`
CPF/CNPJ	do responsável cadastrado

A instalação baixa os parâmetros do PdC dos servidores da PayGo e grava na máquina — pode levar alguns segundos, e é normal a tela parecer parada. No fim aparece a confirmação de que a instalação foi concluída, e o terminal já transaciona.

Instalação é uma vez só

Reinstalar o mesmo PdC, ou mover o PdC para outro computador, exige autorização do suporte da PayGo — chame o portal antes. Formatar a máquina de teste no meio da homologação custa dias.

Sobre o campo “Nº Lógico do Estabelecimento (PDC)”

Ele existe na aba TEF/POS, mas não é enviado ao TEF: quem guarda o número do ponto de captura é a instalação local que você acabou de fazer. Preencher ou deixar em branco não muda o comportamento — use-o só como anotação de qual PdC está naquele caixa.

Etapa 05

Configurar o ERP

Configurações › SoftHouse

Os campos Razão e CNPJ desta tela são a software house que o ERP envia à PayGo em toda transação. Preencha exatamente como você informou no chamado.

Armadilha

A aba TEF/POS do terminal também tem um campo chamado Razão Social. Ele não é lido pelo TEF — quem vale é o da tela SoftHouse. Preencher o campo errado é o tipo de coisa que só aparece quando o analista da PayGo diz que a software house do log não bate com a do cadastro.

Configurações › Terminais › aba TEF/POS

Bloco “Configurações TEF”

Campo	O que pôr
Usa TEF	marcado
Gerenciador TEF	`tefApiPayGoWeb` — é o segundo item da lista, logo abaixo de `tefApiNenhum`
Arq.Log	caminho de um arquivo de log do componente, ex.: `C:\Sistema\logs\tefacbr.log`. Não é o log que a PayGo pede, mas ajuda no suporte
Nome Aplicação	o nome da automação registrado na PayGo
Versão	a versão registrada na PayGo — mantenha igual à versão do executável

A versão é digitada à mão

O ERP não lê a versão do próprio .exe para esse campo. Se você subir de 7.4.4 para 7.4.5 e esquecer de atualizar aqui, o log da PayGo continuará dizendo 7.4.4 — e uma certificação vale para o par nome + versão que foi testado. Inclua esse campo no seu roteiro de atualização.

Bloco “Parâmetros TEF”

Dois destes decidem a sua certificação. Os outros cinco são preferência de operação.

Transação Pendente Perguntar decide os passos 31/32

É o único valor em que o ERP pergunta ao operador e envia a confirmação manual. Em Confirmar, o componente resolve sozinho e manda confirmação automática — que é exatamente o código pelo qual os passos 31/32 reprovam.

Pendência na Inicialização Processar Pendentes decide o passo 51

Em Não Fazer nada o terminal nunca desfaz a venda interrompida por queda de energia — e isso não aparece em teste nenhum, só na auditoria da adquirente.

Cancelar/Estornar também passa, mas é mais agressivo: para transação que já mandou a confirmação ele emite cancelamento da venda, não só o desfazimento da pendente.

Demais campos	Homologação	Nota
QRCode	Auto	A biblioteca decide entre PIN-pad e tela conforme o equipamento.
Imprime Via Cliente	Imprimir ou Perguntar	Escolha sua. Perguntar abre um diálogo a cada venda.
Confirma Transação Auto	desmarcado	A confirmação sai no fim da venda, junto com a NFC-e.
Suporta Desconto	marcado	Era assim na automação aprovada.
Suporta Saque, Via Reduzida e Terminal de Auto Atendimento	desmarcados	Autoatendimento (passos 39/40 da planilha) está fora do escopo — declare como não aplicável.

Base que nunca teve a aba preenchida

Até a 7.4.3 o TEF morria com “Falha ao inicializar o TEF Digital” em qualquer terminal cuja aba TEF nunca tinha sido aberta. A 7.4.4 corrige isso e a migração preenche os quatro combos vazios com o padrão do componente. Um deles você ainda precisa mudar à mão: o padrão de Transação Pendente é Confirmar, e a homologação exige Perguntar.

Financeiro › Forma de Pagamentos

Para cada forma que vai passar no TEF, na aba Cadastro, grupo TEF: Provedor = PayGoDigital - TEF e o Tipo Financiamento. O grupo só aparece para os tipos abaixo.

Tipo da forma	Vira, no TEF	Observação
Cartão de Crédito	Cartão / crédito	Respeita o financiamento e as parcelas
Cartão de Débito	Cartão / débito	Forçado à vista, 1 parcela
Pagamento Instantâneo	Carteira virtual	Pix e carteiras; à vista
Vale Refeição · Combustível · Presente	Voucher	À vista, 1 parcela
Cartão TEF	—	não use O grupo TEF aparece, mas o caminho PayGo não trata esse tipo: a venda para com “Tipo de pagamento TEF não reconhecido”. Use Crédito ou Débito.

Em Tipo Financiamento, Não Definido (Perguntar) faz o ERP perguntar ao operador a cada venda; A Vista, Parcelado Emissor, Parcelado Estabelecimento, Pré Datado e Crédito Emissor fixam a modalidade. Para a planilha, deixe crédito em Não Definido: vários passos exigem parcelamentos diferentes na mesma bateria.

Etapa 06

Rodar a planilha

A regra que mais custa caro

Os testes têm de sair em uma passada só, na ordem, sem interrupção. Parar no meio, reinstalar, trocar de máquina ou reiniciar o sistema fora dos passos que mandam reiniciar obriga a recomeçar do passo 01. Reserve o dia.

Valores

Use valores cheios, sem centavos, de R$ 1,00 a R$ 10,00; acima disso, de 10 em 10.
O autorizador simulado REDE aceita somente valores inteiros.
Valores acima de R$ 1.000,00 disparam desvios de propósito no sandbox. Não use por conta própria — mas é exatamente isso que a planilha explora nos passos 31/32, com R$ 1005,50 e R$ 1005,51.
No sandbox a transação é aprovada sozinha depois de alguns segundos. Não espere senha nem chip real.

Onde rodar

Rode as vendas pelo PDV do Retaguarda recém-compilado, não pelo PDV.exe avulso: os dois são binários separados e o avulso costuma estar defasado. A tela de fechamento é a mesma nos dois, então o que você testar no Retaguarda vale para o outro depois que ele for recompilado.

Etapa 07

Os três passos que reprovam

Estes são os passos em que a nossa automação foi reprovada cinco vezes antes de passar. Nos três, o que a PayGo audita é o código da terceira perna — o número que diz quem resolveu a transação e por quê. O binário já manda o código certo; o que ainda decide é como o teste é conduzido.

passo 51

Queda de energia depois da aprovação

aprovado 17/08/2026

O que o teste faz: aprova uma venda e mata o sistema antes da confirmação, simulando queda de energia. Ao reabrir, a automação tem de desfazer a transação pendente — e antes de qualquer outra conversa com a PayGo.

O que o ERP faz sozinho: na abertura do Retaguarda, antes de o componente subir, ele varre a pasta de trabalho e envia o desfazimento por queda de energia (PWCNF_REV_PWR_AUT, 0x83131) direto pela biblioteca. Terminal que nunca usou PayGo não tem a pasta e a rotina sai sem carregar DLL nenhuma.

O que você faz: nada além de estar na 7.4.4 ou superior e não deixar Pendência na Inicialização em Não Fazer nada.

A prova: no comms, entre o PW_iInit e o PW_iConfirmation(0x83131 …) não pode existir nenhum PW_iNewTransac — nem a consulta de versão. Foi ela que reprovou três vezes.

12:38:56  PW_iInit <0>
12:38:57  PW_iConfirmation(0x83131, 0000039535, 118, 994593, ...) <0>
           ^ nenhuma transacao entre os dois - e isso que a PayGo confere

passos 31 e 32

Confirmação manual da transação pendente

depende de como você conduz

O roteiro, exatamente:

Venda de R$ 1005,50 no C6PAY. Confirme normalmente. O autorizador marca a transação como pendente.
Segunda venda de R$ 1005,51, sem reiniciar o sistema e sem fechar o PDV.
O ERP mostra “Uma transação TEF está pendente. Deseja CONFIRMAR essa transação?” — responda Sim.

A prova: PW_iConfirmation(0x3221 …) — PWCNF_CNF_MANU_AUT, confirmação manual.

Os dois jeitos de errar este passo

Responder Não manda 0x3231 (desfazimento manual), que é o passo 37 e reprova o 31/32. E com o terminal em Transação Pendente = Confirmar o diálogo nem aparece: o componente resolve sozinho e manda 0x121, confirmação automática — o código pelo qual esse passo já reprovou duas vezes.

A segunda venda é abortada pelo autorizador enquanto a pendência existe (retorno -2599) — isso é esperado. Resolvida a pendência, refaça a venda se a planilha pedir o valor lançado.

passo 37

Desfazimento manual

passa desde a 7.4.4

Mesma pendência do passo anterior, resposta oposta: Não no diálogo. Sai PW_iConfirmation(0x3231 …) — PWCNF_REV_MANU_AUT.

Antes da 7.4.4 esse passo era declarado na planilha como “não suporta esta finalidade”. Suporta — preencha com o identificador do teste.

O que declarar como não aplicável

Os passos 39 e 40 (autoatendimento) ficam fora por decisão de projeto: o ERP não certifica essa modalidade. Marque como não suportado e deixe Terminal de Auto Atendimento desmarcado no cadastro.

Limites conhecidos, para não ser pego de surpresa

Com pendência aberta no autorizador, a venda em curso não termina sozinha: o operador resolve a pendência e refaz a venda. E se o TEF aprovar e a NFC-e falhar em seguida, o ERP cancela a transação, mas não envia o código específico de erro fiscal — é um item nosso em aberto, sem impacto nos passos da planilha.

Etapa 08

Entregar as provas

A PayGo analisa o log da biblioteca, não a sua tela nem o print. Tudo o que ela precisa está em C:\Sistema\tef\PGWeb\:

Arquivo	O que traz
comms_AAMMDD.log.txt	A conversa com o autorizador — é o arquivo que decide cada passo
ppsers_AAMMDD.log.txt	A conversa com o PIN-pad, pedida quando há suspeita de equipamento

Envie também, mesmo sem ser pedido, os logs do próprio ERP daquele dia — eles respondem “qual executável estava rodando”, que é a primeira pergunta quando um sintoma não se reproduz:

Arquivo	O que traz
C:\Sistema\logs\AAAA-MM-DD\TEF.log	Cada passo do TEF pelo lado do ERP, com usuário, empresa e terminal
C:\Sistema\logs\Sessao.log	Versão e caminho do executável de cada sessão

Some a planilha preenchida e as vias impressas dos comprovantes gerados durante os testes. Tudo vai anexado no mesmo chamado do Jira.

Etapa 09

Virar para produção

Com o certificado de aptidão na mão, o cliente final entra em produção assim:

A PayGo emite um ponto de captura de produção para aquele estabelecimento — um por caixa.
Instale na máquina do cliente a PGWebLib de produção (não a _CERT) e configure o PdC pelo mesmo caminho da etapa 04, apontando para pos-transac.pgweb.io porta 31735.
No ERP, o único ajuste é o cadastro do terminal — Usa TEF, Gerenciador TEF e os parâmetros da etapa 05. Nada indica “produção” dentro do sistema: quem separa os ambientes é a DLL instalada.
Em cliente com firewall, libere o que está na etapa 03 antes de ir à loja.

Ao subir de versão

A certificação vale para o par nome + versão testado. Ao publicar uma versão nova, atualize o campo Versão na aba TEF/POS dos terminais e confirme com a PayGo se aquela mudança exige recertificação — mexer no fluxo de pagamento normalmente exige; correção em outra área do ERP, não.

Referência

Quando dá errado

Sintoma	Causa provável	O que fazer
“Falha ao inicializar o TEF Digital”	Aba TEF do terminal nunca preenchida (até a 7.4.3), DLL ausente ou PdC não instalado	Atualize para a 7.4.4+, confira a `PGWebLib.dll` na pasta do exe e refaça a instalação do PdC
PIN-pad não é encontrado	Porta acima de COM32, ou cabo USB que não é o do equipamento	Remapeie para a COM livre mais baixa no Gerenciador de Dispositivos
Venda aborta com retorno `-2599`	Existe transação pendente no autorizador	Resolva a pendência no diálogo e refaça a venda — é comportamento correto
“Tipo de pagamento TEF não reconhecido”	Forma de pagamento cadastrada como Cartão TEF	Troque para Cartão de Crédito ou Cartão de Débito
Queda de energia nunca gera desfazimento	Pendência na Inicialização em Não Fazer nada	Mude para Processar Pendentes. Isso não aparece em teste — só na auditoria da adquirente
Passo 31/32 reprovado com `0x121`	Transação Pendente em Confirmar	Mude para Perguntar e refaça respondendo Sim
Passo 31/32 reprovado com `0x3231`	O operador respondeu Não no diálogo	Refaça respondendo Sim — `0x3231` é o passo 37, não o 31/32
Comprovante não imprime	Impressora ESC/POS do terminal não configurada	Configurações › Terminais › aba Configurações › ESC/POS
Não conecta, sem mensagem clara	DLL do ambiente errado, TLS 1.2 desabilitado ou porta 31735 fechada	Confira a DLL (`_CERT` só fala com sandbox) e a lista de rede da etapa 03

Nenhum sintoma bate com esse texto. Tente por uma palavra só — COM32, pendente, DLL — ou limpe o filtro.