Post Técnico
Introdução à Integração com Gateway de Pagamento
Colocar um aplicativo de pagamento em funcionamento significa ser capaz de lidar com pelo menos dois tipos diferentes de integração: primeiro, é preciso saber como integrar o hardware necessário (ou seja, o leitor de cartão e o dispositivo ao qual ele está conectado); em seguida, é preciso saber como se integrar a um "back-end" de pagamentos, como um gateway de pagamento online (a parte responsável por "aprovar" a transação e processá-la para liquidação).
Em postagens anteriores, já abordei bastante a parte de integração de hardware desse processo, que acaba não sendo tão complicada assim, pois com os leitores de cartão ID TECH você pode usar nosso Universal SDK para se comunicar com os dispositivos a partir de um ambiente de linguagem de alto nível, ou optar por uma solução puramente em JavaScript, caso esteja disposto a incluir o Node JS em sua arquitetura. De qualquer forma, comunicar-se com os dispositivos ID TECH não é, na prática, algo muito complexo.
Mas ainda resta a questão: após fazer o leitor de cartão de crédito ler o chip ou a tarja magnética do cartão, como converter essas informações em uma transação aprovada?
Presumivelmente, você já sabe qual processadora de cartões irá processar suas solicitações. Portanto, o desafio se resume a descobrir que tipo de suporte a SDK sua processadora ou gateway oferece para o processamento de requisições online.
A maioria dos gateways ou processadoras dispõe de um programa para desenvolvedores ou de um portal de desenvolvimento online, onde é possível obter SDKs para a criação de aplicativos de pagamento. Os SDKs geralmente permitem desenvolver uma combinação de componentes front-end e back-end para acessar as APIs de pagamento da processadora. Essas APIs, por sua vez, suportam o envio de dados de tarja magnética (MagStripe) e/ou dados de cartão com chip (ICC) pela rede a uma processadora back-end, com o objetivo de obter autorização em tempo real.
A autorização de pagamento é, na verdade, apenas um dos vários tipos de requisição online que você provavelmente precisará suportar. Alguns dos outros tipos de requisição estão apresentados na tabela abaixo.
Tipo de Requisição
Descrição
Auth
Solicitar autorização de pagamento
Conf
Confirmar uma solicitação de autorização anterior
Offline
Liquidar uma transação EMV offline
PreAuth
Confirmar que os dados do cartão são válidos por meio de uma transação de valor reduzido
Refund
Reembolsar uma transação liquidada anteriormente
Test
Testar a conectividade com o processador
VoiceReferralNotification
Notificar o processador sobre o resultado de uma solicitação de referência de voz
Void
Usado para anular uma transação que ainda não foi liquidada
Ao estudar a documentação do SDK do seu processador de pagamento, você perceberá que uma grande variedade de códigos de resultado e/ou códigos de erro se aplica a cada tipo de transação. Como testar todos esses possíveis tipos de erro? Resposta: A maioria dos processadores possui um esquema em que o valor em centavos de uma transação pode ser definido como um valor especial para acionar um erro específico em um ambiente de sandbox de testes. (Por exemplo, se o código de erro para Valor Muito Alto for 1243, o SDK pode permitir que você acione esse erro específico enviando uma transação de teste no valor de R$ 12,43.) Consulte a documentação do SDK do seu provedor para mais detalhes.
Muitos processadores de pagamento oferecem soluções "in app" pré-certificadas (semi-integradas) que permitem rotear dados de cartão criptografados diretamente para o back end, de forma praticamente transparente, mantendo seu aplicativo de pagamento fora do "escopo PCI". Outros, por sua vez, pressupõem que você mesmo lidará com as questões de "escopo" — nesse caso, você provavelmente enviará os dados criptografados do cartão pela rede para o seu próprio servidor, protegido por um firewall, onde (com o auxílio de um HSM) os dados serão descriptografados antes de serem roteados para um adquirente ou gateway.
UM EXEMPLO
Chega de visão geral em alto nível. Vamos falar sobre o que significa, na prática, integrar-se a um back end de pagamentos.
Este exemplo específico obviamente não se aplica a todos os casos (nenhum exemplo único consegue abranger tudo), mas deve dar uma ideia do que você provavelmente encontrará ao integrar-se a um back end.
Neste caso, fui encarregado de desenvolver um aplicativo de demonstração de "terminal virtual" que envia dados de transações para o CreditCall servidor de testes a fim de obter uma autorização em tempo real para transações EMV. O CreditCall disponibiliza uma API de servidor back-end acessível via HTTPS por meio de seu API Direta ChipDNA, que por sua vez pode ser "desenvolvida" utilizando um SDK em Java, C++, Perl ou outras linguagens. Optei pela versão em Java.
No site do ChipDNA Direct , criei uma conta de desenvolvedor e recebi rapidamente (por e-mail) as credenciais de acesso ao servidor de testes da CreditCall. Também fiz o download do SDK Java da CreditCall e comecei a analisar o código de exemplo. Meu objetivo específico era aprender a submeter transações EMV para autorização. Por sorte, um dos arquivos de código de exemplo, ExampleAuthEMV.java, continha exatamente o tipo de código que eu precisava.
Comecei a desenvolver duas classes Java: uma classe servlet para processar requisições HTTP provenientes de um front end baseado em navegador, e uma classe "worker" para encaminhar os dados do navegador (obtidos pelo servlet) ao back end da CreditCall. A primeira resultou em cerca de 250 linhas de Java; a segunda, em 92 linhas.
Não vou apresentar o código da classe servlet, pois trata-se de um código servlet Java bastante padrão, com a diferença de que ele recebe valores TLV (enviados como valores de campos de formulário via AJAX) e os armazena em um objeto java.util.Hashtable em tempo de execução. Esse Hashtable é então passado ao método estático authorize() da minha classe worker. A classe worker utiliza as classes auxiliares (bibliotecas) do SDK ChipDNA Direct da CreditCall para criar um objeto com.creditcall.Request, que é então passado a um objeto Client, o qual realiza a chamada ao servidor da CreditCall. Veja o código a seguir:
Este código é tão conciso e autoexplicativo que praticamente dispensa comentários adicionais. O que há de interessante nele é que as classes Request e Client da CreditCall se encarregam de criar os documentos XML necessários que são enviados ao servidor da CreditCall. Como desenvolvedor, você nunca precisa visualizar, manipular, analisar ou se preocupar com o XML bruto diretamente (como manda a boa prática).
Observe que é necessário informar as credenciais da sua conta de teste nas linhas 18 e 19. (As credenciais exibidas acima são fictícias. Não tente utilizar o código tal como está!) A linha 69 é onde você define a URL do endpoint da CreditCall. A linha 72 realiza a chamada HTTPS de saída propriamente dita.
O servidor CreditCall não é particularmente exigente quanto às tags TLV enviadas nos dados da transação, desde que você inclua as que contêm os dados essenciais do cartão (por exemplo: tags 5A e 57, para EMV por contato; tag 56 para transações sem contato; além de 9F26 e 9F27, que contêm as informações do criptograma). Em resposta aos dados EMV enviados, o servidor CreditCall geralmente retorna TLVs para as tags 8A, 89 e 91, e opcionalmente 71 ou 72 (caso scripts precisem ser transmitidos ao chip do cartão). O código de autorização que você precisa está na tag 89.
Por tentativa e erro, aprendi que o aplicativo do servidor CreditCall não se apressa em recusar uma transação simplesmente porque o cartão apresenta um criptograma AAC. (É possível determinar o tipo de criptograma inspecionando os bits mais significativos da tag 9F27. Zeros indicam AAC, ou seja, Recusa.) Isso não é surpreendente, pois a recomendação do cartão é exatamente isso: uma recomendação. A decisão final de aprovar ou recusar uma transação EMV geralmente cabe ao adquirente. O cartão pode ser — e frequentemente é — sobreposto.
Como você pode perceber, há muito a aprender sobre EMV ao experimentar na prática. Nada substitui uma autorização em ambiente real na hora de validar o código de um aplicativo de pagamento!
Quer mais orientações sobre transações EMV? Acesse nossa página Development Home na ID TECH Knowledge Base. Baixe nosso white paper de desenvolvimento EMV. Ou ligue gratuitamente para um de nossos especialistas e comece com um kit de avaliação: