FAQ ❓

Respostas rápidas às dúvidas mais comuns de quem integra o PINPDV. Para o detalhamento de cada tema, siga os links ao longo das respostas.

Conceito e pré-requisitos#

Preciso de Pinpad ou de algum hardware adicional?#

Não. O PINPDV transforma o próprio Smart POS — maquininha com sistema operacional Android — em terminal de pagamento integrado ao seu sistema, sem Pinpad externo e sem equipamento adicional. Veja Introdução.

O PINPDV funciona na maquininha que o lojista já tem?#

Funciona nos Smart POS homologados das adquirentes suportadas. A lista de dispositivos compatíveis por adquirente está em Adquirentes e Terminais.

O PINPDV é white label?#

Sim. O representante personaliza o produto com a própria marca, configurando a identidade no Portal do Representante PINPDV:

• App: logo e cor
• Portal: logo e cor

E se eu precisar de TEF tradicional (Pinpad em PC)?#

A Multiplus Card também atende TEF tradicional, em quatro modos de integração: TEF Dial, TEF Webservice, DLL com tela e DLL transparente.

Acesso e autenticação#

Como obtenho meu token de integração?#

O token é gerado exclusivamente pelo Portal do Cliente PINPDV (Configurações → Tokens de Acesso → Cadastrar). Não existe endpoint de API para criar tokens. Passo a passo em Primeiros Passos.

O token expira?#

É um token de longa duração — expira apenas na data definida no momento da criação. Além disso, pode ser revogado a qualquer momento pelo próprio responsável, no Portal do Cliente PINPDV. Armazene-o de forma segura; ele vai em todas as requisições no header Authorization: Bearer {token}.

Qual é a URL base da API?#

https://api.pinpdv.com.br. Todas as respostas são em JSON.

Existe limite de requisições (rate limit)?#

Sim: 1 requisição por segundo por token. Acima disso, a requisição pode ser ignorada ou retornar HTTP 429. Seu sistema precisa tratar o 429 com retry e espera de pelo menos 1 segundo. Detalhes em Primeiros Passos.

Módulos e fluxos#

Qual módulo devo usar: TEF Mobile ou Pré-venda?#

• TEF Mobile — um pagamento por vez; seu sistema envia a cobrança e aguarda a conclusão. Ideal para caixa único, checkout, balcão.
• Pré-venda — múltiplas vendas abertas ao mesmo tempo; cada operador finaliza a sua no Smart POS. Ideal para delivery, posto, mesas de restaurante.

A comparação completa está em Introdução.

O que é a Venda Expressa?#

É a venda iniciada diretamente no Smart POS pelo operador, sem o sistema no momento da cobrança. Seu sistema apenas consulta depois — útil para conciliação e auditoria. Não há endpoint para criá-la. Veja Venda Expressa.

Como direciono a transação para um Smart POS específico?#

Pelo campo PinPdvId. No TEF Mobile ele é obrigatório; na Pré-venda é opcional (sem ele, a pré-venda fica disponível para qualquer operador finalizar). Obtenha o id na consulta de dispositivos.

Posso parcelar e escolher o tipo de pagamento?#

Sim. O Valor é obrigatório; o TipoPagamento é opcional — se informado, Parcelas torna-se obrigatório. Os códigos de TipoPagamento estão em Referência.

O PINPDV suporta PIX?#

Sim. O PIX é transacionado pelo PIX da própria maquininha (adquirente). No retorno, o EndToEnd (E2E) do PIX vem no campo autorizacao.

Status e retorno da venda#

Devo usar webhook ou polling?#

Webhook é o recomendado — o PINPDV avisa seu sistema a cada alteração, dispensando consultas e respeitando o rate limit naturalmente. Use polling se não tiver URL pública. Veja Webhook.

Qual a diferença entre Identificador e id?#

O Identificador é definido pelo seu sistema (ex.: o número do pedido) e é o que você usa para consultar o status. O id é o número interno gerado pelo PINPDV. Sempre consulte pelo Identificador.

Uma venda pode ter mais de uma transação?#

Sim, desde que a opção esteja habilitada nas configurações do app PINPDV instalado no Smart POS. Com ela ativa, um pagamento dividido (ou novas tentativas do portador) gera várias entradas no array transacoes, cada uma com seu próprio status. Por isso a consulta de transações é feita pela consulta de venda — veja Transações.

Uma transação negada retorna NSU e autorização?#

Não. Transações negadas não trazem nsu, autorizacao, bandeira e adquirente — a maquininha não devolve esses dados quando rejeita o pagamento.

Impressão#

Como imprimo um documento no Smart POS?#

De duas formas: pela resposta do webhook ou pelo endpoint PUT /comprovante. O conteúdo é texto simples, 38 caracteres por linha. Fluxo completo em Impressão.

Por que o vendaIdentificador da impressão não é o meu identificador?#

Porque o documento é anexado à Venda, que só existe após o pagamento aprovado. O vendaIdentificador é o campo identificador retornado dentro do array vendas na consulta de status — não o identificador que você enviou ao criar a solicitação.

Posso usar \n para quebrar linha no documento?#

Não. O corpo é tratado literalmente — \n, \t etc. seriam impressos como caracteres. Use uma quebra de linha real no corpo da requisição, com Content-Type: text/plain.

Como imprimo um QR Code?#

Insira uma quebra de linha e, na linha seguinte, a URL desejada. O sistema detecta a URL e a converte em QR Code na impressão. Vale para webhook e PUT /comprovante.

A Venda Expressa imprime pelo sistema?#

Não. A Venda Expressa não suporta impressão via sistema (webhook ou PUT /comprovante). Para impressão gerenciada, use TEF Mobile, Pré-venda ou Venda Avulsa.

O que acontece se meu webhook demorar para responder?#

O PINPDV aguarda no máximo 30 segundos; após isso, ocorre timeout e nada é impresso. Não segure a resposta gerando o documento — responda rápido (corpo vazio ou mensagem de espera) e envie o conteúdo depois via PUT /comprovante.

Estorno e cancelamento#

Como cancelo uma solicitação antes do pagamento?#

Enquanto o Smart POS não inicia a transação, use DELETE /pos-venda/{Identificador}. Já em processamento, use a interrupção forçada (?forca=true). Veja TEF Mobile.

Como estorno uma venda já paga?#

Por decisão de segurança, o estorno é feito presencialmente no Smart POS, pelo operador, na seção Cobranças do app PINPDV — não há endpoint de API. Algumas adquirentes não disponibilizam o estorno pelo PINPDV; nesses casos, o estorno é feito direto no app da adquirente.

Adquirentes, fiscal e conciliação#

Quais adquirentes são suportadas?#

As principais do mercado, com dispositivos homologados por adquirente. A lista atualizada (homologadas e em homologação) está em Adquirentes e Terminais.

O retorno do PINPDV atende à NFC-e (pagamento integrado fiscal)?#

Sim. O PINPDV permite que o PDV inicie o pagamento sem intervenção humana e ainda imprime a nota no mesmo equipamento que fez a captura, atendendo aos requisitos fiscais de pagamento integrado de diversos estados. As transações retornam nsu, autorizacao, bandeira, adquirente, valor e dataHora — os dados de vinculação do meio de pagamento, tanto para cartão quanto para PIX (E2E no campo autorizacao).

Como faço a conciliação de recebíveis?#

A consulta de vendas por período (GET /venda com DataInicial/DataFinal) entrega os dados registrados no PINPDV para conferência direto pela API.

Para a conciliação de cartão completa, a Multiplus Card oferece o Conciliador — um produto à parte que cruza:

• Conciliação de vendas — todas as vendas registradas no sistema constam na adquirente?
• Conciliação de taxas — taxa prevista x efetivamente cobrada
• Conciliação bancária — mediante importação de extrato

O PINPDV sozinho não tem acesso às informações de pagamento da adquirente. Documentação do Conciliador em Conciliação.