Funções de PinPad

6.1 Teste da presença de PinPad

É possível verificar a presença do dispositivo PinPad e se ele está operacional. Para tanto, são enviados comandos lógicos de abertura e fechamento do canal de comunicação.

São duas as funções para esta finalidade.

A função original tem o seguinte formato:

int VerificaPresencaPinPad (void)

partir da versão 4.0.114.4, foi criada uma segunda função, onde são enviados menos comandos para o pinpad, e sem que o visor do pinpad ligue/desligue.

int KeepAlivePinPad (void)

Ambas rotinas não possuem parâmetros de entrada, e podem retornar os seguintes valores:

1 - Existe um PinPad operacional conectado ao micro;

0 - Não existe um PinPad conectado ao micro;

-1 - biblioteca de acesso ao PinPad não encontrada;

outro número - erros detectados internamente pela rotina ou pela biblioteca de acesso ao PinPad

6.2 Define mensagem permanente para o PinPad

Permite que seja definida uma mensagem permanente para ser apresentada no PinPad durante o tempo que ele não está em uso. O formato de ativação da rotina é o seguinte:

int EscreveMensagemPermanentePinPad (Mensagem)

Interface ASCII

EscreveMensagemPermanentePinPadA (Resultado, Mensagem)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Mensagem	Entrada,por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad. Recomenda-se que ela possua no máximo 32 caracteres de forma a ser compatível com os PinPad’s existente atualmente em campo.

Para apagar a mensagem e deixar o visor em branco, basta chamar essa função passando o campo Mensagem vazio.

A aplicação, se desejar, pode incluir o caractere ‘|’ (Barra vertical) para indicar uma mudança de linha.

6.3 Leitura da trilha 3 do cartão

Esta função permite que o aplicativo capture uma trilha 3 magnética genérica.

Note que o PinPad deve ter suporte para a leitura da trilha 3.

Não deve ser utilizada para tratamento das transações de pagamento mas apenas para leitura de cartões internos do estabelecimento comercial (p/ex. cartão de supervisor). O formato de ativação é o seguinte:

int LeTrilha3 (Mensagem)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Mensagem	Entrada, por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad.

No retorno, a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém as trilhas através da chamada a função de continuação do processo iterativo.

---

IMPORTANTE: Esta função NÃO pode ser utilizada durante a execução do laço ContinuaFuncaoSiTefInterativo.

---

6.4 Leitura do cartão - rotinas de captura segura

Os rotinas seguintes têm seu funcionamento condicionado a dois pré-requisitos:

1) Configuração do arquivo de chaves .cha no servidor SiTef. Caso a configuração não esteja feita, essas funções retornam o erro 12 (MODO SEGURO NÃO ATIVO).

2) Após a instalação do arquivo de chaves .cha no servidor SiTef, a Automação deve, pelo menos uma vez, se comunicar com o servidor SiTef. Isto é necessário para que a estação PDV faça a baixa dos dados que permitem a execução das rotinas de Leitura do cartão seguro). Para isso, execute um Teste de Comunicação ou uma transação financeira.

int LeCartaoSeguro (Mensagem)

Interface ASCII

LeCartaoSeguroA (Resultado, Mensagem)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Mensagem	Entrada, por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad.

No retorno a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém as trilhas através da chamada a função de continuação do processo iterativo.

Os campos retornados no processo iterativo são os referentes aos campos sensíveis (*2021 a 2046).

Observação:

Estas funções não estão disponíveis para ambientes Mobile. Devido a dificuldades de utilização de entrypoints de funções, e visando facilitar a sua implementação, foi disponibilizada a “Função” 430 que é uma alternativa para utilizar a função “LeCartaoSeguro”.

Esta “Função” segue o fluxo de uma transação “Gerencial” e é acessada através de IniciaFuncaoSiTefInterativo(Ver item “5.2 - Início da transação de Pagamento ou Gerencial”).

• Para utilização da “Função” 430, o parâmetro “Mensagem” a ser exibida no display do pinpad, será solicitada à Automação Comercial no fluxo da transação através do comando 29 (Ver item “5.3.1 - Tabela de códigos de Comando”). Caso não seja fornecida pela Automação, será exibida a mensagem default “PASSE O CARTAO”

• Para leitura do cartão através da função 430, foi incluído o parâmetro adicional “SementeHash”(não utilizada quando a função LeCartaoSeguro é chamada diretamente) que é opcional e será solicitado no fluxo da transação. Se parâmetro “SementeHash” for utilizado, opcionalmente poderá ser fornecida através do parâmetro “ParamAdic” na chamada da função IniciaFuncaoSiTefInterativo, neste caso, não será solicitado no fluxo da transação.

Se solicitado no fluxo da transação através do comando 29 e o parâmetro não é utilizado, retornar o campo vazio.

Caso este parâmetro seja utilizado, os dados retornados para a Automação Comercial serão hash geradas a partir da semente informada (Campo tipo 203x. Ver tabela “Campos que podem ser retornados” abaixo).

Formato do parâmetro em “ParamAdic”:

{SementeHash=XX...XX}

Onde: XX...XX: Máximo 64 caracteres.

---

IMPORTANTE: Essas funções NÃO podem ser utilizadas durante a execução do laço ContinuaFuncaoSiTefInterativo. Para esse tipo de situação existem as versões que fazem o acesso direto a leitora de cartão descritas a seguir.

---

int LeCartaoDiretoSeguro (Mensagem, TipoCampoTrilha1, Trilha1, TipoCampoTrilha2, Trilha2, Timeout, TestaCancelamento)

Interface ASCII

LeCartaoDiretoSeguroA (Resultado, Mensagem, TipoCampoTrilha1, Trilha1, TipoCampoTrilha2, Trilha2, Timeout)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Mensagem	Entrada, por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad.
TipoCampoTrilha1	Saída, por valor	char *	Fixo 12	Indica o tipo de campo ue foi retornado na trilha 1, se ele é mascarado, criptografado ou em Hash.
Trilha1	Saída, por valor	char *	Máx. 128	No retorno contém, caso exista, a Trilha 1 lida
TipoCampoTrilha2	Saída, por valor	char *	Fixo 12	Indica o tipo de campo que foi retornado na trilha 2, se ele é mascarado, criptografado ou em Hash.
Trilha2	Saída, por valor	char *	Máx. 80	No retorno contém, caso exista, a Trilha 2 lida
Timeout	Entrada, por valor	short	Fixo 6	Define o tempo máximo de espera pela passagem do cartão em segundos. Se zero, espera até que o cartão seja passado
TestaCancelamento	Entrada, por valor	Rotina	Não usado	Rotina da aplicação de automação que retorna 0 se é para continuar aguardando pelo cartão e 1 caso deva interromper o processo de aguardar a passagem do cartão

No retorno a rotina devolve o valor 0 (zero) caso tenha sido executada corretamente e um valor diferente de zero em caso de erro ou interrupção.

Para esta rotina específica, os códigos de erro retornados são:

Valor	Descrição
0	Não ocorreu erro
1	Campo de saída insuficiente
2	BIN NAO HABILITADO
3	CNPJ inválido
4	Chave de acesso vencida
5	Versão inválida
6	Chave de criptografia inválida
7	Dados não criptografados com a chave fornecida como parâmetro: a decriptação decriptografia resultou em um número de cartão que não é composto só por dígitos.
8	Dado de entrada inválido

Os campos TipoCampoTrilha1 e TipoCampoTrilha2 indicam o tipo de campo retornado, respeitando o valor estabelecido para os campos sensíveis, com 202x para campos abertos mascarados, 203x para o Hash dos campos, 204x para campos criptografados e 205x. Campos que podem ser retornados:

TipoCampo	Descrição
202x	Campos abertos, mascarados.
203x	Hash dinâmico dos campos
204x	Campos criptografados
205x	Hash fixo dos campos *

x	Campo
1	PAN do cartão
2	Vencimento do cartão (AAMM)
3	Nome do cliente/portador
4	Trilha 1
5	Trilha 2
6	Trilha 3

*As novas implementações devem utilizar o campo 203x, pois o campo 205x devolve um hash criptografado utilizando a chave de criptografia inserida pelo cliente no arquivo .cha. Essa forma de uso (205x) existe apenas por compatibilidade, pois o ideal é utilizar o Hash com Salt (Semente - 203x) uma vez que a informação utilizada para gerar o hash fica escondida apenas dentro das aplicações que o utilizam, tornando o processo de reversão do hash até obter o dado original praticamente impossível de ser executado pela força bruta

---

IMPORTANTE: Essas funções NÃO podem ser utilizadas durante a execução do laço ContinuaFuncaoSiTefInterativo. Para esse tipo de situação existem as versões que fazem o acesso direto a leitora de cartão descritas a seguir.

---

int LeCartaoDiretoSeguroEx (Mensagem, DadosOut, TamDadosOut, Timeout, TestaCancelamento)

Interface ASCII

LeCartaoDiretoSeguroExA (Resultado, Mensagem, DadosOut, TamDadosOut, Timeout)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Mensagem	Entrada, por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad.
DadosOut	Saída, por valor	char *	Variável	Retorna os mesmos dados da rotina LeCartaoDiretoSeguro, concatenados no formato TLV, onde T corresponde ao tipo do campo (tamanho 5), L é o tamanho do campo (tamanho 3) e V é o campo (tamanho do campo)
TamDadosOut	Entrada, por valor	char *	Fixo 6	Tamanho do buffer de DadosOut.
Timeout	Entrada, por valor	short	Fixo 6	Define o tempo máximo de espera pela passagem do cartão em segundos. Se zero, espera até que o cartão seja passado
TestaCancelamento	Entrada, por valor	Rotina	Não usado	Rotina da aplicação de automação que retorna 0 se é para continuar aguardando pelo cartão e 1 caso deva interromper o processo de aguardar a passagem do cartão

int LeTrilhaChipInterativo (Modalidade) LeTrilhaChipInterativoEx (Modalidade, ParamAdic)

Interface ASCII

LeTrilhaChipInterativoA (Resultado, Modalidade)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina.
Modalidade	Entrada, por valor	Int	Fixo	Seleciona o tipo do pagamento: 2 : Débito 3 : Crédito
ParamAdic	Entrada, por valor	char *	Variável	Parâmetros adicionais, como o {SementeHash=XXX..}. É opcional e pode ser vazio

Essas funções funcionam da mesma maneira das LeCartaoSeguro/LeCartaoSeguroA, com a diferença que estas aceitam cartões com chip.

Observação:

Estas funções, “LeTrilhaChipInterativo”, “LeTrilhaChipInterativoEx” e “LeTrilhaChipInt erativoA” não são exportadas para ambiente Mobile. Devido a dificuldades de utilização de entrypoints de funções, neste ambiente, e visando facilitar a sua implementação, foi disponibilizada a “Função” 431 para acesso à função “LeTrilhaChipInterativoEx”. Esta “Função” segue o fluxo de uma transação “Gerencial” e é acessada através de IniciaFuncaoSiTefInterativo(Ver item “3.2 Início da transação de Pagamento ou Gerencial”).

• Para utilização da “Função” 431, o parâmetro “Modalidade”(Tipo do pagamento) e “ParamAdic”(SementeHash), serão solicitados à Automação Comercial no fluxo da transação através do comando 29 (Ver item 3.3.1 Tabela de códigos de Comando).
• Se parâmetro “SementeHash” for utilizado, opcionalmente poderá ser fornecida através do parâmetro “ParamAdic” na chamada da função IniciaFuncaoSiTefInterativo, neste caso, não será solicitado no fluxo da transação. Se solicitado no fluxo da transação através do comando 29 e o parâmetro não é utilizado, retornar o campo vazio.

Caso este parâmetro seja utilizado, os dados retornados para a Automação Comercial serão hash geradas a partir da semente informada (Campo tipo 203x. Ver tabela “Campos que podem ser retornados” acima).

6.5 Leitura de senha

Esta função permite que o aplicativo capture no PinPad uma senha de um cliente de cartão do próprio estabelecimento comercial (cartão proprietário). Não deve, em nenhuma hipótese, ser utilizada para captura de senhas dos cartões tradicionais. Para maiores detalhes, consulte o documento “Acesso a Senha do Cliente para Cartão Proprietário CliSiTef.doc”

int LeSenhaInterativo (ChaveSeguranca)

Interface ASCII

LeSenhaInterativoA (Resultado, ChaveSeguranca)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina
ChaveSeguranca	Entrada, por valor	char *	Fixo 64	Dados gerados por uma biblioteca de segurança fornecida pela Software Express para habilitar a captura da senha do cliente. Neste caso, a CliSiTef poderá interagir com o SiTef para obter ou validar os dados de segurança necessários para a captura

No retorno a rotina devolve os mesmos valores que a rotina de pagamento. O aplicativo obtém a senha através da chamada a função de continuação do processo iterativo.

---

IMPORTANTE : Essas funções NÃO podem ser utilizadas durante a execução do laço ContinuaFuncaoSiTefInterativo. Para esse tipo de situação existem as versões que fazem o acesso direto a leitora de senhas descritas a seguir

---

int LeSenhaDireto (ChaveSeguranca, SenhaCliente)

Interface ASCII

LeSenhaDiretoA (Resultado, ChaveSeguranca, SenhaCliente)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina
ChaveSeguranca	Entrada, por valor	char *	Fixo 64	Dados gerados por uma biblioteca de segurança fornecida pela Software Express para habilitar a captura da senha do cliente. Neste caso, a CliSiTef poderá interagir com o SiTef para obter ou validar os dados de segurança necessários para a captura
Senha	Saída, por valor	char *	Fixo 20	Senha do cliente, em formato criptografado, e que deve ser passada para uma rotina personalizada por cliente para sua descriptografia

No retorno a rotina devolve o valor 0 (zero) caso tenha sido executada corretamente e um valor diferente de zero em caso de erro ou cancelamento pelo usuário.

6.6 Leitura de Confirmação pelo Cliente no PinPad

Estas funções permitem que o aplicativo solicite uma confirmação no PinPad. O formato de ativação é o seguinte:

int LeSimNaoPinPad (Mensagem)

Interface ASCII

LeSimNaoPinPadA (Resultado, Mensagem)

Parâmetro	Tipo	Interface padrão	Interface ASCII	Descrição
Resultado	Saída, por valor	Não usado	Fixo 6	Contém o resultado de resposta à chamada da rotina
Mensagem	Entrada, por valor	char *	Variável	Mensagem a ser apresentada no visor do PinPad.

No retorno a rotina devolve 0 se o cliente pressionou a tecla de Cancelamento, 1 se ele pressionou a tecla de Confirmação e outro valor em caso de erro no acesso ao PinPad.

Notar que essa função não é iterativa ou seja, o controle de execução somente volta para a aplicação após o pressionamento da tecla.

6.7 Define uma mensagem momentânea para o PinPad

Permite que seja definida uma mensagem momentânea para ser apresentada no display do PinPad. O formato de ativação da rotina é:

int EscreveMensagemPinPad (Mensagem)

Parâmetro	Tipo	Interface padrão	Descrição
Mensagem	Entrada, por valor	char *	Mensagem a ser apresentada no visor do PinPad. Recomenda-se que ela possua no máximo 32 caracteres de forma a ser compatível com os PinPad’s existentes atualmente em campo.

Para apagar a mensagem e deixar o visor em branco, basta chamar essa função passando o campo Mensagem vazio.

A aplicação, se desejar, pode incluir o caractere ‘\r’ (carriage return) para indicar uma mudança de linha.

6.8 Leitura de teclas especiais do PinPad

Essa função é utilizada para aguardar o pressionamento de uma tecla no pinpad, retornando seu código correspondente. O formato de ativação da rotina é:

int LeTeclaPinPad (void)

No retorno a rotina devolve:

Valor	Tecla	Descrição
0	[OK] ou [ENTER]	Pressionada a tecla OK ou ENTER
4	[F1]	Pressionada a tecla F1
5	[F2]	Pressionada a tecla F2
6	[F3]	Pressionada a tecla F3
7	[F4]	Pressionada a tecla F4
8	[LIMPA]	Pressionada a tecla LIMPA
13	[CANCELA]	Pressionada a tecla CANCELA
-43	Qualquer outra tecla ou ocorreu algum erro no processo.	Problema na execução de alguma das rotinas no pinpad.

Por questão de segurança, este comando não retorna teclas numéricas, sendo que o pressionamento destas teclas é simplesmente ignorado pelo pinpad durante a execução do comando. Notar que essa função não é iterativa ou seja, o controle de execução somente volta para a aplicação após o pressionamento de uma tecla. Observação sobre o uso desta função para obter as teclas F1, F2, F3 e F4: há alguns pinpads no mercado que não possuem as teclas F1, F2, F3 e F4. Portanto ao utilizar esta função, deve-se deixar um plano B para estes casos.