Receber retorno
Eventos e decisões
Eventos finais da API SmartPOS para interpretar o resultado de pagamentos, estornos e impressões.
Webhook como fonte de decisão
O resultado final chega no webhook configurado no portal do parceiro. Use o campo tipo para decidir o estado da operação no seu sistema.
Como o resultado chega
| Campo | Tipo | Descrição |
|---|---|---|
| Webhook | HTTP POST | O ConnectTEF envia um POST para a URL configurada no portal do parceiro.obrigatório |
| Resposta esperada | HTTP 2xx | Seu endpoint deve confirmar o recebimento depois de salvar o evento.obrigatório |
Eventos finais
| Campo | Tipo | Descrição |
|---|---|---|
| pagamento.aprovado | event | Pagamento autorizado no SmartPOS. |
| pagamento.recusado | event | Pagamento recusado ou não aprovado. |
| estorno.aprovado | event | Estorno aprovado. |
| estorno.falhou | event | Estorno não concluído por falha operacional. |
| impressao.concluida | event | Solicitação de impressão concluída. |
| impressao.falhou | event | Solicitação de impressão não concluída. |
Exemplos de resultado final
exemplo.txtpagamento.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}Use o tipo como decisão principal
O campo tipo já chega interpretado pelo ConnectTEF. Use status e resultadoSmartPOS como complemento de exibição, log e conciliação.
Guarde os dados para estorno
Para conseguir chamar POST /v1/refunds depois, salve no pagamento.aprovado o smartposId e os campos dados.autorizacao.codigo, dados.autorizacao.numeroTransacao, dados.autorizacao.dadosFinalizacao e dados.autorizacao.tipoPagamento.
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. |
| estorno.aprovado | decisão | Marque o estorno como concluído e vincule ao pagamento original. |
| estorno.falhou | decisão | Mantenha o pagamento original e registre a falha para conferência operacional. |
| impressao.concluida | decisão | Registre a impressão como concluída. Este evento não altera o financeiro da venda. |
| impressao.falhou | decisão | Registre a falha de impressão. Este evento não altera o financeiro da venda. |
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 final 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 pelo ERP, PDV ou automação comercial no request original.obrigatório |
| dados.status | string | Status normalizado complementar ao tipo. Use para exibição, filtro e relatório, não como regra principal.obrigatório |
| dados.valorCentavos | integer | Valor da operação em centavos, quando aplicável ao evento. |
| dados.valorFormatado | string | Mesmo valor em formato decimal com ponto, quando a API consegue determinar o valor da operação. |
| dados.formaPagamento | string | Forma de pagamento enviada no request original, quando informada. |
| dados.parcelas | integer | Quantidade de parcelas enviada ou normalizada no request original, quando aplicável. |
| dados.documentoCliente | string | CPF ou CNPJ do cliente ConnectTEF vinculado à operação.obrigatório |
| dados.smartposId | string | Identificador público do SmartPOS que executou ou tentou executar a operação. |
| dados.autorizacao.codigo | string | Código de autorização retornado pelo SmartPOS em pagamento aprovado. Salve para conciliação e estorno. |
| dados.autorizacao.numeroTransacao | string | Número da transação retornado pelo SmartPOS em pagamento aprovado. |
| 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.pagamentoOriginal | object | Dados do pagamento original retornados no webhook de estorno aprovado quando o estorno nasceu pelo contrato público. |
| 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. |
Resposta inicial não finaliza a venda
A resposta do POST confirma aceite, envio ou fila inicial. A decisão operacional deve usar eventos finais como pagamento.aprovado, pagamento.recusado, estorno.aprovado e impressao.concluida.