O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com as APIs da Muxi, descrevendo as funcionalidades e os métodos a serem utilizados, listando informações a serem enviadas e recebidas através de exemplos e com uma linguagem simples e acessível. Desse modo, será necessário apenas conhecimentos básicos em linguagem de programação para Web, requisições HTTP/HTTPS e manipulação de arquivos JSON para interagir com nossas APIs.

Nesse manual, você também encontrará a referência sobre todas as operações disponíveis na API REST da Muxi. Essas operações devem ser executadas utilizando sua chave específica (token de autorização) nos respectivos endpoints a seguir. Para executar uma operação, combine a URL base do ambiente com o endpoint da operação desejada e envie utilizando o verbo HTTP conforme descrito no item do menu ENVIANDO UMA TRANSAÇÃO. Caso esses termos estejam complexos para você, leia o subitem O QUE É WEB SERVICE?.

Para facilitar a integração, nós disponibilizamos um ambiente de Sandbox onde você pode realizar testes antes de mudar o ambiente para produção. Após o desenvolvimento, o acesso deve ser modificado para o ambiente produtivo.

Transações de Cartão Não Presente (CNP) permitem que as empresas digitais vendam de forma conveniente seus produtos ou serviços digitais para clientes em todo o mundo. Nossas APIs oferecem um ambiente seguro para se realizar esse tipo de transação e com isso potencializar seus negócios.

Por meio dos gateways de pagamento, o cliente insere as informações do seu cartão, as quais são enviadas às operadoras de cartão e às instituições financeiras e, a partir daí, o banco confirma se há limite disponível e aprova ou nega a compra em segundos.

Mas é seguro?

S-I-M!! Nós da Muxi sabemos o quanto é ruim sermos enganados. Quando usamos um serviço, não começamos pensando que pode dar errado, que podem nos dar uma volta, e certamente não é isso que oferecemos aos nossos clientes. Temos um compromisso com nossos usuários e parceiros a sempre buscar o mais alto padrão de segurança no que diz respeito a pagamentos. Quer saber como fazemos isso?

• PCI -> Seguimos 100% dos padrões definidos pelo PCI. O Payment Card Industry – Data Security Standard (PCI-DSS) é um padrão de segurança, voltado para a indústria de cartões de pagamento, que definem os modelos de segurança através de padrões que devem ser seguidos de forma rigorosa. Essa certificação é necessária para qualquer empresa que armazene, transmita ou processe informações sigilosas de portadores de cartões. Dados como nome, número do cartão e código de segurança devem ser criptografados para a segurança dos portadores de cartões. E como queremos que você se sinta seguro, somos uma empresa totalmente certificada pelo PCI-DSS.

• Criptografia -> Todos os dados sensíveis que transitam em nosso gateway são protegidos através dos certificados usados durante a transação. Aqui usamos o HTTPS, que é uma implementação do protocolo HTTP sobre uma camada adicional de segurança que utiliza o protocolo SSL/TLS. Essa camada adicional permite que os dados sejam transmitidos por meio de uma conexão criptografada e que se verifique a autenticidade do servidor e do cliente por meio de certificados digitais.

• Token -> Não salvamos os dados do seu cartão, eles são tokenizados. A tokenização permite a utilização dos dados do cartão do portador de forma segura e compatível com as normas do PCI-DSS. O conceito básico consiste em enviar os dados do cartão do cliente diretamente do browser dele para a Muxi e então receber de volta um código (token) que representa o cartão em questão. Leia o subitem Tokenização e esteja por dentro da forma mais segura de efetuar um pagamento hoje em dia.

Precisamos saber quem é você =)

Para usar nossos serviços, serão necessárias duas coisas importantes:

• Identificador do lojista
• Token de Autenticação

E como eu consigo essas coisas, senhor???

Só ligar para gente! Ao entrar em contato com o time operaconal da Muxi, você gerar para você um número de identificação, que chamamos de Merchant Id, e um token de autenticação, que será usado na inicialização do terminal virtual.

Fale-me mais…

Merchant Id -> é um hash de 34 bits que você guardará com você para sempre! Essa hash vai ser tipo o seu CNPJ, ou seja, um número que me diz que lojista você é. Você vai usar esse dado no corpo da transação de inicialização.

Token de Autenticação -> Esse dado será usado no campo Authentication do HTTP header da transação de inicialização de acordo com o ambiente que deseja acessar. Após a inicialização, você receberá de resposta o token transacional (que é diferente do token de autenticação!) e passará a usar este token ao invés do token de autenticação nas próximas transações. Para gerar o nosso token de autenticação nos baseamos na especificação JWT.io, logo o seu tamanho é variável de acordo com a geração do mesmo.

Veja a seguir um exemplo de comando curl para realizar uma requisição de consulta a ciclos de transação.

curl --request GET --url https://hmg-transaction-api.muxi.net.br/v1/financial_cycles --header 'Authorization:<token>'

Webservices permitem que duas (ou mais) maquinas se comuniquem via uma rede. Veja um exemplo:

Para uma explicação mais profunda, imagine o seguinte cenário: A sua empresa negocia produtos em dólar, cujo valor flutua diariamente. É extremamente importante que você tenha esses valores atualizados para que você tome decisões que lhe tragam melhores resultados. Você pode contratar um estagiário pra ficar atualizando esses valores manualmente, ou você pode consumir um serviço que lhe forneça essa informação automaticamente e com confiabilidade.

Esse serviço é o tal do webservice. Você faz uma pergunta “Quantos reais valem um dólar hoje?” e ele lhe responde. Esse processo, a nível de comunicação, dá-se por requisições baseadas no protocolo HTTP. Existe uma URL específica, que chamamos de endpoint, em um servidor que está sempre esperando pela pergunta e, se ela for feita da maneira correta, ele responde. Chamamos essa URL de endpoint porque ela é sim uma URL, mas ela tem vários “finais” que especificam exatamente onde você quer ir. Imagine como se a URL fosse o endereço de uma rua e o endpoint fosse o número da casa, e dentro de cada casa existe um serviço. Por exemplo, em uma casa você entrega a farinha, ovos, leite e te devolvem um bolo; em outra casa você entrega o tecido, linha, agulha e te devolvem uma roupa. Depois da roupa pronta, você ainda pode voltar na casa para fazer um ajuste, ou adicionar um bordado. Assim como existem casas que podem jogar a roupa fora, se você não vai usar mais. Existem também as casas onde você consulta a quantidades de roupas que já solicitou. Isso tudo será traduzido em verbos. Por exemplo: /

• Fazer uma roupa/transação -> POST
• Consultar quantas roupas/transações já foram feitas -> GET
• Alterar/ajustar uma roupa/transação -> PUT
• Excluir/Jogar fora uma roupa/transação -> DELETE

Lembre-se de que a pergunta (ou requisição) deve ser feita corretamente, caso contrário o webservice não vai conseguir entender o pedido. Use esta documentação para conferir se seus dados estão corretos e não há nada faltando. Há também um exemplo de arquivo JSON funcional para download que você pode usar para comparar com o que estiver usando.

Postman

Para agilizar os testes de comunicação com as nossas APIs, pode-se utilizar qualquer cliente HTTP. Aqui na Muxi, nós utilizamos o Postman; pois além de atender muito bem às nossas necessidades, é mais difundido na comunidade. Esse cliente permite configurar e realizar testes antes mesmo de iniciar o desenvolvimento das integrações como as APIs da Muxi. No caso do Postman, existe uma documentation bem desenvolvida explicando como utilizar a ferramenta. Ele também gera para o desenvolvedor exemplos de códigos em algumas linguagens, tais como:

• ASP
• Net
• Java
• PHP
• Ruby
• Python

JSONLint

Para validar se o objeto JSON gerado é válido de acordo com o padrão, podemos utilizar várias ferramentas. Aqui na Muxi, usamos o JSONLint, por ser web e possuir uma interface simples de ser entendida.

SDKs

Para quem usa a linguagem Java estamos desenvolvendo SDKs (Kit de desenvolvimento de software) para facilitar a integração com nossas APIs. Aguarde!

O que é uma Transação?

Do ponto de vista da aplicação, a transação é uma operação que consiste em uma série de instruções ou procedimentos que devem ser realizados em conjunto. Este tipo de circunstância se deve às instruções que apenas tem sentido quando executadas juntas. Nossa aplicação oferece vários tipo de transações como inicialização, autorização, estorno, tokenicação etc. Toda vez que dados forem enviados para API e algo for respondido, teremos uma transação; porém se valores monetários estiverem envolvidos nessa transação, teremos uma transação financeira.

Transação financeira é uma operação comercial que consiste em trocar um bem ou serviço por uma determinada quantidade de dinheiro. O termo também se refere à própria operação técnica do banco de dados que executa uma série de operações. No entanto, o significado mais comum se refere à troca de bens, circunstância própria da atividade econômica.

Exemplos de transações financeiras:

• Autorização / Venda
• Pré-autorização
• Confirmação de Pré-autorização
• Cancelamento de Pré-autorização
• Cancelamento de Venda
• Pagamento Recorrente

Exemplos de transações não financeiras:

• Inicialização
• Cadastro de Assinante
• Registro de Cartão - Tokenização

O que é necessário para realizar uma transação financeira?

Temos diversos meios de envio de uma transação financeira. Para realizá-la, necessitamos antes gerar um token transacional. Quando receber o token de autenticação. Em posse desses dados, enviará uma mensagem de inicialização, e assim obterá o token transacional que é válido por 1 hora, caso gere outro o anterior é invalidado.

Calma aí! Me explica melhor o que é o Token Transacional!

Claro! O token transacional é uma chave única que identifica para nossa sistema quem é você! Toda vez que você quiser transacionar, você começa fazendo uma inicialização com o token de autenticação no campo Authentication do HTTP header. A resposta dessa inicialização vai gerar para você o token transacional. Você vai copiar esse token transacional e trocar o token de autenticação que estava no campo Authetication do cabeçalho por esse token novo. Com isso, você vai poder fazer todas as outras transações, veja um exemplo mais a seguir. O token transacional tem validade de 1 hora, sendo assim, ao acabar esse tempo, você precisa inicializar novamente para conseguir um novo token e voltar a transacionar normalmente.

Header HTTP

Toda requisição precisa de um cabeçalho contendo as informações detalhadas a seguir:

• Content-Type -> Indica o formato do corpo da requisiçao.
• Accept -> Indica o tipo de retorno esperado.
• Authorization -> É o campo preenchido por dois valores possíveis:
  • Token de Autenticação -> Se for uma inicialização.
  • Token Transacional -> Se for qualquer outra transação, exceto a inicialização.

Exemplo

Antes de começar, temos um recado importante!

Possuímos uma collection do Postman frequentemente atualizada com todas as requisições descritas nesta documentação. Caso queira fazer o download para ultilizá-la em seus testes, basta clicar no link a seguir:

https://www.getpostman.com/collections/ab422606e01214a7193c

Posso mudar uma transaçaõ já realizada?

Sim, mas apenas as transações de Cadastro de Assinante, Cadastro de Cartão - Tokenização e Pagamento Recorrente. Para isso você precisa enviar um requisição HTTP/HTTPS usando o método PUT. Veja nos subitens a seguir o exemplo de cada uma dessas transações.

Transações Cartão presente

Por um longo tempo, os meios de pagamento eram limitados a dispositivos caros e complexos que tinham um baixo poder computacional. Em adição a isso, as aplicações financeiras que eram necessárias para fazer pagamentos efetivamente, foram desenvolvidas de um modo custoso e não escalável. Entretanto, com o avanço da tecnologia, smartphones tem sido importantes ferramentas para inovar o meio de pagamentos e suas tecnologias, tornando possivel a melhoria de interação de diferentes interessados, como estabelecimentos, usuários finais, bancos e emissores.

Tendo isso em mente, nós oferecemos para nossos clientes um serviço Android chamado muxiPAY services e um SDK(Software Development Kit) que permite o desenvolvimento de aplicações Android para pagar de maneira transparente, segura e descomplicada. Para que os desenvolvedores se concentrem no que realmente importa, a experiência do usuário e a regra de negócio.

Dispositivos suportados

Atualmente o dispositivo suportados é:

• PAX D150

Preparando o ambiente

Para o desenvolvimento da nossa aplicação, recomendamos o uso do Android Studio que é a IDE oficial de desenvolvimento de apps Android.

Depois do projeto criado, o desenvolvedor deve adicionar ao projeto o módulo do muxiPAY services SDK, provido pela Muxi no formato AAR. Você pode baixar para integrar o SDK ao seu app aqui. As instruções para importar o módulo você encontra aqui.

Após o SDK importado, é hora de instalar o muxiPAY services no seu smartphone. Você pode baixar nossa versão de integração que é uma versão onde não é necessário o uso de um Pinpad

• Versão smartphone.

Você precisará adicionar algumas dependencias no seu app/build.gradle, para criar a ponte entre o skd e o muxiPAY services.

api "com.josesamuel:remoter-annotations:1.2.0"
annotationProcessor "com.josesamuel:remoter:1.2.0"

Você também pode baixar o nosso aplicativo de exemplo que já contém o SDK importado clicando aqui.

Vinculando ao muxiPAY services

Nesse passo, o desenvolvedor deverá adicionar sua lógica com mecanismos de pagamento providos pelo muxiPAY services.

O desevolvedor deve criar um objeto principal que é uma instância da interface IMPSManager, instanciá-la e vincular a aplicação com o serviço. É recomendado fazer isso no método onStart da activity atual, porém você pode fazer o bind com o serviço onde desejar.

Nota bindService deve ser chamado antes de qualquer operação

• Java
• Kotlin

• MPSManager mpsManager = null;
  
  @Override
  protected void onStart() {
      super.onStart();
      if (mpsManager == null) {
          Log.d(TAG,"Instantiating  mpsManager");
          mpsManager = new MPSManager(this.getApplicationContext());
      }
  
      boolean bindService = mpsManager.bindService(getApplicationContext());
  }
  

• var mpsManager: MPSManager = null
  
  override fun onStart() {
      super.onStart()
      if (mpsManager == null) {
          Log.d(TAG,"Instantiating  mpsManager")
          mpsManager = MPSManager(this.applicationContext)
      }
  
      isServiceBound = mpsManager?.bindService(applicationContext)!!
  }
  

Setando Manager callback

A comunicação entre o aplicativo do usuário e o muxiPAY services é estabelecida usando Callbacks. Para facilitar a interação do desenvolvedor, o serviço tem uma classe chamada CallbackAnswer que implementa cinco métodos. Todos esses métodos são chamados quando algum processo do muxiPAY services for encerrado, retornando um objeto do tipo MPSResult que contem informação do STATUS sobre o processo executado. Em caso de ERROR, retorna o código e a descrição do erro ocorrido. Veja na seção Erros mais informações sobre.

• public void onInitAnswer(MPSResult mpsResult); Chamado quando o processo de inicialização é finalizado
• public void onTransactionAnswer(MPSResult mpsResult); Chamado quando o processo de transação é finalizado
• public void onCancelAnswer(MPSResult mpsResult); Chamado quando o processo de cancelamento é finalizado
• public void onDeconfigureAnswer(MPSResult mpsResult); Chamado quando o processo de desconfiguração é finalizado
• public void onServiceConnected(); Chamado quando o serviço é conectado
• public void onServiceDisconnected(); Chamado quando o serviço para de forma inesperada

O desenvolvedor deve usar o método setMpsManagerCallback para definir o Callback instanciado que deve ser notificado quando o processo terminar. Por exemplo, adicionando tratamento para onInitAnswer:

• Java
• Kotlin

• mpsManager.setMpsManagerCallback(new CallbackAnswer() {
          @Override
          public void onInitAnswer(final MPSResult mpsResult) {
              runOnUiThread(new Runnable() {
                  @Override
                  public void run() {
                      if (mpsResult.getStatus() == MPSResult.Status.SUCCESS) {
  
                          //  faça alguma coisa com o sucesso
  
                      } else {
  
                          //  faça alguma coisa com o erro
  
                      }
                  }
              });
          }
  }
  

• mpsManager?.setMpsManagerCallback(object : CallbackAnswer(){
      override fun onInitAnswer(mpsResult: MPSResult?) {
          super.onInitAnswer(mpsResult)
          runOnUiThread {
              if (mpsResult?.status == MPSResult.Status.SUCCESS) {
  
                  //  faça alguma coisa com o sucesso
  
              } else {
  
                  //  faça alguma coisa com o erro
  
              }
          }
      }
  })
  

Nota 1: Callback é chamada em outra thread. Para atualizar a tela da sua aplicação, use runOnUiThread method ou alguma outra forma que faça o processamento em uma Thread diferente da UiThread ou MainThread

Nota 2: CallbackAnswer é preparada para sobrescrever apenas callbacks necessários. Assim, o desenvolvedor escolhe os métodos que devem ser sobrescritos na activity atual.

Inicialização

O Objeto IMPSManager será usado para chamar o método de inicialização, passando os seguintes parâmetros:

1. Um booleano indicando se algumas mensagens deverão ser exibidas na tela do pinpad.
2. O identificador do comerciante (CNPJ, por exemplo).
3. A chave de autenticação, que será fornecida pela Muxi.

Nota: É recomendado executar essa chamada em outra thread, para evitar o travamento da Thread principal(UI Thread).

• Java
• Kotlin

• 
  mpsManager.initialize(pinpadMSG, MERCHANT_ID, AUTHENTICATION_TOKEN);
  
  

• 
  mpsManager?.initialize(pinpadMSG, MERCHANT_ID, AUTHENTICATION_TOKEN)
  
  

Após a inicialização, onInitAnswer é chamado

Realizando uma transação

Agora, com o Pinpad pareado, deve-se passar o endereço MAC do mesmo como parâmetro do método setCurrentBluetoothDevice, sendo possivel realizar sua primeira transação.

• Java
• Kotlin

• 
  mpsManager.setCurrentBluetoothDevice(bluetoothDevice);
  
  

• 
  mpsManager?.currentBluetoothDevice = bluetoothDevice
  
  

O desenvolvedor deve acessar o método transaction através da instância da classe IMPSManager. Esse método espera um objeto do tipo MPTransaction como parâmetro. Veja o exemplo abaixo.

• Java
• Kotlin

• MPSTransaction currentTransaction = new MPSTransaction();
  currentTransaction.setAmount("2000");
  currentTransaction.setCurrency(MPSTransaction.CurrencyType.BRL);
  currentTransaction.setInstallments(1);
  currentTransaction.setTransactionMode(MPSTransaction.TransactionMode.CREDIT);
  currentTransaction.setRate(false);
  currentTransaction.setMerchantId(MERCHANT_ID);
  

• val currentTransaction = MPSTransaction()
  currentTransaction?.amount = "2000"
  currentTransaction?.currency = MPSTransaction.CurrencyType.BRL
  currentTransaction?.installments = 1
  currentTransaction?.transactionMode = MPSTransaction.TransactionMode.CREDIT
  currentTransaction?.rate = false
  currentTransaction?.merchantId = MERCHANT_ID
  

Então, chamar o método transaction, passando o objeto criado como parâmetro. É recomendado executar essa chamada em outra thread, para evitar o travamento da Thread principal(UI Thread).

• Java
• Kotlin

• 
  mpsManager.transaction(transaction);
  
  

• 
  mpsManager?.transaction(transaction)
  
  

O exemplo acima realiza uma transação de crédito, com 1 (uma) parcela e com o valor de 20.00 BRL.

Nota: O tipo da transação e a moeda são do tipo enum.

Cada transação pode ser aprovada ou negada. O desenvolvedor deve receber o resultado da transação e tratá-la, usando onTransactionAnswer.

No caso da resposta SUCCESS em onTransactionAnswer, o recibo do cliente e do estabelecimento são guardados em duas Strings, para serem tratadas no futuro. Essas strings são acessadas através dos métodos getClientReceipt e getEstablishment, respectivamente.

Por outro lado, o código e descrição do erro são guardados em duas Strings, para serem tratadas no futuro. Essas strings são acessadas através dos métodos getCode e getDescriptionError, respectivamente.

• Java
• Kotlin

• @Override
  public void onTransactionAnswer(final MPSResult mpsResult) {
      runOnUiThread(new Runnable() {
          @Override
          public void run() {
              if (mpsResult.getStatus()== MPSResult.Status.SUCCESS) {
  
                  //  fazer o que desejar usando mpsResult.getClientReceipt()
                  //  e mpsResult.getEstablishmentReceipt()
  
              } else {
  
                  //  tratar o erro usando mpsResult.getCode()
                  //  e mpsResult.getDescriptionError()
  
              }
          }
      }
  }
  

• override fun onTransactionAnswer(mpsResult: MPSResult?) {
      super.onTransactionAnswer(mpsResult)
      runOnUiThread {
          if (mpsResult.getStatus()== MPSResult.Status.SUCCESS) {
  
                  //  fazer o que desejar usando mpsResult.getClientReceipt()
                  //  e mpsResult.getEstablishmentReceipt()
  
              } else {
  
                  //  tratar o erro usando mpsResult.getCode()
                  //  e mpsResult.getDescriptionError()
  
              }
      }
  }
  

Note que o jeito de lidar com erros é facil. Se a transação é negada por causa de um error ocorrido lendo o cartão, a lógica de negócio pode implementar um método “tente novamente”. Existem muitas possibilidades.

Cancelando um pagamento

O fluxo de cancelamento é muito similar ao de transação. onCancelAnswer será chamado quando o processo de cancelamento terminar.

Existem duas opções de cancelamento:

1. Cancelar a ultima transação
2. Cancelar qualquer transação

Cancelar a ultima transação

Para cancelar a ultima transação, é necessário criar uma instância de MPSTransaction e setar o tipo.

• Java
• Kotlin

• MPSTransaction transaction = new MPSTransaction();
  transaction.setCurrency(MPSTransaction.CurrencyType.BRL);
  transaction.setTransactionMode(MPSTransaction.Transaction.CREDIT);
  

• val transaction = MPSTransaction()
  transaction?.currency = MPSTransaction.CurrencyType.BRL
  transaction?.transactionMode = MPSTransaction.TransactionMode.CREDIT
  

Cancelar qualquer transaction

Para cancelar qualquer transação, é necessário criar uma instância de MPSTransaction, setar o tipo, o identificador da transação, por exemplo DOC(CV), e o código de autorização. No exemplo abaixo, muxiPAY services irá buscar uma transação do tipo CREDIT, com o identificador de transação igual a 123456 e o código de autorização igual a 12345678.

• Java
• Kotlin

• MPSTransaction transaction = new MPSTransaction();
  transaction.setCurrency(MPSTransaction.CurrencyType.BRL);
  transaction.setTransactionMode(MPSTransaction.TransactionMode.CREDIT);
  transaction.setCv("123456");
  transaction.setAuth("12345678");
  

• val transaction = MPSTransaction()
  transaction?.currency = MPSTransaction.CurrencyType.BRL
  transaction?.transactionMode = MPSTransaction.TransactionMode.CREDIT
  transaction?.cv = "123456"
  transaction?.auth = "12345678"
  

Então você deve chamar o método cancelTransaction, passando o objeto criado, transaction, como parâmetro. É recomendado executar essa chamada em outra thread, para evitar o travamento da Thread principal(UI Thread).

• Java
• Kotlin

• 
  mpsManager.cancelTransaction(transaction);
  
  

• 
  mpsManager?.cancelTransaction(transaction)
  
  

Código fonte

Além disso, o desenvolvedor pode consultar, se necessário, o código fonte de um exemplo que provemos no Github

• muxiPAY services sample
• Javadoc SDK

Após realizar todos os testes e se sentir seguro, desinstale a versão de integração do muxiPAY services e instale nossa versão de produção aqui, onde esta versão necessita de um Pinpad. Para saber como parear o Pinpad com seu aparelho, verifique com o fabricante

Erros

Posso consultar as transações que eu já fiz?

Claro! Para isso você precisa enviar um requisição HTTP/HTTPS usando o método GET. Veja nos subitens a seguir o exemplo de cada uma dessas transações.

Posso registar as transações que já foi processada?

Sim! Para isso você precisa enviar um requisição HTTP/HTTPS usando o método POST. Veja nos subitens a seguir o exemplo de cada uma dessas transações. Fazendo isso você vai gerar somente o registro de uma transação que já foi feita e assim esta poderá ser incluída nos fluxos do nosso produto.

Como incluir novos estabelecimentos comerciais para operar no muxiPAY?

Para incluir novos estabelecimentos comerciais visando a operação no muxiPAY você precisa enviar um requisição HTTP/HTTPS usando o método POST. De acordo com o seu tipo de operação podem ser requisitados ou não algumas informações.