NAV
Java

Introdução

Este documento descreve o processo de integração da Automação Comercial com o Cappta Android para a plataforma móvel Android.

Requisitos Mínimos

Abaixo listamos os requisitos mínimos para que a integração funcione corretamente:

Código de exemplo

Disponibilizamos o código de exemplo para integração que segue exatamente os passos deste documento no GitHub, caso tenha interesse sinta-se a vontade para utiliza-lo para facilitar o desenvolvimento e até mesmo sugerir melhorias =).

Integração

A comunicação entre o App da Automação Comercial e o Cappta Android ocorrerá por um recurso do Android chamado AppLink.

O AppLink é bem simples, seu aplicativo irá realizar uma requisição para uma URI, mas ao invés de acessar um site como esperado, haverá um outro app no seu dispositivo que irá atenter aquela requisição, para mais detalhes clique aqui

Como o funcionamento do AppLink é unidirecional, para todas as operações que disponibilizamos, utilizaremos um outro link de resposta que deverá ser controlado pelo seu app.

As chamadas seguem o padrão <scheme>://<action> como pode ser visto nos exemplos abaixo:

Operações da API

Abaixo descrevemos como funciona cada uma das operações disponíveis na integração:

Operação Descrição
Pagamento Operação de pagamento presencial
Estorno Estorno de pagamento aprovado no mesmo dia
Reimpressão Reimpressão de comprovantes de pagamento e estorno

Requisição de Pagamento

Para realizar uma operação de pagamento é bem simples, basta iniciar uma nova Activity contendo um Intent configurado com uma URI confirme demonstrado no exemplo ao lado.

//TODO incluir import dos packages necessários e envolver método em uma classe

private void SendPayment() {
      String scheme = "exemplo";
      String authKey = "00000000-0000-0000-0000-000000000000";
      String paymentType = "credit";
      String paymentId = "123456";
      int paymentAmountInCents = 100;
      int installments = 999;
      int installmentType = 1;

      Uri capptaAppLink = new Uri.Builder()
          .scheme("cappta")
          .authority("payment")
          .appendQueryParameter("scheme", scheme)
          .appendQueryParameter("authKey", authKey)
          .appendQueryParameter("amount", paymentAmountInCents)
          .appendQueryParameter("paymentId", paymentId)
          .appendQueryParameter("paymentType", paymentType)
          .appendQueryParameter("installments", installments)
          .appendQueryParameter("installmentType", installmentType)
          .build();

      Intent capptaIntent = new Intent(Intent.ACTION_VIEW, capptaAppLink);

      this.startActivityForResult(capptaIntent, 0);
}
Parâmetro Tipo Obrigatório? Descrição
scheme string sim Como descrito na sessão Integração, precisamos saber qual é o aplicativo de origem desta requisição
authKey string sim Chave de identificação da Automação Comercial na Cappta
amount int sim Valor pagamento, em centavos
paymentId string não Chave de identificação do pagamento utilizada pela Automação Comercial, será devolvida exatamente como recebemos durante a resposta desta requisição
paymentType string não Tipo do pagamento, sendo credit para Crédito e debit para Débito
installments int não Quantidade de parcelas, somente necessário quando o pagamento for um Crédito Parcelado, iremos considerar somente valores maiores ou iguais a 2
installmentType int não Determina a configuração do parcelamento, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis

Requisição de Estorno

Assim como uma requisição de pagamento não à segredos para realizar uma de estorno, confira no exemplo de código ao lado.

//TODO incluir import dos packages necessários e envolver método em uma classe

private void SendPaymentReversal() {
      String scheme = "exemplo";
      String authKey = "00000000-0000-0000-0000-000000000000";
      String administrativeCode = "00000000000";
      String administrativePassword = "00000000";

      Uri capptaAppLink = new Uri.Builder()
          .scheme("cappta")
          .authority("payment")
          .appendQueryParameter("scheme", scheme)
          .appendQueryParameter("authKey", authKey)
          .appendQueryParameter("administrativeCode", administrativeCode)
          .appendQueryParameter("administrativePassword", administrativePassword)
          .build();

      Intent capptaIntent = new Intent(Intent.ACTION_VIEW, capptaAppLink);

      this.startActivityForResult(capptaIntent, 0);
}
Parâmetro Tipo Obrigatório? Descrição
scheme string sim Como descrito na sessão Integração, precisamos saber qual é o aplicativo de origem desta requisição
authKey string sim Chave de identificação da Automação Comercial na Cappta
administrativeCode string sim Identificador único para pagamentos, é devolvido quando a requisição de pagamento é autorizada (pode ser consultado no portal de transações Cappta)
administrativePassword string não Senha solicitada no Cappta Android necessária para liberar o acesso à estorno de pagamentos

Requisição de Reimpressão

Disponibilizamos dois tipos de reimpressão de comprovantes:

Abaixo demonstramos como funcionam ambos os modos.

Reimpressão de comprovante específico

Para a reimpressão seguimos a mesma linha de raciocinio das operações anteriores, confira no exemplo de código ao lado.

//TODO incluir import dos packages necessários e envolver método em uma classe

private void SendReceiptReprint() {
      String scheme = "exemplo";
      String authKey = "00000000-0000-0000-0000-000000000000";
      String administrativeCode = "00000000000";

      Uri capptaAppLink = new Uri.Builder()
          .scheme("cappta")
          .authority("payment")
          .appendQueryParameter("scheme", scheme)
          .appendQueryParameter("authKey", authKey)
          .appendQueryParameter("administrativeCode", administrativeCode)
          .build();

      Intent capptaIntent = new Intent(Intent.ACTION_VIEW, capptaAppLink);

      this.startActivityForResult(capptaIntent, 0);
}
Parâmetro Tipo Obrigatório? Descrição
scheme string sim Como descrito na sessão Integração, precisamos saber qual é o aplicativo de origem desta requisição
authKey string sim Chave de identificação da Automação Comercial na Cappta
administrativeCode string sim Identificador único para pagamentos, é devolvido quando a requisição de pagamento é autorizada (pode ser consultado no portal de transações Cappta)

Reimpressão do último comprovante

Ao invés de reimprimir um comprovantes específico, também há a possibilidade de reimprimir o comprovante da última operação aprovada, confira ao lado.

//TODO incluir import dos packages necessários e envolver método em uma classe

private void SendReceiptReprint() {
      String scheme = "exemplo";
      String authKey = "00000000-0000-0000-0000-000000000000";

      Uri capptaAppLink = new Uri.Builder()
          .scheme("cappta")
          .authority("payment")
          .path("last")
          .appendQueryParameter("scheme", scheme)
          .appendQueryParameter("authKey", authKey)
          .build();

      Intent capptaIntent = new Intent(Intent.ACTION_VIEW, capptaAppLink);

      this.startActivityForResult(capptaIntent, 0);
}
Parâmetro Tipo Obrigatório? Descrição
scheme string sim Como descrito na sessão Integração, precisamos saber qual é o aplicativo de origem desta requisição
authKey string sim Chave de identificação da Automação Comercial na Cappta

Trantando respostas do AppLink

Independente da operação realizada, após receber a requisição o Cappta Android irá processar executar o que foi solicitado e ao final da operação terá de devolver os dados para o app da Automação Comercial via AppLink assim como ocorre na requisição.

Para que o seu app esteja apto a receber requisições via AppLink será necessário criar uma Activity que receberá as respostas e configura-la no seu arquivo AndroidManifest.xml. Isso é necessário para que o Android saiba ligar o padrão da URI que o Cappta Android irá enviar ao seu app, a configuração do seu arquivo de manifest deve seguir as orientações do exemplo ao lado.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="<package_do_seu_app>">

  <!-- Este xml é apenas ilustrativo, não copie e cole pois não irá funcionar -->
  <application>

    <!-- Aqui vão todas as Activities do seu app -->

    <!-- Esta será a Activity que recebera as respostas do AppLink do Cappta Android -->
    <activity android:name=".activities.ResultActivity">
      <intent-filter>

        <!-- Necessário para definir que esta Activity será exibida ao receber uma requisição externa -->
        <action android:name="android.intent.action.VIEW" />

        <!-- Necessário para definir que esta Activity pode ser acessada via um link no navegador ou outro app -->
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- AppLink para respostas de pagamento, será interpretado como <seu_app>://payment (não esqueça de substituir o placeholder <seu_app>) -->
        <data
          android:host="payment"
          android:scheme="<seu_app>" />

        <!-- AppLink para respostas de pagamento, será interpretado como <seu_app>://payment-reversal (não esqueça de substituir o placeholder <seu_app>) -->
        <data
          android:host="payment-reversal"
          android:scheme="<seu_app>" />

        <!-- AppLink para respostas de pagamento, será interpretado como <seu_app>://receipt-reprint (não esqueça de substituir o placeholder <seu_app>) -->
        <data
          android:host="receipt-reprint"
          android:scheme="<seu_app>" />
      </intent-filter>
    </activity>
  </application>
</manifest>

Ao ser ativada, sua Activity poderá acessar os dados da respostas como demonstrado no exemplo ao lado.

public class ResultActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    this.setContentView(R.layout.activity_result);

    // Recupera o AppLink recebido
    Uri appLinkUri = Uri.parse(this.getIntent().getDataString()) ;

    String responseCode = appLinkUri.getQueryParameter("responseCode");

    // Verifica se a operação foi realizada com sucesso
    if (responseCode.equals("0")) {

      // Recupera os comprovantes e o número de controle (mais a frente iremos detalhar todos os campos disponíveis na resposta)
      String customerReceipt = appLinkUri.getQueryParameter("customerReceipt");
      String merchantReceipt = appLinkUri.getQueryParameter("merchantReceipt");
      String administrativeCode = appLinkUri.getQueryParameter("administrativeCode");
    } else {
      // Caso não seja exibe o motivo
      String reason = appLinkUri.getQueryParameter("reason");
      Toast.makeText(this, reason, Toast.LENGTH_LONG).show();
    }
  }
}
Parâmetro Tipo Descrição
acquirerAffiliationKey string Número de afiliação do estabelecimento na rede adquirente. Obs.: Também conhecido como “Número Lógico” ou “Código do Estabelecimento”
acquirerAuthorizationCode string Código de autorização retornado pela adquirente
authorizationDateTime string Contém a data + hora completa da autorização do pagamento ou cancelamento
acquirerName string Nome da adquirente responsável pela aprovação do pagamento ou cancelamento
acquirerUniqueSequentialNumber string Número sequencial único da adquirente
administrativeCode string Identificador único para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta
cardBrandName string Nome da bandeira do cartão do cliente
customerReceipt string Comprovante de pagamento ou estorno do cliente
installments int Número de parcelas do pagamento, somente caso tenha sido crédito parcelado
installmentModel int Determina o tipo de parcelamento selecionado pelo usuário, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis
merchantReceipt string Comprovante de pagamento ou estorno do estabelecimento
paymentId string Somente devolvido quando recebido durante uma requisição de pagamento
responseCode int Para operações aprovadas sempre será igual a 0
uniqueSequentialNumber string Número sequencial único do canal de pagamento
Parâmetro Tipo Descrição
paymentId string Somente devolvido quando recebido durante uma requisição de pagamento
reason string Motivo pela qual a operação foi negada
responseCode int Código que representa o motivo pela qual a operação foi negada, verifique a tabela Códigos de motivo para operações negadas para consultar os valores possíveis

Códigos de motivo para operações negadas

Código Descrição
1 Não autenticado/Alguma das informações fornecidas para autenticação não é válida
2 Cappta Android está sendo inicializado
3 Formato da requisição recebida pelo Cappta Android é inválido
4 Operação cancelada pelo operador
5 Pagamento não autorizado/pendente/não encontrado
6 Pagamento ou cancelamento negados pela rede adquirente ou falta de conexão com internet
7 Erro interno no Cappta Android
8 Erro na comunicação com o Cappta Android

Tipos de Parcelamento

Código Descrição
1 Parcelamento Administradora - Configuração de parcelamento em que os juros são arcados pelo banco ou administradora, o limite de parcelas e valor mínimo são pré-estabelecidos e a venda não é tratada como parcelada para o lojista sendo assim o valor será depoistado integralmente em sua conta bancária. O cliente irá pagar as prestações com juros que serão revertidos para o banco/administradora do cartão
2 Parcelamento Lojista - É o parcelamento em que a quantidade de parcelas é definida no ato da compra. O limite de quantidade de parcelas e valor mínimo para cada uma pode ser determinado nas configurações do CapptaGpPlus. O lojista irá receber os créditos mensalmente em sua conta e o custo pelo financiamento é definido e arcado pelo próprio estabelecimento