Webhook

Configure um webhook para receber atualizações de status sem depender apenas de consultas por polling.

O webhook é indicado para acompanhar eventos de pagamento e impressão. Para formulários, use a consulta do próprio formulário quando precisar confirmar preenchimento ou cancelamento.

Configurar webhook da loja

POST https://api.smarttef.mobi/manager/store/update

Use o token da loja. Para configurar apenas o webhook, basta enviar webhookUrl; os demais dados cadastrais da loja não são necessários.

{
  "webhookUrl": {
    "url": "https://erp.example.com/webhooks/smart-tef",
    "authorization_token": "Bearer token-do-erp"
  }
}

Campo	Obrigatório	Descrição
`webhookUrl.url`	Sim	URL que receberá os eventos de status. Com a URL vazia, nenhum webhook é enviado.
`webhookUrl.authorization_token`	Não	Valor enviado, sem alteração, no header `Authorization` do callback.

Quando o webhook é enviado

O webhook é disparado quando o POS altera o status de um card. O payload traz o card completo com o status resultante.

Pagamento

Ação no POS	`payment_status` enviado
Inicia o processamento do pagamento	`PROC_PAG`
Conclui o pagamento	`CNC` ou `PARTIAL_PAG`, conforme o status gravado
Rejeita o pagamento	`REJ_PAG`
Libera o card, que volta para a fila	`PDT`
Solicita estorno pelo POS	`SOL_EST`
Inicia o processamento do estorno	`PROC_EST`
Conclui o estorno	`EST`
Rejeita o estorno	`REJ_EST`

Impressão

Ação no POS	`print_status` enviado
Inicia a impressão	`PROC`
Conclui a impressão	`IMP`
Rejeita a impressão	`REJ`

Operações feitas pelo ERP (criação, cancelamento e solicitação de estorno) não disparam webhook, porque o próprio ERP já recebe o resultado na resposta da chamada. Cards criados pela Lupa online também não geram webhook na criação, apenas quando o POS os processa.

O endpoint do parceiro deve responder com sucesso HTTP. Guarde o identificador do card recebido no payload para conciliar eventos duplicados ou reenviados.

Exemplo de payload enviado para pagamento

Quando um POS altera o estado de um card, o Smart TEF envia o JSON correspondente para o webhook configurado.

{
  "acquirer": null,
  "acquirer_cnpj": null,
  "autorization_code": null,
  "batt_level": 58,
  "card_brand": null,
  "charge_id": "570",
  "charging": false,
  "cnpj": "22140418000160",
  "conn_type": 1,
  "controle_versao": "Versão 1.3.4",
  "coupon": null,
  "create_at": "2026-02-25T16:05:56.853Z",
  "extras": {},
  "fee_type": null,
  "form_order": [],
  "grouped_payments": [],
  "has_details": false,
  "installments": 1,
  "location": {
    "lat": "1231311",
    "long": "1231313"
  },
  "min_installments": null,
  "nsu_host": null,
  "nsu_sitef": null,
  "order_type": "NRM",
  "package_name": null,
  "payment_date": null,
  "payment_extras": null,
  "payment_identifier": "019c9631-91d1-72ca-9fdf-aed3a471b92b",
  "payment_status": "PROC_PAG",
  "payment_type": "OTHERS",
  "payment_value": null,
  "reason": null,
  "refound_coupon": null,
  "refund_autorization_code": null,
  "refund_date": null,
  "refund_serial_pos": null,
  "refund_user_id": null,
  "serial_pos": "6502T1",
  "type": "PAYMENT",
  "update_at": "2026-02-25T16:05:58.690Z",
  "user_id": 24,
  "value": "10"
}

Importante

No card de pagamento, a propriedade type será sempre PAYMENT.

Os campos seguem a mesma estrutura descrita em Card de pagamento. Campos enviados pela adquirente podem permanecer null até a conclusão. O payload do webhook também inclui:

Campo	Descrição
`min_installments`	Menor quantidade de parcelas permitida, quando definida na criação.
`package_name`	Pacote do aplicativo Android que processou o card no POS.
`grouped_payments`	Cards originais que foram agrupados no POS para gerar este card. Lista vazia quando não houver agrupamento.
`form_order`	Formulário vinculado ao card. Lista vazia quando não houver.

Lojas com Múltiplos Pagamentos habilitado também recebem partial_payments (lista dos pagamentos parciais) e remaining_payment_amount (valor que ainda falta pagar).

Exemplo de payload enviado para impressão

{
  "cnpj": "22140418000160",
  "create_at": "2026-02-25T16:13:46.286Z",
  "file": "https://storage.example.com/smart-tef/019c9638-print.png",
  "has_details": true,
  "location": {
    "lat": "12",
    "long": "12"
  },
  "order_type": "CRD_UNICO",
  "print_id": "460",
  "print_identifier": "019c9638-bb85-7e8f-8a5a-6899ee9f6f9a",
  "print_status": "PROC",
  "reason": null,
  "serial_pos": "6502T1",
  "type": "PRINT",
  "update_at": "2026-02-25T16:13:50.773Z",
  "user_id": 24
}

Importante

No card de impressão, a propriedade type será sempre PRINT.

Os campos seguem a mesma estrutura descrita em Card de impressão.

Reprocessar webhook

Para reenviar o webhook de um card, use o token da loja:

POST https://api.smarttef.mobi/commands/webhook/send

{
  "identifier": "019c9631-91d1-72ca-9fdf-aed3a471b92b",
  "type": "PAYMENT"
}

Campo	Obrigatório	Descrição
`identifier`	Sim	`payment_identifier` ou `print_identifier` do card.
`type`	Sim	`PAYMENT` ou `PRINT`.

O payload reenviado traz o status atual do card, não estados anteriores.
A resposta de sucesso indica que o reenvio foi enfileirado, não que o seu endpoint recebeu o evento.
Se a loja não tiver webhookUrl.url configurada, nada é enviado, mesmo com resposta de sucesso.

Use o reprocessamento quando o endpoint parceiro estiver indisponível, responder com erro ou precisar receber novamente o evento após correção operacional. Veja o contrato completo em Reprocessar webhook da loja.