Referência da API

Solicitar pagamento

Cria uma intenção de pagamento no SmartPOS. A resposta inicial confirma aceite, envio ou fila; a aprovação ou recusa chega depois pelo webhook.

POST

/v1/payments

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": "12345678000195",7    "smartposId": "POS001",8    "valorCentavos": 14990,9    "formaPagamento": "credito",10    "parcelas": 1,11    "modoExecucao": "imediato",12    "comprovante": {13      "imprimir": {14        "cliente": true,15        "loja": true16      },17      "visualizar": {18        "cliente": false,19        "loja": false20      }21    }22  }'

Headers

Campo	Tipo	Descrição
x-api-key	string	Chave de autenticação da integração, gerada no portal do parceiro.obrigatório
Content-Type	header	Use application/json em chamadas com body.obrigatório

Campos do body

Campo	Tipo	Descrição
referencia	string	Identificador único desta tentativa operacional. Gere uma nova referência para cada pagamento enviado à API, inclusive nova tentativa da mesma venda após cancelamento, recusa, troca de cartão ou falha de comunicação. Use um UUID começando no primeiro caractere e não coloque nada antes dele.obrigatório
documentoCliente	string	CPF ou CNPJ do cliente ConnectTEF vinculado aos SmartPOS. Envie preferencialmente somente números.obrigatório
smartposId	string	Obrigatório no modo imediato. No modo manual, pode ser omitido para publicar nos SmartPOS disponíveis do cliente.
valorCentavos	integer	Valor em centavos. Exemplo: 14990 representa R$ 149,90.obrigatório
formaPagamento	string	Opcional. Valores aceitos: credito, debito, pix ou voucher. Se omitido, o SmartPOS usa o fluxo padrão disponível.
parcelas	integer	Número de parcelas quando aplicável. Use 1 para venda à vista ou omita quando não houver parcelamento.
parcelamento	string	Obrigatório quando formaPagamento for credito e parcelas for maior que 1. Valores aceitos: estabelecimento ou administradora.
modoExecucao	string	Use imediato para iniciar no SmartPOS informado. Use manual para criar um card para o operador confirmar. Se omitido, usa imediato.
comanda	object	Dados exibidos no card da fila manual. Obrigatório somente quando modoExecucao for manual.
comprovante	object	Preferências de impressão e preview dos comprovantes do cliente e da loja.

Use referência única desde o primeiro caractere

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 reenviar uma nova solicitação. Algumas adquirentes podem considerar apenas os 10 primeiros caracteres; por isso, use um UUID começando no primeiro caractere e não coloque nada antes dele.

Pode usar sufixo depois do UUID, como 550e8400-e29b-41d4-a716-446655440000-INFOPET. Evite formatos como INFOPET_550e8400-e29b-41d4-a716-446655440000, _MEU_SUFIXO-550e8400-e29b-41d4-a716-446655440000, PEDIDO_0001 ou CAIXA01_0001.

Campos de comanda/manual

Campo	Tipo	Descrição
comanda.identificacao	string	Identificação exibida no card da fila manual, como nome, mesa, senha ou pedido.obrigatório
comanda.itens[].titulo	string	Título do item exibido no card.
comanda.itens[].descricao	string	Descrição complementar do item exibido no card.
comanda.endereco	string	Endereço ou contexto operacional exibido ao operador, quando fizer sentido.

Campos de comprovante

Campo	Tipo	Descrição
comprovante.imprimir.cliente	boolean	Quando true, solicita impressão do comprovante do cliente no SmartPOS.
comprovante.imprimir.loja	boolean	Quando true, solicita impressão do comprovante da loja no SmartPOS.
comprovante.visualizar.cliente	boolean	Quando true, solicita preview do comprovante do cliente, conforme disponibilidade do SmartPOS.
comprovante.visualizar.loja	boolean	Quando true, solicita preview do comprovante da loja, conforme disponibilidade do SmartPOS.

Regras de execução

Campo	Tipo	Descrição
modoExecucao imediato	regra	Inicia a cobrança no SmartPOS informado. Exige smartposId.
modoExecucao manual	regra	Cria um card para o operador iniciar depois. Pode omitir smartposId para publicar nos SmartPOS disponíveis do cliente.
comanda no manual	regra	Obrigatória quando modoExecucao for manual, pois define o conteúdo exibido ao operador.

Resposta inicial

202 Accepted

Resposta inicialimediato

1{2  "referencia": "550e8400-e29b-41d4-a716-446655440000",3  "status": "processando",4  "mensagem": "Pagamento enviado ao SmartPOS.",5  "targets": [6    {7      "smartposId": "POS001",8      "status": "enviado"9    }10  ]11}

Campos da resposta

Campo	Tipo	Descrição
referencia	string	Mesma referência enviada na requisição. Use para consultar, conciliar e deduplicar a operação.obrigatório
status	string	Estado inicial da operação. Não representa aprovação, recusa ou conclusão final.obrigatório
mensagem	string	Mensagem resumida sobre o aceite, envio ou fila inicial da operação.obrigatório
smartposId	string	SmartPOS direcionado pela operação, quando a rota retorna esse campo no nível principal.
targets	array	SmartPOS que receberam ou deveriam receber a solicitação inicial.obrigatório
targets[].smartposId	string	Identificador público do SmartPOS de destino.obrigatório
targets[].status	string	Resultado inicial de publicação para aquele SmartPOS.obrigatório

Responda antes de processar

Salve o evento e retorne HTTP 2xx rapidamente dentro de 1 ou 2 segundos no máximo. A conclusão da venda ou pedido, conciliação ou emissão fiscal devem rodar depois, fora do request do webhook.

Evento recebido

Use o campo tipo para decidir o estado da operação no seu sistema.

Webhookpagamento.aprovado

1{2  "id": "evt_01JZ9VC5HB2FHVNSX6Z0SJ7Q5M",3  "tipo": "pagamento.aprovado",4  "criadoEm": "2026-05-28T14:30:00Z",5  "dados": {6    "referencia": "550e8400-e29b-41d4-a716-446655440000",7    "documentoCliente": "12345678000195",8    "status": "aprovado",9    "valorCentavos": 14990,10    "valorFormatado": "149.90",11    "formaPagamento": "credito",12    "parcelas": 1,13    "smartposId": "POS001",14    "autorizacao": {15      "codigo": "J214KAN5OTM4I58FN5J59EK3NGIAMKSI",16      "numeroTransacao": "533450",17      "dadosFinalizacao": "533450|J214KAN5OTM4I58FN5J59EK3NGIAMKSI|J214KAN5OTM4I58FN5J59EK3NGIAMKSI",18      "tipoPagamento": "credito"19    },20    "resultadoSmartPOS": {21      "executado": true,22      "codigoStatus": "0",23      "mensagemOperador": "Transação autorizada"24    }25  }26}

Eventos

Campo	Tipo	Descrição
pagamento.aprovado	event	Pagamento autorizado no SmartPOS.
pagamento.recusado	event	Pagamento recusado ou não aprovado.

Decisão operacional

Campo	Tipo	Descrição
pagamento.aprovado	decisão	Finalize a venda, baixe o pedido e salve dados.autorizacao.* para eventual estorno.
pagamento.recusado	decisão	Não finalize a venda. Mostre a mensagem do SmartPOS e permita nova tentativa quando fizer sentido.

Propriedades do evento

Campo	Tipo	Descrição
id	string	Identificador único do evento. Use para idempotência, inclusive em reenvio manual.obrigatório
tipo	string	Evento interpretado pelo ConnectTEF. Este é o campo principal para decidir o que fazer no sistema comercial.obrigatório
criadoEm	string ISO 8601	Data e hora em que o ConnectTEF gerou o evento.obrigatório
dados.referencia	string	Referência enviada no request original.obrigatório
dados.status	string	Status normalizado complementar ao tipo. Use para exibição, filtro e relatório.obrigatório
dados.valorCentavos	integer	Valor da operação em centavos.
dados.valorFormatado	string	Mesmo valor em formato decimal com ponto.
dados.formaPagamento	string	Forma de pagamento enviada no request original, quando informada.
dados.parcelas	integer	Quantidade de parcelas enviada ou normalizada no request original.
dados.documentoCliente	string	CPF ou CNPJ do cliente ConnectTEF vinculado à operação.obrigatório
dados.smartposId	string	Identificador público do SmartPOS que executou a operação.
dados.autorizacao.codigo	string	Código de autorização retornado pelo SmartPOS. Salve para conciliação e estorno.
dados.autorizacao.numeroTransacao	string	Número da transação retornado pelo SmartPOS.
dados.autorizacao.dadosFinalizacao	string	Dado técnico de finalização usado em fluxos como estorno.
dados.autorizacao.tipoPagamento	string	Tipo de pagamento interpretado pelo ConnectTEF a partir do retorno do SmartPOS.
dados.resultadoSmartPOS.executado	boolean	Indica se o SmartPOS executou a operação antes de retornar o resultado.
dados.resultadoSmartPOS.codigoStatus	string	Código bruto do SmartPOS, mantido para diagnóstico e conferência.
dados.resultadoSmartPOS.mensagemOperador	string	Mensagem operacional retornada pelo SmartPOS para exibição ou log.

erro.jsonJSON

1{2  "erro": {3    "codigo": "API_KEY_INVALIDA",4    "mensagem": "API key invalida ou inativa.",5    "acao": "Confira se a chave foi copiada do portal do parceiro e se está ativa."6  }7}

HTTP	Código	Quando acontece	Como corrigir
400	`CAMPO_OBRIGATORIO`	Algum campo obrigatório está ausente ou vazio.	Revise referencia, documentoCliente, valorCentavos e modoExecucao antes de reenviar.
400	`CAMPO_INVALIDO`	Algum campo foi enviado com tipo, tamanho ou formato inválido.	Revise o campo indicado em erro.campo antes de reenviar.
400	`DOCUMENTO_CLIENTE_INVALIDO`	documentoCliente não é CPF/CNPJ válido ou o cliente não foi encontrado.	Confira o cadastro do cliente e envie o documento preferencialmente somente com números.
400	`VALOR_INVALIDO`	valorCentavos ou parcelas não é inteiro positivo dentro do limite aceito.	Envie valorCentavos em centavos, sem casas decimais, e parcelas como número inteiro.
400	`FORMA_PAGAMENTO_INVALIDA`	formaPagamento, parcelas ou parcelamento não formam uma combinação aceita.	Use credito, debito, pix ou voucher; em crédito parcelado, informe parcelamento.
400	`SMARTPOS_OBRIGATORIO_MODO_IMEDIATO`	modoExecucao é imediato e smartposId não foi informado.	Liste os SmartPOS do cliente, escolha um smartposId e reenvie a solicitação.
400	`COMANDA_OBRIGATORIA_MODO_MANUAL`	modoExecucao é manual e os dados de comanda não foram enviados.	Envie comanda.identificacao e os dados que devem aparecer no card do operador.
400	`WEBHOOK_NAO_CONFIGURADO`	O parceiro ainda não configurou URL de webhook.	Configure o webhook no portal do parceiro antes de iniciar operações.
401	`API_KEY_NAO_INFORMADA`	O header x-api-key não foi enviado.	Informe a chave da integração no header x-api-key.
401	`API_KEY_INVALIDA`	A chave não existe, foi rotacionada ou está inativa.	Use a chave ativa gerada no portal do parceiro.
403	`CLIENTE_NAO_AUTORIZADO`	A API key não autoriza operação para o cliente informado.	Confira se o cliente pertence ao parceiro da chave utilizada.
404	`SMARTPOS_NAO_ENCONTRADO`	smartposId não pertence ao cliente informado ou não está vinculado.	Use GET /v1/customers/{documentoCliente}/smartpos e selecione um smartposId válido.
409	`REFERENCIA_DUPLICADA`	A referência já foi usada em uma tentativa operacional anterior.	Se está consultando ou conciliando a operação já criada, reutilize o retorno salvo. Se é uma nova tentativa, gere uma nova referência.
500	`ERRO_INTERNO`	A API encontrou uma falha inesperada ao processar a solicitação.	Registre status, referência e corpo da resposta antes de acionar o suporte.

Atenção

Não finalize a venda com a resposta inicial. Finalize apenas quando receber pagamento.aprovado no webhook.

Próximo passo

Receber o resultado finalUse os webhooks para saber se o pagamento foi aprovado ou recusado.