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

Resumo do que será ensinado

Neste documento você aprenderá, de forma estruturada, como iniciar uma transação de pagamento via API ConnectTEF em um POS já vinculado ao seu PDV/ERP. Vamos detalhar o fluxo completo de pagamento, os parâmetros obrigatórios e opcionais, como montar o JSON da requisição, qual é a resposta imediata da API e como interpretar o retorno enviado via Webhook após a finalização da transaçã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 para enviar pedidos de pagamento ao POS vinculado, tratar corretamente a resposta assíncrona via Webhook e registrar o resultado da transação (aprovada, cancelada ou com falha), garantindo segurança, rastreabilidade e coerência com o fluxo oficial da documentação do ConnectTEF.

Segue o detalhamento de como realizar Pagamento via API ConnectTEF

1. Pré-requisitos antes de usar o endpoint de Pagamento

   • Ter o POS (SmartPOS) já vinculado ao PDV/ERP pelo fluxo de Vinculação:
     • Ou seja, você já deve possuir:
     • O numeroSerie (identificador da automação, por exemplo caixa001).
     • O CPFCNPJ do estabelecimento, obtido na vinculação.
     • O Webhook configurado e testado.
   • Ter o certificado digital de cliente X.509 válido configurado (mTLS), pois todas as chamadas à API ConnectTEF exigem esse certificado para autenticação mútua.
   • Ter um endpoint de Webhook público pronto para receber o resultado final da transação.

   Pontos de atenção

   • Sem vinculação e sem certificado válido, o pagamento não funcionará corretamente.
   • O sistema deve estar preparado para trabalhar com fluxo assíncrono, já que o resultado não é devolvido na mesma chamada.

2. Objetivo do endpoint de Pagamento

   • O endpoint de Pagamento inicia uma transação de venda em um POS vinculado ao PDV.
   • Ele envia ao POS:
     • Valor da transação.
     • Tipo de pagamento (crédito, débito, PIX etc.).
     • Quantidade de parcelas.
     • Dados adicionais da venda (comanda, identificador etc.).
   • Após o cliente concluir o pagamento no POS, o resultado completo é enviado para o Webhook definido na requisição.

   Ponto importante

   • A chamada ao endpoint não retorna o status final da transação; ela apenas confirma que a solicitação foi enviada ao POS. O resultado definitivo chega depois, via Webhook.

3. Fluxo geral do Pagamento (visão passo a passo)

   1. Seu sistema chama o endpoint de Pagamento via API ConnectTEF.
   2. A API:
      • Valida o certificado mTLS.
      • Verifica numeroSerie e CPFCNPJ.
      • Encaminha a transação para o POS vinculado.
   3. O POS:
      • Exibe os detalhes da venda ao cliente (valor, forma de pagamento, parcelas).
      • Processa o pagamento (cartão, PIX, voucher, etc.).
   4. Ao finalizar (aprovado, cancelado ou erro):
      • O ConnectTEF envia um callback HTTP para o seu Webhook com todos os dados da transação (status, valor, bandeira, código de autorização, etc.).

   Pontos de atenção

   • Seu sistema deve:
     • Registrar a identificação da transação ao enviar o pagamento.
     • Aguardar o callback do Webhook para concluir a venda.
     • Atualizar o status interno (aprovado/rejeitado) conforme os dados recebidos.

4. Configuração básica da requisição de Pagamento

   • Método HTTP: POST.
   • Endpoint (integração via API – Pagamento):
     
     • https://apitef.pdvpos.com.br/api/v1/web-service/pagamento.
   • Header obrigatório:
     
     • Content-Type: application/json.
   • Query Params obrigatórios:
     
     • numeroSerie: identificador único da automação/PDV (ex.: caixa001).
     • CPFCNPJ: CPF ou CNPJ obtido na vinculação (campo CPFCNPJ).

   Pontos de atenção

   • Sempre utilize o mesmo numeroSerie e CPFCNPJ configurados na etapa de vinculação para garantir que a transação seja roteada ao POS correto.

5. Campos do corpo da requisição (Body JSON)

   O corpo da requisição é um array JSON de transações. Cada objeto representa uma operação de pagamento. Campos típicos (modelo recomendado pela documentação):

   • identificacao (string, obrigatório):

     • Identificador único da transação no seu sistema (ex.: código da venda, número do pedido).
     • Serve para correlacionar a resposta do Webhook com a venda interna.

   • tipoTransacao (number, obrigatório):

     • Código do tipo de transação (ver lista abaixo).

   • quantidadeParcelas (number, opcional, padrão 1):

     • Número de parcelas em transações de crédito.

   • valorTotal (number, obrigatório):

     • Valor total da transação (ex.: 29.90).

   • imprimirComprovante (bool, opcional, padrão false):

     • Se true, o POS imprime o comprovante da transação.

   • callbackUrl (string, obrigatório):

     • URL do seu Webhook para receber o resultado final da transação.

   • callbackToken (string, opcional):

     • Token que será enviado no header token do Webhook, para você validar que a chamada veio do ConnectTEF.

   • naoExecutar (bool, opcional, padrão false):

     • Se true, a transação não é executada imediatamente; ela é adicionada à lista de cobranças pendentes do POS, permitindo cobrança posterior.

   • textoEspecialCliente (string, opcional):

     • Texto que pode ser exibido no POS quando se usa naoExecutar: true, orientando o operador/cliente.

   • uuidTerminal (string, opcional):

     • UUID do terminal, caso você queira direcionar diretamente a transação para um POS específico.

   • comanda (json, opcional):

     • Estrutura com detalhes da venda (itens, identificador, endereço), exibida no POS.

   Pontos de atenção

   • Defina identificacao de forma única para cada venda para facilitar conciliação e suporte.
   • Utilize callbackToken para aumentar a segurança do seu Webhook.

6. Tabela de tipos de transação (tipoTransacao)

   Os códigos aceitos para tipoTransacao são:

   • 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

   • Verifique se o POS e a adquirente do estabelecimento suportam o tipo de transação selecionado (ex.: número máximo de parcelas, suporte a voucher, etc.).

7. Exemplo completo de requisição de Pagamento

   • URL de exemplo:

     POST https://apitef.pdvpos.com.br/api/v1/web-service/pagamento?numeroSerie=caixa001&CPFCNPJ=42580012000182

   • Body JSON de exemplo:

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

Pontos de atenção

• Perceba que o corpo é um array; você pode enviar uma ou mais transações, conforme sua regra de negócio.
• O campo identificacao será devolvido no Webhook, permitindo associar a transação à venda.

1. Resposta imediata da API após a requisição

   Após enviar o pagamento, a API devolve uma resposta imediata, por exemplo:

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

• status: geralmente "transacao_enviada", confirmando que a operação foi encaminhada ao POS.

• mensagem: texto descritivo.

• referencia: normalmente igual ao valor de identificacao, para você correlacionar com sua venda.

  Pontos de atenção

• Essa resposta não diz se o pagamento foi aprovado; apenas garante que o pedido chegou ao POS.

• Você deve aguardar o Webhook para saber o resultado real.

1. Retorno via Webhook após finalização da transação

   Quando o cliente finaliza o pagamento no POS, o ConnectTEF envia uma requisição ao seu Webhook (método POST) com um JSON contendo os dados da transação, incluindo:

   • executada: true se a transação foi executada no POS (independente de sucesso ou falha).
   • statusTransacao:
     
     • "0" = transação aprovada.
     • Qualquer outro código = falha (ver textoEspecialOperador).
   • textoEspecialOperador: mensagem com a causa do erro, se houver (ex.: “Cartão inválido”).
   • identificacao: mesmo valor enviado na requisição de pagamento.
   • valorTotal: valor processado.
   • bandeiraCartao: bandeira utilizada (VISA, MASTERCARD, etc.).
   • quantidadeParcelas: número de parcelas.
   • nomeRede: nome da rede adquirente (STONEY, CIELO, etc.).
   • cnpj: CNPJ do estabelecimento vinculado ao POS.
   • numeroTransacao: número único da transação na adquirente.
   • codigoAutorizacaoTransacao: código de autorização fornecido pela adquirente.
   • dataTransacaoComprovante: data da transação (formato ddMMyyyy).
   • horaTransacaoComprovante: hora da transação (formato hhmmss).
   • razaoSocial: razão social do estabelecimento no POS.
   • timestampTransacaoHost: timestamp da transação na processadora.

   Pontos de atenção

   • Use statusTransacao e textoEspecialOperador para definir se a venda foi concluída com sucesso ou se precisa de tratamento especial.
   • Armazene numeroTransacao e codigoAutorizacaoTransacao para conciliação financeira e auditoria.

2. Interpretando exemplos de sucesso e falha

   • Exemplo de sucesso no Webhook:

     "executada": true,
     "statusTransacao": "0",
     "textoEspecialOperador": "Transação aprovada"
   

   • Significa que a transação foi executada e aprovada pela adquirente.

     • Exemplo de falha:

     "executada": true,
     "statusTransacao": "1001",
     "textoEspecialOperador": "Cartão inválido"
   

   • A transação foi executada no POS, mas não foi aprovada (motivo especificado em textoEspecialOperador).

   Pontos de atenção

   • Seu sistema deve tratar tanto o estado de execução (executada) quanto o resultado (statusTransacao).
   • Em falhas, é recomendável registrar o motivo e permitir novo pagamento ou outra forma de cobrança.

3. Boas práticas de implementação no seu sistema

   • Persistência de dados:
     • Salvar identificacao, numeroTransacao, codigoAutorizacaoTransacao, statusTransacao, valorTotal e bandeiraCartao.
   • Controle de fluxo:
     • Não finalize a venda (nota fiscal, baixa de estoque, etc.) antes de receber o Webhook.
   • Segurança do Webhook:
     • Valide o callbackToken enviado no header token.
     • Restrinja acesso ao endpoint apenas ao ConnectTEF na sua infraestrutura (firewall, WAF).
   • Logs e monitoramento:
     • Logar requisições de pagamento e Webhooks recebidos para auditoria e suporte.

4. Próximos passos após implementar Pagamento

   • Após dominar o fluxo de Pagamento, a documentação recomenda seguir para:
     
     • Estorno: como desfazer transações autorizadas, usando endpoint próprio.
     • Testando via Postman: como simular chamadas da API para validar o comportamento do seu sistema em ambiente controlado.
   • Use o mesmo padrão (numeroSerie, CPFCNPJ, Webhook, token) para esses demais fluxos, mantendo consistência.

   Pontos de atenção

   • Tenha clareza de que Pagamento e Estorno são complementares: um registra a cobrança, o outro a reversão, ambos orientados pelo ConnectTEF via API.

Informações Importantes

• Função do endpoint de Pagamento: iniciar transações de venda em POS vinculados, usando numeroSerie e CPFCNPJ da vinculação.
• Fluxo assíncrono:
  • A solicitação de pagamento é enviada via API.
  • O resultado final vem apenas via Webhook.
• Segurança (mTLS + token):
  • Todas as chamadas exigem certificado digital de cliente.
  • O Webhook pode (e deve) usar callbackToken para validar a origem.
• Campos críticos:
  • identificacao: chave de ligação entre seu sistema e a transação TEF.
  • statusTransacao: "0" = sucesso; outros códigos = falha.
  • textoEspecialOperador: explica o erro, quando houver.
• Benefícios de seguir corretamente o procedimento:
  • Pagamentos integrados de forma segura, rastreável e padronizada.
  • Menos erros operacionais e maior facilidade de conciliação financeira.
  • Base sólida para adicionar funcionalidades como estorno, relatórios e automações de venda.
• Recomendações gerais:
  • Utilize este documento como referência na sua base de conhecimento interna para treinar desenvolvedores e equipe de suporte.
  • Siga sempre a ordem da documentação oficial: Vinculação → Pagamento → Estorno → Testes.
  • Mantenha sua infraestrutura e certificados sempre atualizados, evitando erros de conexão e segurança.

Este texto está pronto para ser colado em um documento Word. Aplique o padrão visual da sua base de conhecimento: título com fonte 34, demais cabeçalhos com fonte 18, e o corpo em fonte menor, mantendo os pontos críticos em negrito para facilitar a leitura por iniciantes.