Pesquisar artigos na Base de Dados de Conhecimento

CONNECTTEF – INTEGRAÇÃO VIA API (PAGAMENTO).

Resumo do que será ensinado

Neste documento você aprenderá, passo a passo, como iniciar uma transação de pagamento via API ConnectTEF usando o endpoint de Pagamento. O material explica o fluxo completo de pagamento, parâmetros obrigatórios, corpo da requisição, tipos de transação disponíveis, resposta imediata e como interpretar o retorno enviado via Webhook após a finalização no POS.

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de configurar seu sistema (PDV/ERP/WEB/SaaS) para solicitar pagamentos ao POS vinculado, enviar corretamente todos os parâmetros necessários, receber e tratar o retorno do Webhook, identificando transações aprovadas ou com falha e armazenando as informações relevantes para controle financeiro e de vendas.

Segue o detalhamento de como utilizar o endpoint de Pagamento via API ConnectTEF

Entender o objetivo do endpoint de Pagamento
- O endpoint de Pagamento é responsável por iniciar uma transação de venda em um POS já vinculado ao seu PDV.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- Ao chamar esse endpoint:
  - Seu sistema cria uma solicitação de pagamento.
  - A API ConnectTEF envia a requisição ao POS correspondente.
  - O POS exibe a venda ao cliente (valor, forma de pagamento, parcelas).
  - Após finalização ou erro/cancelamento, o resultado completo é encaminhado ao Webhook configurado.
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
Ponto importante
- Este endpoint não devolve o resultado final da transação na resposta imediata; o status definitivo é enviado via Webhook.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Visão geral do fluxo de pagamento

O fluxo padrão de pagamento via API funciona assim:

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
1. Seu sistema solicita um pagamento através do endpoint de Pagamento.
2. A API ConnectTEF:
  - Valida o certificado mTLS (certificado de cliente).
  - Aceita a requisição.
  - Encaminha a operação ao POS vinculado ao PDV (usando numeroSerie e CPFCNPJ).
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
3. O POS:
  - Exibe os dados da venda ao cliente (valor, tipo de transação, parcelas).
  - Processa o pagamento (cartão, PIX, voucher etc.).
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
4. Após a conclusão (sucesso, cancelamento ou erro):
  - O ConnectTEF envia o resultado completo da transação para o Webhook informado em callbackUrl, incluindo campos como statusTransacao, executada, valorTotal, bandeiraCartao etc.
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Seu sistema deve estar preparado para armazenar a identificação da transação e aguardar o callback do Webhook para atualizar o status da venda.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Configuração da requisição de pagamento
- Método HTTP: POST.
  
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- Endpoint:
  - https://apitef.pdvpos.com.br/api/v1/web-service/pagamento.
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- Headers obrigatórios:
  
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - Content-Type: application/json.
- Query Params obrigatórios:
  
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - numeroSerie: identificador único da automação/PDV (por exemplo: caixa001).
  - CPFCNPJ: CPF ou CNPJ do cliente/estabelecimento, obtido na etapa de Vinculação.
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
- Use sempre o mesmo numeroSerie e CPFCNPJ que foram utilizados e obtidos na vinculação do POS, garantindo consistência entre vínculos e transações.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  .
Campos do corpo da requisição (Body Params)

O corpo da requisição é enviado em formato JSON. A documentação define os campos da seguinte forma:

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- Campos principais:
  - identificacao (string, obrigatório):
  - Identificador único da transação na sua aplicação (ex.: venda-12345).
  - Deve ser utilizado para localizar a venda ao receber o Webhook.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - callbackUrl (string, obrigatório):
  - URL do Webhook que receberá a resposta final da transação.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - callbackToken (string, opcional):
  - Token que será enviado no header token das chamadas ao seu Webhook.
  - Serve para você validar se a chamada veio do ConnectTEF.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - imprimirComprovante (bool, opcional, padrão false):
  - Se true, o POS imprime o comprovante da transação.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - naoExecutar (bool, opcional, padrão false):
  - Se true, a transação não é executada imediatamente e é adicionada à lista de cobranças pendentes do POS (modo cobrança posterior).
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - uuidTerminal (string, opcional):
  - UUID do terminal para direcionar explicitamente a solicitação a um POS específico (quando houver mais de um vinculado).
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - textoEspecialCliente (string, opcional):
  - Texto exibido no POS quando naoExecutar = true, permitindo mostrar instruções ou detalhes adicionais ao cliente.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - valorTotal (number, opcional, padrão 0.00):
  - Valor total da transação (ex.: 29.90).
  - Deve corresponder ao valor da venda no seu sistema.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - quantidadeParcelas (number, opcional, padrão 1):
  - Número de parcelas para transações de crédito.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - tipoTransacao (number, opcional):
  - Código que define a forma de pagamento (crédito, débito, PIX, voucher etc.).
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  - comanda (json, opcional):
  - Estrutura JSON com informações adicionais exibidas no POS, como itens da venda, identificador e endereço.
    
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
Exemplo de JSON de comanda:

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "identificador": "Ismael Almeida",
     "itens": [
       {
         "titulo": "Coca cola",
         "descrição": "Bem gelada"
       }
     ],
     "endereco": "R. Humberto I, 1005 - Vila Mariana"
   }

Pontos de atenção

Use identificacao de forma única em cada venda para facilitar a conciliação entre seu sistema e os dados devolvidos pelo Webhook.
Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
.

Tabela de tipos de transação (tipoTransacao)

Os códigos aceitos para o campo tipoTransacao são:

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- 10 – Cartão de Crédito à Vista.
- 11 – Crédito Parcelado pelo Estabelecimento.
- 12 – Crédito Parcelado pela Administradora.
- 20 – Cartão de Débito.
- 30 – PIX / Carteira Digital.
- 60 – Voucher / PAT.
- 99 – Outras formas de transação.
Pontos de atenção
- Garanta que o tipo de transação definido seja compatível com o meio de pagamento suportado pelo POS e pela adquirente do estabelecimento.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  .

Exemplo completo de chamada de pagamento

Requisição (exemplo):

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- URL:
  POST https://apitef.pdvpos.com.br/api/v1/web-service/pagamento?numeroSerie=caixa001&CPFCNPJ=42580012000182
- Body JSON:

 [
   {
     "identificacao": "abc123",
     "tipoTransacao": 10,
     "quantidadeParcelas": 1,
     "valorTotal": 29.90,
     "imprimirComprovante": true,
     "callbackUrl": "https://webhook.com.br/response",
     "callbackToken": "abc1234",
     "naoExecutar": true,
     "comanda": {
       "identificador": "Ismael Almeida",
       "itens": [
         {
           "titulo": "Coca cola",
           "descrição": "Bem gelada"
         }
       ],
       "endereco": "R. Humberto I, 1005 - Vila Mariana"
     }
   }
 ]

Pontos de atenção

Note que o corpo da requisição é um array de objetos, permitindo o envio de uma ou mais transações na mesma chamada, conforme sua necessidade.
Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
.

Resposta imediata da API (síncrona)
- Ao receber a requisição, a API ConnectTEF devolve uma resposta imediata, indicando que a transação foi encaminhada ao POS:
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

   {
     "status": "transacao_enviada",
     "mensagem": "Transação enviada ao POS",
     "referencia": "abc123"
   }

Campos principais:
- status: normalmente "transacao_enviada", indicando que foi encaminhada ao POS.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
- mensagem: texto explicativo.
- referencia: geralmente igual ao valor de identificacao, permitindo correlacionar com a venda.
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
Pontos de atenção
Esse retorno não indica se a transação foi aprovada; apenas confirma que o pedido foi enviado ao POS.

Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
.

Retorno via Webhook após finalização da transação
- Após o cliente finalizar o pagamento no POS (

Você achou esse artigo útil?

Problema de Comunicação Constante no Conect TEF

Problema de Comunicação Constante no Conect TEF Descrição do Problema O sistema ...
Conect TEF fechando sozinho

Conect TEF fechando sozinho. Descrição do Problema Alguns clientes que utilizam o Co...
Como acessar e cadastrar gerenciador (NOME DO SISTEMA).

Resumo do que será ensinado Neste documento será apresentado, de forma detalhada e passo a...
CONNECTEF – MODELO DE IMPLANTAÇÃO AUTÔNOMO (SELF‑SERVICE).

Resumo do que será ensinado Neste documento você vai entender, de forma estruturada e simp...
CONNECTTEF – INTRODUÇÃO À PLATAFORMA.

Resumo do que será ensinado Neste documento você vai entender, de forma clara e estruturad...

Pesquisar artigos na Base de Dados de Conhecimento

CONNECTTEF – INTEGRAÇÃO VIA API (PAGAMENTO).

Você achou esse artigo útil?

Artigos relacionados

Problema de Comunicação Constante no Conect TEF

Conect TEF fechando sozinho

Como acessar e cadastrar gerenciador (NOME DO SISTEMA).

CONNECTEF – MODELO DE IMPLANTAÇÃO AUTÔNOMO (SELF‑SERVICE).

CONNECTTEF – INTRODUÇÃO À PLATAFORMA.