Esta operação realiza o envio de dados da automação comercial para o Pin Pad, permitindo a transmissão de informações estruturadas que orientam o comportamento do Pin Pad durante a operação, incluindo cenários de pagamento via Pix com QR Code e QR Code por aproximação, mantendo o dispositivo como um elemento de exibição e interação, sem interferência na lógica transacional.

Entre as principais funcionalidades da operação destacam-se:

Envio de imagens personalizadas para exibição no display do Pin Pad;
Apresentação de instruções visuais para conduzir fluxos do processo de pagamento;
Pix: Acionamento de funcionalidades específicas do dispositivo de acordo com o fluxo da aplicação;
Suporte à customização da experiência do usuário no ponto de interação.

Pagamentos via Pix

Esta operação oferece uma funcionalidade específica para pagamentos via Pix, permitindo o envio de dados no padrão EMV® QR Code para a geração de QR Codes dinâmicos integrados à API do banco ou do Provedor de Serviço de Pagamento (PSP). Nesse processo, a automação comercial é responsável por gerar o payload do QR Code de acordo com as especificações da instituição financeira ou do PSP e transmiti-lo ao Pin Pad por meio desta operação.

Após receber os dados, o Pin Pad atua exclusivamente na renderização e exibição do QR Code em sua tela, possibilitando sua leitura pelo dispositivo do portador. Além disso, quando suportado pelo equipamento, a interface NFC pode ser habilitada, permitindo formas alternativas de interação para a conclusão do pagamento por meio de carteiras digitais, como o Google Wallet.

📘
O Pin Pad não realiza qualquer validação, geração ou enriquecimento dos dado s enviados. Toda a responsabilidade pela construção do QR Code EMV, integração com APIs bancárias, definição de valores, identificação da transação e regras de negócio associadas ao pagamento é exclusivamente da automação comercial.

Parâmetros de entrada

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	M	Código da operação a ser realizada: fixo "10" (`CFL_OPER_PPSEND`).
`PPOper`	string	N2	M	Operação a ser executada no Pin Pad. Consulte a tabela de valores de `PPOper`.
`PPImageB64Buffer`	string	AN...100000	O	Imagem codificada em Base64 com tamanho máximo de 100.000 bytes. Obrigatório para `PinpadOper` (`03`, `05`).
`PPImageFile`	string	AN12	O	Nome da imagem com tamanho fixo de 12 caracteres, sendo 8 para o nome e 4 para a extensão (ex.: `EXEMPLOS.PNG`). Obrigatório para `PinpadOper` (`03`, `04`, `05`).
`QrCodeStringBuffer`	string	A...512	O	Payload do QR Code para pagamento Pix. Obrigatório para `PinpadOper` (`01`, `02`).
`QrCodeAid`	string	H...32	O	Aplicação que realizará o pagamento Pix. Obrigatório para `PinpadOper` (`02`).
`QrCodeHostName`	string	A...99	O	HostName responsável pela geração do Pix a ser pago. Obrigatório para `PinpadOper` (`02`).
`PPTextStringBuffer`	string	A...32	O	Texto a ser exibido no display PinPad. Para PinpadOper (08, 10).*
`TimeOut`	string	N02	M	Tempo limite (timeout) para captura da operação.

📘
*Campo PPTextStringBuffer vs display do pin pad

O display do Pin Pad tem 2 linhas de 16 caracteres cada, totalizando o limite de 32 caracteres do campo.

O texto deve ser enviado como uma única string contígua de até 32 caracteres — a aplicação não deve inserir quebras de linha nem distribuir manualmente 16 caracteres por linha;

O próprio Pin Pad é responsável por dividir a string recebida: os primeiros 16 caracteres são exibidos na linha 1, e os caracteres seguintes (posições 17 a 32) na linha 2 — sem respeitar espaços ou limites de palavra;

Caracteres além do 32º (a partir da posição 33) são truncados pelo Pin Pad e não são exibidos;

Exemplo: enviando a string contígua "texto 1texto 2texto 3" (21 caracteres, sem separadores adicionais) em PPTextStringBuffer, o Pin Pad exibe:

Linha 1 (16 caracteres): texto 1texto 2te
Linha 2 (5 caracteres): xto 3

Mensagem de notificação recebida na “callback” da operação

Durante o processamento de uma operação, a biblioteca Client Conecta pode enviar à automação comercial uma ou mais notificações de status ou mensagens informativas relacionadas à execução em andamento. Essas notificações são entregues por meio da função de callback, previamente definida e configurada pela aplicação da automação comercial no momento da invocação da operação.

As mensagens são enviadas de forma assíncrona, permitindo o acompanhamento em tempo real do fluxo de processamento no Pin Pad, incluindo eventos de interação com o portador, exibição de conteúdos ou etapas intermediárias da operação.

Cada notificação é estruturada no formato JSON, encapsulada em uma string, contendo as informações relevantes para interpretação e tratamento por parte da automação, conforme o seguinte padrão:

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	M	Código da operação a ser realizada: fixo "10" (`CFL_OPER_PPSEND`).
`Code`	string	N..2	M	Código de identificação do conteúdo do JSON enviado na função de callback. Contém o código da mensagem de notificação, conforme definido em Mensagens de notificação.
`MsgNotify`	string	A..99	M	Mensagem de notificação gerada durante o processamento da transação.

Dados de Resposta recebido na “callback” da operação

Campo	Tipo	Formato	Presença	Descrição
`Oper`	string	N..3	M	Código da operação a ser realizada: fixo "10" (`CFL_OPER_PPSEND`).
`Code`	string	N..2	M	Código de identificação do conteúdo do JSON enviado na função de callback. Fixo "0" indica que o JSON contém os dados de resposta da operação realizada.
`PPKeyOutput`	string	N...3	O	Tecla do Pin Pad acionada. Confira os valores possíveis para este campo na tabela abaixo.
`PPImageListOutput`	string	A...180	O	Lista dos nomes das imagens existentes no Pin Pad. Nessa lista são retornados apenas os nomes dos arquivos, sem a respectiva extensão.

📘
Para as operações PinpadOper 01 e 02, o Client Conecta recebe da automação o payload do QR Code no padrão EMV®, realiza o processamento necessário para gerar a imagem correspondente e a encaminha ao Pin Pad já renderizada e preparada para exibição ao portador.

👍
Valores possíveis para PPKeyOutput

Nome Valor Descrição
ST_OK 000 Tecla [OK/ENTER] pressionada.
ST_F1 004 Pressionada tecla de função #1.
ST_F2 005 Pressionada tecla de função #2.
ST_F3 006 Pressionada tecla de função #3.
ST_F4 007 Pressionada tecla de função #4.
ST_BACKSP 008 Pressionada tecla de limpar ("backspace").
ST_CANCEL 013 Operação cancelada pelo portador do cartão.

Nome	Valor	Descrição
ST_OK	000	Tecla [OK/ENTER] pressionada.
ST_F1	004	Pressionada tecla de função #1.
ST_F2	005	Pressionada tecla de função #2.
ST_F3	006	Pressionada tecla de função #3.
ST_F4	007	Pressionada tecla de função #4.
ST_BACKSP	008	Pressionada tecla de limpar ("backspace").
ST_CANCEL	013	Operação cancelada pelo portador do cartão.

Retornos

Código	Descrição
`CFL_OK`	Operação realizada com sucesso.
`CFL_ERROR_INVCALL`	Operação não permitida no momento.
`CFL_ERROR_INVPARAM`	Os parâmetros informados são inválidos.

Tabela de operações no Pin Pad

PPOper	Descrição	Campos obrigatórios
01	Pix sem o NFC habilitado.	Solicitação: Oper PPOper QrCodeStringBuffer Timeout Retorna: Oper PPOper Code
02	Pix com o NFC habilitado.	Solicitação: Oper PPOper QrCodeStringBuffer QrCodeAid CodeHostName Timeout Retorna: Oper PPOper Code
03	Carrega uma imagem no Pin Pad. Obs.: É importante verificar os tipos de imagem suportados pelo Pin Pad. Essa informação é obtida no Open da aplicação.	Solicitação: Oper PPOper PPImageB64Buffer PPImageFile Retorna: Oper PPOper Code
04	Exibe uma imagem já carregada no Pin Pad.	Solicitação: Oper PPOper PPImageFile Retorna: Oper PPOper Code
05	Apaga uma imagem do Pin Pad.	Solicitação: Oper PPOper PPImageFile Retorna: Oper PPOper Code
06	Exibe na tela uma imagem já carregada no Pin Pad e, em seguida, encerra a conexão com o dispositivo.	Solicitação: Oper PPOper PPImageFile. Retorna: Oper PPOper Code
07	Retorna a lista de nomes das imagens carregadas no Pin Pad.	Solicitação: Oper PPOper Retorna: Oper PPOper Code PPImageListOutput
08	Exibe um texto personalizado no Pin Pad.	Solicitação: Oper PPOper PPTextStringBuffer Retorna: Oper PPOper Code
09	Exibe na tela uma imagem já carregada no Pin Pad e aguarda uma ação do usuário por meio do acionamento de uma tecla de função do dispositivo.	Solicitação: Oper PPOper PPImageFile Retorna: Oper PPOper Code PPKeyOutput
10	Exibe um texto personalizado no Pin Pad e aguarda o acionamento de uma tecla especial pelo portador. Se PPTextStringBuffer for enviado vazio (""), não atualiza o texto exibido e apenas aguarda a tecla.	Solicitação: Ope PPOper PPTextStringBuffer Timeout. Retorna: Oper PPOper Code PPKeyOutput

Exemplos de requisição e resposta

Carregamento de imagem

Requisição

{ 
  "PPimageFile": "TESTE001.PNG", 
  "PPImageB64Buffer": "iVBORw0KGgoAAAANSUhEUgAAALQAdd", 
  "PPOper": "03", 
  "Oper": "010" 
}

Resposta

{ 
  "Oper": "10", 
  "PPOper": "04", 
  "PPImageFiel": "TESTE001.PNG", 
}

Envio de QR Code Pix (QR Code EMV)

Requisição

{ 
"Oper": "10", 
"PPOper": "01", 
"QrCodeStringBuffer": "00020126330014BR.GOV.BCB. 
PIX011139715179860520400005303986540515. 
005802BR5901N6001C62170513LojaDoRodrigo630485BE", 
"Timeout": "20" 
}

Resposta

{ 
"Oper": "010", 
"Code": "00", 
"PPOper": "01" 
}

Envio de QR Code Pix com NFC (QR Code EMV)

Requisição

{ 
"Oper": "10", 
"PPOper": "02", 
"QrCodeStringBuffer": "00020126330014BR.GOV.BCB. 
PIX011139715179860520400005303986540515. 
005802BR5901N6001C62170513LojaDoRodrigo 
.......................   630485BE", 
"QrCodeAid": "A00000047643276C1FDE7A39B9C05716", 
"QrCodeHostName": "cielo.pix.com.br", 
"Timeout": "20"}

Resposta

 
"Oper": "010", 
"Code": "00", 
"PPOper": "02" 
}

Com texto exibido no display

Requisição

{ 
  "Oper": "10", 
  "PPOper": "10", 
  "PPTextStringBuffer": "TESTE DE STRING PARA O PINPAD   ", 
  "Timeout": "10" 
}

Resposta

{ 
  "Oper": "010", 
  "Code": "00", 
  "PPOper": "10", 
  "PPKeyOutput": "04" 
}

Sem texto exibido no display

Requisição

{ 
  "Oper": "10", 
  "PPOper": "10", 
  "PPTextStringBuffer": "", 
  "Timeout": "20" 
}

Resposta

{ 
  "Oper": "010", 
  "Code": "00", 
  "PPOper": "10", 
  "PPKeyOutput": "07" 
}