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 Pin Pad. Obrigatório para `PinpadOper` (`08`).
`TimeOut`	string	N02	M	Tempo limite (timeout) para captura da operação.

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	ME	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	ME	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.
`PinpadKey`	string	N...3	O	Tecla do Pin Pad acionada.
`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.

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 PPImageKeyOutput

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" 
}