TEF Mobile ⭐

O módulo mais direto: seu sistema solicita o pagamento, o Smart POS processa.

O Smart POS opera como um terminal TEF integrado ao seu sistema — sem Pinpad externo, sem operação manual de valor. O operador só confirma e aproxima/insere o cartão.

Endpoints#

Validando no portal antes de integrar#

No Portal do Cliente, você pode criar e acompanhar transações TEF Mobile sem escrever código — útil para validar o fluxo completo no seu ambiente de homologação antes de iniciar a integração.

Iniciando uma transação#

Defina qual Smart POS receberá a transação e faça a requisição:

curl --request POST \
  --url 'https://api.pinpdv.com.br/pos-venda' \
  --header 'Authorization: Bearer {SEU_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "PinPdvId": 1,
    "Identificador": "pedido-001",
    "Valor": 100.11,
    "Descricao": "Pedido #001",
    "TipoPagamento": 2,
    "Parcelas": 1
  }'

200 - OK

{
  "id": 61239,
  "identificador": "pedido-001",
  "descricao": "Pedido #001",
  "valor": 100.11,
  "parcelas": 1,
  "expiraEm": "2026-06-12T09:31:00-03:00",
  "tipoPagamento": 2,
  "pagamentoTipo": { "key": 2, "value": "Credito" },
  "status": { "key": 0, "value": "Aguardando" },
  "situacao": { "key": 0, "value": "Aguardando" },
  "vendas": []
}

A resposta já traz a solicitação criada em Aguardando, com o array vendas vazio — ele será preenchido quando o pagamento for processado.

O Identificador é definido pelo seu sistema — use o ID do pedido ou qualquer referência única. Você vai usá-lo para consultar o status.

Acompanhando o status#

Depois de iniciar a transação, você precisa saber o que aconteceu — se o pagamento foi aprovado, negado ou se o operador abandonou a operação. Há duas formas de receber esse retorno; escolha a que melhor se encaixa no seu sistema:

Webhook (o PINPDV avisa você)#

Cadastre uma URL de webhook no Portal do Cliente PINPDV. A partir daí, o PINPDV chama sua URL via POST automaticamente a cada mudança na venda — criação, atualização de status e conclusão — enviando o mesmo conteúdo da consulta de status. É o caminho mais eficiente: dispensa polling e respeita o rate limit naturalmente.

O payload, a ativação da URL e o uso da resposta estão detalhados em Webhook.

Polling (o seu sistema pergunta)#

Se não houver webhook cadastrado, consulte periodicamente o status usando o Identificador definido na criação. Respeite o rate limit de 1 requisição por segundo.

curl --request GET \
  --url 'https://api.pinpdv.com.br/pos-venda/{Identificador}' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

Como interpretar a resposta#

A resposta tem três níveis hierárquicos. Cada nível tem seu próprio status — leia de fora para dentro:

Boas práticas de polling:

• Consulte a cada 1 segundo (respeitando o rate limit)
• Considere pagamento confirmado quando vendas[0].transacoes contiver uma entrada com status.value = "Aprovada" — qualquer outro status de transação (negada, cancelada pelo operador, etc.) deve ser tratado como sem pagamento
• Defina um timeout máximo de espera no seu sistema (ex.: 3 minutos) para lidar com casos em que o operador abandona a operação sem cancelar
• Use o Identificador que você definiu na criação — não o id numérico retornado

Exemplo — pagamento aprovado (o portador tentou o cartão duas vezes: a primeira foi negada, a segunda aprovada — ambas ficam registradas na mesma venda):

200 - OK

{
  "id": 177179,
  "identificador": "TEF-GN-NEGAPROV2-0207171052",
  "valor": 31.50,
  "status": {
    "key": 2,
    "value": "Concluido"
  },
  "vendas": [
    {
      "identificador": "095cd66fd1b14a7197a90a3e4b4ccf3e",
      "valor": 31.50,
      "status": {
        "key": 0,
        "value": "Realizada"
      },
      "transacoes": [
        {
          "valor": 31.50,
          "parcelas": 1,
          "status": {
            "key": 5,
            "value": "Negado"
          },
          "tipoPagamento": 2,
          "dados": {
            "dataHora": "2026-07-02T17:10:54.085",
            "nsu": null,
            "autorizacao": null,
            "bandeira": null,
            "adquirente": null
          }
        },
        {
          "valor": 31.50,
          "parcelas": 1,
          "status": {
            "key": 0,
            "value": "Aprovada"
          },
          "tipoPagamento": 2,
          "dados": {
            "dataHora": "2026-07-02T17:11:14.799",
            "nsu": "000000353",
            "autorizacao": "164550",
            "bandeira": "MASTERCARD",
            "adquirente": "Getnet"
          }
        }
      ],
      "pinPdv": {
        "codigo": "283190",
        "nome": "Getnet 283190"
      }
    }
  ]
}

Exemplo — sem pagamento aprovado (operador cancelou a operação no Smart POS antes de concluir o pagamento):

200 - OK

{
  "id": 177186,
  "identificador": "TEF-GN-CANCEL-0207171239",
  "valor": 9.99,
  "status": {
    "key": 2,
    "value": "Concluido"
  },
  "vendas": [
    {
      "identificador": "b778c9f4e06d4f05944c9913b9b5e299",
      "valor": 9.99,
      "status": {
        "key": 8,
        "value": "Cancelada"
      },
      "transacoes": [
        {
          "valor": 9.99,
          "parcelas": 1,
          "status": {
            "key": 78,
            "value": "CanceladaOperador"
          },
          "tipoPagamento": 3,
          "dados": {
            "dataHora": "2026-07-02T17:12:42.258",
            "nsu": null,
            "autorizacao": null,
            "bandeira": null,
            "adquirente": null
          }
        }
      ],
      "pinPdv": {
        "codigo": "283190",
        "nome": "Getnet 283190"
      }
    }
  ]
}

Repare que, mesmo com status.value = "Concluido" no nível 1 (a requisição terminou de processar), o nível 2 (vendas[0].status.value) já indica "Cancelada" em vez de "Realizada" — sinal de que não houve pagamento, sem precisar nem chegar ao nível 3.

Interrompendo uma transação#

Enquanto o Smart POS não iniciar a transação, é possível cancelar a solicitação pelo sistema:

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/pos-venda/{Identificador}' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Interrupção forçada#

Se precisar interromper uma solicitação TEF MOBILE que já está em processamento utilize o método forçado. Ele exclui a solicitação TEF MOBILE.

Cancelamento de venda já paga#

curl --request DELETE \
  --url 'https://api.pinpdv.com.br/pos-venda/{Identificador}?forca=true' \
  --header 'Authorization: Bearer {SEU_TOKEN}'

202 - Accepted

Envie sua impressão#

Ao concluir a transação, o Smart POS pode imprimir o conteúdo que você enviar — comprovante, cupom ou qualquer texto livre — via webhook ou PUT /comprovante. O fluxo completo (formato, modos de envio e QR Code) está em Impressão.