Card de pagamento

Use ordens de pagamento para enviar uma cobrança ao Smart TEF e acompanhar seu ciclo até a conclusão, rejeição, cancelamento ou estorno.

Headers

Nome	Descrição	Valor
`Authorization`	Token JWT da loja.	`Bearer {token}`
`ocp-apim-subscription-key`	Gateway Token recebido na criação da loja.	`{subscription-key}`
`Content-Type`	Formato do corpo da requisição.	`application/json`

Mais detalhes sobre os tokens em Autenticação.

Criar pagamento

POST https://api.smarttef.mobi/commands/order/create

Esses cards podem ser enviados para um ou mais POS com a finalidade de realizar um pagamento.

Exemplo de body para um card do tipo normal:

{
  "value": 1.0,
  "payment_type": "DEBIT",
  "installments": 1,
  "charge_id": "Identificador único",
  "order_type": "NRM",
  "extras": {
    "CPF": "000.000.000-00",
    "Nome": "Teste da Silva"
  },
  "has_details": true
}

Campo	Tipo	Obrigatório	Descrição
`value`	`number`	Sim	Valor do pagamento, com separador decimal.
`payment_type`	`string`	Não	Tipo do pagamento. Veja tipos de pagamento.
`fee_type`	`string`	Não	Em crédito, define quem paga os juros: `F_STORE` ou `F_CLIENT`.
`installments`	`number`	Não	Quantidade de parcelas. Padrão `1`. Acima de 1, só com `payment_type` igual a `CREDIT`.
`min_installments`	`number`	Não	Menor quantidade de parcelas permitida.
`charge_id`	`string`	Não	Identificador do card criado pelo ERP.
`order_type`	`string`	Não	`CRD_UNICO` para exibir imediatamente ou `NRM` para lista.
`user_id`	`number`	Condicional	Usuário que receberá o card quando `order_type` for `CRD_UNICO`. Não pode ser enviado junto com `serial_pos`.
`serial_pos`	`string`	Condicional	Serial do POS que receberá o card quando `order_type` for `CRD_UNICO`. Não pode ser enviado junto com `user_id`.
`extras`	`object`	Não	Campos extras como `CPF`, `CNPJ` e `Nome`.
`has_details`	`boolean`	Não	Define se os detalhes extras podem ser exibidos em tela auxiliar.
`form`	`object`	Não	Formulário associado ao pagamento, quando aplicável.

Regras de pagamento

Tema	Regra
Valor	`value` deve ser maior ou igual a `1` e aceitar no máximo duas casas decimais.
Parcelas	`installments` deve ser maior que zero. Parcelamento maior que uma parcela só deve ser usado com `payment_type: "CREDIT"`.
Parcela mínima	`min_installments` só se aplica a crédito e não pode ser maior que `installments`.
Juros	`fee_type` se aplica a crédito parcelado. Em crédito com mais de uma parcela e sem `fee_type`, a API assume `F_STORE`.
Dados extras	`extras.CPF` e `extras.CNPJ` podem ser enviados com ou sem pontuação. Use `Nome` com até 80 caracteres.
Duplicidade	`charge_id` deve ser único para ordens pendentes, processando ou em fluxo de estorno na mesma loja.
Formulário agregado	Quando `form` for enviado na criação do pagamento, o retorno inclui os dados do formulário vinculado ao pagamento.

Retorno da criação

{
  "payment_identifier": "019c964f-5ecf-7889-97c2-1121e6f65f5c",
  "payment_status": "PDT",
  "order_type": "NRM",
  "charge_id": "966",
  "form": {
    "form_identifier": "019c964f-5eca-7a15-a1b4-433e8ae004f8",
    "form_status": "PDT",
    "order_type": "NRM",
    "form_url": "https://storage.example.com/smart-tef/form-818",
    "form_name": "form-818",
    "fill_out_type": "REQUEST_MANDATORY_FORM"
  }
}

Campo	Descrição
`payment_identifier`	Identificador único gerado para cada card.
`payment_status`	Status atual do card.
`order_type`	Tipo do card, único ou normal.
`charge_id`	Identificador informado pelo ERP.
`form`	Dados do formulário anexado, quando houver.

Veja o contrato completo em Criar pagamento.

Consultar pagamento

POST https://api.smarttef.mobi/pooling/order/get

Envie ao menos um dos parâmetros abaixo. Enviando os dois, a API aplica os dois filtros ao mesmo tempo.

{
  "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7"
}

Ou:

{
  "charge_id": "1"
}

Campo	Tipo	Obrigatório	Descrição
`charge_id`	`string`	Condicional	Identificador do ERP. Pode retornar vários cards relacionados.
`payment_identifier`	`string`	Condicional	Identificador do pagamento, em UUID. Retorna apenas o card informado.

A resposta é sempre uma lista. Se nenhum card for encontrado, a API responde 400 com a mensagem payment order not found.

Exemplo de retorno de consulta

[
  {
    "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7",
    "cnpj": "99999999999999",
    "create_at": "2026-02-12T14:43:53.336Z",
    "update_at": "2026-02-12T14:44:53.336Z",
    "value": "10",
    "payment_value": null,
    "payment_date": null,
    "autorization_code": null,
    "order_type": "NRM",
    "payment_type": "OTHERS",
    "payment_status": "PDT",
    "card_brand": null,
    "installments": 1,
    "nsu_host": null,
    "nsu_sitef": null,
    "acquirer": null,
    "serial_pos": "",
    "user_id": 0,
    "payment_extras": null,
    "extras": {
      "CPF": "",
      "Nome": ""
    },
    "has_details": true,
    "type": "PAYMENT",
    "charge_id": "313",
    "controle_versao": null,
    "conn_type": null,
    "batt_level": null,
    "charging": null,
    "location": {
      "lat": "",
      "long": ""
    },
    "reason": null,
    "refund_autorization_code": null,
    "refund_serial_pos": null,
    "refund_user_id": null,
    "coupon": null,
    "refound_coupon": null,
    "fee_type": null,
    "refund_date": null,
    "acquirer_cnpj": null
  }
]

Importante

Campos preenchidos pela adquirente podem retornar null até a conclusão da transação.

Campos de retorno

Campo	Descrição
`payment_identifier`	Identificador único gerado para cada card.
`cnpj`	CNPJ da loja que receberá o pagamento.
`create_at`	Data da criação do card.
`update_at`	Data da última atualização.
`value`	Valor solicitado no pagamento.
`payment_value`	Valor efetivamente pago no Smart POS.
`payment_date`	Data do pagamento.
`autorization_code`	Código de autorização do pagamento.
`order_type`	`CRD_UNICO` ou `NRM`.
`payment_type`	Tipo do pagamento.
`payment_status`	Status atual do card.
`card_brand`	Nome da bandeira.
`installments`	Número de parcelas.
`nsu_host`	NSU atribuído pelo host da adquirente.
`nsu_sitef`	NSU atribuído pelo SiTef.
`acquirer`	Nome da adquirente.
`serial_pos`	Serial do POS que realizou a transação.
`user_id`	ID do usuário que realizou a transação.
`payment_extras`	Dados extras recebidos no processamento do pagamento.
`extras`	Campos extras enviados pelo ERP.
`has_details`	Indica se `extras` pode ser exibido no app.
`type`	Tipo do card. Para pagamento, será `PAYMENT`.
`charge_id`	Identificador do card criado pelo usuário.
`controle_versao`	Versão do app Smart TEF.
`conn_type`	Tipo de conexão do terminal.
`batt_level`	Percentual de bateria.
`charging`	Indica se o terminal está no carregador.
`location.lat`	Latitude do terminal.
`location.long`	Longitude do terminal.
`reason`	Motivo da rejeição, quando houver.
`refund_autorization_code`	Código de autorização do reembolso.
`refund_serial_pos`	Serial do POS que realizou o reembolso.
`refund_user_id`	ID do usuário que realizou o reembolso.
`coupon`	Links para comprovantes do pagamento.
`refound_coupon`	Links para comprovantes do estorno.
`fee_type`	Tipo de juros em crédito: `F_STORE` ou `F_CLIENT`.
`refund_date`	Data do reembolso.
`acquirer_cnpj`	CNPJ da adquirente.

Veja o contrato completo em Consultar pagamento.

Listar pagamentos

POST https://api.smarttef.mobi/pooling/order

Lista os cards da loja atualizados dentro de uma janela de 24 horas.

{
  "datetimeInitial": "2026-02-09 00:00:00",
  "datetimeFinal": "2026-02-10 00:00:00"
}

Campo	Tipo	Obrigatório	Descrição
`datetimeInitial`	`string`	Sim	Início da janela, no formato `YYYY-MM-DD HH:MM:SS`.
`datetimeFinal`	`string`	Sim	Fim da janela, no formato `YYYY-MM-DD HH:MM:SS`. Precisa ser exatamente 24 horas depois de `datetimeInitial`.

A janela precisa ter exatamente 24 horas, com tolerância de 1 segundo. Qualquer outro intervalo é recusado.
O filtro é aplicado sobre update_at, não sobre a data de criação.
A lista pooling traz pagamentos, impressões e formulários independentes. Use o campo type de cada item para distinguir PAYMENT, PRINT e FORM.
pooling_time indica o intervalo recomendado, em segundos, entre uma listagem e a próxima.

Veja o contrato completo em Listar pagamentos.

Cancelar pagamento pendente

POST https://api.smarttef.mobi/commands/order/status/cancelar

O cancelamento só será possível enquanto o pagamento estiver pendente e o processamento no POS ainda não tiver sido iniciado.

{
  "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7"
}

Retorno do cancelamento

{
  "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7",
  "payment_status": "CAN_ERP",
  "order_type": "NRM"
}

Campo	Descrição
`payment_identifier`	Identificador único gerado para cada card.
`payment_status`	Status atual do card.
`order_type`	Tipo do card, único ou normal.

Veja o contrato completo em Cancelar pagamento pendente.

Solicitar estorno

POST https://api.smarttef.mobi/commands/order/status/estornar

Use este endpoint para solicitar a reversão de uma transação já concluída. Depois da solicitação, acompanhe o status por consulta ou webhook até EST ou REJ_EST.

{
  "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7"
}

Importante

Pagamentos PIX processados pela PagSeguro, Getnet, Stone, Vero, SafraPay ou Sipag não podem ser estornados. Nesse caso, a API recusa a solicitação e o card não é enviado ao terminal. Os outros meios de pagamento dessas adquirentes continuam liberados.

Retorno do estorno

{
  "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7",
  "payment_status": "SOL_EST",
  "order_type": "NRM"
}

Campo	Descrição
`payment_identifier`	Identificador único gerado para cada card.
`payment_status`	Status atual do card.
`order_type`	Tipo do card, único ou normal.

Estorno recusado

{
  "status": 400,
  "data": {
    "message": "Estorno indisponível para pagamentos PIX processados pela PagSeguro.",
    "error_code": "PIX_REFUND_NOT_SUPPORTED",
    "acquirer": "PAGSEGURO",
    "payment_identifier": "68ab8366-29db-438e-9a39-8ca72691c0b7",
    "timestamp": "2026-02-09T12:00:00.000Z",
    "path": "/commands/order/status/estornar"
  }
}

Trate a recusa pelo error_code PIX_REFUND_NOT_SUPPORTED, não pelo texto de message, que muda conforme a adquirente. acquirer traz o valor gravado no pagamento: PAGSEGURO, GETNET, STONE, VERO, SAFRA ou SIPAG.

Veja o contrato completo em Solicitar estorno.

Card de pagamento

On this page