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`	Bearer Token recebido na criação da loja.	`Bearer <token>`
`ocp-apim-subscription-key`	Gateway Token recebido na criação da loja.	`<subscription-key>`
`Content-Type`	Conteúdo da requisição.	`application/json`

Criar pagamento

POST /smarttef/commands/erp/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": false
}

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`	Condicional	Quantidade de parcelas. Obrigatório quando `payment_type` for `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. Quando não enviado, considere o padrão da loja.
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.

Verificar status do card

POST /smarttef/pooling/erp/order/get

Use apenas um dos parâmetros abaixo por requisição.

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

Ou:

{
  "charge_id": "1"
}

Campo	Tipo	Obrigatório	Descrição
`charge_id`	`string`	Condicional	Identificador do ERP. Quando usado, o retorno pode ser uma lista com todos os cards relacionados.
`payment_identifier`	`string`	Condicional	Identificador do pagamento. Quando usado, retorna apenas o card informado.

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": false,
    "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.

Cancelar pagamento pendente

POST /smarttef/commands/erp/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.

Solicitar estorno

POST /smarttef/commands/erp/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"
}

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.

Card de pagamento

On this page