Nesta seção você irá aprender mais sobre os detalhes de cada funcionalidade do SDK .NET para mPOS, como fazer o download e instalação do pacote, configurar as bibliotecas básicas que seguem o protocolo ABECS, além de ver o fluxo de criação de uma transação. Vamos lá!

Download do SDK

O SDK .NET pode ser instalado através do pacote PagarMe.Mpos no nuget.

Configurando o ambiente

Para que o SDK .NET funcione, os seguintes passos são necessários:

Instalação dos componentes nativos do SDK mpos.dll e tms.dll, que devem ser colocados no diretório de binários do seu projeto (e.g. a pasta bin).

Para a integração da Pagar.Me.Mpos 2.0.0, use:

Para versões anteriores do SDK, use:

Instalação dos componentes nativos do SQLite3. Componentes sqlite3_32.dll e sqlite3_64.dll adequados devem ser colocados exatamente no diretório de binários do seu projeto (e.g. a pasta bin), e você pode usar também o Bibliotecas. Existem outras possibilidades de download desses componentes, variando com versão do Windows, por exemplo. Possível download do SQLite

Criando uma transação

O código abaixo demonstra um fluxo completo que poderia ser usado pela sua aplicação
para capturar os dado do cartão, gerar o card_hash e usá-lo para criar uma transação com
a API Pagar.Me. Este exemplo usa também o SDK para a criação de transações em nosso [NuGet] (https://www.nuget.org/packages/Pagar.me/). No entanto, caso esteja construindo um app mobile, recomendamos que envie o card_hash para um servidor externo e crie a transação a partir de lá.

using System;
using System.IO.Ports;
using System.Threading.Tasks;

using PagarMe;
using PagarMe.Mpos;

namespace PagarMeCSharpLibPoCs
{
	public class PaymentProcessor
	{
		private readonly SerialPort _port;
		private readonly Mpos _mpos;

		public PaymentProcessor(string device)
		{
			_port = new SerialPort(device, 140000, Parity.None, 8, StopBits.One);
			_port.Open();
      
      /* Guardamos arquivos de cache no diretório C:\\Storage\\. É *obrigatório* colocar a última barra ao final do path! */      
			_mpos = new Mpos(_port.BaseStream, "SUA ENCRYPTION KEY", "C:\\Storage\\");

      /* Os eventos abaixo podem ser usados para controlar o fluxo de 
         sua aplicação
      */
			_mpos.NotificationReceived += (sender, e) => Console.WriteLine("Status: {0}", e);
			_mpos.TableUpdated += (sender, e) => Console.WriteLine("LOADED: {0}", e);
			_mpos.Errored += (sender, e) => Console.WriteLine("I GOT ERROR {0}", e);
			_mpos.PaymentProcessed += (sender, e) => Console.WriteLine("HEY CARD HASH " + e.CardHash);
			_mpos.FinishedTransaction += (sender, e) => Console.WriteLine("FINISHED TRANSACTION!");

		}


		public async Task Initialize()
		{
			await _mpos.Initialize();
       
      // Você pode solicitar o download das tableas EMV neste momento
			await _mpos.SynchronizeTables(false);
		}



		public async Task Pay(int amount)
		{
			var result = await _mpos.ProcessPayment(amount, null, PagarMe.Mpos.PaymentMethod.Credit);
   
			Console.WriteLine("CARD HASH = " + result.CardHash);
      
			var transaction = new Transaction
			{
				CardHash = result.CardHash,
				Amount = amount
			};

			await transaction.SaveAsync();

			Console.WriteLine("Transaction ARC = " + transaction.AcquirerResponseCode + ", Id = " + transaction.Id);
			Console.WriteLine("ACQUIRER RESPONSE CODE = " + transaction.AcquirerResponseCode);
			Console.WriteLine("EMV RESPONSE = " + transaction["card_emv_response"]);

			int x = Int32.Parse(transaction.AcquirerResponseCode);
			object obj = transaction["card_emv_response"];
			string response = obj == null ? null : obj.ToString();
			await _mpos.FinishTransaction(true, x, (string)obj);
			await _mpos.Close();
		}
	}
}

Atualizando 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 à Pagar.me via SDK.

Para baixar as tabelas EMV, as seguintes operações são realizadas:

  1. Download das tabelas EMV pela API Pagar.me;
  2. 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:

bool force = false; // Define o comportamento da atualização de tabelas
await mpos.SynchronizeTables(force);

O valor booleano force dos exemplos especifica o comportamento de atualização de tabelas no PinPad. Caso esteja setado como true, faz o download instala as tabelas baixadas no PinPad. Caso esteja como false, instala as tabelas no PinPad somente 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.

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:

var result = await _mpos.ProcessPayment(amount, null, PagarMe.Mpos.PaymentMethod.Credit);

A função de processamento ProcessPayment aceita os seguintes 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). Segue detalhe de cada opção:

ParâmetroSignificado
amountQuantia a ser cobrada em centavos (ex. 100 = R$1,00)
applicationsUm 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.
magstripePaymentMethodA 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.

Caso 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 do 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:

await _mpos.FinishTransaction(true, x, (string)obj);
await _mpos.Close();

Logo, considere a seguinte assinatura para o método FinishTransaction:

FinishTransaction(bool success, int responseCode, string emvData)

Começando com o parâmetro success, 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:

{
  "card_pin_mode": "online",
  "acquirer_response_code": "0000",
  "card_emv_response": "124046c481.ca8c"
}

Sendo:

ParâmetroCorrespondência no objeto transaction
responseCodeacquirer_response_code, diz respeito ao código de retorno do adquirente Pagar.me para sua aplicação.
emvDatacard_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 o fechamento da conexão com o PinPad.

🚧

Vale ressaltar

Caso não tenha sido possível conexão com a API Pagar.me para inicializar uma transação (e o parâmetro success seja false), responseCode deve ser 0 e emvData deve ser null.

❗️

Parâmetro local_time

Ao 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).


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: