Android
Nesta seção você irá aprender mais sobre os detalhes de cada funcionalidade do SDK Android para mPOS. Veja como fazer o download e configurar as bibliotecas básicas que seguem o protocolo ABECS. Além disso, veja o fluxo de criação de uma transação. Vamos lá!
Download do SDK
O SDK Android pode ser encontrado em duas distribuições, dependendo do sistema de build sendo usado:
Aplicação de Exemplo
No repositório pagarme/mpos-android há uma aplicação simples que mostra o necessário para uma integração com nosso SDK Android.
Configurando o ambiente
Permissões Android
Adicione as seguintes linhas ao AndroidManifest.xml do seu projeto, no interior da tag <manifest>:
Essas linhas garantem as permissões necessárias para que o aplicativo e o SDK possam realizar operações com Bluetooth e com conexões à Internet.
Instruções para build com Ant:
-
Após fazer o download em Ant, você encontra os seguintes arquivos:
- mpos-android-native.jar
- mpos-android.jar
-
Adicione os JARs incluídos na distribuição ao seu projeto.
Instruções para build com Gradle:
-
Dentro do diretório de sua application Android (geralmente '/app'), você encontra os seguintes arquivos:
- AndroidManifest.xml - build.gradleApós fazer o download em Gradle, os seguintes arquivos ficam disponíveis:
- mpos-android-native.jar - mpos-android.aar -
Adicione as seguintes linhas ao build.gradle:
Essas linhas incluem os componentes nativos e os componentes Java do SDK para Android no seu projeto, além de uma biblioteca para gerar localmente um identificador da transação, que possibilita desfazimento da mesma, caso o fluxo seja interrompido.
- Adicione os arquivos:
- mpos-android-native.jar
- mpos-android.aar
ao diretório libs abaixo do diretório de sua application Android.
Fluxo pré-transação
O código abaixo demonstra um fluxo completo que pode ser usado por sua aplicação,
para capturar os dados de cartão, gerar o card_hash e usá-lo para criar uma transação com
a API Pagar.me a partir de um servidor externo. Vamos lá:
Atualizando as tabelas EMV
Para as diferentes aplicações de cartão de crédito (diferentes bandeiras, crédito/débito) existem um conjunto de especificações de como o PinPad deve se comportar, assim como certificados que permitem lidar com elas. Este conjunto é denominado tabelas EMV e pode ser obtido junto ao Pagar.me via SDK.
Para baixar as tabelas EMV, as seguintes operações são realizadas:
- Download das tabelas EMV pela API Pagar.me;
- Transferência das tabelas baixadas para o PinPad.
A API Pagar.me fornece as tabelas EMV e então as bibliotecas, como no exemplo abaixo, fazem a instalação no PinPad:
O valor booleano force dos exemplos especifica o comportamento de atualização de tabelas no PinPad. Caso esteja setado como true, faz o download e instala as tabelas baixadas no PinPad. Caso esteja como false, somente instala as tabelas no PinPad se a versão no PinPad for diferente da versão das tabelas na API Pagar.me, evitando instalações de forma redundante.
O parâmetro loaded nos eventos lançados por ocasião do término de atualização de tabelas indica, se true, que foram instaladas tabelas no PinPad; se false, que essa instalação não foi necessária.
Limpeza do banco de dados localSempre que as tabelas são atualizadas, há uma tentativa de limpar as transações mais antigas que o limite estabelecido para o banco de transações local.
Processando os dados de cartão
Para processar e obter um card_hash — que deverá ser enviado à API Pagar.me para que a transação seja criada — o seguinte código pode ser utilizado:
Este SDK usa uma função de processamento chamada payAmount com três parâmetros: amount, applications e magstripePaymentMethod.
O primeiro é um inteiro representando a quantia a ser cobrada em centavos (no caso dos exemplos, 100 = R$1,00). As opções possíveis são as seguintes:
| Parâmetro | Significado |
|---|---|
| amount | Quantia a ser cobrada em centavos (ex. 100 = R$1,00) |
| applications | Um conjunto de EMVApplication que sua aplicação deseja selecionar. Uma EMVApplication consiste da combinação bandeira e método de pagamento (ex. Visa Crédito, Master Débito, Amex Crédito). Em caso de valor nulo, a escolha de possíveis aplicações é feita pelo PinPad. |
magstripePaymentMethod | A tarja magnética não permite seleção de método de pagamento no PinPad, o que requer sempre que a aplicação o defina. Possíveis valores: PaymentMethod.CreditCard ou PaymentMethod.DebitCard |
Vale ressaltarCaso o conjunto de aplicações especificado não seja suportado pelo cartão inserido (ex. applications contém Visa Crédito e o cartão é Master Crédito), o pinpad retorna o erro 70.
Finalizando uma transação
Após a obtenção de um card_hash por meio do processamento no SDK, e seu envio à API Pagar.me para criação de uma transação, é necessário finalizar o procedimento como um todo. Para tal, o seguinte código deve ser usado:
Logo, considere a seguinte assinatura para o método finishTransaction:
Começando com o parâmetro connected, ele define se a conexão com a API Pagar.Me foi bem-sucedida, e os demais podem ser encontrados no response da API Pagar.Me para seu servidor:
Sendo:
| Parâmetro | Correspondência no objeto transaction |
|---|---|
| responseCode | acquirer_response_code, diz respeito ao código de retorno do adquirente Pagar.Me para sua aplicação. |
| emvData | card_emv_response: String responsável por finalizar a comunicação entre PinPad e cartão, e usada somente quando a autenticação foi Pin Online, veja a seguir. |
card_pin_mode
Você deve usar este parâmetro para validar se é necessário executar o finishTransaction. Sempre que o retorno estiver como online, é necessário finalizar a transação, caso contrário apenas execute o fechamento da conexão com o PinPad.
Vale ressaltarCaso não tenha sido possível fazer uma conexão com a API Pagar.me, para inicializar uma transação (e o parâmetro connected seja false), responseCode deve ser 0 e emvData deve ser
null.
Parâmetro local_timeAo criar uma transação de mundo físico, deve ser enviado o parâmetro
local_time, que refere-se a data e hora do dispositivo que está efetuando a transação, em formato ISO String (2017-10-31T14:53:00.000Z).
Banco de dados local
Há um banco de dados no SDK que armazena um histórico de transações dos últimos dias. Uma instância da classe TransactionStorage (me.pagar.mposandroid.localtransactionsdb) pode ser utilizada para definir o limite de dias de armazenamento de uma transação.
Para definir o limite, chame o método setStorageLimit(int). Por padrão, transações serão armazenadas por 30 dias. As transações devem ser armazenadas por, no mínimo, 1 dia. O limite superior para armazenamento é de 120 dias.
As seguintes informações são salvas no banco, encapsuladas em objetos da classe Transaction (me.pagar.mposandroid.localtransactionsdb) .
| Campo | Descrição |
|---|---|
| localTransactionId | Identificador local da transação. Pode ser utilizado para buscar por uma transação ou para estorná-la, caso seja necessário. |
| amount | Valor da transação. |
| firstDigits | 6 primeiros dígitos do cartão de crédito da transação. |
| lastDigits | 4 últimos dígitos do cartão de crédito da transação. |
| createdAt | Data e hora de criação da transação (objeto Date). |
A classe TransactionStorage possui, também, o método getSearcher. Ele fornece um objeto da classe Searcher (me.pagar.mposandroid.localtransactionsdb) para buscas no banco de dados.
A classe Searcher provê uma interface fluente para definição de filtros de busca. Com exceção dos métodos de execução da busca, todos os seus métodos públicos retornam uma instância atualizada do mesmo objeto.
Abaixo segue a documentação da classe Searcher:
| Método | Descrição |
|---|---|
| Searcher localTransactionId(String) | Define o local_transaction_id de filtro. Equivalente a WHERE local_transaction_id = . |
| Searcher amount(int) | Define o amount de filtro. Equivalente a WHERE amount = . |
| Searcher firstDigits(String) | Define o card_first_digits de filtro. Equivalente a WHERE first_digits = . |
| Searcher lastDigits(String) | Define o card_last_digits de filtro. Equivalente a WHERE last_digits = . |
| Searcher createdAt(Date) | Define o created_at de filtro. Equivalente a WHERE created_at::timestamp = . |
| Searcher range(Date start, Date end) | Define um intervalo de tempo de filtro. Equivalente a WHERE created_at::timestamp >= *start* AND created_at::timestamp <= *end* |
| Searcher page(int) | Define a página de busca. Por padrão a primeira página é trazida na busca. Mínimo: 1 |
| Searcher limit(int) | Define o limite de elementos trazidos por página de busca. Por padrão 10 elementos são trazidos. Mínimo: 1 |
| ArrayList<Transaction> run() | Executa a query com os filtros estabelecidos. Retorna uma ArrayList de objetos Transaction. A resposta obedece aos parâmetros de paginação definidos ou os valores padrão, caso não haja definição do usuário. Equivalente a |
| int count() | Retorna a quantidade de elementos que satisfazem os filtros estabelecidos. Equivalente aSELECT COUNT(*).
|
Podemos, então, buscar todas as transações feitas pelos cartões com início 516230 cujo valor foi R$ 15,95 da seguinte forma:
Caso haja 50 transações nesse formato, podemos encontrar as transações 31-40 da seguinte forma:
Updated 5 months ago
Próximo
Excelente! Você aprendeu como integrar sua aplicação com nosso SDK para mPOS, mas caso encontre algum erro ao longo do caminho, a seguinte tabela pode te ajudar na resolução, segue: