Primeiros passos

Passo a passo da integração

Veja como conectar seu sistema ao SmartPOS e começar a solicitar pagamentos pelo ConnectTEF.

Antes de seguir

Para executar os exemplos abaixo, gere sua API Key de teste no Portal do parceiro .

Identifique o SmartPOS do cliente

Para solicitar um pagamento, estorno ou impressão, seu sistema precisa informar qual maquininha deve executar a operação.

Para identificar a maquininha, é preciso gerar um QR Code e exibir na tela do seu sistema. O cliente deve abrir o Connect TEF no SmartPOS e ler o QR Code.

Após a leitura, a API enviará os dados da maquininha para o seu webhook. Use o smartposId recebido nas solicitações de pagamento, estorno e impressão.

Notebook exibindo um QR Code enquanto um SmartPOS com a câmera aberta aponta para a leitura do código.

Integração sem SmartPOS físico

Ao gerar o QR Code com uma API Key de teste, a API simula a leitura e envia para o seu webhook dois SmartPOS virtuais: POS-HML-APROVADO e POS-HML-FALHA.

Use o smartposId recebido no webhook para seguir com pagamento, estorno e impressão sem depender de uma maquininha em mãos.

Gere o QR Code

Gere um QR Code para identificar o SmartPOS do cliente. A API retornará o valor no campo qrCode.

POST/qrcode

POST /qrcodecURL

1curl -X POST "https://api.connecttef.com.br/qrcode" \2  -H "x-api-key: <sua_api_key>" \3  -H "Content-Type: application/json" \4  -d '{5    "documentoCliente": "<cpf_ou_cnpj_do_cliente_cadastrado>",6    "referencia": "loja-123-pdv-001"7  }'

Exiba o QR Code

Transforme o valor de qrCode em um QR Code visual e exiba na tela do seu sistema.

O cliente deve abrir o Connect TEF no SmartPOS que será usado nas operações e ler o QR Code.

201 CreatedJSON

1{2  "qrCode": "QR#22b02ed1-fe3c-42b5-9caa-b28f42829a92",3  "referencia": "loja-123-pdv-001",4  "expiresAt": 17877218485}

Receba o smartposId

Após a leitura, a API envia o evento smartpos.identificado para o webhook configurado.

O evento contém o smartposId do SmartPOS que leu o QR Code.

Guarde esse smartposId e informe-o nas solicitações de pagamento, estorno e impressão.

smartpos.identificadoJSON

1{2  "id": "evt_077e529d79f24bdf97f69c3189eedc6b",3  "tipo": "smartpos.identificado",4  "criadoEm": "2026-08-26T05:14:09.201Z",5  "dados": {6    "qrCodeId": "22b02ed1-fe3c-42b5-9caa-b28f42829a92",7    "referencia": "loja-123-pdv-001",8    "documentoCliente": "<cpf_ou_cnpj_do_cliente_cadastrado>",9    "smartposId": "POS-HML-APROVADO",10    "numeroSerieTerminal": "POS-HML-APROVADO",11    "adquirente": "Homologacao"12  }13}

Crie um pagamento

Use o smartposId recebido na identificação e envie o pagamento.

Referência sem prefixo fixo

A referência identifica a tentativa operacional enviada à API, não a venda, pedido, mesa, comanda ou cupom. Gere uma nova referência para cada tentativa, inclusive quando o operador cancelar, o pagamento for recusado, o cliente trocar o cartão ou o sistema enviar uma nova solicitação. Use preferencialmente um UUID começando no primeiro caractere. Algumas adquirentes podem considerar apenas os 10 primeiros caracteres; por isso, não coloque nada antes do UUID. Se precisar identificar a origem, coloque essa informação somente depois do UUID, como sufixo: 550e8400-e29b-41d4-a716-446655440000-INFOPET.

terminalcURL

1curl -X POST "https://api.connecttef.com.br/v1/payments" \2  -H "x-api-key: <sua_api_key>" \3  -H "Content-Type: application/json" \4  -d '{5    "referencia": "550e8400-e29b-41d4-a716-446655440000",6    "documentoCliente": "<cpf_ou_cnpj_do_cliente_cadastrado>",7    "smartposId": "POS-HML-APROVADO",8    "valorCentavos": 200,9    "formaPagamento": "credito",10    "parcelas": 1,11    "modoExecucao": "imediato"12  }'

Receba o webhook

Salve o evento, responda HTTP 2xx rapidamente e finalize a venda apenas quando receber pagamento.aprovado.

pagamento.aprovadoJSON

1{2  "id": "evt_01JZK8EXEMPLO",3  "tipo": "pagamento.aprovado",4  "criadoEm": "2026-07-16T12:00:00.000Z",5  "dados": {6    "referencia": "550e8400-e29b-41d4-a716-446655440000",7    "documentoCliente": "<cpf_ou_cnpj_do_cliente_cadastrado>",8    "valorCentavos": 200,9    "valorFormatado": "2.00",10    "formaPagamento": "credito",11    "parcelas": 1,12    "smartposId": "POS-HML-APROVADO",13    "status": "aprovado",14    "resultadoSmartPOS": {15      "executado": true,16      "codigoStatus": "0",17      "mensagemOperador": "Homologacao aprovada"18    },19    "autorizacao": {20      "codigo": "AUTH-HML-APROVADO",21      "numeroTransacao": "NSU-HML-APROVADO",22      "dadosFinalizacao": "NSU-HML-APROVADO|AUTH-HML-APROVADO|AUTH-HML-APROVADO",23      "tipoPagamento": "credito"24    }25  }26}

Guarde para estorno

Se a operação puder ser estornada depois, salve smartposId e os campos de dados.autorizacao recebidos no evento aprovado.

Solução de problemas

Algo não saiu como esperado? Consulte nossos guias de erro.

Códigos HTTP

Entenda o significado de cada status retornado pela API.

Erros comuns

Códigos de erro específicos e como resolvê-los.

Pronto!

Sua integração básica está funcionando. Para estornos, reenvios e tratamento avançado de webhooks, explore a navegação ao lado.