Post Técnico

Desenvolvendo para EMV, Parte III

30 de janeiro de 2019

Em Parte I desta série, falamos sobre como as transações com chip diferem das transações com MagStripe. Vimos que há uma quantidade considerável de comunicação de ida e volta entre o leitor e o cartão. Mas (boas notícias!) também vimos que grande parte dessa comunicação é tratada automaticamente — ou seja, fora do controle do desenvolvedor do aplicativo de pagamento — pelo kernel EMV do leitor.

Em Parte II, falamos um pouco sobre as diversas tags (ou dados TLV) que você pode esperar receber durante uma transação EMV e o que algumas delas significam. Também mencionamos que uma transação EMV ocorre em fases (com nomes como Iniciar, Autenticar e Concluir). E vimos que diferentes TLVs são retornados durante as diferentes fases.

Também mencionamos (muitas vezes, aliás) que, embora seja perfeitamente possível realizar uma transação EMV enviando comandos de firmware diretamente ao leitor de cartão (via USB ou RS-232), em geral é mais fácil interagir com o leitor por meio do Universal SDK da ID TECH. (Acesse aqui para downloads. Esteja preparado para especificar uma plataforma: Windows, Linux, MacOS, iOS ou Android.)

Por que o SDK é mais fácil? Bem, para começar, ele cuida da configuração das comunicações seriais (USB, RS-232 ou Bluetooth) com o leitor. Ele também dispensa você de precisar conhecer

comandos de firmware no nível do dispositivo e protocolos de baixo nível associados. Além disso, você obtém bibliotecas de código prontas para uso que auxiliam na interpretação de códigos de erro e na análise de dados.

Outro grande diferencial do Universal SDK é que ele inclui código de exemplo mostrando como utilizar as diversas bibliotecas que facilitam essas tarefas. (Continue lendo.)

Como começar a usar o SDK? Veja a seguir as principais etapas.

Etapa 1: Instalar o SDK

Se você já sabe para qual sistema operacional irá desenvolver, acesse Development — Home na Base de Conhecimento e navegue até o download adequado. Há versões separadas para Windows, Linux, MacOS, iOS e Android.

Descompacte o arquivo e tente carregar o projeto de exemplo (disponível na pasta Source Code) na IDE de sua preferência. Compile e execute o aplicativo de exemplo com o leitor ID TECH conectado. Verifique se o aplicativo consegue se comunicar com o leitor.

Etapa 2: Configurar o Leitor

Não espere conseguir realizar uma transação EMV assim que tirar o leitor da caixa! Sua primeira transação falhará se você não tiver configurado o leitor previamente. No mínimo, isso significa carregar o leitor com:

Configurações do terminal
AIDs
CAPKs (Chaves Públicas de Autoridade Certificadora)

ID TECH fornece valores de exemplo para esses itens (apenas para fins de teste), mas você ainda precisa executar os comandos que carregam esses valores de exemplo. Eles não são carregados até que você execute os comandos! (Felizmente, uma vez que esses itens estejam carregados no leitor, não é necessário recarregá-los a cada inicialização. Os valores são persistentes. A configuração é feita apenas uma vez.) Consulte o código de exemplo do SDK para ver como isso é feito.

A configuração EMV é um tema bastante abrangente. Não tentaremos esgotá-lo neste post. Para uma introdução ao assunto, confira nossa publicação anterior sobre Configurações do Terminale leia também a seção de Configuração do nosso EMV White Paper (PDF: download gratuito).

Etapa 3: Executar uma Transação

O aplicativo de exemplo contém código para realizar isso. Percorra o aplicativo para ver como ele funciona. Caso contrário, você precisará, no mínimo, configurar um callback personalizado (uma função que será invocada automaticamente pelo SDK no momento adequado) e então chamar emv_startTransaction() você mesmo.

A comunicação com o leitor de cartão ocorre de forma assíncrona, o que significa que ao chamar um método como emv_startTransaction(), o SDK entrará em contato com o leitor, desencadeando uma sequência de eventos, mas o seu programa não ficará bloqueado enquanto esses eventos ocorrem. Em vez disso, o controle é imediatamente devolvido ao seu aplicativo (juntamente com um código de sucesso/erro). O código do SDK monitorará o leitor em busca de atualizações. Quando o leitor conclui a fase inicial da transação EMV, por exemplo, ele envia dados TLV para o computador host (geralmente via USB). O SDK interceptará esses dados, invocará seu callback personalizado e entregará os dados a ele.

Em resumo, você precisa configurar um callback personalizado se quiser receber retorno do leitor!

Como é um Callback?

Na versão Windows do Universal SDK, seu callback personalizado deve ter uma assinatura C# semelhante a esta:

Para garantir que seu callback seja de fato utilizado, você precisa registrá-lo no SDK em tempo de execução, da seguinte forma:

Este exemplo pressupõe que você está usando o VP3300 como seu leitor de cartão, mas o SDK obviamente suportará qualquer leitor de pagamento ID TECH que você estiver utilizando. Afinal, este é um SDK Universal .

Como É o Código de Transação?

Quando você quiser iniciar uma transação, precisará executar um código semelhante a este:

A chamada para emv_startTransaction() resultará no envio de uma solicitação (via USB ou serial) ao leitor. O leitor realizará um ATR (ou seja, entrará em contato com o chip do cartão) e acionará o kernel EMV.

Supondo que o Início da Transação seja bem-sucedido (sem timeout ou erros) e que você tenha registrado um callback (conforme descrito anteriormente), esse callback será executado após um ou dois segundos. O código do seu callback deve conter uma instrução "switch" bastante abrangente, com vários casos para tratar diferentes tipos de resultados. O resultado desejado, é claro, é uma transação EMV bem-sucedida com dados TLV. Portanto, você provavelmente terá um código semelhante ao seguinte, que será executado (no seu callback) ao final da fase de Início:

Este código pressupõe que você configurou suas preferências de forma a executar automaticamente a fase de Autenticação da Transação, permitindo ir diretamente do Início para a Conclusão. (Não precisa ser feito dessa forma, é claro. Tudo depende dos seus requisitos.) Em um aplicativo de pagamento real, seu aplicativo pausaria durante este 'case' para se conectar ao gateway ou adquirente online. Em seguida, você passaria a tag 8A (e possivelmente outras) para emv_completeTransaction().

Para ver como analisar os dados da transação (os TLVs) retornados após cada fase da transação, pesquise no código de exemplo por "displayCardData(IDTTransactionData cardData)". Você encontrará vários exemplos de como interpretar os dados.

Dúvidas?

É natural que surjam dúvidas ao começar a utilizar o SDK. Vale lembrar que o SDK acompanha uma ampla documentação (nos formatos HTML e PDF). Mas se suas perguntas precisarem de respostas mais detalhadas, estamos aqui para ajudar! Entre em contato com nossos especialistas: