Post Técnico
Desenvolvendo para EMV, Parte III
Em Parte I desta série, falamos sobre como as transações com cartão com chip diferem das transações por 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 significado de algumas delas. Também mencionamos que uma transação EMV ocorre em fases (com nomes como Início, Autenticação e Conclusão). E vimos que diferentes TLVs são retornados durante as diferentes fases.
Também mencionamos (muitas vezes, na verdade) que, embora seja 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 fazer os downloads. Esteja preparado para especificar uma plataforma: Windows, Linux, MacOS, iOS ou Android.)
Por que o SDK é mais fácil? Em primeiro lugar, ele cuida da configuração das comunicações seriais (USB, RS-232 ou Bluetooth) com o leitor. Além disso, isola o desenvolvedor da necessidade de conhecer
comandos de firmware em nível de dispositivo e os protocolos de baixo nível associados. Você também conta com 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 benefício do Universal SDK é que ele vem acompanhado de 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 correspondente. Há versões separadas para Windows, Linux, MacOS, iOS e Android.
Descompacte o arquivo e tente carregar o projeto de exemplo (localizado 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: Configure Seu Leitor
Não espere conseguir realizar uma transação EMV direto da caixa! Sua primeira transação falhará se você não tiver dedicado tempo para configurar o leitor. No mínimo, isso significa carregar o leitor com:
- Configurações do terminal
- AIDs
- CAPKs (Chaves Públicas da Autoridade Certificadora)
O 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 o leitor tenha esses itens carregados, 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 artigo. Para uma introdução ao assunto, consulte nossa publicação anterior sobre Configurações do Terminal, e também leia 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 o código para 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, em seguida, 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 série 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 de Início da transação EMV, por exemplo, ele envia dados TLV ao computador host (geralmente via USB). O SDK interceptará esses dados, invocará seu callback personalizado e entregará os dados a ele.
Resumindo: 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 em C# com a seguinte estrutura:
Para garantir que seu callback seja de fato utilizado, é necessário registrá-lo no SDK em tempo de execução, da seguinte forma:
Este exemplo pressupõe que você está usando o VP3300 como leitor de cartão, mas obviamente o SDK oferecerá suporte a qualquer leitor de pagamento ID TECH que você estiver utilizando. Afinal, este é um Universal SDK.
Como É o Código de Transação?
Quando você quiser iniciar uma transação, será necessário 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 Start Transaction seja bem-sucedido (sem timeout ou erros) e que você tenha registrado um callback (conforme descrito anteriormente), seu callback será executado após um ou dois segundos. O código do callback deve conter um "switch" relativamente extenso, com vários cases para tratar diferentes tipos de resultados. O resultado esperado, naturalmente, é uma transação EMV bem-sucedida com dados TLV. Portanto, você provavelmente terá um código semelhante ao exemplo a seguir, que será executado (no seu callback) ao final da fase de Start:
Este código pressupõe que você configurou suas preferências de modo a executar automaticamente a fase Authenticate Transaction, permitindo ir diretamente do Start para o Complete. (Não é necessário fazer dessa forma, naturalmente. Tudo depende dos seus requisitos.) Em um aplicativo de pagamento real, o app faria uma pausa neste 'case' para se conectar online ao gateway ou adquirente. 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á diversos exemplos de como interpretar os dados.
Dúvidas?
É possível 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 à disposição! Entre em contato com nossos especialistas: