PAX - Biblioteca Compartilhada - V108a PDF

Biblioteca Compartilhada para Pinpad -
Especificação Detalhada
Versão 1.08a (15/Abr/2013)
Copyright 2002-2013 © Rede Amex / Redecard / Cielo

Este documento possui informações de propriedade intelectual exclusiva da
Rede Amex / Redecard / Cielo, não podendo ser reproduzido, utilizado ou divulgado por qualquer modo ou meio,
total ou parcialmente, para qualquer fim, sem a devida autorização prévia.
Alterações
Versão Data Responsável Descrição da Alteração

0.91 19/Jul/02 WFM (SETIS) Versão inicial (draft).
0.93 01/Ago/02 WFM (SETIS) Inclui alterações propostas em reunião de 30/Jul com Amex,
Redecard e Visanet.
0.94 17/Ago/02 WFM (SETIS) Preenchimento/evolução geral do documento.
0.95 04/Set/02 WFM (SETIS) Inclui alterações propostas em reunião de 02/Set.
0.96 03/Out/02 WFM (SETIS) Alterações para incluir processamento de cartões Visa Cash.
0.97 24/Out/02 WFM (SETIS) Preenchidos itens vazios sobre VISA Cash.
0.98 13/Nov/02 WFM (SETIS) Incluída opção de arquitetura com seleção prévia do
adquirente.
0.99 24/Jan/03 WFM (SETIS) Incluído tratamento do evento PP_NOTIFY nas funções
“blocantes”.
0.99 13/Mar/03 WFM (SETIS) Alterações para compatibilização da especificação com as
aplicações de TEF discado e Visanet V30.
1.00 21/Ago/03 WFM (SETIS) Alterações nas mensagens de erro.
1.01 02/Out/03 WFM (SETIS) Diversas alterações acordadas entre as redes em Set/03.
1.02 21/Nov/03 WFM (SETIS) Inclusão das funções PP_iStartCheckEvent / PP_iCheckEvent.
1.03 09/Dez/03 WFM (SETIS) Função PP_iStartGetCard volta a ser como na versão 1.01.
1.04 22/Jan/04 WFM (SETIS) PP_CheckEvent retorna PP_MCDATAERR.
1.05 01/Abr/04 WFM (SETIS) Criada PP_StartRemoveCard.
1.05b 26/Jul/04 WFM (SETIS) Pequenas correções em todo o documento
1.05c 03/Ago/04 WFM (SETIS) Incluída função PP_GetDUKPT e DUKPT 3DES.
1.05d 08/Nov/04 WFM (SETIS) Incluído retorno PP_PINBUSY.
1.05e 12/Mai/05 WFM (SETIS) Incluídos comandos PP_StartGenericCmd/PP_GenericCmd.
1.05f 01/Jul/05 WFM (SETIS) Incluído “Transaction Category Code” na tabela de Parâmetros
x AID.
1.05g 05/Ago/05 WFM (SETIS) Todos os tratamentos proprietários do módulo Visanet foram
movidos para outro documento, que será anexo deste.
1.06a 04/Abr/08 WFM (SETIS) Definição das novas funções PP_ChipDirect e
PP_ChangeParameter.
1.07a 08/Fev/11 WFM (SETIS) Melhor detalhamento da criptografia de PAN nas trilhas no
modo de “Comunicação Segura”.
1.07b 03/Mar/11 WFM (SETIS) Inclusão do tratamento de cartões sem contato VISA,
MasterCard e Amex.
1.07b 11/Ago/11 WFM (SETIS) Incluídos TACs para cartões sem contato na Tabela de
Parâmetros x AID.
Versão Data Responsável Descrição da Alteração
1.07b 18/Nov/11 WFM (SETIS) Melhor definição do tamanho do registro da Tabela de
Parâmetro x AID, de forma a garantir compatibilidade com
TEFs antigos.
1.08a 15/Abr/13 WFM (SETIS)  Versão divulgada especialmente para identificar o
mapeamento de chaves definido pela ABECS.
 Alterado PP_StartCheckEvent/PP_CheckEvent para suportar
cartões com chip sem contato.
 Referência à capacidade de processamento de até 100 AIDs
simultâneos.
 Alterações e correções não funcionais para melhor
compreensão da especificação.
ÍNDICE
1. Introdução...................................................................................................................................... 7
2. Arquitetura .................................................................................................................................... 8
2.1. A Biblioteca de Pinpad ........................................................................................................................... 8
2.2. Aplicações internas ao pinpad .............................................................................................................10
3. A Biblioteca de Pinpad .................................................................................................................. 11
3.1. Considerações Gerais...........................................................................................................................11
3.1.1. Formato das funções .............................................................................................................................. 11
3.1.2. Códigos de retorno ................................................................................................................................. 11
3.1.3. Mensagens de erro ................................................................................................................................. 14
3.1.4. Funções “blocantes” ............................................................................................................................... 17
3.2. Funções de Controle ............................................................................................................................18
PP_Open .................................................................................................................................................................. 19
PP_Close................................................................................................................................................................... 20
PP_Abort .................................................................................................................................................................. 21
3.3. Funções Básicas de Pinpad ..................................................................................................................22
PP_GetInfo ............................................................................................................................................................... 23
PP_DefineWKPAN .................................................................................................................................................... 25
PP_Display ................................................................................................................................................................ 27
PP_DisplayEx ............................................................................................................................................................ 28
PP_StartGetKey ........................................................................................................................................................ 29
PP_GetKey................................................................................................................................................................ 30
PP_StartGetPIN ........................................................................................................................................................ 31
PP_GetPIN ................................................................................................................................................................ 33
PP_StartCheckEvent ................................................................................................................................................. 35
PP_CheckEvent ........................................................................................................................................................ 36
PP_EncryptBuffer ..................................................................................................................................................... 38
PP_GetDUKPT .......................................................................................................................................................... 40
PP_StartChipDirect................................................................................................................................................... 41
PP_ChipDirect .......................................................................................................................................................... 43
PP_StartRemoveCard ............................................................................................................................................... 45
PP_RemoveCard ....................................................................................................................................................... 46
PP_StartGenericCmd ................................................................................................................................................ 47
PP_GenericCmd ....................................................................................................................................................... 48
3.4. Funções de processamento de cartão .................................................................................................49
PP_StartGetCard ...................................................................................................................................................... 50
PP_GetCard .............................................................................................................................................................. 52
PP_ResumeGetCard ................................................................................................................................................. 56
PP_ChangeParameter .............................................................................................................................................. 57
PP_StartGoOnChip ................................................................................................................................................... 58
PP_GoOnChip ........................................................................................................................................................... 61
PP_FinishChip ........................................................................................................................................................... 64
3.5. Funções para Manutenção das Tabelas ..............................................................................................67
PP_TableLoadInit ..................................................................................................................................................... 68
PP_TableLoadRec ..................................................................................................................................................... 69
PP_TableLoadEnd..................................................................................................................................................... 70
PP_GetTimeStamp ................................................................................................................................................... 71
4. Tratamentos internos à Biblioteca/Pinpad .................................................................................... 72
4.1. Função PP_StartGetCard / PP_GetCard...............................................................................................72
4.1.1. Cartão magnético ................................................................................................................................... 73
4.1.2. Cartão com chip com contato................................................................................................................. 73
4.1.3. Cartão com chip sem contato ................................................................................................................. 76
4.2. Função PP_StartGoOnChip / PP_GoOnChip ........................................................................................79
4.2.1. Aplicação de Crédito/Débito EMV com contato ..................................................................................... 79
4.2.2. Aplicação Visa Cash sobre TIBC v1 ou v3 ................................................................................................ 80
4.2.3. Aplicação Easy-Entry sobre TIBC v1 ........................................................................................................ 81
4.2.4. Aplicação de Crédito/Débito EMV sem contato ..................................................................................... 81
4.3. Função PP_FinishChip ..........................................................................................................................82
4.3.1. Aplicação de Crédito/Débito EMV com contato ..................................................................................... 82
4.3.2. Aplicação Visa Cash sobre TIBC v1 ou v3 ................................................................................................ 84
4.3.3. Aplicação Easy-Entry sobre TIBC v1 ........................................................................................................ 84
4.3.4. Aplicação de Crédito/Débito EMV sem contato ..................................................................................... 84
4.4. Comunicação Segura ...........................................................................................................................86
4.4.1. Formato de criptografia de PAN ............................................................................................................. 87
4.4.2. Exemplos ................................................................................................................................................ 88
4.4.3. Decodificação das trilhas pelo “checkout” ............................................................................................. 90
4.4.4. Uso de certificado RSA ........................................................................................................................... 90
5. A Biblioteca de Acesso TEF ............................................................................................................ 91
6. Fluxos de operação no “checkout” ................................................................................................ 92
6.1. Transação com cartão magnético ou sem contato simulando tarja (sem senha) ...............................94
6.2. Transação com cartão magnético ou sem contato simulando tarja (com senha) ..............................95
6.3. Tentativa de transação com cartão magnético que possui chip .........................................................96
6.4. Transação com cartão com chip ..........................................................................................................97
6.5. Transação negada pelo cartão com chip .............................................................................................98
6.6. Transação negada pelo cartão com chip após aprovação do Host .....................................................99
6.7. Transação com chip aprovada offline ................................................................................................100
6.8. Fallback de cartão com chip ..............................................................................................................101
7. Tabelas de Parâmetros ............................................................................................................... 102
7.1. Tabela de Parâmetros x AID ..............................................................................................................103
7.1.1. Parâmetros para aplicações padrão EMV............................................................................................. 104
7.1.2. Parâmetros para aplicações padrão Easy-Entry sobre TIBC v1 ............................................................ 106
7.1.3. Parâmetros para aplicações padrão Visa Cash sobre TIBC v1 ou v3 .................................................... 106
7.2. Tabela de Chaves Públicas .................................................................................................................107
7.3. Tabela de Certificados Revogados .....................................................................................................109
8. Protocolo Serial .......................................................................................................................... 110
8.1. Nível de Enlace...................................................................................................................................111
8.2. Nível de Aplicação..............................................................................................................................113
8.2.1. Mensagens de Notificação ................................................................................................................... 114
8.3. Exemplos:...........................................................................................................................................115
9. Funcionalidades Adicionais ......................................................................................................... 117
9.1. Consulta de versões ...........................................................................................................................117
10. Convenções para a plataforma Win32 .................................................................................. 118
10.1. Formato da Biblioteca .......................................................................................................................118
10.2. Arquivo de Configuração ...................................................................................................................118
Apêndice A - Formatos usados no documento..................................................................................... 119
Biblioteca Compartilhada para Pinpad - Especificação Detalhada 1.08a (15/Abr/2013)
1. Introdução
Os sistemas de automação comercial contam com aplicações de “checkout” que são hoje
responsáveis, entre outras coisas, pela aceitação de cartões de pagamento.
Os cartões de pagamento em meio magnético não apresentam complexidade significativa no ponto
de aceitação e são de total domínio técnico dos fornecedores das aplicações “checkout”. Dessa
maneira, a integração de soluções e suas certificações não têm apresentado grandes problemas.
Com o advento dos cartões com chip no Brasil (principalmente no que diz respeito ao padrão EMV), o
processamento de transações de pagamento tornou-se muitas vezes mais complexo do que o feito
com o conhecido cartão magnético, tornando impeditivo o seu desenvolvimento direto pelo
fornecedor de aplicações de “checkout”. Além do alto investimento desse trabalho e do necessário
desvio do foco dessas empresas, a certificação de inúmeras soluções diferentes se tornaria inviável.
Uma solução para esse impasse reside na criação de núcleos de software e hardware capazes de
efetuar todos os complexos tratamentos dos diferentes cartões de pagamento, isentando dessa
responsabilidade os desenvolvedores de aplicações de “checkout” e viabilizando as certificações das
soluções finais.
Este documento destina-se a descrever um núcleo de software capaz de cumprir essa finalidade em
conjunto com um equipamento do tipo “pinpad” para o tratamento, entre outras coisas, dos
seguintes cartões em aplicações de “checkout”:
 Cartão magnético convencional;
 Cartão com chip EMV com contato; e
 Cartão com chip sem contato (Visa, MasterCard e American Express).
Observações:
 Um conhecimento básico da norma EMV é importante para a compreensão deste documento,

sendo que os seguintes documentos serviram de base para sua confecção:
 EMV 4.3 Book 1 (Application Independent ICC to Terminal - Interface Requirements)
 EMV 4.3 Book 2 (Security and Key Management)
 EMV 4.3 Book 3(Application Specification)
 EMV 4.3 Book 4 (Cardholder, Attendant, and Acquirer Interface Requirements)
 Os termos extraídos da norma EMV permanecem em inglês neste documento (em destaque) de
maneira a se evitar a perda de referência e, assim, facilitar sua compreensão.
 Outros documentos necessários:
 PPMChip - MasterCard PayPass M/Chip - Reader Card Application Interface Specification
- Version 2.1 - April 2010.
 PPMagStr - MasterCard PayPass Mag Stripe - Technical Specifications - Version 3.3 -
December 2007.
 VCPS - Visa Contactless Payment Specification - Version 2.0.2 - July 2006 (including
Addtions and Clarifications 3.0 - August 2007).
 ExpPay - Expresspay 2.0.1 - Terminal Specification - August 2010.
Copyright 2002-2013 © Rede Amex / Redecard / Cielo 7/119

2. Arquitetura
Este capítulo destina-se a descrever a arquitetura de software a ser adotada para a Biblioteca de
Pinpad e para as aplicações internas ao pinpad.
2.1. A Biblioteca de Pinpad

Os sistemas de “checkout” acessam os cartões e obtém a senha do portador através de um
dispositivo denominado “pinpad”.
Propõe-se que esse pinpad seja acessível à uma aplicação de “checkout” através de uma biblioteca
(ou interface) padronizada capaz de gerenciar todo os processos necessários para a aceitação de
cartões, sejam eles magnéticos ou com chip.
Cada modelo de pinpad existente possui uma biblioteca distinta que é responsável por tratá-lo de
acordo com seu tipo de interface, protocolo, linguagem e características diversas. A interface de
funções com o aplicativo de “checkout”, entretanto, é sempre a mesma. Esta biblioteca será
doravante denominada “Biblioteca de Pinpad”.
PDV (Intel/PC)
Aplicativo de “checkout”
Outros
funções aplicativos e/ou
padronizadas bibliotecas
Biblioteca
de PIN-pad
Interface Interface Interface Interface
Outros dispositivos, tais como scanner,

impressora, display
PIN-pad
Dessa maneira, o aplicativo de “checkout” acessa somente funções padronizadas de alto nível dessa
biblioteca, não tendo que conhecer os comandos de cada modelo de pinpad bem como tratar todo o
complexo fluxo necessário para o processamento de cartões com chip.

O diagrama a seguir ilustra a arquitetura da Biblioteca de Pinpad, apresentando suas principais

funções e sua forma de interação com outros componentes presentes.
Aplicativo de “checkout”
PP_StartGetCard PP_StartGoOnChip
PP_Open PP_FinishChip PP_Close
PP_GetCard PP_GoOnChip
PP_Display PP_StartGetKey PP_StartGetPIN PP_StartRemoveCard

PP_GetKey PP_GetPIN PP_RemoveCard
Biblioteca de PIN-pad PIN-Pad
Servidor TEF
AIDs aceitos
Conjunto
Funções Biblioteca + PIN-pad
Chaves Públicas
Software House Certif. Revogados
Fornecedor PIN-pad “time-stamps”
Principais características da arquitetura:
 Uma vez que a forma como as funcionalidades descritas neste documento é implementada
depende exclusivamente das características técnicas do pinpad, não é possível estipular o que
deve ser processado internamente ao pinpad e o que deve ser processado pela sua biblioteca.
Assim sendo, todas as funcionalidades aqui descritas serão sempre atribuídas ao conjunto
“Biblioteca + pinpad”.
 O conjunto “Biblioteca + pinpad” deve ser capaz de gerenciar tabelas de parâmetros necessárias
para o processamento de cartões com chip. Estas tabelas estão descritas no Capítulo 7. O local
onde as tabelas são armazenadas depende das características técnicas do pinpad.
 O conjunto “Biblioteca + pinpad” deve ser capaz de armazenar e atualizar um “time-stamp” que
indica a versão das tabelas. Deve-se gerenciar um “time-stamp” único para todas as tabelas e
um “time-stamp” para cada rede adquirente.

2.2. Aplicações internas ao pinpad

Para pinpads que possuem a capacidade de “multi-aplicação”, recomenda-se a adoção de uma
arquitetura onde diversas aplicações independentes possam coexistir, cada uma com seus arquivos
de dados independentes.
Biblioteca de PIN-pad
PIN-pad “multi-aplicação”
Aplicação principal (Gerenciador)
Aplicação “01” Aplicação “02” Aplicação “03”

(Rede Amex) (Redecard) (Cielo)
Tabela de Tabela de Tabela de

Parâmetros x AID Parâmetros x AID Parâmetros x AID

Chaves Públicas Chaves Públicas Chaves Públicas

Certif. Revogados Certif. Revogados Certif. Revogados
“time-stamp” “time-stamp” “time-stamp”
Apesar desta especificação prever a convivência de diversas redes adquirentes em uma única
aplicação, a arquitetura acima é recomendada para casos em que se requer total independência dos
módulos, mesmo que estes sejam inicialmente idênticos e regidos por esta mesma especificação.

3. A Biblioteca de Pinpad
Este capítulo destina-se a descrever detalhadamente a Biblioteca de Pinpad, enfocando sua interface
de acesso.
3.1. Considerações Gerais
3.1.1. Formato das funções

A Biblioteca de Pinpad fornece funções padronizadas com o seguinte formato básico:
int PP_FunctionName (...);
Para compatibilidade das definições da biblioteca entre diversas plataformas, os parâmetros de

entradas e saída serão sempre strings ASCII, de preferência de tamanhos fixos.
As funções possuem dois tipos de parâmetros: os de entrada e os de saída. Como regra, os
parâmetros de saída somente apresentam dados válidos no caso do processamento da função ter
sido bem sucedido.
Tipo Correspondente em linguagem C

Parâmetro de entrada INPUT const char *
Parâmetro de saída OUTPUT char *
3.1.2. Códigos de retorno

Todas as funções da biblioteca, independentemente do que fazem, possuem o mesmo tipo
padronizado de código retorno, conforme a tabela a seguir.
Constante Valor Descrição

PP_OK 0 Operação efetuada com sucesso - parâmetros de retorno
(OUTPUT) contém dados válidos.
PP_PROCESSING 1 Em processamento. Deve-se chamar a função novamente
ou PP_Abort para finalizar.
PP_NOTIFY 2 Em processamento. Deve-se apresentar no “checkout” uma
mensagem retornada pela função e chamá-la novamente
ou PP_Abort para finalizar.
PP_F1 4 Pressionada tecla de função #1.


PP_BACKSP 8 Pressionada tecla de apagar (backspace).
Status de 10 a 29 : Erros básicos da biblioteca
PP_INVCALL 10 Chamada inválida à função. Operações prévias são
necessárias.
PP_INVPARM 11 Parâmetro inválido passado à função.
PP_TIMEOUT 12 Esgotado o tempo máximo estipulado para a operação.
PP_CANCEL 13 Operação cancelada pelo operador.
PP_ALREADYOPEN 14 Pinpad já aberto.
PP_NOTOPEN 15 Pinpad não foi aberto.
PP_EXECERR 16 Erro interno de execução - problema de implementação da
biblioteca (software).
PP_INVMODEL 17 Função não suportada pelo modelo de pinpad.
PP_NOFUNC 18 Função não disponível na Biblioteca do pinpad.
PP_TABEXP 20 Tabelas expiradas (pelo “time-stamp”).
PP_TABERR 21 Erro ao tentar gravar tabelas (falta de espaço, por exemplo)
PP_NOAPPLIC 22 Aplicação da rede adquirente não existe no pinpad.
23 a 29 Reservado para uso futuro
Status de 30 a 39 : Erros de comunicação/protocolo com o pinpad
PP_PORTERR 30 Erro de comunicação: porta serial do pinpad provavelmente
ocupada.
PP_COMMERR 31 Erro de comunicação: pinpad provavelmente desconectado
ou problemas com a interface serial.
PP_UNKNOWNSTAT 32 Status informado pelo pinpad não é conhecido.
PP_RSPERR 33 Mensagem recebida do pinpad possui formato inválido.
PP_COMMTOUT 34 Tempo esgotado ao esperar pela resposta do pinpad (no
caso de comandos não blocantes).
35 a 39 Reservado para uso futuro
Status de 40 a 49 : Erros básicos reportados pelo pinpad
PP_INTERR 40 Erro interno do pinpad.
PP_MCDATAERR 41 Erro de leitura do cartão magnético.
PP_ERRPIN 42 Erro na captura do PIN - Master Key pode não estar
presente.
PP_NOCARD 43 Não há cartão com chip presente no acoplador.


PP_PINBUSY 44 Pinpad não pode processar a captura de PIN
temporariamente devido a questões de segurança (como
quando é atingido o limite de capturas dentro de um
intervalo de tempo).
45 a 49 Reservado para uso futuro.
Status de 50 a 59 : Erros de processamento de cartão com chip (SAM)
PP_SAMERR 50 Erro genérico no módulo SAM.
PP_NOSAM 51 SAM ausente, “mudo”, ou com erro de comunicação.
PP_SAMINV 52 SAM inválido, desconhecido ou com problemas.
53 a 59 Reservado para uso futuro.
Status de 60 a 79 : Erros de processamento de cartão com chip com contato
PP_DUMBCARD 60 Cartão não responde (“mudo”) ou chip não presente.
PP_ERRCARD 61 Erro de comunicação do pinpad com o cartão com chip.
PP_CARDINV 62 Cartão do tipo inválido ou desconhecido, não pode ser
tratado (não é EMV nem TIBC v1).
PP_CARDBLOCKED 63 Cartão bloqueado por número excessivo de senhas
incorretas (somente para Easy-Entry TIBC v1 e moedeiro
VISA Cash).
PP_CARDNAUTH 64 Cartão TIBC v1 não autenticado pelo módulo SAM (somente
para Easy-Entry TIBC v1 e moedeiro VISA Cash).
PP_CARDEXPIRED 65 Cartão TIBC v1 expirado (somente para Easy-Entry TIBC v1 e
moedeiro VISA Cash).
PP_CARDERRSTRUCT 66 Cartão com erro de estrutura - arquivos estão faltando.
PP_CARDINVALIDAT 67 Cartão foi invalidado.
Se o cartão for TIBC v1, quando seleção de arquivo ou ATR
retornar status ‘6284’.
Se o cartão for EMV, quando seleção de aplicação retornar
status ‘6A81’.
PP_CARDPROBLEMS 68 Cartão com problemas. Esse status é válido para muitas
ocorrências no processamento de cartões TIBC v1 e EMV
onde o cartão não se comporta conforme o esperado e a
transação deve ser finalizada.
PP_CARDINVDATA 69 O cartão, seja TIBC v1 ou EMV, comporta-se corretamente
porém possui dados inválidos ou inconsistentes.
PP_CARDAPPNAV 70 Cartão sem nenhuma aplicação disponível para as
condições pedidas (ou cartão é reconhecido como TIBC v1
ou EMV mas não possui nenhuma aplicação compatível com
a requerida).


PP_CARDAPPNAUT 71 Somente para cartão EMV. A aplicação selecionada não
pode ser utilizada (o Get Processing Options retornou
status ‘6985’ ou houve erro no comando Select final), e não
há outra aplicação compatível na lista de candidatas.
PP_NOBALANCE 72 Somente para aplicação de moedeiro. O saldo do moedeiro
é insuficiente para a operação.
PP_LIMITEXC 73 Somente para aplicação de moedeiro. O limite máximo para
a operação foi excedido.
PP_CARDNOTEFFECT 74 Cartão ainda não efetivo, data de ativação posterior à data
atual (somente para moedeiro VISA Cash sobre TIBCv3).
PP_VCINVCURR 75 Moeda inválida (somente para moedeiro VISA Cash).
PP_ERRFALLBACK 76 Erro de alto nível no cartão EMV que é passível de
“fallback” para tarja magnética.
77-79 Reservado para uso futuro
Status de 80 a 99 : Erros de processamento de cartão com chip sem contato
PP_CTLSSMULTIPLE 80 Mais de um cartão sem contato foi apresentado ao leitor
(este código de retorno é opcional e depende da
capacidade do equipamento em detectar esta situação).
PP_CTLSSCOMMERR 81 Erro de comunicação entre o terminal (antena) e o cartão
com chip sem contato.
PP_CTLSSINVALIDAT 82 Cartão foi invalidado (seleção de aplicação retornou status
‘6A81’).
PP_CTLSSPROBLEMS 83 Cartão com problemas. Esse status é válido para muitas
ocorrências no processamento de cartões sem contato em
que o cartão não se comporta conforme o esperado e a
transação deve ser finalizada.
PP_CTLSSAPPNAV 84 Cartão sem nenhuma aplicação disponível para as
condições pedidas (nenhum AID não encontrado).
PP_CTLSSAPPNAUT 85 A aplicação selecionada não pode ser utilizada (o Get
Processing Options retornou status ‘6985’ ou houve erro no
comando Select final), e não há outra aplicação compatível
na lista de candidatas.
86-99 Reservado para uso futuro
3.1.3. Mensagens de erro

Determinados códigos de retorno implicam na apresentação de mensagens de erro, tanto no display
do pinpad como no “checkout”. Convenciona-se que as mensagens de pinpad devem ser formatadas
em 2 linhas x 16 colunas, enquanto as mensagens do “checkout” devem ser formatadas em 1 linha x
32 colunas. Recomenda-se que o “checkout” sempre apresente também o código numérico do erro
para facilitar o suporte e depuração de problemas, como no exemplo:

51 - ERRO PINPAD
A tabela a seguir ilustra as mensagens recomendadas para cada código de retorno:
Constante Mensagem do pinpad Mensagem do “checkout”

PP_INVCALL ERRO PINPAD
PP_INVPARM ERRO PINPAD
PP_TIMEOUT ERRO PINPAD
PP_CANCEL ERRO PINPAD
PP_ALREADYOPEN ERRO PINPAD
PP_NOTOPEN ERRO PINPAD
PP_EXECERR ERRO PINPAD
PP_INVMODEL ERRO PINPAD
PP_NOFUNC ERRO PINPAD
PP_TABEXP (não gera mensagem de erro - ver
PP_ResumeGetCard)
PP_TABERR ERRO PINPAD
PP_NOAPPLIC ERRO PINPAD
PP_PORTERR ERRO PINPAD
PP_COMMERR ERRO PINPAD
PP_UNKNOWNSTAT ERRO PINPAD
PP_RSPERR ERRO PINPAD
PP_COMMTOUT ERRO PINPAD
PP_INTERR ERRO PINPAD
PP_MCDATAERR ERRO DE LEITURA ERRO DE LEITURA TENTE NOVAMENTE
TENTE NOVAMENTE
PP_ERRPIN ERRO PINPAD
PP_NOCARD CARTAO REMOVIDO CARTAO REMOVIDO
PP_PINBUSY PINPAD OCUPADO TENTE NOVAMENTE
PP_SAMERR PROBL.MOD.SAM - LIGUE HELP DESK
PP_NOSAM PROBL.MOD.SAM - LIGUE HELP DESK
PP_SAMINV PROBL.MOD.SAM - LIGUE HELP DESK
PP_DUMBCARD CARTAO COM ERRO CARTAO COM ERRO OU MAL INSERIDO
OU MAL INSERIDO
PP_ERRCARD CARTAO COM ERRO CARTAO COM ERRO OU MAL INSERIDO
OU MAL INSERIDO
PP_CARDINV CARTAO CARTAO INVALIDO
INVALIDO

Constante Mensagem do pinpad Mensagem do “checkout”

PP_CARDBLOCKED CARTAO CARTAO BLOQUEADO
BLOQUEADO
PP_CARDNAUTH CARTAO CARTAO INVALIDO
INVALIDO
PP_CARDEXPIRED CARTAO CARTAO VENCIDO
VENCIDO
PP_CARDERRSTRUCT CARTAO CARTAO INVALIDO
INVALIDO
PP_CARDINVALIDAT CARTAO CARTAO INVALIDADO
INVALIDADO
PP_CARDPROBLEMS CARTAO CARTAO INVALIDO
INVALIDO
PP_CARDINVDATA CARTAO CARTAO INVALIDO
INVALIDO
PP_CARDAPPNAV MODO INVALIDO MODO INVALIDO, PASSE O CARTAO
PASSE O CARTAO
PP_CARDAPPNAUT CARTAO NAO CARTAO NAO ACEITO
ACEITO
PP_NOBALANCE SALDO SALDO INSUFICIENTE NO MOEDEIRO
INSUFICIENTE
PP_LIMITEXC EXCEDE LIMITE EXCEDE LIMITE POR TRANSACAO
POR TRANSACAO
PP_CARDNOTEFFECT CARTAO CARTAO NAO EFETIVO
NAO EFETIVO
PP_VCINVCURR CARTAO POSSUI CARTAO POSSUI MOEDA INVALIDA
MOEDA INVALIDA
PP_ERRFALLBACK CARTAO CARTAO INVALIDO
INVALIDO
PP_CTLSSMULTIPLE MAIS DE UM MAIS DE UM CARTAO APRESENTADO
CARTAO
PP_CTLSSCOMMERR ERRO COMUNICACAO ERRO DE COMUNICACAO COM O CARTAO
COM O CARTAO
PP_CTLSSINVALIDAT CART. INVALIDADO CARTAO INVALIDADO USE CHIP/TARJA
USE CHIP/TARJA
PP_CTLSSPROBLEMS CARTAO INVALIDO CARTAO INVALIDO, USE CHIP/TARJA
USE CHIP/TARJA
PP_CTLSSAPPNAV MODO INVALIDO MODO INVALIDO, USE CHIP/TARJA
USE CHIP/TARJA
PP_CTLSSAPPNAUT NAO ACEITO NAO ACEITO, USE CHIP/TARJA
USE CHIP/TARJA

3.1.4. Funções “blocantes”

Todas as funções da biblioteca devem obrigatoriamente ser “não blocantes”, ou seja, não devem
“prender” o processamento mais do que o necessário.
Por esse motivo, algumas funções que no meio de seu processamento dependem da intervenção
humana (passagem de cartão, captura de senha, seleção de aplicação do cartão com chip) são
“quebradas” em duas funções “não blocantes”:
PP_StartFunc ( ) Inicia o processo e somente possui parâmetros de entrada.
PP_Func ( ) Finaliza o processo e somente possui parâmetros de saída. Caso o processo

esteja em andamento, retorna PP_PROCESSING ou PP_NOTIFY.
PP_StartFunc
Erro
OK
Fim
PP_NOTIFY Mostra
PP_Func mensagem
Erro no “checkout”
Fim OK
2 PP_PROCESSING Operador
deseja
finalizar? Não
Sim
PP_Abort
Quando a função retorna PP_NOTIFY, ela informa uma mensagem a ser apresentada no “checkout”.
O processo pode ser finalizado através da função PP_Abort ( ) sempre que PP_Func ( ) retornar
PP_PROCESSING ou PP_NOTIFY.

3.2. Funções de Controle

Chamamos de “Funções de Controle” àquelas utilizadas para gerenciar os recursos de hardware e
software necessários ao funcionamento da biblioteca e do próprio pinpad.
Função Descrição
PP_Open Aloca os recursos de hardware e software para utilização do pinpad.
PP_Close Libera os recursos de hardware e software alocados ao pinpad.
PP_Abort Aborta uma operação em andamento no pinpad
As funções PP_Open e PP_Close devem obrigatoriamente ser utilizadas, respectivamente, no início e

no fim de uma seqüência de funções utilizando esta biblioteca.
Início
PP_Open
PP_Func
PP_Close
Fim

PP_Open
Esta função aloca os recursos de hardware e software necessários ao funcionamento do conjunto
bibliotecas/pinpad.
A chamada bem sucedida desta função é pré-requisito para todas as outras da biblioteca.
Sintaxe: int PP_Open (INPUT psCom);
Entradas:
psCom Porta serial onde se encontra conectado o pinpad (2 dígitos, de “01” a “99”).
Saídas:
não há.
Retorno:
PP_OK ...........................Biblioteca inicializada e recursos atribuídos com sucesso.
PP_PORTERR .................Erro de comunicação: porta serial do pinpad provavelmente ocupada.
PP_COMMERR ..............Erro de comunicação: pinpad provavelmente desconectado ou
problemas com a interface serial.
PP_ALREADYOPEN ........Função PP_Open já havia sido chamada.
Exemplo:
char sCom[2];
int iStat;
/* Inicia Biblioteca com pinpad na COM1 */
memcpy (sCom, “01”, 2);

iStat = PP_Open (sCom);
if (iStat != PP_OK) return iStat;

PP_Close
Esta função libera os recursos de hardware e software alocados ao pinpad. A chamada a esta função
é imprescindível após o uso das funções da biblioteca.
Outras atribuições de PP_Close:
 Desligar a alimentação do cartão com chip, caso ativa.
 Desabilitar o modo “Comunicação Segura”, caso tenha sido usada a função PP_DefineWKPAN.
Sintaxe: int PP_Close (INPUT psIdleMsg);
Entradas:
psIdleMsg Mensagem de 32 caracteres (2 linhas x 16 colunas) a ser deixada no display
do pinpad após o fechamento.
Saídas:
não há.
Retorno:
PP_OK ...........................Biblioteca finalizada e recursos liberados com sucesso.
PP_NOTOPEN................Função PP_Open não foi previamente chamada.
Exemplo:
int iStat;
/* Inicia Biblioteca com pinpad na COM2 */
iStat = PP_Open (“02”);

/* Finaliza a Biblioteca */
/* ------> 32 posições:
“12345678901234567890123456789012” */
PP_Close (“SUPERMERCADOS•••ALEGRIA••••••••”);
Após a finalização da Biblioteca, o pinpad passará a apresentar a mensagem:
SUPERMERCADOS
ALEGRIA

PP_Abort
Esta função finaliza um processo em andamento, iniciado por uma função do tipo PP_StartFunc. Ela
deve ser chamada caso o operador do “checkout” decida “abortar” a operação enquanto a função
complementar PP_Func estiver retornando PP_PROCESSING (ver item 3.1.4 - Funções “blocantes”).
Sintaxe: int PP_Abort (void);
Entradas:
não há.
Saídas:
não há.
Retorno:
PP_OK ...........................Esta função retorna sempre OK.

3.3. Funções Básicas de Pinpad

Este item contempla as “funções básicas” de um pinpad.
PP_GetInfo Obtém informações básicas sobre o pinpad
PP_DefineWKPAN Define a chave de criptografia para o número do cartão
PP_Display Envia uma mensagem ao display do pinpad.
PP_DisplayEx Envia uma mensagem ao display do pinpad, com formato livre.
PP_StartGetKey Aguarda o pressionamento de uma tecla no pinpad.
PP_GetKey
PP_StartGetPIN Captura a senha do portador do cartão dentro dos padrões
PP_GetPIN criptográficos exigidos pelas redes adquirentes.
PP_StartCheckEvent Aguarda um evento no pinpad, como pressionamento de tecla,
PP_CheckEvent passagem de cartão com tarja, inserção e remoção de cartão com
chip.
PP_EncryptBuffer Criptografa um bloco de dados utilizando uma Master Key do
pinpad.
PP_GetDUKPT Obtém os dados correntes de um registro DUKPT
PP_StartChipDirect Efetua operação direta com o cartão com chip
PP_ChipDirect
PP_StartRemoveCard Aguarda a remoção do cartão com chip inserido.
PP_RemoveCard
PP_StartGenericCmd Executa um comando genérico proprietário de uma das redes
PP_GenericCmd adquirentes.

PP_GetInfo
Esta função obtém informações sobre o pinpad e suas aplicações. Caso uma informação não exista
ou não se aplique para o modelo de pinpad, ela deverá ser fornecida em branco (espaços).
Sintaxe: int PP_GetInfo (INPUT psInput, OUTPUT psOutput);
Entradas:
psInput String ASCII de 2 caracteres indicando o tipo de informação sendo
requisitada:
Posição Formato Descrição
001-002 N2 “00” para informações gerais;
“01” para info. sobre a aplicação Rede Amex;
“02” para info. sobre a aplicação Redecard; e
“03” para info. sobre a aplicação Cielo.
Saídas:
psOutput Informações requisitadas, cujo layout depende do parâmetro psInput.
Se psInput igual a “00” (informações gerais):
001-020 A20 Nome do fabricante do pinpad
021-039 A19 Modelo / versão do hardware, no formato
“xxx...xxx;mmm”, onde “xxxx” é o nome do
equipamento e “mmm” a capacidade de
memória (“512KB”, “1MB”, “2MB”, ...).
040 A1 Se o pinpad suporta cartão com chip sem
contato, este campo deve conter a letra “C”,
caso contrário um espaço em branco.
041-060 A20 Versão do software básico/firmware (formato
livre)
061-064 A4 Versão da especificação, no formato “V.VV”
(neste caso, fixo “1.08”)
065-080 A16 Versão da aplicação básica, no formato
“VVV.VV AAMMDD” (com 3 espaços à direita).
081-100 A20 Número de série do pinpad (com espaços à
direita)
Se psInput diferente de “00” (informações sobre a aplicação da Rede
Adquirente):
001-020 A20 Nome da Rede Adquirente (com espaços à
direita)


021-033 A13 Versão da aplicação da Rede Adquirente, no
formato
“VVV.VV AAMMDD”
034-040 A7 Informações proprietárias da Rede Adquirente.
041-042 N2 Tamanho em bytes dos dados a seguir (“00” a
“yy”)
043-??? Hxx(Byy) Dados binários de identificação do SAM, caso
existente, no layout exigido pela Rede
Adquirente.
Retorno:
PP_OK ...........................Operação bem sucedida- os resultados estão em psOutput.

PP_DefineWKPAN
A função PP_DefineWKPAN permite que o “checkout” habilite a criptografia de número de cartão,
evitando que este dado circule em claro pelo protocolo serial do pinpad, conforme processo
detalhado no item 4.4. Além disso, esta função define a chave (WKPAN) a ser utilizada no processo.
Esta função pode ser chamada a qualquer momento depois da função PP_Open. A partir desse
instante o pinpad passa a trabalhar em modo aqui denominado “Comunicação Segura”, até que seja
chamada a função PP_Close.
Sintaxe: int PP_DefineWKPAN (INPUT psInput, OUTPUT psOutput);
Entradas:
psInput O formato da entrada depende da modalidade de criptografia a ser utilizada:
Modalidade 1: Uso de WKPAN externa, criptografada por uma “Master Key”
String ASCII de 36 caracteres no seguinte formato:
001 N1 Modalidade:
“1” = WKPAN externa criptografada por Master
Key
002 N1 Modo de criptografia:
“0” - Master Key / Working DES (8 bytes)
“1” - Master Key / Working 3DES (16 bytes)
003-004 N2 Índice da Master Key a ser utilizada.
005-036 H32(B16) WKPAN criptografada pela Master Key (se modo =
“0”, somente os 8 primeiros bytes são utilizados).
Modalidade 2: Uso de WKPAN 3DES aleatória, gerada pelo pinpad

String ASCII de 263 caracteres no seguinte formato:
001 N1 Modalidade:
“2” = WKPAN 3DES aleatória
002-257 H256(B128) Módulo da chave pública RSA a ser usada na
geração do certificado (IMPORTANTE: o primeiro
byte deve ser maior do que 54h, devido ao
formato do certificado - ver item 4.4.4).
258-263 H6(B3) Expoente da chave pública RSA a ser usada na
geração do certificado (tipicamente “000003” ou
“010001”).
Saídas:
psInput O formato da saída depende da modalidade de criptografia a ser utilizada:
Na Modalidade 1, não há dados de saída.

Na Modalidade 2, o pinpad devolve uma string ASCII de 256 caracteres no

seguinte formato:
001-256 H256(B128) Certificado RSA contendo uma chave WKPAN
aleatória, conforme definido no item 4.4.
Retorno:
PP_OK ...........................Operação bem sucedida.
PP_INVPARM ................Parâmetro inválido passado à função.
PP_ERRPIN ....................A Master Key referenciada não existe.

PP_Display
Esta função envia uma mensagem ao display do pinpad. Devido à diversidade de formatos de display,
esta biblioteca convenciona que as mensagens devam ter 2 linhas por 16 colunas.
Sintaxe: int PP_Display (INPUT psMsg);
Entradas:
psMsg Mensagem de 32 caracteres (2 linhas x 16 colunas) a ser apresentada no
display do pinpad.
Saídas:
não há.
Retorno:
PP_OK ...........................Mensagem apresentada com sucesso.
Exemplo:
/* Mostra mensagem “OPERACAO REALIZADA” centralizada no pinpad */
/* --------> 32 posições:
“12345678901234567890123456789012” */
PP_Display (“••••OPERACAO••••••••REALIZADA•••”);
Após a execução de PP_Display, o pinpad passará a apresentar a mensagem:
OPERACAO
REALIZADA

PP_DisplayEx
Esta função envia uma mensagem ao display do pinpad, de formato livre, permitindo o uso de todos
os recursos do display do equipamento.
Sintaxe: int PP_DisplayEx (INPUT psMsg);
Entradas:
psInput String ASCII de caracteres com o seguinte formato:
001-003 N3 Tamanho da mensagem a seguir (xxx).
004-??? Axxx Mensagem a ser apresentada, podendo conter
caracteres de controle aceitos pelo display do
pinpad, tal como o CR (0Dh) para quebra de
linha.
Saídas:
não há.
Retorno:
PP_OK ...........................Mensagem apresentada com sucesso.
Exemplo:
/* Mostra mensagem “ESTA OPERACAO FOI” <CR>

“REALIZADA COM SUCESSO” <CR> <CR>
“FIM!”*/
PP_Display (“039ESTA OPERACAO FOI\rREALIZADA COM SUCESSO\r\rFIM!”);
Após a execução de PP_Display, um pinpad com display 4 x 20 passará a apresentar a

mensagem:
ESTA OPERACAO FOI

REALIZADA COM SUCESS
FIM!
Já um pinpad com display 2 x 16 apresentará a seguinte mensagem:
ESTA OPERACAO FO
REALIZADA COM SU

PP_StartGetKey
O conjunto PP_StartGetKey / PP_GetKey (conforme descrito no item 3.1.4 - Funções “blocantes”)
captura uma tecla pressionada no pinpad.
Sintaxe: int PP_StartGetKey (void);
Entradas:
não há.
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GetKey deve ser chamado para se
obter os resultados.

PP_GetKey
Esta função finaliza o processo iniciado por PP_StartGetKey (conforme descrito no item 3.1.4 -
Funções “blocantes”), devendo ser chamada constantemente enquanto retornar PP_PROCESSING.
Enquanto nessa situação, o processo pode ser cancelado pelo “checkout” através da função
PP_Abort.
Sintaxe: int PP_GetKey (void);
Entradas:
não há.
Saídas:
não há.
Retorno:
PP_OK ...........................Pressionada tecla de confirmação (OK ou ENTER)
PP_CANCEL ...................Pressionada tecla de cancelamento.
PP_BACKSP ...................Pressionada tecla de limpeza (backspace).
PP_F1 a PP_F4 ..............Pressionada tecla de função.
PP_PROCESSING ...........Em processamento - deve-se chamar PP_GetKey novamente ou
PP_Abort para finalizar.
Exemplo:
/* Função para aguardar tecla no pinpad. Supõe-se a existência de
uma função “TestaCancelamento” que verifica o cancelamento pelo
checkout */
int AguardaTecla (void)

{
int iStat;
iStat = PP_StartGetKey ();

do {
iStat = PP_GetKey ();
if (iStat == PP_PROCESSING && TestaCancelamento () == TRUE) {
PP_Abort ();
return APP_CANCEL;
}
} while (iStat == PP_PROCESSING);
return iStat;
}

PP_StartGetPIN
O conjunto PP_StartGetPIN / PP_GetPIN (conforme descrito no item 3.1.4 - Funções “blocantes”)
captura a senha do usuário (PIN) ou dados de identificação positiva e retorna um bloco de dados
criptografados segundo o método Master Key / Working Key (DES ou 3DES) ou DUKPT (DES ou 3DES).
Conforme colocado, além da captura de PIN convencional, as funções prevêem a entrada de uma
seqüência de mais de um dado, de maneira a ser fazer “identificação positiva”.
 Para a criptografia de PIN, deve-se considerar somente um único dado a ser capturado.
 Para a identificação positiva, pode-se considerar mais de um dado a ser capturado, sendo que
estes são concatenados para a geração do PIN-block. Caso o resultado tenha menos do que 4
dígitos, este é completado com zeros à esquerda. Caso tenha mais do que 12, os dígitos à direita
devem ser ignorados.
Durante a digitação no pinpad, a mensagem de 2x16 fornecida não deve ser alterada ou sobreposta,
sendo que os dados digitados devem aparecer na forma de asteriscos abaixo da mensagem.
<linha 1 da msg>
<linha 2 da msg>
****
Sintaxe: int PP_StartGetPIN (INPUT psInput);
Entradas:
“2” - DUKPT DES
“3” - DUKPT 3DES
002-003 N2 Índice da Master Key ou do registro de
tratamento DUKPT.
004-035 H32(B16) Para os modos “0” e “1”, é a Working Key
(criptografada pela Master Key).
No modo “0”, somente os 8 primeiros bytes são
utilizados.
Nos modos “2” e “3” este campo é ignorado.
036-037 N2 Tamanho do PAN (de “13” a “19”). Caso o PAN
tenha menos de 13 dígitos, ele deverá ser
completado com zeros à esquerda.
038-056 A19 PAN, alinhado à esquerda (espaços à direita).
Se o pinpad estiver em modo “Comunicação
Segura”, o PAN deve ser codificado usando-se
DES/3DES Reverso com a chave WKPAN (ver item
4.4)
057 N1 Quantidade de dados a serem capturados (n)


058-059 N2 Tamanho mínimo do dado 1
060-061 N2 Tamanho máximo do dado 1
062-093 A32 Mensagem de 2 linhas x 16 colunas para
apresentação no momento do pedido do dado 1.
094-095 N2 Tamanho mínimo do dado 2
096-097 N2 Tamanho máximo do dado 2
098-129 A32 Mensagem de 2 linhas x 16 colunas para
apresentação no momento do pedido do dado 2.
... ... ....
???-??? N2 Tamanho mínimo do dado n
???-??? N2 Tamanho máximo do dado n
???-??? A32 Mensagem de 2 linhas x 16 colunas para
apresentação no momento do pedido do dado n.
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GetPIN deve ser chamado para se

PP_GetPIN
Esta função finaliza o processo iniciado por PP_StartGetPIN (conforme descrito no item 3.1.4 -
Funções “blocantes”), devendo ser chamada constantemente enquanto retornar PP_PROCESSING ou
PP_NOTIFY. Enquanto nessa situação, o processo pode ser cancelado pelo “checkout” através da
função PP_Abort.
Durante o processamento são enviadas mensagens de notificação contendo as próprias descrições
dos dados sendo requeridos (que são parâmetros de entrada de PP_StartGetPIN), a partir da captura
do segundo dado. Portanto não há mensagem de notificação quando somente um dado é requerido,
como no caso de captura simples de PIN. Isso é feito para avisar o operador do checkout, de maneira
a auxiliar o portador do cartão na entrada dos dados de identificação positiva.
IMPORTANTE: O pinpad sempre apaga o display após a captura de PIN, seja esta bem ou mal
sucedida.
Sintaxe: int PP_GetPIN (OUTPUT psOutput, OUTPUT psMsgNotify);
Entradas:
não há.
Saídas:
psOutput String ASCII de 36 caracteres com o seguinte formato:
001-016 H16(B8) PIN criptografado
017-036 H20(B10) Número de série da chave (Key Serial Number),
somente no caso de DUKPT. Para
Master/Working Key, este campo é ignorado.
psMsgNotify Mensagem de 32 caracteres a ser apresentada no “checkout” caso a função
retorne PP_NOTIFY.
Retorno:
PP_OK ...........................PIN digitado e criptografado com sucesso - os resultados estão em
psOutput.
PP_INVCALL ..................Função PP_StartGetPIN não foi previamente chamada.
PP_PROCESSING ...........Em processamento - deve-se chamar PP_GetPIN novamente ou
PP_NOTIFY ....................Em processamento - deve-se apresentar no “checkout” a mensagem
psMsgNotify e depois chamar PP_GetPIN novamente ou PP_Abort para
finalizar.
PP_CANCEL ...................Operação cancelada.
PP_ERRPIN ....................Master Key ou DUKPT não está presente no pinpad (IMPORTANTE: não
deve ser feita captura de PIN caso a chave não exista, sendo que este
erro deve retornar imediatamente!).

Exemplo:
int iStat;
char sInput[93], sOutput[36], sMsgNotify[32];
/* Testa a apresentação de PIN com a Master Key da Cielo:

Modo de criptografia: “0” (DES)
Master Key: “09” (Cielo)
Working Key: “9ACF04325A0B796D”
Número Cartão (PAN): “4391998410650011”
Mensagem: “DIGITE SUA SENHA”
*/
memcpy (sInput, “0099ACF04325A0B796D0000000000000000”

“164391998410650011•••”
“10412DIGITE•SUA•SENHA••••••••••••••••”, 93);
iStat = PP_StartGetPIN (sInput);

do {
iStat = PP_GetPIN (sOutput, sMsgNotify);
if (iStat == PP_NOTIFY)
MostraMsgCheckout (sMsgNotify);
PP_Abort ();
return APP_CANCEL;
}
} while (iStat == PP_PROCESSING || iStat == PP_NOTIFY);
/* A partir daqui, se o PIN digitado for “1234”, sOutput deverá

conter o resultado: “316B8250796DE34F00000000000000000000” */

PP_StartCheckEvent
O conjunto PP_StartCheckEvent / PP_CheckEvent (conforme descrito no item 3.1.4 - Funções
“blocantes”) aguarda a ocorrência de um determinado evento no pinpad. Os seguintes eventos
podem ser verificados:
 Pressionamento de uma tecla;
 Passagem de um cartão magnético;
 Inserção de um cartão com chip; e
 Remoção de um cartão com chip.
Sintaxe: int PP_StartCheckEvent (INPUT psInput);
Entradas:
001 N1 Controla evento de pressionamento de tecla.
Se =”0”, ignora teclas.
Se =”1”, verifica pressionamento de tecla.
002 N1 Controla evento de passagem de cartão
magnético.
Se =”0”, ignora cartão magnético.
Se =”1”, verifica passagem de cartão magnético.
003 N1 Controla evento de inserção/remoção de cartão
com chip.
Se =”0”, ignora cartão com chip.
Se =”1”, verifica inserção de cartão com chip.
Se =”2”, verifica remoção de cartão com chip.
004 N1 Controla evento de aproximação de cartão com
chip sem contato.
Se =”0”, não ativa a antena.
Se = “1”, ativa a antena e verifica a presença de
um cartão sem contato.
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_CheckEvent deve ser chamado para
se obter os resultados.

PP_CheckEvent
Esta função finaliza o processo iniciado por PP_StartCheckEvent (conforme descrito no item 3.1.4 -
PP_Abort.
IMPORTANTE:
 Esta função não deve mudar o estado do cartão com chip, ligando-o ou desligando-o. Caso o
cartão com chip seja selecionado para geração de evento, somente o seu sensor de presença
deve ser verificado.
 Caso a detecção de cartão sem contato tenha sido requerida em PP_StartCheckEvent, a antena
sempre deve ser desligada ao final de PP_CheckEvent (mesmo que o evento detectado seja
outro).
Sintaxe: int PP_CheckEvent (OUTPUT psOutput);
Entradas:
não há.
Saídas:
psOutput String ASCII, cujo formato depende do evento gerado:
Evento de teclado:
001 N1 Identificação do evento ocorrido: “0”
002-003 N2 Código da tecla pressionada:
”00” - OK ou ENTER ”07” - F4
”04” - F1 ”08” - BACKSPACE
”05” - F2 ”13” - CANCEL
”06” - F3
Evento de cartão magnético:
002-003 N2 Tamanho da trilha 1
004-079 A76 Trilha 1 (sem os sentinelas e com o byte de
formato - primeiro caractere alfanumérico),
alinhada à esquerda com espaços à direita (*)
082-118 A37 Trilha 2 (sem os sentinelas), alinhada à esquerda
com espaços à direita (*)
119-121 N3 Tamanho da trilha 3 (**)

(*)
Se o pinpad estiver em modo “Comunicação Segura”, o PAN das trilhas
vem codificado pela chave WKPAN (ver item 4.4).
(**)
Se o pinpad estiver em modo “Comunicação Segura”, o campo de
“Tamanho da trilha 3” não deve ser preenchido, pois a Trilha 2 pode atingir
40 caracteres (ver explicação no item 4.4)!!
Evento de cartão com chip:
002 N1 Presença do cartão com chip:
“0” - Cartão com chip ausente.
”1” - Cartão com chip presente.
Evento de cartão com chip sem contato:
002 N1 Presença do cartão com chip sem contato:
“0” - Cartão com chip sem contato não foi
detectado em 2 (dois) minutos.
”1” - Cartão com chip sem contato foi detectado.
Retorno:
PP_OK ...........................Evento ocorrido.
PP_INVCALL ..................Função PP_StartCheckEvent não foi previamente chamada.
PP_PROCESSING ...........Em processamento - deve-se chamar PP_CheckEvent novamente ou
PP_MCDATAERR ...........Detectado evento de cartão magnético, porém houve erro de leitura
(nenhuma trilha pôde ser lida).

PP_EncryptBuffer
Esta função criptografa um bloco de dados de 8 bytes utilizando uma Master Key e uma Working Key,
seguindo o mesmo algoritmo utilizado pela captura de PIN.
Sintaxe: int PP_EncryptBuffer (INPUT psInput, OUTPUT psOutput);
Entradas:
psInput String ASCII de 51 caracteres com o seguinte formato:
002-003 N2 Índice da Master Key
004-035 H32(B16) Working Key (criptografada pela Master Key),
sendo que no modo “0”, somente os 8 primeiros
bytes são utilizados.
036-051 H16(B8) Dados a serem criptografados.
No modo “Comunicação Segura”, estes dados
vêm codificados usando-se DES/3DES Reverso
com a chave WKPAN (ver item 4.4)
Saídas:
001-016 H16(B8) Dados criptografados.
Retorno:
PP_OK ...........................Processo finalizado com sucesso.
PP_ERRPIN ....................Master Key não está presente no pinpad.
PP_INVPARM ................Índice de Master Key fornecido está fora da faixa usada pelo pinpad (ou
outro parâmetro inválido foi fornecido em psInput).
Exemplo:
int iStat;
char sOutput[16];

/* Testa a criptografia de um dado com a Master Key da Redecard:

Modo de criptografia: “0” (DES)
Master Key: “08” (Redecard)
Working Key: “9ACF04325A0B796D”
Dados a criptografar: “0C5A407BF1F826DC”
*/
iStat = PP_EncryptBuffer (“0089ACF04325A0B796D00000000000000000”

“C5A407BF1F826DC”, sOutput);
/* A partir daqui sOutput deverá

conter o resultado: “2AAEC43CD3302BFF” */

PP_GetDUKPT
Esta função obtém o KSN (Key Serial Number) corrente de um registro de tratamento DUKPT.
Sintaxe: int PP_GetDUKPT (INPUT psInput, OUTPUT psOutput);
Entradas:
psInput String ASCII de 3 caracteres com o seguinte formato:
“2” - DUKPT DES
”3” - DUKPT 3DES
002-003 N2 Índice do registro de tratamento DUKPT.
Saídas:
001-020 H20(B10) KSN (Key Serial Number)
Retorno:
PP_OK ...........................Dados obtidos com sucesso.
PP_INVMODEL ..............Esta funcionalidade não é suportada pelo pinpad.
PP_ERRPIN ....................Não há dados carregados para o índice fornecido.
PP_INVPARM ................Índice fornecido está fora da faixa usada pelo pinpad.

PP_StartChipDirect
O conjunto PP_StartChipDirect / PP_ChipDirect (conforme descrito no item 3.1.4 - Funções
“blocantes”), permite o acesso direto aos cartões com chip (principal ou SAM).
Adicionalmente, este comando possibilita a captura de um PIN para verificação direta no chip.
Sintaxe: int PP_StartChipDirect (INPUT psInput);
Entradas:
psInput String ASCII de tamanho variável (até 527 caracteres), com o seguinte
formato:
001 N1 Cartão com chip a ser usado:
“0” - Cartão do acoplador principal
“1” - SAM #1
...
“8” - SAM #8
“9” - Cartão sem contato.
002 N1 Operação a ser executada:
“0” - Desligar o cartão (para cartão sem contato,
desativa-se a antena).
“1” - Ligar o cartão (para cartão sem contato,
ativa-se a antena e, depois, o cartão).
“2” - Trocar comando com o cartão
“3” - Verificar PIN diretamente no cartão
003-005 N3 Tamanho do comando a seguir, em bytes.
Para operação “0” ou “1”, o tamanho é zerado.
006-??? Hxx(Byy) Comando a ser enviado ao cartão.
Se operação = “2”, aceitam-se seguintes
formatos:
CLA INS P1 P2
CLA INS P1 P2 Le
CLA INS P1 P2 Lc XX XX ... XX
CLA INS P1 P2 Lc XX XX ... XX Le
Se operação = “3”, deve-se fornecer somente os
quatro primeiros bytes do comando a ser
enviado ao cartão (CLA INS P1 P2), pois o resto é
montado automaticamente conforme formato
do “pinblock”.
??? N1 Formato do “pinblock” (somente se operação =
“3”):
“0” = 0T PP PP ... FF (8 bytes, PIN 4 a 12 dígitos)
“1” = 2T PP PP ... FF (8 bytes, PIN 4 a 12 dígitos)
“2” = PP PP PP ... FF (8 bytes, PIN 4 a 12 dígitos)


???-??? A32 Mensagem de 2 linhas x 16 colunas para
apresentação no momento do pedido do PIN
(somente se operação = “3”).
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GetPIN deve ser chamado para se

PP_ChipDirect
Esta função finaliza o processo iniciado por PP_StartChipDirect (conforme descrito no item 3.1.4 -
PP_Abort.
Sintaxe: int PP_ChipDirect (OUTPUT psOutput);
Entradas:
não há.
Saídas:
psOutput String ASCII de tamanho variável (até 519 caracteres) com o seguinte
formato:
001-003 N3 Tamanho da resposta do cartão a seguir, em
bytes..
004-??? Hxx(Byy) Resposta do cartão:
Se operação = “0”, não há.
Se operação = “1”, é o ATR completo do cartão.
Se operação = “2” ou “3”, é a resposta ao
comando enviado, seguida obrigatoriamente
pelos bytes SW1 e SW2.
Retorno:
PP_PROCESSING ...........Em processamento - deve-se chamar PP_ChipDirect novamente ou
PP_INVCALL ..................Função PP_StartChipDirect não foi previamente chamada.
PP_INVMODEL ..............Esta funcionalidade não é suportada pelo pinpad.
PP_NOCARD ..................Não há cartão com chip presente no acoplador (ou antena).
PP_DUMBCARD ............Cartão não responde (“mudo”) ou chip não presente (não se aplica a
cartões sem contato).
PP_ERRCARD.................Erro de comunicação do pinpad com o cartão com chip.
Observações:
 Dependendo da implementação do pinpad, ele poderá ou não tratar internamente os status de
retorno “61 xx” e “6C xx” dos cartões T=0. Dessa forma, a aplicação de “checkout” terá que estar
preparada para tratar externamente esses dois casos, caso o pinpad já não o faça.
 Para cartões sem contato, a antena deve ser automaticamente desativada no caso dos erros
PP_NOCARD e PP_ERRCARD.

 O “checkout” deve sempre desativar a antena após o uso de cartão sem contato. Caso isto não
seja feito, o fabricante do pinpad pode estabelecer um “timeout” de ociosidade (sugestão 2
minutos) e desligar a antena automaticamente.

PP_StartRemoveCard
O conjunto PP_StartRemoveCard / PP_RemoveCard (conforme descrito no item 3.1.4 - Funções
“blocantes”) aguarda a remoção do cartão com chip. Ele possui dois comportamentos diferentes, de
acordo com a presença ou não de um cartão no acoplador de “cartão usuário” com chip.
Cartão presente:
Desliga a alimentação do cartão com chip e apresenta a mensagem definida por psMsg,
alternada com uma mensagem de “RETIRE O CARTAO”, permanecendo neste estado até a
retirada do cartão.
Cartão ausente:
Apresenta a mensagem definida por psMsg e retorna imediatamente.
Em ambos os casos, a mensagem definida por psMsg é deixada ao final no display.
Aconselha-se sempre o uso desta função ao final do fluxo de operação, seja ele bem ou mal
sucedido.
Sintaxe: int PP_StartRemoveCard (INPUT psMsg);
Entradas:
psMsg Mensagem de 32 caracteres (2 linhas x 16 colunas) a ser apresentada no
display do pinpad.
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_RemoveCard deve ser chamado para

PP_RemoveCard
Esta função finaliza o processo iniciado por PP_StartRemoveCard (conforme descrito no item 3.1.4 -
função PP_Abort.
Caso um cartão com chip esteja inserido, a mensagem de notificação “RETIRE O CARTAO” deve ser
enviada uma única vez ao “checkout”.
Sintaxe: int PP_RemoveCard (OUTPUT psMsgNotify);
Entradas:
não há.
Saídas:
retorne PP_NOTIFY.
Retorno:
PP_OK ...........................Cartão foi retirado (ou já não estava presente).
PP_PROCESSING ...........Em processamento - deve-se chamar PP_RemoveCard novamente ou
psMsgNotify e depois chamar PP_RemoveCard novamente ou PP_Abort
para finalizar.
PP_INVCALL ..................Função PP_StartRemoveCard não foi previamente chamada.

PP_StartGenericCmd
O conjunto PP_StartGenericCmd / PP_GenericCmd (conforme descrito no item 3.1.4 - Funções
“blocantes”) executa um comando proprietário de uma das redes adquirentes.
O detalhamento dos possíveis comandos proprietários existentes não é objeto desta especificação,
sendo definidos em documentação à parte fornecida pela rede adquirente. Esta especificação
fornece apenas o formato genérico para a montagem desses comandos.
Sintaxe: int PP_StartGenericCmd (INPUT psInput);
Entradas:
psInput String ASCII de tamanho variável com o seguinte formato:
001-002 N2 Identificador da Rede Adquirente, conforme
Tabela de Parâmetros x AID.
003-005 N3 Tamanho dos dados a seguir, em caracteres.
006-??? A??? Dados proprietários cujo formato é especificado
pela rede adquirente em questão.
Saídas:
não há.
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GenericCmd deve ser chamado para

PP_GenericCmd
Esta função finaliza o processo iniciado por PP_StartGenericCmd (conforme descrito no item 3.1.4 -
função PP_Abort.
Sintaxe: int PP_GenericCmd (OUTPUT psOutput, OUTPUT psMsgNotify);
Entradas:
não há.
Saídas:
psOutput String ASCII de tamanho variável com o seguinte formato:
001-003 N3 Tamanho dos dados a seguir, em caracteres.
004-??? A??? Dados proprietários de resposta cujo formato é
especificado pela rede adquirente em questão.
retorne PP_NOTIFY.
Retorno:
PP_OK ...........................Operação finalizada com sucesso.
PP_PROCESSING ...........Em processamento - deve-se chamar PP_GenericCmd novamente ou
psMsgNotify e depois chamar PP_GenericCmd novamente ou PP_Abort
para finalizar.
PP_INVCALL ..................Função PP_StartGenericCmd não foi previamente chamada.
Outros retornos ............Demais retornos específicos do processamento no módulo da rede
adquirente não podem ser previstos por esta especificação.

3.4. Funções de processamento de cartão

Este item detalha as funções de “alto-nível” responsáveis pelo processamento de cartão durante
uma operação de pagamento.
PP_StartGetCard Inicia o processo de aceitação de um cartão, seja ele magnético ou
PP_GetCard com chip.
PP_ResumeGetCard Continua o processo de aceitação de um cartão com chip após a
manutenção de tabelas de parâmetros (seja ela bem ou mal
sucedida).
PP_ChangeParameter Altera temporariamente o valor de um dos parâmetros EMV das
tabelas usadas no processamento do cartão.
PP_StartGoOnChip Continua o processo de aceitação de um cartão, caso seja um cartão
PP_GoOnChip com chip.
PP_FinishChip Finaliza o processo de aceitação de um cartão com chip caso a
transação tenho requerido autorização online.
O fluxo a seguir destina-se a ilustrar, simplificadamente, o encadeamento lógico destas funções.

Fluxos completos encontram-se no Capítulo 6.
Início
PP_StartGetCard
PP_GetCard
PP_ResumeGetCard
...
magnético chip
Tipo cartão?
PP_StartGoOnChip
PP_GoOnChip
...
aprovar offline ou
pedir autorização online
decisão?
negada
PP_FinishChip
continua... continua... continua...

PP_StartGetCard
O conjunto PP_StartGetCard / PP_GetCard (conforme descrito no item 3.1.4 - Funções “blocantes”)
inicia o processo de pagamento com cartão, seja ele magnético ou com chip.
Sintaxe: int PP_StartGetCard (INPUT psInput);
Entradas:
001-002 N2 Identificador da Rede Adquirente, conforme
Tabela de Parâmetros x AID. Para abranger
todas as redes, deve-se usar o valor “00”.
003-004 N2 Tipo de aplicação desejada, conforme Tabela de
Parâmetros x AID. Para qualquer aplicação, usar
“99”. Para uma lista de específica de aplicações,
usar “00”.
005-016 N12 Valor inicial da transação em centavos (Amount,
authorized), podendo ser 0 (zero) caso este dado
não esteja disponível no início da transação.
017-022 N6 Data da transação (“AAMMDD”)
023-028 N6 Hora da transação (“HHMMSS”)
029-038 N10 “Time-stamp” das tabelas de parâmetros,
formado por dia, mês, ano e um número
seqüencial (“DDMMAAAASS”) - ver Capítulo 4.
Caso seja definida uma Rede Adquirente, este
“time-stamp” refere-se somente às tabelas
relativas a ela.
039-040 N2 Quantidade de entradas da lista a seguir, se tipo
de aplicação desejada for “00”
IMPORTANTE: Este campo não é opcional,
devendo receber o valor “00” caso não haja lista
a seguir.
041-??? N4 Identificador da rede + índice para Tabela de
Parâmetros x AID.
... ...
???-??? N4 Identificador da rede + índice para Tabela de
Parâmetros x AID.


??? N1 Habilita interface de cartão sem contato?
“1” - Sim (default)
“0” - Não
IMPORTANTE: Para manter compatibilidade com
versões anteriores da especificação, este campo
é opcional. Se não recebido, assume-se “1” (Sim).
Saídas:
não há
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GetCard deve ser chamado para se

PP_GetCard
Esta função finaliza o processo iniciado por PP_StartGetCard (conforme descrito no item 3.1.4 -
Funções “blocantes”), devendo ser chamada diversas vezes enquanto retornar PP_PROCESSING ou
função PP_Abort.
Sintaxe: int PP_GetCard (OUTPUT psOutput, OUTPUT psMsgNotify);
Entradas:
não há
Saídas:
001-002 N2 Tipo de cartão lido:
“00” - Magnético
“01” - Moedeiro VISA Cash sobre TIBC v1
“03” - EMV com contato
“04” - Easy-Entry sobre TIBC v1
“05” - Chip sem contato simulando tarja
“06” - EMV sem contato
003 N1 Status da última leitura de cartão com chip. Este
dado é usado pelo Servidor TEF quando o tipo de
cartão lido for “0” (magnético) e este tem
indicação da presença de chip, de modo a recusá-
lo ou não.
“0” - Bem sucedida (ou outro status que não
implica em fallback). Nesse caso o cartão
magnético com indicação da presença de chip
não deve ser aceito.
“1” - Erro passível de fallback. Nesse caso o
Servidor TEF pode solicitar aprovação de
transação com cartão magnético, mesmo que
este tenha indicação da presença de chip
(depende das definições da rede adquirente).
“2” - Aplicação requerida não suportada. Nesse
caso o Servidor TEF pode solicitar aprovação de
transação com cartão magnético, mesmo que
este tenha indicação da presença de chip
(depende das definições da rede adquirente).
004-005 N2 Tipo de aplicação selecionada, conforme Tabela
de Parâmetros x AID (posição 043-044).
006-007 N2 Identificador da rede adquirente, conforme
Tabela de Parâmetros x AID (posição 005-006).


008-009 N2 Índice do registro da Tabela de Parâmetros x AID
(posição 007-008).
012-087 A76 Trilha 1 (sem os sentinelas e com o byte de
formato - primeiro caractere alfanumérico),
alinhada à esquerda com espaços à direita (*)
127-129 N3 Tamanho da trilha 3 (**)
234-235 N2 Tamanho do PAN
236-254 A19 PAN, alinhado à esquerda com espaços à direita
(*)
255-256 N2 Application PAN Sequence Number

257-272 A16 Application Label, com espaços à direita.
273-275 N3 Service Code
276-301 A26 Cardholder Name, com espaços à direita
302-307 N6 Application Expiration Date (YYMMDD)
308-309 N2 Tamanho do número externo do cartão.
310-328 A19 Número externo do cartão, alinhado à esquerda
329-336 N8 Saldo, para o caso de moedeiro.
337-339 N3 Issuer Country Code
340-342 N3 Tamanho dos dados a seguir, em caracteres
343-??? A??? Dados de retorno específicos da rede adquirente
selecionada (uso futuro)
IMPORTANTE: Dependendo do cartão utilizado, nem todos os campos
acima são preenchidos. Para maiores informações, ver detalhamento de
cada situação no item 4.1deste documento.
(*)
Se o pinpad estiver em modo “Comunicação Segura”, o PAN vem
codificado pela chave WKPAN (ver item 4.4).
(**)
Se o pinpad estiver em modo “Comunicação Segura”, o campo de
“Tamanho da trilha 3” não deve ser preenchido, pois a Trilha 2 pode atingir
40 caracteres (ver explicação no item 4.4)!!
retorne PP_NOTIFY.

Retorno:
Esta função, devido a sua complexidade, admite a maioria dos códigos de retorno possíveis,
destacando-se:
PP_INVCALL ..................Função PP_StartGetCard não foi previamente chamada.
PP_MCDATAERR ...........Erro de leitura de cartão magnético (esta situação não deve “limpar” o
“status da última leitura do cartão com chip”).
PP_PROCESSING ...........Em processamento - deve-se chamar PP_GetCard novamente ou
psMsgNotify e depois chamar PP_GetCard novamente ou PP_Abort
para finalizar.
PP_TABEXP ...................Tabelas do pinpad estão expiradas e não há Biblioteca TEF configurada
(ver referências para este caso em PP_ResumeGetCard, no Item 3.5).
Observações:
Um sistema que suporta cartões sem contato deve desabilitar essa interface nos seguintes
casos:
 Quando o PP_GetCard retornar os erros PP_CTLSSPROBLEMS, PP_CTLSSAPPNAV,
PP_CTLSSAPPNAUT ou PP_CTLSSINVALIDAT.
 Quando PP_GetCard retornar o erro PP_CTLSSCOMMERR pela segunda vez consecutiva.
Início
PP_StartGetCard PP_StartGetCard
Habilita cartão sem Habilita cartão sem
contato = “1” (Sim) contato = “0” (Não)
Mostra Erro Mostra Erro

PP_GetCard
PP_NOTIFY
PP_PROCESSING PP_CTLSSPROBLEMS, PP_CTLSAPPNAV,
PP_CTLSSAPPNAUT ou PP_CTLSSINVALIDAT
PP_CTLSCOMMERR (se primeira vez) PP_CTLSCOMMERR (se segunda vez consecutiva)

ou PP_CTLSSMULTIPLE
Continua...

Exemplo:
int iStat;
/* Aguarda o processamento de cartão:

Tipo de aplicação: “99” (qualquer)
Valor da transação: R$ 238,50
Data/hora: 04/Set/02 16:42:30
Timestamp das tabelas: “1808200201”
Desabilita interface sem contato
*/
memcpy (sInput, “00990000000238500209041642301808200201000”, 41);
iStat = PP_StartGetCard (sInput);

do {
iStat = PP_GetCard (sOutput, sMsgNotify);
PP_Abort ();
return APP_CANCEL;
}
if (iSt == PP_MCDATAERR)
PP_Display (“ERRO•DE•LEITURA•TENTE•NOVAMENTE•”);
} while (iStat == PP_PROCESSING || iStat == PP_MCDATAERR
|| iStat == PP_NOTIFY);
/* Passado um cartão magnético, sOutput conterá algo como:
“00000000074B5390702278480569^MARTINS/WILSON FAZZIO•••^0207101987”
“600000000000530000000••375390702278480569=0207101000098765300000”
“0•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••”
“•••••••••••••••••••••••••••••••••••••••••00•••••••••••••••••••00”
“••••••••••••••••000••••••••••••••••••••••••••00000000•••••••••••”
“••••••••00000000000000”
*/
/* Inserido um cartão com chip EMV, sOutput conterá algo como:
“03001010500•••••••••••••••••••••••••••••••••••••••••••••••••••••”
“•••••••••••••••••••••••29376436871651006=0305000523966••••••••00”
“0•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••”
“•••••••••••••••••••••••••••••••••••••••••15376436871651006••••01”
“AMEX•GREEN••••••246SERGIO SANTOS•••••••••••••05013100•••••••••••”
“••••••••00000000076000”
*/

PP_ResumeGetCard
Caso PP_GetCard retorne PP_TABEXP, isso indica que o “time-stamp” das tabelas difere. Nesse caso,
o “checkout” deverá tentar atualizá-las através das funções descritas no item 3.5.
Independentemente do resultado dessa operação, o processo deverá continuar através da função
PP_ResumeGetCard.
Esta função comporta-se como se fosse uma nova chamada a PP_StartGetCard, considerando-se os
mesmos parâmetros passados anteriormente, de maneira a retomar o processo sem a verificação do
“time-stamp”.
Sintaxe: int PP_ResumeGetCard (void);
Entradas:
não há
Saídas:
não há
Retorno:
PP_OK ...........................Processo retomado com sucesso. PP_GetCard deve ser chamado para se
PP_INVCALL ..................Chamada inválida, PP_GetCard não retornou PP_TABEXP.
Exemplo:
iStat = PP_StartGetCard (sSrvConPar, sInput);

do {
iStat = PP_GetCard (sOutput, sMsgNotify);
PP_Abort ();
return APP_CANCEL;
}
if (iStat == PP_TABEXP) {
AtualizaTabelas ();
iStat = PP_ResumeGetCard ();
if (iStat == PP_OK) continue;
}
} while (iStat == PP_PROCESSING || iStat == PP_MCDATAERR
|| iStat == PP_NOTIFY);

PP_ChangeParameter
Este comando permite que o “checkout” altere temporariamente qualquer um dos parâmetros da
Tabela de Parâmetros x AID (ver item 7.1) correspondente à aplicação selecionada no cartão com
chip, sendo que ele somente pode ser utilizado após o comando PP_GetCard. O valor não é alterado
nas tabelas, sendo somente relevante para o cartão sendo processado no momento.
Ele é extremamente útil para resolver situações específicas não previstas pelas tabelas, como, por
exemplo, o caso de estabelecimentos que utilizam mais de uma moeda (ver exemplo).
Sintaxe: int PP_ChangeParameter (INPUT psInput);
Entradas:
001-002 N2 Tamanho dos dados a seguir, em bytes.
003-??? Hxxx(Byyy) Seqüência de parâmetros a alterar, no formato
TLV.
Saídas:
não há
Retorno:
PP_OK ...........................Comando executado com sucesso.
PP_INVCALL ..................Chamada inválida. A chamada anterior de PP_GetCard não processou
com sucesso um cartão com chip EMV.
Exemplo:
int iStat;
char sInput[40];
/* Após o PP_StartGetCard/PP_GetCard,
altera a moeda para dólar:
Transaction Currency Code = 840 -> 5F2A020840
Transaction Currency Exponent = 2 -> 5F360102
*/
memcpy (sInput, “095F2A0208405F360102”, 20);
iStat = PP_ChangeParameter (sInput);


PP_StartGoOnChip
O conjunto PP_StartGoOnChip / PP_GoOnChip (conforme descrito no item 3.1.4 - Funções
“blocantes”) continua o processo de tratamento de cartões com chip. Caso PP_GetCard tenha
reportado a passagem de um cartão magnético (ou chip sem contato simulando tarja), esta função
não deverá ser utilizada.
Sintaxe: int PP_StartGoOnChip (INPUT psInput, INPUT psTags, INPUT psTagsOpt);
Entradas:
001-012 N12 Novo valor da transação (Amount, authorized) em
centavos, podendo incluir novos valores
apresentados ao “checkout” após
PP_StartGetCard (como por exemplo, taxa do
serviço, saque ou troco). Caso não existam
acréscimos ao valor, ele deverá ser aqui mantido
idêntico ao passado em PP_StartGetCard.
013-024 N12 Parcela do valor da transação referente a saque
ou troco - cashback (Amount, other) em centavos.
Caso esse valor não exista, este campo deve ser
preenchido com zeros.
025 N1 Resultado da consulta à Lista Negra (só para EMV
com contato):
“0” - PAN não consta na Lista Negra.
”1” - PAN consta na Lista Negra.
026 N1 Obrigatoriedade de conexão (só para EMV com
contato):
“0” - Transação pode ser efetuada offline.
“1” - Transação somente pode ser efetuada
online.
027 N1 Requerimento de PIN nas tabelas do Servidor TEF
(para uso no caso de cartões Easy-Entry TIBC v1):
“0” - Não é exigida a verificação de um PIN; ou
“1” - É exigida a verificação de um PIN.
“2” - DUKPT DES
”3” - DUKPT 3DES
029-030 N2 Índice da Master Key ou do registro de
tratamento DUKPT.


031-062 H32(B16) Para os modos “0” e “1”, é a Working Key
(criptografada pela Master Key).
No modo “0”, somente os 8 primeiros bytes são
utilizados.
Nos modos “2” e “3” este campo é ignorado.
063 N1 Gerenciamento de risco EMV com contato
(Terminal Risk Management):
“0” - Não faz o gerenciamento de risco.
“1” - Faz o gerenciamento de risco usando os
parâmetros a seguir.
064-071 H8(B4) Terminal Floor Limit (em centavos)
072-073 N2 Target Percentage to be used for Biased Random
Selection
074-081 H8(B4) Threshold Value for Biased Random Selection
(em centavos)
082-083 N2 Maximum Target Percentage to be used for
Biased Random Selection
084-086 N3 Tamanho dos dados a seguir, em caracteres
087-??? A??? Parâmetros de entrada específicos da rede
adquirente selecionada (uso futuro)
psTags String ASCII de tamanho variável com o seguinte formato:
001-003 N3 Tamanho em bytes da lista de tags a seguir
(“000” a “yyy”).
004-??? Hxxx(Byyy) Lista de tags mandatórias(**) para montagem do
campo 55 da mensagem ISO8583.
psTagsOpt String ASCII de tamanho variável com o seguinte formato:
(“000” a “yyy”).
004-??? Hxxx(Byyy) Lista de tags opcionais(**) para montagem do
campo 55 da mensagem ISO8583.
(**) Não deve haver distinção de tratamento entre tags “mandatórias” e
“opcionais”, sendo que a existência dos dois parâmetros é mantida apenas
para compatibilidade com as versões anteriores da especificação.
Saídas:
não há
Retorno:
PP_OK ...........................Processo iniciado com sucesso. PP_GoOnChip deve ser chamado para se


PP_INVCALL ..................Função PP_GetCard não foi previamente chamada (ou cartão lido é
magnético ou sem contato simulando tarja).

PP_GoOnChip
Esta função finaliza o processo iniciado por PP_StartGoOnChip (conforme descrito no item 3.1.4 -
Funções “blocantes”), devendo ser chamada diversas vezes enquanto retornar PP_PROCESSING ou
função PP_Abort.
Sintaxe: int PP_GoOnChip (OUTPUT psOutput, OUTPUT psMsgNotify);
Entradas:
não há
Saídas:
001 N1 Decisão tomada:
“0” - Transação aprovada offline.
“1” - Transação negada.
“2” - Transação requer autorização online.
002 N1 Assinatura em papel deve ser obtida (“0”-não /
“1”-sim).
003 N1 PIN foi verificado offline (“0”-não / “1”-sim).
004 N1 Número de apresentações inválidas de PIN
offline (retornar ‘9’ caso este valor seja  10).
005 N1 PIN offline foi bloqueado na última apresentação
inválida (“0”-não / “1”-sim).
006 N1 PIN capturado para verificação online (“0”-não /
“1”-sim). Se este campo estiver com “0”, os dois
campos seguintes não devem ser considerados.
007-022 H16(B8) PIN criptografado
023-042 H20(B10) Número de série da chave (Key Serial Number),
somente no caso de DUKPT. Para
Master/Working Key, este campo é ignorado.
043-045 N3 Tamanho em bytes dos dados para envio no
campo 55 da mensagem ISO8583 (de “000” a
“yyy”).
046-??? Hxxx(Byyy) Dados para envio no campo 55 da mensagem
ISO8583, no formato TLV (alinhados à esquerda,
primeiro os mandatórios depois os opcionais).
Campos com tags não encontradas simplesmente
não são enviados aqui.
???-??? N3 Tamanho dos dados a seguir, em caracteres


???-??? A??? Dados de retorno específicos da rede adquirente
retorne PP_NOTIFY.
Retorno:
destacando-se:
PP_INVCALL ..................Função PP_StartGoOnChip não foi previamente chamada.
PP_PROCESSING ...........Em processamento - deve-se chamar PP_GoOnChip novamente ou
psMsgNotify e depois chamar PP_GoOnChip novamente ou PP_Abort
para finalizar.
Exemplo:
int iStat;
/* Continua o processamento de cartão com chip EMV:

Novo valor da transação: R$ 274,65
Valor de saque/troco: R$ 71,00
Lista Negra: “0” (não consta)
Obrigatoriedade de conexão: “0” (transação pode ser offline)
Requerimento de PIN: “1” (é exigido)
Modo de criptografia: “2” (DUKPT DES)
Registro de tratamento DUKPT: “07”
Faz gerenc. de risco EMV (Floor Limit = R$ 100,00)
*/
memcpy (sInput, “000000027465000000007100001207”

“00000000000000000000000000000000”
“100002710200000138875000”, 86);
/* Os dados EMV requeridos pela rede são:

9F27 - Cryptogram Information Data
9F26 - Application Cryptogram
95 - Terminal Verification Results
9B - Transaction Status Information
9F34 - Cardholder Verification Method Results
9F10 - Issuer Application Data
... e opcionalmente:
5F20 - Cardholder Name
5F28 - Issuer Country Code
*/
iStat = PP_StartGoOnChip (sInput, “0109F279F26959B9F349F10”,

“0045F205F28”);

do {
iStat = PP_GoOnChip (sOutput, sMsgNotify);
PP_Abort ();
return APP_CANCEL;
}
} while (iStat == PP_PROCESSING || iStat == PP_NOTIFY);
/* A partir daqui, sOutput poderá conter algo como:
“2000018D540BCF3001577AFFFF9876543210E0000C047”
“9F2701809F260804CA8F1428AB5901950580000100009B02E800”
“9F34030201009F100706011A039000005F28020076000”
- Transação requer autorização online

- PIN deve ser verificado online (DUKPT)
- 47 bytes em formato TLV devem ser enviados no campo 55
*/

PP_FinishChip
Este comando finaliza o processamento de cartão com chip, caso PP_GoOnChip tenha requerido
aprovação online ou caso a transação já tenha sido aprovada offline. Uma transação negada em
PP_GoOnChip (decisão “1”) não requer uma chamada a PP_FinishChip.
Sintaxe: int PP_FinishChip (INPUT psInput, INPUT psTags, OUTPUT psOutput);
Entradas:
001 N1 Status da comunicação com o Host:
“0” - OK, comunicação bem sucedida.
“1” - Não foi possível comunicar com o Host.
Nesse caso, os demais campos deste parâmetro
não são tratados, devendo ser passados zerados.
002 N1 Tipo de Emissor:
“0” - EMV ‘Full Grade’.
“1” - EMV ‘Partial Grade’.
003-004 A2 Authorization Response Code (Código de
autorização recebido do Host)
005-007 N3 Tamanho em bytes dos dados recebidos no
campo 55 da mensagem ISO8583 (de “000” a
“yyy”)
008-??? Hxxx(Byyy) Dados em formato TLV recebidos no campo 55
da mensagem ISO8583
???-??? A??? Parâmetros de entrada específicos da rede
adquirente selecionada (uso futuro)
psTags String ASCII de tamanho variável com o seguinte formato:
(“000” a “yyy”).
004-??? Hxxx(Byyy) Lista de tags para montagem de conjunto de
dados finais requeridos.

Saídas:
001 N1 Decisão tomada:
“0” - Transação aprovada.
“1” - Transação negada pelo cartão.
“2” - Transação negada pelo Host.
002-004 N3 Tamanho em bytes dos dados finais requeridos
(de “000” a “yyy”).
005-??? Hxxx(Byyy) Dados finais requeridos, no formato TLV. Campos
com tags não encontradas simplesmente não são
enviados aqui.
???-??? N2 Tamanho em bytes do Issuer Script Results
(de “00” a “yy”).
???-??? Hxx(Byy) Issuer Script Results
???-??? A??? Dados de retorno específicos da rede adquirente
Retorno:
destacando-se:
PP_OK ...........................Processo finalizado com sucesso.
PP_INVCALL ..................Função PP_GoOnChip não foi previamente chamada.
Exemplo:
int iStat;
char sInput[500], sOutput[500];
/* Finaliza o processamento de cartão com chip EMV:

Status da comunicação com Host: “0” (bem sucedida)
Tipo de Emissor: “0” (Full Grade)
Authorization Response Code: “00” (aprovada)
Dados recebidos no campo 55: “9108330D56C80029FC3A”
*/
memcpy (sInput, “00000109108330D56C80029FC3A000”, 30);
/* Os dados EMV finais requeridos pela rede são:

9F27 - Cryptogram Information Data
9F26 - Application Cryptogram
*/

iStat = PP_FinishChip (sInput, “0049F279F26”, sOutput);

/* A partir daqui, sOutput poderá conter algo como:
“00159F2701409F260819C5D08A4419BBD900000”
- Transação aprovada
- 15 bytes em formato TLV
- 0 bytes de Issuer Script Results
*/

3.5. Funções para Manutenção das Tabelas

Conforme especificado no Capítulo 7, o pinpad conta com um conjunto interno de tabelas de
parâmetros para o processamento de cartões com chip. Estas tabelas podem ser carregadas (ou
atualizadas) através das seguintes funções:
PP_TableLoadInit Inicia o processo de carga de tabelas
PP_TableLoadRec Carrega um ou mais registros das tabelas
PP_TableLoadEnd Finaliza o processo de carga de tabelas
PP_GetTimeStamp Obtém o “time-stamp” das tabelas.
IMPORTANTE: O pinpad gerencia tabelas separadas para cada rede adquirente. Desta forma:
 Quando os comandos acima referenciam uma das redes (identificador da rede ≥ “01”),
somente as tabelas desta rede são alteradas, preservando-se as outras. O “time-stamp”,
neste caso, refere-se somente às tabelas desta rede, podendo ser diferente dos “time-
stamps” das tabelas das outras redes.
 Quando os comandos acima referenciam todas as redes (identificador da rede = “00”), todas
as tabelas são alteradas, sendo que todas as redes passam a ter tabelas com o mesmo “time-
stamp”.

PP_TableLoadInit
Esta função inicia o processo de carga (ou atualização) de tabelas. Caso ela retorne PP_OK ou
PP_TABEXP, o processo pode continuar através das funções PP_TableLoadRec e PP_TableLoadEnd.
IMPORTANTE: Esta função não faz críticas quanto ao conteúdo do “time-stamp”, apenas retorna
status diferenciado por uma questão informativa. Ela deve sempre iniciar o processo de carga de
tabelas, acatando incondicionalmente a demanda do “checkout”.
Sintaxe: int PP_TableLoadInit (INPUT psInput);
Entradas:
psInput String ASCII de 12 caracteres contendo:
001-002 N2 Identificador da Rede Adquirente cujas tabelas
serão atualizadas, conforme Tabela de
Parâmetros x AID. Para abranger todas as redes,
deve-se usar o valor “00”.
seqüencial (“DDMMAAAASS”).
relativas a ela.
Saídas:
não há.
Retorno:
PP_OK ...........................Tabelas já estão atualizadas (“time-stamp” é o mesmo).
PP_TABEXP ...................Tabelas estão desatualizadas (“time-stamp” é diferente).

PP_TableLoadRec
Esta função carrega um ou mais registros das tabelas, armazenando-os de forma temporária. Isso é
importante para preservar as tabelas atuais em caso de erro na operação de atualização.
Sintaxe: int PP_TableLoadRec (INPUT psInput);
Entradas:
psInput String ASCII contendo um ou mais registros de tabelas concatenados,
conforme layout descrito no Capítulo 7. Considerando-se que cada registro é
iniciado pelo seu tamanho
001-002 N2 Quantidade de registros a seguir
003-??? Um ou mais registros concatenados, cada um
iniciado pela informação de tamanho, conforme
descrito no Capítulo 7.
Saídas:
não há.
Retorno:
PP_INVCALL ..................Função PP_TableLoadInit não foi previamente chamada com retorno
PP_OK ou PP_TABEXP.
PP_TABERR ...................Erro ao tentar armazenar registros.

PP_TableLoadEnd
Esta função finaliza o processo de carga (ou atualização) de tabelas, fazendo com que os registros
fornecidos através de PP_TableLoadRec sejam armazenados de forma definitiva, substituindo as
tabelas anteriores (caso existentes). Nesse momento, o “time-stamp” fornecido através de
PP_TableLoadInit passa a vigorar para as novas tabelas.
Sintaxe: int PP_TableLoadEnd (void);
Entradas:
não há.
Saídas:
não há.
Retorno:
PP_INVCALL ..................Função PP_TableLoadInit não foi previamente chamada com retorno
PP_OK ou PP_TABEXP.
PP_TABERR ...................Erro ao tentar armazenar tabelas.

PP_GetTimeStamp
Esta função obtém o “time-stamp” das tabelas, para uso caso o “checkout” necessite dessa
informação.
Sintaxe: int PP_GetTimeStamp (INPUT psInput, OUTPUT psOutput);
Entradas:
psInput String ASCII de 2 caracteres contendo:
001-002 N2 Identificador da Rede Adquirente cujas tabelas
serão atualizadas, conforme Tabela de
Parâmetros x AID. Deve-se usar o valor “00”
quando utiliza-se um “time-stamp” único para
todas as redes (isso só faz sentido se as tabelas
foram carregadas usando-se também “00” na
função PP_TableLoadInit).
Saídas:
psOutput String ASCII de 10 caracteres contendo:
seqüencial (“DDMMAAAASS”).
relativas a ela.
Caso não exista tabela carregada para a rede
informada, o “time-stamp” será “0000000000”.
Retorno:
PP_OK ...........................Operação executada com sucesso

4. Tratamentos internos à
Biblioteca/Pinpad
Este capítulo destina-se a auxiliar o desenvolvimento do conjunto Biblioteca/Pinpad, descrevendo

detalhadamente os tratamentos a serem feitos em cada uma das funções.
A compreensão deste capítulo não é necessária para o desenvolvedor da aplicação de “checkout”,
uma vez que este se limita a ser “usuário” da Biblioteca de Pinpad.
4.1. Função PP_StartGetCard / PP_GetCard

Estas funções pedem a passagem de um cartão magnético ou a inserção ou a aproximação de um
cartão com chip. Dessa maneira, elas automaticamente apresentam a seguinte mensagem do display
do pinpad (sempre enfatizando a inserção do chip):
INSIRA OU
PASSE O CARTAO
Caso o pinpad suporte cartão sem contato e todas as condições abaixo sejam válidas, a seguinte
mensagem deve ser mostrada (sempre enfatizando a aproximação de um cartão sem contato) e a
antena deve ser ativada:
APROXIME, INSIRA
OU PASSE CARTAO
Condições para ativação da interface sem contato:
 Caso o parâmetro de habilitação da interface sem contato exista em PP_StartGetCard, ele deve
indicar “Sim”.
 Ao menos um dos registros da Tabela de Parâmetros x AID envolvidos na seleção indique essa
tecnologia (posição 167  “0”);
 Se o valor fornecido estiver zerado, ao menos um desses registros da Tabela de Parâmetros x
AID indique a possibilidade de processamento online nesse caso (posição 166  “0”); e
 Ao menos um desses registros da Tabela de Parâmetros x AID possua o parâmetro
Terminal/Reader Contactless Transaction Limit (posição 168-175) com valor superior ao valor
fornecido para a transação.
IMPORTANTE:
 Caso já exista um cartão inserido no leitor de chip, a mensagem acima não deve ser mostrada,
sendo que a interface sem contato não necessita ser ativada.
 Após a inserção do cartão, a mensagem deve ser imediatamente apagada do display.
 O conjunto “PP_StartGetCard / PP_GetCard” pode ser chamado pelo “checkout” mais de uma
vez, independentemente do acionamento de outras funções (“PP_StartGoOnChip”,

“PP_GoOnChip”, “PP_FinishChip”, “PP_RemoveCard”, etc). Caso isso ocorra, o processamento

iniciado pela chamada anterior é desprezado e um novo é iniciado, sem a necessidade da
remoção do cartão.
Dependendo do cartão utilizado, o processamento é diferente e descrito a seguir.
4.1.1. Cartão magnético

Caso um cartão magnético seja passado, seus dados são simplesmente retornados por PP_GetCard,
como mostrado as seguir. Em caso de erro de leitura, PP_GetCard deve retornar PP_MCDATAERR.
psOutput:
Posição Descrição Valor

001-002 Tipo de cartão lido “00” - Magnético
003 Status da última leitura de cartão com chip:
“0” - Bem sucedida (ou status desconhecido).
“1” - Erro de acesso, possível fallback.
“2” - Aplicação requerida não suportada.
010-011 Tamanho da trilha 1 ≠ “00” se trilha 1 lida
012-087 Trilha 1 (sem os sentinelas e com o byte de formato Dados da trilha 1 lida
- primeiro caractere alfanumérico), alinhada à
esquerda com espaços à direita.
090-126 Trilha 2 (sem os sentinelas), alinhada à esquerda Dados da trilha 2 lida
com espaços à direita.
130-233 Trilha 3 (sem os sentinelas), alinhada à esquerda Dados da trilha 3 lida
4.1.2. Cartão com chip com contato

Caso seja inserido um cartão com chip, o pinpad deve apresentar a seguinte mensagem no display:
PROCESSANDO...
Primeiramente deve-se comparar o “time-stamp” armazenado com o fornecido em

PP_StartGetCard. Caso sejam diferentes, deve-se efetuar o processo de atualização das tabelas de
EMV.
A seguir o cartão é ativado e seu tipo é identificado de modo a ser processado diferentemente, de
acordo com o descrito nos subitens a seguir.
Caso haja um problema no processamento do cartão com chip, PP_GetCard deverá retornar um erro
maior ou igual a PP_DUMBCARD de acordo com a tabela do item 3.1.2.

Essa ocorrência é então armazenada de maneira volátil pela Biblioteca de Pinpad para ser reportada
no parâmetro de retorno “Status da última leitura de cartão com chip” na próxima chamada às
funções PP_StartGetCard / PP_GetCard. Essa ocorrência não é preservada após uma chamada a
PP_Close.
Valor a ser colocado no campo

“status da última leitura de cartão “0” “1” “2”
com chip”
PP_DUMBCARD
PP_OK PP_ERRCARD
Status do último PP_GetCard. PP_CARDAPPNAV
outros status PP_SAMERR
PP_ERRFALLBACK
4.1.2.1. Cartão com chip EMV

Caso seja um cartão com chip EMV, deve-se efetuar o processamento inicial de seleção de aplicação
(Application Selection) estipulado pela norma EMV1.
Durante a seleção da aplicação, a mensagem “SELECIONADO: xxxxxxx” deverá ser enviada ao
“checkout” através do recurso PP_NOTIFY (onde “xxxxxxxx” é a etiqueta da aplicação), para cada
mudança de seleção no menu, indicando assim o item atualmente em destaque.
Como etiqueta da aplicação, deve-se utilizar o Application Preferred Name ao invés do Applicaton
Label caso esteja presente e o Issuer Code Table Index for compatível com o Additional Terminal
Capabilities.
4.1.2.1.1. Aplicação de Crédito/Débito EMV
Caso seja selecionada uma aplicação de crédito ou débito, ela segue a norma EMV e, assim, deve-se
continuar com os seguintes processamentos estipulados pela norma EMV:
 Obtenção das opções de processamento (Get Processing Options); e
 Leitura dos dados da aplicação (Read Application Data).
Os seguintes parâmetros de entrada de PP_StartGetCard devem ser inseridos no banco de dados

EMV para processamento antes do Get Processing Options:
 Valor inicial da transação (Amount, authorized) - Tags ‘9F02’ e ‘81’;
 Data da transação (“AAMMDD”) - Tag ‘9A’; e
 Hora da transação (“HHMMSS”) - Tag ‘9F21’.
OBS: Caso o cartão reporte no Get Processing Options um status (SW1/SW2) cujo comportamento
não é regido pela norma EMV, esta situação deve ser considerada como um erro passível de fallback.
Assim, a função PP_GetCard deverá retornar erro PP_ERRFALLBACK.
Os seguintes dados são retornados por PP_GetCard ao final do processamento:
1
IMPORTANTE: De forma global, o Kernel EMV do equipamento deve suportar até 100 AIDs simultâneos no processo
de seleção, provenientes de uma ou mais tabelas de diferentes redes adquirentes.

psOutput:

001-002 Tipo de cartão lido “03” - Chip EMV
“0” - Bem sucedida
004-005 Tipo de aplicação selecionada, conforme Tabela de
Parâmetros x AID.
006-007 Identificador do adquirente, conforme Tabela de
Parâmetros x AID.
008-009 Índice do registro da Tabela de Tabela de
Parâmetros x AID
088-089 Tamanho da trilha 2
090-126 Trilha 2 (sem os sentinelas), alinhada à esquerda Tag ‘57’
234-235 Tamanho do PAN
236-254 PAN, alinhado à esquerda com espaços à direita. Tag ‘5A’
255-256 Application PAN Sequence Number Tag ‘5F34’
257-272 Application Label, com espaços à direita. Tag ‘50’ ou ‘9F12’(*)
273-275 Service Code Tag ‘5F30’
276-301 Cardholder Name, com espaços à direita. Tag ‘5F20’
302-307 Application Expiration Date (YYMMDD) Tag ‘5F24’
337-339 Issuer Country Code Tag ‘5F28’
(*) Se o Issuer Code Table Index for compatível com o Additional Terminal Capabilities.
OBSERVAÇÕES:
 Esta especificação não prevê que o Transaction Sequence Counter (Tag ‘9F41’) seja enviado pelo
checkout, portanto ele deve ser gerido internamente pelo pinpad. Dessa maneira, esse contador
deve ser iniciado em 1 (o valor zero não deve ser usado, segundo a norma) e incrementado no
sempre que detectada a inserção de um cartão EMV. Devem-se manter contadores separados
para cada rede adquirente.
4.1.2.1.2. Aplicação Visa Cash sobre TIBC v3
Caso seja selecionada uma aplicação de moedeiro VISA Cash, os procedimentos a serem efetuados
são proprietários da VISA e sua descrição encontra-se em documento anexo fornecido pela Cielo.
4.1.2.2. Cartão com chip TIBC v1

Caso o cartão inserido seja identificado como um TIBC v1, os procedimentos a serem efetuados são
proprietários da VISA e sua descrição encontra-se em documento anexo fornecido pela Cielo.

4.1.3. Cartão com chip sem contato

Caso seja apresentado um cartão sem contato ao pinpad, este deverá verificar se os AIDs fornecidos
pelo PPSE têm correspondência na Tabela de Parâmetros x AID, considerando-se somente os
registros que cumpram os seguintes requisitos:
 A posição 167 deve ser diferente de “0”;
 Se o valor da transação está zerado, a posição 166 deve ser diferente de “0”; e
 O parâmetro Terminal/Reader Contactless Transaction Limit (posição 168-175) deve ser maior
do que o valor da transação.
Caso seja encontrada mais de uma aplicação, deve-se verificar o valor da posição 196 dos registros
correspondentes.
 Se todos os registros tiverem o valor “0”, deve-se selecionar automaticamente a aplicação de
maior prioridade.
 Se ao menos um registro tiver o valor “1”, deve-se apresentar um menu de seleção idêntico ao
usado nos cartões com contato. O portador deve escolher uma das aplicações e o pinpad deverá
aguardar novamente o cartão, apresentando a seguinte mensagem:
APROXIME O
CARTAO NOVAMENTE
Identificada a aplicação a ser usada, deve-se verificar o valor da posição 167 na Tabela de
Parâmetros x AID, de forma a efetuar os processamentos:
Valor Cartão Tratamento

apresentado
“1” VISA (qualquer) Trata cartão como “MSD” (simulando tarja), conforme descrito em
VCPS (ver item 4.1.3.1).
“2” VISA (qualquer) Trata cartão como “qVSDC”, conforme descrito em VCPS (ver
item 4.1.3.2).
“3” PayPass (qualquer) Trata cartão como “PayPass Mag Stripe” (simulando tarja),
conforme descrito em PPMagStr (ver item 4.1.3.1).
“4” PayPass M/Chip Trata cartão como “M/Chip”, conforme descrito em PPMChip
(ver item 4.1.3.2).
“4” PayPass Mag Stripe Trata cartão como “PayPass Mag Stripe” (simulando tarja),
conforme descrito em PPMagStr (ver item 4.1.3.1).
“5” Expresspay Trata cartão como “Magstripe Mode” (simulando tarja), conforme
(qualquer) descrito em ExpPay (ver item 4.1.3.1).
“6” Expresspay EMV Trata cartão como “EMV Mode”, conforme descrito em ExpPay
(ver item 4.1.3.2).
“6” Expresspay Trata cartão como “Magstripe Mode” (simulando tarja), conforme
Magstripe descrito em ExpPay (ver item 4.1.3.1).
Pelas características dos cartões sem contato, todo o processamento é feito já na função
PP_StartGetCard / PP_GetCard, independentemente do modelo/padrão acima. Caso a transação

requeira verificação do portador (PIN Online), isso deverá ser feito em PP_StartGoOnChip /
PP_GoOnChip.
Caso ocorra qualquer erro de processamento do cartão sem contato, a seguinte mensagem deve ser
apresentada
4.1.3.1. Cartão com chip sem contato simulando tarja

Independentemente do padrão (VISA, MasterCard ou Amex), quando o cartão sem contato simula
uma tarja magnética deve-se retornar os seguintes dados:
psOutput:

001-002 Tipo de cartão lido “05” - Chip sem contato
simulando tarja
Parâmetros x AID.
Parâmetros x AID.
Parâmetros x AID
012-087 Trilha 1 (sem os sentinelas), alinhada à esquerda Montado conforme VCPS,
com espaços à direita. PPMagStr, ou ExpPay.
090-126 Trilha 2 (sem os sentinelas), alinhada à esquerda Montado conforme VCPS,
com espaços à direita. PPMagStr, ou ExpPay.
4.1.3.2. Cartão com chip EMV sem contato

O processamento deve ser efetuado conforme VCPS, PPMChip ou ExpPay, sendo que os
seguintes dados são retornados por PP_GetCard ao final do processamento:
psOutput:

001-002 Tipo de cartão lido “06” - Chip EMV sem contato


Parâmetros x AID.
Parâmetros x AID.
Parâmetros x AID
090-126 Trilha 2 (sem os sentinelas), alinhada à esquerda Tag ‘57’
234-235 Tamanho do PAN
236-254 PAN, alinhado à esquerda com espaços à direita. Tag ‘5A’
255-256 Application PAN Sequence Number Tag ‘5F34’
276-301 Cardholder Name, com espaços à direita. Tag ‘5F20’
302-307 Application Expiration Date (YYMMDD) Tag ‘5F24’
337-339 Issuer Country Code Tag ‘5F28’

4.2. Função PP_StartGoOnChip / PP_GoOnChip

Estas funções são chamadas pelo “checkout” caso tenha sido lido um cartão com chip, excetuando-se
o caso do cartão sem contato simulando tarja (que, para todos os efeitos, é processado como um
cartão magnético). Os tratamentos envolvidos são diferentes dependendo do tipo de chip, descritos
a seguir.
4.2.1. Aplicação de Crédito/Débito EMV com contato

O processamento de cartão com chip EMV deve continuar a seguir os processamentos estipulados
pela norma EMV:
 Análise das restições de processamento (Processing Restrictions);
 Autenticação de dados (Offline Data Authentication);
 Verificação de portador (Cardholder Verification);
 Gerenciamento de risco do terminal (Terminal Risk Management);
 Análise de ação do terminal (Terminal Action Analysis); e
 Análise de ação do cartão (Card Action Analysis).
Os seguintes parâmetros de entrada de PP_StartGoOnChip devem ser inseridos no banco de dados

EMV para uso no processamento:
 Novo valor da transação (Amount, authorized) - Tags ‘9F02’ e ‘81’ (este valor deve ser atualizado,
podendo diferir do valor armazenado anteriormente).
 Valor de saque ou troco - cashback (Amount, other) - Tags ‘9F03’ e ‘9F04’.
O parâmetro “Obrigatoriedade de conexão”, caso ativo, deve fazer com que o resultado do Terminal
Action Analysis nunca gere TC (aprovado offline).
O parâmetro “Resultado da consulta à Lista Negra” deve ativar o bit do TVR Card appears on
terminal exception file
Caso seja necessária a captura do PIN do usuário, os seguintes pontos devem ser levados em
consideração:
 Na captura do PIN, a seguinte mensagem deve ser utilizada no pinpad, incluindo a informação
de valor total da transação (campo “novo valor da transação”):
VALOR:nnn.nnn,nn n.nnn.nnn.nnn,nn
senha: ou senha:
**** ****
 Antes de pedir o PIN ao usuário, a mensagem “SOLICITE A SENHA” deverá ser enviada ao
“checkout” através do recurso PP_NOTIFY.
 Mensagens de erro de verificação e/ou bloqueio de PIN também devem ser enviadas ao
“checkout” através do recurso PP_NOTIFY. As seguintes mensagens estão previstas: "SENHA

INVALIDA", "PROX. ERRO BLOQUEIA SENHA" e "SENHA BLOQUEADA". Para maiores

informações, consultar as especificações das aplicações das redes adquirentes.
 Caso a verificação do portador demande captura de PIN criptografado para verificação online,
deve-se utilizar os parâmetros fornecidos em PP_StartGoOnChip para esse fim.
 O display deve sempre ser apagado após a captura de PIN, seja esta bem ou mal sucedida.
Os seguintes dados são retornados PP_GoOnChip ao final do processamento:
psOutput:

001 Decisão tomada: “0” - Transação aprovada offline;
ou
“1” - Transação negada; ou
“2” - Transação requer
autorização online.
002 Assinatura em papel deve ser obtida (“0”-não / “1”- de acordo com resultado do
sim). CVM
003 PIN já foi verificado offline (“0”-não / “1”-sim). de acordo com resultado do
CVM
004 Número de apresentações inválidas de PIN offline.
005 PIN offline foi bloqueado na última apresentação de acordo com resultado do
inválida (“0”-não / “1”-sim). CVM
006 PIN capturado para verificação online (“0”-não / “1”- de acordo com resultado do
sim). Se este campo estiver com “0”, os dois campos CVM
seguintes não devem ser considerados.
007-022 PIN criptografado
023-042 Número de série da chave (Key Serial Number),
somente no caso de DUKPT. Para Master/Working
Key, este campo é ignorado.
043-045 Tamanho em bytes dos dados para envio no campo
55 da mensagem ISO8583 (de “000” a “yyy”).
046-??? Dados para envio no campo 55 da mensagem Montado a partir das listas
ISO8583, no formato TLV (alinhados à esquerda). mandatórias e opcionais de
Campos com tags não encontradas simplesmente PP_StartGoOnChip
4.2.2. Aplicação Visa Cash sobre TIBC v1 ou v3

Este tipo de cartão é proprietário da VISA e seu processamento está descrito em documento anexo
fornecido pela Cielo.

4.2.3. Aplicação Easy-Entry sobre TIBC v1

4.2.4. Aplicação de Crédito/Débito EMV sem contato

O cartão sem contato é processado inteiramente na função PP_StartGetCard / PP_GetCard. Desta
forma, o valor da transação (Amount, authorized) não pode ser alterado em PP_StartGoOnChip. Caso
isso aconteça, o pinpad deve retornar PP_INVPARM.
Caso o processamento decida por pedir PIN Online, isso é feito da mesma forma descrita no item
4.2.1.
Os seguintes dados são retornados por PP_GoOnChip ao final do processamento:
psOutput:

001 Decisão tomada: “0” - Transação aprovada offline;
ou
“1” - Transação negada; ou
“2” - Transação requer
autorização online.
002 Assinatura em papel deve ser obtida (“0”-não / “1”- de acordo com resultado do
sim). CVM
006 PIN capturado para verificação online (“0”-não / “1”- de acordo com resultado do
sim). Se este campo estiver com “0”, os dois campos CVM
seguintes não devem ser considerados.
007-022 PIN criptografado
023-042 Número de série da chave (Key Serial Number) e
contador (Key Counter), somente no caso de DUKPT.
Para Master/Working Key, este campo é ignorado.
043-045 Tamanho em bytes dos dados para envio no campo
55 da mensagem ISO8583 (de “000” a “yyy”).
046-??? Dados para envio no campo 55 da mensagem Montado a partir das listas
ISO8583, no formato TLV (alinhados à esquerda). mandatórias e opcionais de
Campos com tags não encontradas simplesmente PP_StartGoOnChip
OBS: Deve-se tem em mente que o processamento de cartões sem contato, tanto VISA como
MasterCard, é uma simplificação do EMV com contato e, desta forma, alguns dados do campo 55
podem não existir, como o Cryptogram Information Data (tag ‘9F27) no caso do qVSDC.

4.3. Função PP_FinishChip

Esta função é chamada pelo “checkout” caso PP_GoOnChip tenha requerido aprovação online ou
caso a transação já tenha sido aprovada offline. Os tratamentos envolvidos são diferentes
dependendo do tipo de chip, descritos a seguir.
OBS: Independentemente do tratamento descrito a seguir, esta função deve desligar a alimentação
do cartão com chip ao final do processamento.
4.3.1. Aplicação de Crédito/Débito EMV com contato

No caso de cartão EMV, diversas situações são contempladas em PP_FinishChip, descritas a seguir:
4.3.1.1. Aprovada offline

Caso a transação já tenha sido aprovada offline pelo cartão em PP_StartGoOnChip / PP_GoOnChip, o
Servidor TEF faz as vezes de Host e armazena a transação para envio futuro, devolvendo o código de
resposta “00”.
Nesse caso, a Biblioteca de Pinpad não faz mais nada, somente “rebatendo” a decisão do Servidor
TEF.
Os seguintes dados são retornados PP_FinishChip ao final do processamento:
psOutput:

001 Decisão tomada: “0” - Transação aprovada
002-004 Tamanho em bytes dos dados finais requeridos (de “000”
“000” a “yyy”).
???-??? Tamanho em bytes do Issuer Script Results (de “00” “00”
a “yy”).
4.3.1.2. Não foi possível comunicar com o Host

Caso a comunicação com o Host não tenha sido bem sucedida, o processamento EMV prossegue
para o caso do “Unable To Go Online”, descrito pela norma. Ao final, a transação pode ser aprovada
ou negada pelo cartão no procedimento de finalização (Completion).

psOutput:

001 Decisão tomada: “0” - Transação aprovada; ou
“1” - Transação negada pelo
cartão.
002-004 Tamanho em bytes dos dados finais requeridos (de
“000” a “yyy”).
005-??? Dados finais requeridos, no formato TLV. Campos Montado a partir da lista de
com tags não encontradas simplesmente não são PP_FinishChip
enviados aqui.
???-??? Tamanho em bytes do Issuer Script Results (de “00” “00”
a “yy”).
4.3.1.3. Comunicou com Host / Emissor “Partial Grade”

Caso a comunicação com o Host tenha sido bem sucedida mas o emissor é do tipo “Partial Grade”, a
Biblioteca de Pinpad não faz mais nada, somente “rebatendo” sua decisão (não processa o
Completion - 2nd Generate AC).
psOutput:

(caso reposta do Host = “00”)
Host.
(caso resposta do Host  “00”)
002-004 Tamanho em bytes dos dados finais requeridos (de “000”
“000” a “yyy”).
???-??? Tamanho em bytes do Issuer Script Results (de “00” a “00”
“yy”).
4.3.1.4. Comunicou com Host / Emissor “Full Grade”

Caso a comunicação com o Host tenha sido bem sucedida e o emissor seja do tipo “Full Grade”, o
processamento de cartão com chip EMV deve continuar a seguir os processamentos estipulados pela
norma EMV:
 Processamento online (Online Processing);
 Processamento de scripts (Issuer-to-Card Script Processing); e
 Finalização (Completion).
Os seguintes parâmetros de entrada de PP_FinishChip devem ser inseridos no banco de dados EMV
para uso no processamento:

 Authorization Response Code (Código de autorização recebido do Host) - Tag ‘8A’.

 TLVs recebidos do Emissor através no campo 55 (normalmente o Issuer Authentication Data -
Tag ‘91’ e os Issuer Script Templates - Tags ‘71’ e ‘72’).
psOutput:

001 Decisão tomada: “0” - Transação aprovada; ou
cartão; ou
Host.
002-004 Tamanho em bytes dos dados finais requeridos (de
“000” a “yyy”).
005-??? Dados finais requeridos, no formato TLV. Campos Montado a partir da lista de
com tags não encontradas simplesmente não são PP_FinishChip
enviados aqui.
???-??? Tamanho em bytes do Issuer Script Results (de “00” a
“yy”).
???-??? Issuer Script Results Resultado do processamento
dos scripts do emissor
4.3.2. Aplicação Visa Cash sobre TIBC v1 ou v3

4.3.3. Aplicação Easy-Entry sobre TIBC v1

4.3.4. Aplicação de Crédito/Débito EMV sem contato

No caso de cartão sem contato, a Biblioteca de Pinpad não faz mais nada, somente “rebatendo” a
decisão informada em psInput.

psOutput:

(caso reposta do Host = “00”)
“2” - Transação negada p/ Host.
(caso resposta do Host  “00” ou
status da comunicação  “0”)
002-004 Tamanho em bytes dos dados finais requeridos (de “000” (*)
“000” a “yyy”).
???-??? Tamanho em bytes do Issuer Script Results (de “00” a “00”
“yy”).
(*) Caso o “checkout” passe uma lista de tags em PP_FinishChip, ela deve ser simplesmente
ignorada.

4.4. Comunicação Segura

Para evitar que dados sensíveis (como o número do cartão - PAN) trafeguem livremente pela porta
serial do pinpad, esta especificação implementa uma modalidade de trabalho denominada
“Comunicação Segura”.
Nesta modalidade, o número de cartão sempre transitará criptografado por uma chave DES (ou
3DES) denominada WKPAN.
Esta especificação prevê que a chave WKPAN possa ser gerada de duas formas:
Modalidade 1:
Se uma Master Key (DES ou 3DES) do pinpad for conhecida, a WKPAN poderá ser gerada
externamente e fornecida ao pinpad criptografada por esta Master Key. O tamanho da chave
WKPAN deverá respeitar o tamanho da Master Key conhecida (8 bytes para DES, 16 bytes para
3DES).
“Checkout” “Pinpad”
MK WKPAN MK
Alg-1
Alg WKPAN
WKPAN
WKPAN
Modalidade 2:
Uma chave WKPAN aleatória, sempre 3DES, poderá ser gerada internamente no pinpad e
fornecida ao “checkout” através de um certificado RSA, conforme descrito no item 4.4.4.
Kpub Kpub
Kpriv
WKPAN
RSA WKPAN
RSA
WKPAN
A ativação da “Comunicação Segura”, assim como a definição da chave WKPAN, é feita através da
função PP_DefineWKPAN, sendo que as seguintes funções da Biblioteca são afetadas nessa
modalidade:
 PP_CheckEvent;
 PP_StartGetPIN;

 PP_EncryptBuffer; e
 PP_GetCard.
4.4.1. Formato de criptografia de PAN

Em “Comunicação Segura”, o número do cartão (PAN) sempre trafegará codificado pela WKPAN:
 Quando enviado do pinpad para o “checkout”, sempre será usado o algoritmo DES/3DES.
 Quando enviado do “checkout” para o pinpad, sempre será usado o algoritmo DES/3DES
Reverso.
PAN
Alg-1 PAN
Alg
PAN
WKPAN WKPAN
PAN
Alg
Alg-1 PAN
PAN
A codificação do número do cartão deverá respeitar as seguintes regras:

 Somente os 16 dígitos menos significativos do PAN são criptografados, considerando-se que eles
perfazem um bloco de 8 bytes em codificação BCD. Dado que os parâmetros das funções são em
ASCII, os dígitos numéricos decimais do PAN podem ser substituídos diretamente pelos dígitos
hexadecimais do criptograma gerado.
 Espaços em branco no meio do número do cartão (tipicamente na trilha 1 de alguns emissores)
deverão ser convertidos para dígitos ‘E’ (em hexadecimal).
 A seguinte regra deve ser utilizada para identificação do PAN dentro das trilhas (seja 1, 2 ou 3):
 Da esquerda para a direita, localizar o primeiro caractere numérico (‘0’ a ‘9’) ou espaço em
branco. Ele marca o início do PAN.
 Continuar percorrendo a trilha para localizar o caractere separador (“^” ou “=”) ou até
atingir seu final.
 O PAN obtido não será criptografado nos seguintes casos:
 Se tiver menos de 13 dígitos.
 Se contiver algum caractere não numérico (‘0’ a ‘9’) e diferente de espaço em branco.
 Caso o PAN tenha menos de 16 dígitos, ele será acrescido de dígitos ‘F’ (em hexadecimal) à
direita, até completar esse tamanho.
IMPORTANTE: Por conta desta regra, a Trilha 2 pode ultrapassar 37 caracteres em algumas
situações (tipicamente quando o PAN tem menos do que 16 dígitos). Desta forma, o campo

“Tamanho da Trilha 3” nunca deve ser preenchido no modo de “Comunicação Segura”, mesmo
que a Trilha 3 tenha sido lida com sucesso (somente o campo “Trilha 3” é preenchido).
 A informação de tamanho do PAN ou trilha contida nos parâmetros de entrada e saída das
funções deve respeitar o tamanho da informação enviada, incluindo a criptografia. A entidade
que receber o dado criptografado, seja o “checkout” ou o pinpad, deverá eliminar eventuais ‘F’s
ao final do PAN depois de decodificado e recalcular seu tamanho real.
4.4.2. Exemplos
Os exemplos a seguir consideram uma WKPAN tipo DES de valor ‘EB 52 8A 43 B1 27 53 FD’:
Exemplo 1: Trilha 1 enviada pelo pinpad, com PAN contendo espaços em branco.
 Aberta (59 caracteres):
“B3764 361234 56006^NOME NOME NOME NOME NOME N^0905060640431”
 PAN Identificado (17 caracteres):
“3764 361234 56006”
 Codificação:
“764E361234E56006” => DES => “5716A983F0E4643B”
 Criptografada (59 caracteres):
“B35716A983F0E4643B^NOME NOME NOME NOME NOME N^0905060640431”
Exemplo 2: PAN de 19 dígitos enviado pelo “checkout” ao pinpad.

 Aberto (19 caracteres):
“6234987432874320001”
 Codificação:
“4987432874320001” => DES Reverso => “407E5D4F32598B98”
 Criptografado (19 caracteres):
“623407E5D4F32598B98”
Exemplo 3: Trilha 1 enviada pelo pinpad, com PAN de 13 dígitos.

“B3764361234006^NOME NOME NOME NOME NOME N^0905060640431”
“3764361234006”
 Codificação:
“3764361234006FFF” => DES => “A4F4729D58CAA7DA”
“BA4F4729D58CAA7DA^NOME NOME NOME NOME NOME N^0905060640431”
Exemplo 4: PAN de 15 dígitos enviado pelo “checkout” ao pinpad.

 Aberto (15 caracteres):
“376436123456006”

 Codificação:
“376436123456006F” => DES Reverso => “431E6D386E688B0B”
 Criptografado (16 caracteres):
“431E6D386E688B0B”

“6002938264523821=09050606404312376450”
“6002938264523821”
 Codificação:
“6002938264523821” => DES => “BC27B145C5DE8BEB”
“BC27B145C5DE8BEB=09050606404312376450”
Exemplo 6: Trilha 2 de 37 caracteres enviada pelo pinpad, porém com PAN de 13 dígitos, causando a
invasão do “Tamanho da Trilha 3” depois de criptografada.
“3827418937101=09050606404312376450123”
“3827418937101”
 Codificação:
“3827418937101FFF” => DES => “1CCE9197C5C6E3FF”
 Criptografada (40 caracteres!!!):
“1CCE9197C5C6E3FF=09050606404312376450123”

“4916748362525378000==5300053205322056019300000010000004050=00000
000000000000=00000000000000000=7=3012056”
“4916748362525378000”
 Codificação:
“6748362525378000” => DES => “FE8E271A114C1A35”
“491FE8E271A114C1A35==5300053205322056019300000010000004050=00000
000000000000=00000000000000000=7=3012056”
Exemplo 8: Trilha 2 enviada pelo pinpad, sem separador. Neste caso, para manter coerência com a
regra definida, é como se a trilha inteira fosse o PAN.
“9823746589273648956239486587923497851”
“9823746589273648956239486587923497851”

 Codificação:
“9486587923497851” => DES => “2C05DF894573C7FA”
“9823746589273648956232C05DF894573C7FA”
4.4.3. Decodificação das trilhas pelo “checkout”

Mesmo habilitada a “Comunicação Segura”, em algumas situações (como explicado no item 4.4.1)
uma ou mais trilhas retornadas pelo pinpad podem não sofrer criptografia alguma, no caso em que
não tenha sido possível isolar um PAN válido. Entretanto, esta especificação não prevê uma forma de
informar ao “checkout” esta ocorrência, podendo gerar erros quando este tentar decriptografar uma
trilha recebida.
Este item procura definir uma regra padronizada para que o “checkout” possa identificar se a trilha
contém de fato um PAN criptografado:
 Percorrer a trilha da esquerda para a direita até localizar um separador (“^” ou “=”) ou até
chegar ao seu final. O bloco de caracteres mais à direita deve ser considerado como um PAN
criptografado.
 Se o bloco encontrado tiver menos de 16 caracteres, então não houve criptografia.
 Se o bloco encontrado tiver algum caractere fora da faixa hexadecimal (‘0’ a ‘9’ / ‘A’ a ‘F’),
então não houve criptografia.
 Decriptografar o bloco usando a chave WKPAN. Somente caracteres numéricos (‘0’ a ‘9’), espaços
em branco (codificados como ‘E’) ou o preenchimento ao final (‘F’, ‘FF’ ou ‘FFF’) são aceitos
nesse resultado. Se ele não apresentar esta coerência, deduz-se que não houve criptografia.
4.4.4. Uso de certificado RSA

No comando PP_DefineWKPAN, quando requerida a “Modalidade 2”, o pinpad retornará um
certificado RSA criptografado pela chave pública fornecida que, após “aberto”, possui o seguinte
layout de 128 bytes:

001 A1 Cabeçalho do certificado (fixo = “T” / 54h)
002 N1 Versão do certificado (fixo = “1” / 31h)
003-011 N9 Número seqüencial gerado pelo pinpad (apenas para diversificação do
certificado)
012-043 B16(H32) Chave WKPAN gerada aleatoriamente pelo pinpad
044-127 N84 Não usado (seqüência de zeros = “00000...0000”).
128 A1 Finalizador do certificado (fixo = “X”)
Ao abrir o certificado, o “checkout” deve verificar se o cabeçalho, a versão e o finalizador estão

corretos, validando sua integridade. O número seqüencial deve ser desprezado.

5. A Biblioteca de Acesso TEF
A “Biblioteca de Acesso TEF” foi inicialmente concebida como sendo uma biblioteca adicional de
responsabilidade do fornecedor do Servidor TEF e teria a função de comunicar-se com ele para obter
as tabelas de parâmetros (descritas no Capítulo 7).
Dado que os sistemas nunca foram implementados desta forma, este conceito foi retirado da
especificação, sendo que este capítulo foi mantido apenas para preservar a indexação do
documento.

6. Fluxos de operação no “checkout”
Este capítulo descreve fluxos de operação no “checkout” utilizando as funções de alto-nível da

biblioteca de pinpad, recomendando a seqüência correta esperada.
Os fluxos a seguir resumem todo o processamento dentro do “checkout”, não se levando em conta,
por questão de simplificação, o uso das funções PP_Open e PP_Close (ver item 3.2).

Os itens a seguir descrevem separadamente alguns fluxos considerando o diálogo entre o “checkout”
e o Servidor TEF e entre o “checkout” e o conjunto “bibliotecas + pinpad”. Os seguintes casos mais
comuns estão contemplados nos fluxos a seguir:
 Transação com cartão magnético ou sem contato simulando tarja (sem senha);
 Transação com cartão magnético ou sem contato simulando tarja (com senha);
 Tentativa de transação com cartão magnético que possui chip;
 Transação com cartão com chip (com ou sem contato);
 Transação negada pelo cartão com chip (com ou sem contato);
 Transação negada pelo cartão com chip (com contato) após aprovação do Host;
 Transação com chip aprovada offline (com ou sem contato); e
 Fallback de cartão com chip (com contato).

6.1. Transação com cartão magnético ou sem contato

simulando tarja (sem senha)
Este fluxo descreve a transação com um cartão magnético convencional (ou chip sem contato
simulando tarja) que não requer senha.
Bibliotecas+
Servidor TEF Checkout
PIN-pad
PP_StartGetCard
Um cartão é
apresentado
(mag. ou sem
PP_GetCard contato/tarja)
tipo de cartão: “00” ou “05”
Consulta trilha 2
tabela de BIN
Parâmetros para a transação: Operador

- Formas de parcelamento, etc... entra os
dados
necessários
autorização dados p/ autorização online
resposta da autorização Imprime

comprovante
confirmação

6.2. Transação com cartão magnético ou sem contato

simulando tarja (com senha)
Este fluxo descreve a transação com um cartão magnético convencional (ou chip sem contato
simulando tarja) que requer senha.
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão é
apresentado
(mag. ou sem
PP_GetCard contato/tarja)
tipo de cartão: “00” ou “05”
Consulta trilha 2
tabela de BIN

- Dados para criptografia de PIN entra os
-Formas de parcelamento, etc.. dados
necessários
PP_StartGetPIN
Portador
digita o PIN
PP_GetPIN
autorização dados p/ autorização online
resposta da autorização Imprime

comprovante
confirmação

6.3. Tentativa de transação com cartão magnético que possui

chip
Este fluxo descreve a tentativa de iniciar uma transação com a tarja magnética de um cartão que
também possui chip. Nesse caso, a presença do chip é identificada pelo Servidor TEF através dos
indicadores contidos na tarja e o cartão não é aceito pelo “checkout”.
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão
magnético é
PP_GetCard passado
tipo de cartão: “00”
Consulta -trilha 2
tabela de BIN -Status último chip: “0” (OK)
Cartão é identificado como tendo

chip Cartão não é
aceito
Deve-se apresentar no
checkout uma mensagem
solicitando o uso do chip
ao invés da tarja
magnética.

6.4. Transação com cartão com chip

Este fluxo descreve a transação com cartão com chip, seja ele EMV com contato (“03”), EMV sem
contato (“06”) ou Easy-Entry sobre TIBC v1 (“04”).
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão
com chip é
PP_GetCard apresentado
- tipo de cartão: “03”, “04”, “06”
- Trilha 2
Consulta - código da rede adquirente
-- Código da rede adquirente
tabela de BIN

- Tags para montagem do campo 55 dados
- Formas de parcelamento, etc.. necessários
PP_StartGoOnChip
PP_GoOnChip
- decisão: aprovar online
autorização dados p/ autorização online, - dados para envio no campo 55
incluindo o campo 55
resposta da autorização,
incluindo o campo 55 PP_FinishChip
- response code: aprovada
- dados recebidos no campo 55
- decisão: aprovada
- Dados Finais
Imprime
comprovante
- Confirmação PP_RemoveCard
confirmação - Dados Finais

6.5. Transação negada pelo cartão com chip

Este fluxo descreve a transação com cartão com chip EMV com contato (“03”) ou EMV sem contato
(“06”) que acaba sendo negada por ele.
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão
com chip é
- tipo de cartão: “03” ou “06”
- Trilha 2 (ou PAN)
tabela de BIN

PP_StartGoOnChip
PP_GoOnChip
- decisão: negada offline
dados da transação negada,

formatados como campo 55
PP_RemoveCard
Transação não
é aceita

6.6. Transação negada pelo cartão com chip após aprovação do

Host
Este fluxo descreve a transação com cartão com chip EMV com contato (“03”) que acaba sendo
negada por ele mesmo após a aprovação do Host.
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão
com chip é
PP_GetCard inserido
- tipo de cartão: “03”
- Trilha 2
tabela de BIN

PP_StartGoOnChip
PP_GoOnChip
- decisão: aprovar online
autorização dados p/ autorização online - dados para envio no Bit55
resposta da autorização
PP_FinishChip
- dados recebidos no Bit55
- decisão: negada
- desfazimento
- dados da transação negada,
desfaziment formatados como campo 55
o
PP_RemoveCard
Transação não
é aceita

6.7. Transação com chip aprovada offline

Este fluxo descreve a transação com cartão com chip aprovada offline, sem comunicação com o Host.
Este caso somente pode acontecer com cartão EMV com contato (“03”) ou sem contato (“06”).
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão
com chip é
- tipo de cartão: “03” ou “06”
- Trilha 2
tabela de BIN

PP_StartGoOnChip
PP_GoOnChip
- decisão: aprovada offline
Armazena dados da transação, - dados para envio no campo 55
dados para formatados como campo 55
envio futuro
Se armazenamento OK,
transação é “autorizada” PP_FinishChip
- decisão: aprovada
Imprime
comprovante
confirmação PP_RemoveCard

6.8. Fallback de cartão com chip

Este fluxo ilustra o caso do fallback de cartão com chip (com contato), ou seja, o caso em que uma
transação desse tipo de cartão acaba sendo aceita através da tarja magnética devido a problemas
com o chip.
Bibliotecas+
PIN-pad
PP_StartGetCard
Um cartão é
inserido no
PP_GetCard leitor de chip
erro!!!
PP_RemoveCard O cartão é
retirado
PP_StartGetCard
Um cartão
magnético é
passado
PP_GetCard
tipo de cartão: magnético
Consulta -trilha 2 último status de chip: erro
tabela de BIN -Status último chip: “1” (fallback)
Parâmetros para a transação:

- Formas de parcelamento
- Master Key / Working Key
Cartão é identificado como tendo chip,

mas este está com erro.
A transação segue então pelo fluxo de
tarja magnética, porém é identificada
como “fallback” na mensagem de
pedido de autorização com o Host.

7. Tabelas de Parâmetros
Este item descreve as tabelas que devem estar contidas no conjunto Biblioteca + Pinpad de modo
que ele possa processar os cartões com chip EMV.
Estão contempladas as seguintes tabelas:
 Tabela de Parâmetros x AID
 Tabela de Chaves Públicas
 Tabela de Certificados Revogados

7.1. Tabela de Parâmetros x AID

Esta tabela é composta de diversos registros sempre iniciados com o layout a seguir, tendo como
“chave” o AID. Identificado um cartão com um determinado AID, são definidos diversos parâmetros
referentes à rede adquirente responsável pelo seu processamento.
O formato do registro e o significado dos parâmetros variam de acordo com o “padrão da aplicação”,
considerando:
 Moedeiro Visa Cash sobre TIBC v1;
 Moedeiro Visa Cash sobre TIBC v3;
 EMV; e
 Easy-Entry sobre TIBC v1.

001-003 N3 Tamanho do registro, incluindo este campo.
004 N1 Identificação da Tabela de Parâmetros x AID (fixo “1”)
005-006 N2 Identificador da rede adquirente:
“01” - Rede Amex
“02” - Redecard
“03” - Cielo
007-008 N2 Índice do registro na tabela (de “01” a “99”)
009-010 N2 Tamanho do AID, em bytes (de “02” a “’16”)
011-042 H32(B16) AID - Application Identifier (alinhado à esquerda)
043-044 N2 Tipo de Aplicação:
“01” – Crédito
“02” – Débito
“03” – Moedeiro
“??” - Outras aplicações (“CDC”? / “Voucher”?)
045-060 A16 Etiqueta default da aplicação
061-062 N2 Padrão da aplicação:
“03” - EMV (com ou sem contato)
“04” - Easy-Entry sobre TIBC v1
... ... ...

7.1.1. Parâmetros para aplicações padrão EMV

Posição Formato Tag Descrição
001-003 N3 Tamanho do registro, incluindo este campo. O pinpad deverá ser
capaz de aceitar registros de:
 284 bytes: correspondente às especificações anteriores (os TACs
para cartão sem contato devem ser considerados zerados).
 314 bytes: correspondente à especificação atual.
 >314 bytes: previsão para especificações futuras (desprezar os
dados extras recebidos).
004 N1 Identificação da Tabela de Parâmetros x AID (fixo “1”)
“02” - Redecard
“03” - Cielo
009-010 N2 Tamanho do AID, em bytes (de “05” a “’16”)
011-042 H32(B16) 9F06 AID - Application Identifier (alinhado à esquerda)
043-044 N2 Tipo de Aplicação:
“01” – Crédito
“02” – Débito
045-060 A16 Etiqueta default da aplicação
061-062 N2 Padrão da aplicação: “03” - EMV
063-066 H4(B2) 9F09 Application Version Number (Terminal) - opção #1
075-077 N3 9F1A Terminal Country Code
078-080 N3 5F2A Transaction Currency Code
081 N1 5F36 Transaction Currency Exponent
082-096 A15 9F16 Merchant Identifier
097-100 N4 9F15 Merchant Category Code
101-108 A8 9F1C Terminal Identification


109-114 H6(B3) 9F33 Terminal Capabilities (Mapa de bits indicando as capacidades do
terminal, com o formato: abcxxxxx defgkxxx hijmxxxx)
a = Digitação de número do cartão.
b = Cartão magnético.
c = Cartão com chip de contatos.
d = Verificação em cartão com chip de PIN “em aberto”.
e = Verificação online de PIN com criptografia.
f = Assinatura em papel.
g = Verificação em cartão com chip de PIN com criptografia.
k = Aceita o método “No CVM” (sem verificação do portador).
h = SDA - Autenticação estática de dados do cartão com chip.
i = DDA - Autenticação dinâmica de dados do cartão com chip.
j = Captura de cartão.
m = Autenticação offline CDA.
115-124 H10(B5) 9F40 Additional Terminal Capabilities
125-126 N2 9F35 Terminal Type:
“21” – online
”22” – offline com capacidade online
”23” – somente offline
”24” – online, não atendido
”25” – offline com capacidade online, não atendido
”26” – somente offline, não atendido
127-136 H10(B5) Terminal Action Code – Default
137-146 H10(B5) Terminal Action Code – Denial
147-156 H10(B5) Terminal Action Code – Online
157-164 H8(B4) 9F1B Terminal Floor Limit (valor “default” para uso antes de
PP_StartGoOnChip), em centavos.
165 A1 9F53 Transaction Category Code
166 A1 Indica a ação para cartão com chip sem contato se o valor da
transação estiver zerado:
“0” = Não suporta;
“1” = Suporta, porém somente online.
167 N1 Capacidade de tratamento do terminal para o referido AID, caso
este seja localizado em um cartão com chip sem contato:
“0” = Não suporta;
“1” = Suporta VISA MSD;
“2” = Suporta VISA qVSDC;
“3” = Suporta MasterCard PayPass Mag Stripe;
“4” = Suporta MasterCard PayPass M/Chip;
“5” = Suporta Amex Expresspay Magstripe Mode; e
“6” = Suporta Amex Expresspay EMV Mode.
168-175 H8(B4) Terminal/Reader Contactless Transaction Limit
176-183 H8(B4) Terminal/Reader Contactless Floor Limit


184-191 H8(B4) Terminal/Reader CVM Required Limit
192-195 H4(B2) 9F6D PayPass Mag Stripe Application Version Number (Terminal)
196 N1 Indica a forma de seleção da aplicação do cartão sem contato:
“0” = A aplicação é selecionada automaticamente pela prioridade;
ou
“1” = Deve ser mostrado menu de seleção caso exista outra
aplicação compatível.
197-236 H40(B20) Default Transaction Certificate Data Object List (TDOL)
(completado com bytes “00” à direita)
237-276 H40(B20) Default Dynamic Data Authentication Data Object List (DDOL)
(completado com bytes “00” à direita)
277-284 A8 Authorization Response Codes para transações offline.
Este campo é desprezado pelo pinpad, dado que estes códigos
foram fixados a partir da norma EMV 4.0, deixando de ser
parâmetros. Apenas por convenção, manter “Y1Z1Y3Z3”.
285-294 H10(B5) Terminal Action Code – Default (para cartões sem contato)
295-304 H10(B5) Terminal Action Code – Denial (para cartões sem contato)
305-314 H10(B5) Terminal Action Code – Online (para cartões sem contato)
Exemplo de registro:
3141020107A0000000041010000000000000000000
01MASTERCARD••••••030082008200820769862MERCH0000000001
1234TERM0001E0F0C06000B0F00021
C8000000000000000000C80000000000002710
R•••••••••••••••••••••••••••••••
9F02069F03060000000000000000000000000000
9F02069F03069F1A0295055F2A029A039C010000
Y1Z1Y3Z3
C8000000000000000000C800000000
7.1.2. Parâmetros para aplicações padrão Easy-Entry sobre TIBC v1

Esta tabela é proprietária e seu formato encontra-se descrito em documento anexo fornecido pela
Cielo.
7.1.3. Parâmetros para aplicações padrão Visa Cash sobre TIBC v1 ou

v3
Esta tabela é proprietária e seu formato encontra-se descrito em documento anexo fornecido pela
Cielo.

7.2. Tabela de Chaves Públicas

Esta tabela contém as chaves públicas das entidades certificadoras, utilizadas pelos cartões EMV nos
processos que demandam criptografia RSA (tipicamente autenticação estática, autenticação
dinâmica e verificação criptografada de PIN).
Ela é composta de diversos registros com o layout a seguir, tendo como “chave” o RID e o
Certification Authority Public Key Index.

001-003 N3 Tamanho do registro, incluindo este campo (fixo “611”)
004 N1 Identificação da Tabela de Chaves Públicas (fixo “2”)
“02” - Redecard
“03” - Cielo
009-018 H10(B5) RID - Registered Application Provider Identifier
019-020 H2(B1) 9F22 Certification Authority Public Key Index
021-022 H2(B1) Reservado para uso futuro - preencher com zeros (“00”)
023 N1 Tamanho em bytes do Certification Authority Public Key Exponent
(“1” ou “3”)
024-029 H6(B3) Certification Authority Public Key Exponent (alinhado à esquerda)
030-032 N3 Tamanho em bytes do Certification Authority Public Key Modulus
(até “248”)
033-528 H496 Certification Authority Public Key Modulus (alinhado à esquerda)
(B248)
529 N1 Status do Check Sum (Hash SHA-1)
“0” = Não utilizado
“1” = Presente
530-569 H40(B20) Certification Authority Public Key Check Sum (Hash SHA-1).
570-611 N42 Reservado para uso futuro - preencher com zeros (“0000...00”)

Exemplo de registro:
61120305A00000000399001030000128AB79FCC9520896967E776E64444E5DCDD
6E13611874F3985722520425295EEA4BD0C2781DE7F31CD3D041F565F747306EE
D62954B17EDABA3A6C5B85A1DE1BEB9A34141AF38FCF8279C9DEA0D5A6710D08D
B4124F041945587E20359BAB47B7575AD94262D4B25F264AF33DEDCF28E09615E
937DE32EDC03C54445FE7E3827770000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000000000000000000000000000000000000
0000000014ABFFD6B1C51212D05552E431C5B17007D2F5E6D0000000000000000
00000000000000000000000000

7.3. Tabela de Certificados Revogados

Esta tabela contém os números de série dos certificados revogados de chave pública de emissor.
Ela é composta de diversos registros com o layout a seguir, tendo como “chave” o RID e o
Certification Authority Public Key Index e o Certificate Serial Number.

001-003 N3 Tamanho do registro, incluindo este campo (fixo “026”)
004 N1 Identificação da Tabela de Certificados Revogados (fixo “3”)
“02” - Redecard
“03” - Cielo
009-018 H10(B5) RID - Registered Application Provider Identifier
019-020 H2(B1) 9F22 Certification Authority Public Key Index
021-026 H6(B3) Certificate Serial Number

8. Protocolo Serial
Este capítulo define uma implementação de protocolo serial para o caso de pinpads que têm
capacidade para executar, internamente, todo o processamento das funções definidas no Capítulo 3.
A implementação deste protocolo é obrigatória (salvo exceções acordadas com as redes adquirentes)
pois traz as seguintes vantagens:
 Uma Biblioteca implementada com o mesmo protocolo passa a ser genérica, podendo ser
utilizada com diversos pinpads; e
 O desenvolvedor do checkout poderá, caso desejado, acessar diretamente o pinpad pela porta
serial, dispensando o uso de bibliotecas externas.
É importante que o pinpad preserve também o seu protocolo serial nativo para compatibilidade com
outros sistemas.

8.1. Nível de Enlace

A comunicação serial deve se dar a 8 bits de dados, sem paridade e 1 bit de parada. A velocidade
deverá ser configurável no pinpad, sendo que, devido ao alto volume de informações trocadas,
recomenda-se 19.200 bps.
A seqüência de mensagens trocadas sempre se origina no “checkout” através de um envio de
comando para o pinpad que, após o processamento, envia uma resposta. O pinpad nunca envia
mensagens não requisitadas ao “checkout”.
As mensagens trocadas possuem o seguinte formato:
Conteúdo Tamanho Descrição
(bytes)
SYN (16H) 1 Caractere de início da mensagem.
DADOS_MSG 1 a 1024 Conteúdo da mensagem, sendo que somente podem ser enviados
caracteres de 20h a 7Fh. O formato de DADOS_MSG é descrito no
item 8.2.
ETB (17H) 1 Caractere de fim da mensagem.
CRC 2 CRC16 de todos os bytes de DADOS_MSG e ETB, utilizando o
(MSB/LSB) polinômio gerador x16 + x12 + x5 + x0, conforme exemplo em
linguagem C a seguir.
#define CRC_MASK 0x1021 /* x^16 + x^12 + x^5 + x^0 */
UINT16 CRC_Calc (unsigned char *pbData, int iLength)

{
UINT16 wData, wCRC = 0;
int i;
for ( ;iLength > 0; iLength--, pbData++) {

wData = (UINT16) (((UINT16) *pbData) << 8);
for (i = 0; i < 8; i++, wData <<= 1) {
if ((wCRC ^ wData) & 0x8000)
wCRC = (UINT16) ((wCRC << 1) ^ CRC_MASK);
else
wCRC <<= 1;
}
}
return wCRC;
}
Após a recepção de uma mensagem, o pinpad confere o CRC e envia um ACK (06h) se os dados
estiverem corretos. Caso os valores não coincidam, envia um NAK (15h) e descarta a mensagem.
O “checkout” deve aguardar um ACK ou um NAK durante 2 segundos após o envio da mensagem. O
não recebimento de algum desses bytes aborta a comunicação. O checkout deve tentar o envio da
mensagem 3 vezes, abortando após o 3º NAK recebido.

Por outro lado, o “checkout” deve verificar o CRC de uma resposta recebida do pinpad e enviar um
NAK caso haja erro. Em caso de acerto, nada deverá ser enviado.
As figuras a seguir exemplificam algumas situações previstas pelo protocolo.
Checkout PIN-pad
CRC CRC ETB Dn ... D2 D1 SYN
CRC confere. Um ACK
é enviado e a
ACK mensagem é aceita.
CRC confere. A SYN D1 D2 ... Dn ETB CRC CRC

resposta é aceita e não
se deve enviar ACK...
Checkout PIN-pad
CRC CRC ETB Dn ... D2 D1 SYN CRC não confere. Um
NAK é enviado e a
NAK mensagem é
Um NAK é recebido! rejeitada.
A mensagem é
CRC CRC ETB Dn ... D2 D1 SYN
retransmitida. CRC confere. Um ACK
é enviado e a
ACK mensagem é aceita.
SYN D1 D2 ... Dn ETB CRC CRC

CRC não confere. Um
NAK é enviado e a
NAK
resposta é rejeitada.
CRC confere. A
SYN D1 D2 ... Dn ETB CRC CRC
resposta é aceita e não
se deve enviar ACK...
No caso dos comandos “blocantes”, o “checkout” deverá esperar pela resposta indefinidamente.
Entretanto, este tipo de comando pode ser abortado a qualquer momento pelo “checkout” através
do envio de um caractere CAN (18h). Isso equivale ao comando PP_Abort.
Ao receber o caractere CAN, o pinpad deve abortar a operação em curso, enviar um caractere EOT
(04h) e voltar ao aguardo de um novo comando. Na verdade, o pinpad deve sempre responder EOT a
um CAN, independentemente do seu estado.
O “checkout” deve aguardar o EOT durante 2 segundos, de modo a obter confirmação do
cancelamento, tentando até 3 vezes o envio do CAN. Durante essa espera, o “checkout” deve ignorar
outros caracteres que venha a receber, pois, coincidentemente, pode haver uma resposta do pinpad
ou uma mensagem de notificação sendo devolvida no momento do cancelamento.
IMPORTANTE: Enquanto o pinpad estiver processando um comando “blocante”, somente o CAN o
fará parar a operação, sendo quaisquer outros bytes ignorados. Caso um comando seja enviado ao
pinpad durante este estado, ele é simplesmente rejeitado.
Os comandos “não blocantes” não podem ser interrompidos pelo checkout. Nesse caso, deve-se
adotar um timeout de 10 segundos para a espera da resposta. Excedido esse tempo, reporta-se o
erro PP_COMMTOUT.

8.2. Nível de Aplicação

As mensagens trocadas entre o checkout e o pinpad são traduções diretas das funções definidas no
Capítulo 3. Para isso, o campo DADOS_MSG possui o seguinte formato, dependendo do sentido da
mensagem:
Comando (Checkout → Pinpad):
Formato Descrição
A3 Código do comando: “CHP” = PP_ChipDirect
“CNG” = PP_ChangeParameter
“OPN” = PP_Open (*) “GIN” = PP_GetInfo
“CLO” = PP_Close “ENB” = PP_EncryptBuffer
“DSP” = PP_Display “TLI” = PP_TableLoadInit
”DEX” = PP_DisplayEx ”TLR” = PP_TableLoadRec
“GKY” = PP_StartGetKey/PP_GetKey ”TLE” = PP_TableLoadEnd
“GPN” = PP_StartGetPIN/PP_GetPIN “GDU” = PP_GetDUKPT
“RMC” = PP_StartRemoveCard/PP_RemoveCard “GTS” = PP_GetTimeStamp
“GEN” = PP_StartGenericCmd/PP_GenericCmd “DWK” = PP_DefineWKPAN
“CKE” = PP_StartCheckEvent/PP_CheckEvent
(***)
“GCR” = PP_StartGetCard/PP_GetCard/PP_ResumeGetCard
“GOC” = PP_StartGoOnChip/PP_GoOnChip
“FNC” = PP_FinishChip
N3 Tamanho em caracteres do primeiro parâmetro do tipo INPUT (se houver)
var Primeiro parâmetro do tipo INPUT (se houver)
N3 Tamanho em caracteres do segundo parâmetro do tipo INPUT (se houver)
var Segundo parâmetro do tipo INPUT (se houver)
... ...
(*)
O parâmetro psCom diz respeito somente à abertura da porta serial e, portanto, não deve ser
enviado ao pinpad através do protocolo.
(***)
A função PP_ResumeCard é acionada através do comando “GCR” sem parâmetros.

Resposta (Pinpad → Checkout):
Formato Descrição
A3 Código da resposta (idêntico ao código do Comando)
N3 Status (código de retorno, conforme item 3.1.2)
N3 Tamanho em caracteres do primeiro parâmetro do tipo OUTPUT (se houver)
var Primeiro parâmetro do tipo OUTPUT (se houver)
N3 Tamanho em caracteres do segundo parâmetro do tipo OUTPUT (se houver)
var Segundo parâmetro do tipo OUTPUT (se houver)
... ...
Observações:
 As funções “blocantes” (do tipo PP_StartFunc / PP_Func) deverão seguir a seguinte regra: A
função inicial (PP_StartFunc) simplesmente envia comando, retornando imediatamente após a
recepção do ACK. A função final (PP_Func) deve verificar a se uma resposta foi recebida, saindo
imediatamente com status PP_PROCESSING caso não haja nada no buffer de recepção serial. O
cancelamento pela função PP_Abort é feito conforme descrito no item 8.1.
 Na função PP_Open é interessante que, após a abertura da porta, um CAN seja enviado ao
pinpad para cancelar qualquer eventual comando “blocante” que esteja em processamento.
Após esse procedimento, recebido o EOT, o comando “OPN” pode ser enviado normalmente ao
pinpad.
8.2.1. Mensagens de Notificação

Durante a execução de funções “blocantes”, o pinpad pode enviar mensagens de notificação a serem
apresentadas no “checkout”, conforme descrito no item 3.1.4. Isso é feito através do comando a
seguir:
Mensagem de Notificação (Pinpad → Checkout):
Formato Descrição
A3 “NTM”
N3 Status (sempre “000”)
N3 Tamanho em caracteres da mensagem de notificação (de “000” a “032”)
var Mensagem de notificação
Neste caso, a função sendo executada retorna o status PP_NOTIFY e a mensagem é devolvida no
parâmetro psMsgNotify.

8.3. Exemplos:
Os dados a seguir ilustram o mesmo exemplo apresentado na função PP_GoOnChip, porém
utilizando o protocolo de comunicação definido (para facilitar a visualização, as informações de
tamanho estão sublinhadas):
Checkout->Pinpad:
<SYN>GOC08600000002746500000000710000120700000000000000000000000000
0000001000027102000001388750000230109F279F26959B9F349F100110045F205
F28<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>NTM000016SOLICITE•A•SENHA<ETB><CRC><CRC>
<SYN>GOC0001422000018D540BCF3001577AFFFF9876543210E0000C0479F270180
9F260804CA8F1428AB5901950580000100009B02E8009F34030201009F100706011
A039000005F28020076000<ETB><CRC><CRC>
No exemplo anterior, o “checkout” pode cancelar a operação enviando um CAN, conforme exemplo
a seguir:
Checkout->Pinpad:
<SYN>GOC08600000002746500000000710000120700000000000000000000000000
0000001000027102000001388750000230109F279F26959B9F349F100110045F205
F28<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>NTM000016SOLICITE•A•SENHA<ETB><CRC><CRC>
Checkout->Pinpad:
<CAN>
Pinpad->Checkout:
<EOT>

Os dados a seguir ilustram a carga de tabelas no pinpad, usando os mesmos dados dos exemplos do
item 7.1:
Checkout->Pinpad:
<SYN>GCR0400099000000001500021024193845231020020100<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>GCR020<ETB><CRC><CRC>
Checkout->Pinpad:
<SYN>TLI002310200201<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>TLI020<ETB><CRC><CRC>
Checkout->Pinpad:
<SYN>TLR4570328410107A00000000410100000000000000000000201MASTERCARD
••••••030082008200820769862MERCH00000000011234TERM0001E0F0C06000B0F
00021C8000000000000000000C800000000••••••••••••••••••••••••••••••••
••••••••••••••••••••••••••••••••••••••••••••••••9F02069F03069F1A029
5055F2A029A039C010000Y1Z1Y3Z306210202101000000000000000000000000000
000302VISA•ELECTRON•••041091030652005060708000000000000000000000030
3VISA•CASH•••••••010000050000000000000000000015210198607612,.R$••1<
ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>TLR000<ETB><CRC><CRC>
Checkout->Pinpad:
<SYN>TLE<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>TLE000<ETB><CRC><CRC>
Checkout->Pinpad:
<SYN>GCR<ETB><CRC><CRC>
Pinpad->Checkout:
<ACK>
<SYN>NTM000022SELECIONADO: AMEX GOLD<ETB><CRC><CRC>
<SYN>NTM000023SELECIONADO: AMEX GREEN<ETB><CRC><CRC>
<SYN>GCR00034203001010200••••••••••••••••••••••••••••••••••••••••••
••••••••••••••••••••••••••••••••••29376436871651006=0305000523966••
••••••000••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
••••••••••••••••••••••••••••••••••••••••••••••15376436871651006••••
01AMEX•GREEN••••••246JOAO•DA•SILVA•••••••••••••04123100••••••••••••
•••••••00000000076000<ETB><CRC><CRC>

9. Funcionalidades Adicionais
9.1. Consulta de versões

Considerando-se que o pinpad é multi-aplicação, existem instalados diversos aplicativos
independentes no mesmo equipamento, cada um com uma versão diferente, podendo ter sido
certificados em momentos distintos. Dessa maneira, para facilitar a operação de técnicos de campo,
é importante que exista uma forma simples de verificar as versões das aplicações instaladas.
Assim, deve-se permitir a consulta das versões quando o pinpad estiver em estado ocioso através da
digitação de uma seqüência de teclas pré-determinada.
Aplicação Seqüência de teclas

Principal (Gerenciador) [CLEAR/BACKSP] → [ENTER] → [0]
Rede Amex [CLEAR/BACKSP] → [ENTER] → [1]
Redecard [CLEAR/BACKSP] → [ENTER] → [2]
Cielo [CLEAR/BACKSP] → [ENTER] → [3]
Pressionada a seqüência correta, o pinpad deve soar um “bip” e apresentar as seguintes telas,
contendo as mesmas informações devolvidas pelo comando PP_GetInfo:
Aplicação Principal (Gerenciador):
xxxxxxxxxx;mmm Onde: xxxxxxxxxx;mmm = Modelo / versão do hardware.

VVV.VV AAMMDD VVV.VV AAMMDD = Versão da aplicação básica.
1.08 1.08 = Versão da especificação
Outras aplicações (Redes Adquirentes):
NNNNNNNNNNNNN Onde: NNNNNNNNNNNNN = Nome da Rede Adquirente

VVV.VV AAMMDD VVV.VV AAMMDD = Versão da aplicação da Rede
PPPPPPP Adquirente.
PPPPPPP = Informações proprietárias da Rede
Adquirente.
A mensagem deve ser apresentada e deixada simplesmente no display, até que seja recebido um
comando que o altere.
OBS: Pinpads que já processam o teclado quando em estado ocioso (“bufferizando” ou enviando as
teclas pela serial) devem continuar a fazê-lo normalmente, porém atentando-se à seqüência sendo
digitada para mostrar corretamente a tela de informações de versão.

10. Convenções para a plataforma

Win32
Para a implementação da Biblioteca Compartilhada de Pinpad em ambiente MS/Windows 32 bits, as

seguintes convenções devem ser respeitadas para facilitar a compatibilidade entre as bibliotecas
geradas pelos diversos fabricantes.
10.1. Formato da Biblioteca

Para MS/Windows 32 bits, a Biblioteca de Pinpad deverá ser gerada no formado DLL (Dynamic Link
Library). Caso esta seja gerada em linguagem C (ou C++) as funções exportadas deverão ser
declaradas como sendo do tipo “standard call” (__stdcall), de maneira a serem reconhecidas por
outras linguagens como o Visual Basic.
Não há convenção quanto ao nome da biblioteca, ficando este a critério do desenvolvedor.
10.2. Arquivo de Configuração

As bibliotecas deverão adotar um arquivo de configuração padronizado de nome “PPCOMP.INI”,
localizado no diretório do MS/Windows. Este arquivo é responsável por:
 Definir o nome e a localização da Biblioteca de Pinpad para que o “checkout” possa utilizá-la; e
 Definir os nomes e as localizações das Bibliotecas de Acesso TEF para que a Biblioteca de Pinpad
possa utilizá-las.
Formato do PPCOMP.INI no diretório do MS/Windows:
[Libs]
PPCOMP=<path> \ <nome da Biblioteca de Pinpad>

Apêndice A - Formatos usados no

documento
Para facilitar a integração dos módulos de software definidos neste documento com os diversos
sistemas de “checkout” e TEF existentes, optou-se pelas seguintes regras na formatação de todos os
dados envolvidos, sejam eles tabelas de configuração ou parâmetros de entrada e saída das
bibliotecas:
 Sempre que possível, os dados possuem tamanhos fixos pré-definidos; e
 Todos os dados são compostos de strings com caracteres ASCII de 20h (espaço) a 7Eh (~),
incluindo também o caractere CR (0Dh).
Os seguintes tipos de campos estão previstos na composição dos dados:
 Numérico decimal (N): Permite somente caracteres de “0” a “9” representando um número
decimal.
Exemplo: N3 representa um número de “000” a “999”.
 Numérico hexadecimal (H) ou bytes (B): Permite somente caracteres de “0” a “9” e “A” a “F”
representando um número hexadecimal ou um conjunto de bytes, sendo cada byte
representado por 2 desses caracteres.
Exemplo: H8(B4) representa um número de “00000000” a “FFFFFFFF” ou uma cadeia de 4 bytes.
 Alfanumérico (A): Permite qualquer caractere de 20h (espaço) a 7Eh (~) e normalmente
representa um texto “visível” (nome, etiqueta, mensagem). Quando a informação for menor do
que o campo definido, ela deverá ser alinhada à esquerda com espaços à direita.
Exemplo: A5 pode conter uma mensagem de 5 caracteres como “TEXTO”.
Informações de tamanho variável:
Informações de tamanho variável são representadas sempre por dois campos, na seguinte ordem:
 Um campo numérico (de N1 a N3) indicando o tamanho da informação em bytes (se esta
representar bytes) ou em caracteres (se esta for alfanumerica); e
 Um campo para armazenar a informação. Caso este campo seja de tamanho fixo, a informação
virá alinhada sempre à esquerda, sendo o campo preenchido à direita com “FF” caso este seja
do tipo hexadecimal/bytes ou com “ ” (espaços) caso este seja do tipo alfanumérico.

PAX - Biblioteca Compartilhada - V108a PDF

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

PAX - Biblioteca Compartilhada - V108a PDF

Enviado por

Direitos autorais:

Formatos disponíveis

Biblioteca Compartilhada para Pinpad -

Copyright 2002-2013 © Rede Amex / Redecard / Cielo

Versão Data Responsável Descrição da Alteração

 Um conhecimento básico da norma EMV é importante para a compreensão deste documento,

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 7/119

2.1. A Biblioteca de Pinpad

Interface Interface Interface Interface

Outros dispositivos, tais como scanner,

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 8/119

O diagrama a seguir ilustra a arquitetura da Biblioteca de Pinpad, apresentando suas principais

PP_Display PP_StartGetKey PP_StartGetPIN PP_StartRemoveCard

Biblioteca de PIN-pad PIN-Pad

Software House Certif. Revogados

Fornecedor PIN-pad “time-stamps”

Principais características da arquitetura:

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 9/119

2.2. Aplicações internas ao pinpad

Aplicação principal (Gerenciador)

Aplicação “01” Aplicação “02” Aplicação “03”

Tabela de Tabela de Tabela de

Tabela de Tabela de Tabela de

Tabela de Tabela de Tabela de

“time-stamp” “time-stamp” “time-stamp”

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 10/119

3.1. Considerações Gerais

3.1.1. Formato das funções

int PP_FunctionName (...);

Para compatibilidade das definições da biblioteca entre diversas plataformas, os parâmetros de

Tipo Correspondente em linguagem C

3.1.2. Códigos de retorno

Constante Valor Descrição

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 11/119

Constante Valor Descrição

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 12/119

Constante Valor Descrição

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 13/119

Constante Valor Descrição

3.1.3. Mensagens de erro

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 14/119

A tabela a seguir ilustra as mensagens recomendadas para cada código de retorno:

Constante Mensagem do pinpad Mensagem do “checkout”

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 15/119

Constante Mensagem do pinpad Mensagem do “checkout”

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 16/119

3.1.4. Funções “blocantes”

PP_StartFunc ( ) Inicia o processo e somente possui parâmetros de entrada.

PP_Func ( ) Finaliza o processo e somente possui parâmetros de saída. Caso o processo

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 17/119

3.2. Funções de Controle

As funções PP_Open e PP_Close devem obrigatoriamente ser utilizadas, respectivamente, no início e

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 18/119

Sintaxe: int PP_Open (INPUT psCom);

/* Inicia Biblioteca com pinpad na COM1 */

memcpy (sCom, “01”, 2);

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 19/119

Sintaxe: int PP_Close (INPUT psIdleMsg);

/* Inicia Biblioteca com pinpad na COM2 */

iStat = PP_Open (“02”);

Após a finalização da Biblioteca, o pinpad passará a apresentar a mensagem:

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 20/119

Sintaxe: int PP_Abort (void);

Copyright 2002-2013 © Rede Amex / Redecard / Cielo 21/119

3.3. Funções Básicas de Pinpad