Skip to content
/ mobile-integracao-uri Public
forked from PGPagamentos/mobile-integracao-uri

Exemplo de integração por uri da automação com o Paygo Integrado.

1 star 3 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

css-organizar/mobile-integracao-uri

BranchesTags
 
 

Repository files navigation

Especificação de Integração Direta

Versão 1.00 (05 mar 2021)

HISTÓRICO

Versão Data Autor Descrição
0.90 02 dez 2020 Marcel Luz Primeira versão, ainda incompleta, para avaliação do mecanismo.
1.00 05 mar 2021 Vanessa A Gangi Finalizada primeira versão.

ÍNDICE

1. Sobre este documento

2. Arquitetura

3. Especificação - Integração Direta

1. Sobre este documento

1.1. Escopo

O objetivo deste documento é especificar a integração direta de aplicativos de Automação Comercial, com o aplicativo PayGo Integrado para a plataforma Android.

1.2. Público

Este documento destina-se essencialmente a desenvolvedores de aplicativos de Automação Comercial, que por alguma restrição técnica (como linguagem de programação utilizada, ambiente ou até mesmo regra de negócio) não podem utilizar a integração via SDK (Interface Automação).

2. Arquitetura

A figura abaixo ilustra a arquitetura do aplicativo PayGo Integrado:

architecture

Na arquitetura ilustrada, a integração entre as aplicações da Automação Comercial e do PayGo Integrado é totalmente abstraída pela biblioteca Interface Automação. Essa biblioteca está escrita em linguagem Java, e é compilada em formato aar (Android Archive), que é um padrão da plataforma Android, pois permite a compilação de código e recursos da plataforma (arquivos de layout, manifestos, etc.). O objetivo principal dessa biblioteca é abstrair a comunicação entre aplicações, que é feita via Intents, deixando a integração com a Automação mais simplificada para desenvolvedores que tenham grande familiaridade com a linguagem Java (ou Kotlin).

Devido ao fato de existirem diversos frameworks para a plataforma Android que permitem o uso de linguagens não nativas para a plataforma Android (Java, Kotlin ou C/C++), a integração via biblioteca aar fica inviabilizada, devido a incompatibilidade desses frameworks com o padrão. De tal maneira que para estes casos, a integração só é possível de ser efetuada de forma direta, ou seja, utilizando o recurso de Intents.

3. Especificação - Integração Direta

3.1. Conceitos básicos

Existem três tipos de operação que podem ser efetuados através do PayGo Integrado:

  • Transação (seja ela financeira ou não);
  • Confirmação;
  • Resolução de pendência.

As operações de Transação podem ser acionadas através do seguinte Intent Action:

br.com.setis.payment.TRANSACTION

Já as operações de Confirmação/Resolução de pendência devem ser acionadas através do seguinte Intent Action:

br.com.setis.confirmation.TRANSACTION

A resposta da transação efetuada é retornada pela seguinte Intent Action (a ser tratada pela aplicação através de seu Manifest):

br.com.setis.interfaceautomacao.SERVICO

Todos os parâmetros transacionais e de confirmação trocados entre Automação Comercial e o aplicativo PayGo Integrado seguem o formato URI (Universal Resources Identifier).

3.2. Formato da URI

A URI segue o padrão RFC2396. A formatação das URIs trocadas entre a Automação Comercial e o aplicativo PayGo Integrado seguem o seguinte padrão:

<scheme>://<authority>/<path>?<query>

Sendo os componentes identificados a seguir:

Componente Formato
<scheme> Fixo: "app"
<authority> Tipo de operação a ser efetuado, podendo ser:
  • "payment", para operações do tipo Transação;
  • "confirmation", para operações do tipo Confirmação;
  • "resolve", para operações do tipo Resolução de pendência.
<path> Indica a origem da operação:
  • "input": Indica que a operação está sendo requisitada pela Automação Comercial;
  • "output": Indica que é uma resposta de operação requisitada pela automação.
<query> Contém os parâmetros da requisição/resposta, no formato "<chave>=<valor>". Os parâmetros são separados pelo caractere '&'.

3.3. Parâmetros das Operações

Para os parâmetros de operação, sejam eles de requisição ou de resposta, serão adotados os seguintes padrões de identificação:

  • Quanto à presença:

  • M → Indica que o parâmetro é mandatório;

  • MC → Indica que o parâmetro é mandatório condicional. As condições para seu uso estarão descritas juntas à especificação do parâmetro.

  • O → Indica que o parâmetro é opcional.

  • Quanto ao formato:

  • N → Indica que o parâmetro é numérico;

  • AN → Indica que o parâmetro é alfanumérico (são aceitos apenas caracteres na faixa ASCII, sem caracteres especiais);

  • C → Indica que o parâmetro é uma constante. Seus possíveis valores estarão documentados junto ao campo;

  • B → Indica que o parâmetro é booleano (assume valor "true" se verdadeiro e "false" se falso).

3.3.1. Transação – Requisição

A tabela a seguir indica os parâmetros de requisição para uma transação:

Parâmetro Presença Formato Descrição
operation M C Operação a ser realizada. Valores possíveis:
  • VENDA (operação de venda);
  • ADMINISTRATIVA (operação administrativa);
  • CANCELAMENTO (operação de cancelamento);
  • INSTALACAO (operação de instalação);
  • REIMPRESSAO (operação de reimpressão do último comprovante);
  • RELATORIO_SINTETICO (obtém relatório sintético);
  • RELATORIO_DETALHADO (obtém relatório detalhado);
  • RELATORIO_RESUMIDO (obtém relatório resumido);
  • TESTE_COMUNICACAO (realiza teste de comunicação);
  • EXIBE_PDC (exibe o número do ponto de captura);
  • VERSAO (exibe a versão instalada);
  • CONFIGURACAO (operação de configuração);
  • MANUTENCAO (operação de manutenção).
transactionId M AN Identificador gerado na automação comercial para a transação.
amount MC N Valor da operação. Mandatório se a operação for do tipo VENDA ou CANCELAMENTO.
currencyCode MC N Código da moeda, de acordo com ISO4217. Mandatório se operação possuir o parâmetro "amount".
boardingTax O N Taxa de embarque.
serviceTax O N Taxa de serviço.
provider O AN Nome do provedor utilizado na transação.
cardType O C Tipo de cartão. Valores possíveis:
  • CARTAO_DESCONHECIDO;
  • CARTAO_CREDITO;
  • CARTAO_DEBITO;
  • CARTAO_VOUCHER;
  • CARTAO_PRIVATELABEL;
  • CARTAO_FROTA.
finType O C Tipo de financiamento. Valores possíveis:
  • FINANCIAMENTO_NAO_DEFINIDO;
  • A_VISTA;
  • PARCELADO_EMISSOR;
  • PARCELADO_ESTABELECIMENTO;
  • PRE_DATADO;
  • CREDITO_EMISSOR.
paymentMode O C Modalidade de pagamento. Valores possíveis:
  • PAGAMENTO_CARTAO;
  • PAGAMENTO_DINHEIRO;
  • PAGAMENTO_CHEQUE;
  • PAGAMENTO_CARTEIRA_VIRTUAL.
installments O N Número de parcelas.
predatedDate O AN Data do pré-datado.
fiscalDocument O AN Número do documento fiscal.
taxId O AN CPNJ/CPF do estabelecimento.
billNumber O AN Número da fatura.
phoneNumber O AN Número de telefone, com DDD.
posId O AN Identificador do ponto de captura.
originalAuthorizationCode O AN Código de autorização original.
originalTransactionNsu O AN NSU da transação original.
originalTransactionDateTime O AN Data/hora da transação original.
additionalPosData1 O AN Dados adicionais relevantes para a automação (#1).
additionalPosData2 O AN Dados adicionais relevantes para a automação (#2).
additionalPosData3 O AN Dados adicionais relevantes para a automação (#3).
additionalPosData4 O AN Dados adicionais relevantes para a automação (#4).

3.3.2. Transação – Resposta

A tabela a seguir indica os parâmetros de resposta para uma transação:

Parâmetro Presença Formato Descrição
operation M C Operação realizada. Valores possíveis:
  • VENDA (operação de venda);
  • ADMINISTRATIVA (operação administrativa);
  • CANCELAMENTO (operação de cancelamento);
  • INSTALACAO (operação de instalação);
  • REIMPRESSAO (operação de reimpressão do último comprovante);
  • RELATORIO_SINTETICO (obtém relatório sintético);
  • RELATORIO_DETALHADO (obtém relatório detalhado);
  • RELATORIO_RESUMIDO (obtém relatório resumido);
  • TESTE_COMUNICACAO (realiza teste de comunicação);
  • EXIBE_PDC (exibe o número do ponto de captura);
  • VERSAO (exibe a versão instalada);
  • CONFIGURACAO (operação de configuração);
  • MANUTENÇÃO (operação de manutenção).
transactionResult M N Resultado da transação efetuada.
amount MC N Valor autorizado, para o caso de uma operação de VENDA.
currencyCode MC N Código da moeda, de acordo com ISO4217. Mandatório se operação possuir o parâmetro "amount".
requiresConfirmation M B Indica se a transaçao requer ou não confirmação.
confirmationTransactionId MC AN Identificador de confirmação para a transação, caso a confirmação seja requerida.
cashbackAmount O N Valor do troco.
discountAmount O N Valor do desconto.
balanceVoucher O N Saldo do cartão voucher.
dueAmount O N Valor devido.
fiscalDocument O AN Número do documento fiscal.
transactionNsu O AN NSU do host.
terminalNsu O AN NSU local.
authorizationCode O AN Código de autorização.
transactionId O AN Identificador da transação para a automação.
merchantId O AN Identificador do estabelecimento.
posId O AN Identificador do ponto de captura.
merchantName O AN Nome do estabelecimento em que o ponto de captura está cadastrado.
transactionDateTime O AN Data/hora da transação original.
installments O N Número de parcelas.
predatedDate O AN Data do pré-datado.
finType O C Tipo de financiamento. Valores possíveis:
  • FINANCIAMENTO_NAO_DEFINIDO;
  • A_VISTA;
  • PARCELADO_EMISSOR;
  • PARCELADO_ESTABELECIMENTO;
  • PRE_DATADO;
  • CREDITO_EMISSOR.
providerName O AN Nome do provedor.
cardType O C Tipo de cartão. Valores possíveis:
  • CARTAO_DESCONHECIDO;
  • CARTAO_CREDITO;
  • CARTAO_DEBITO;
  • CARTAO_VOUCHER;
  • CARTAO_PRIVATELABEL;
  • CARTAO_FROTA.
cardEntryMode O AN Modo de entrada do cartão.
maskedPan O AN Número do cartão, truncado ou mascarado.
defaultMaskedPan O AN Número do cartão mascarado no formato BIN + *** + 4 últimos dígitos. Ex: 543211******9876.
cardholderVerificationMode O AN Modo de verificação de senha.
cardName O AN Nome do cartão ou do emissor do cartão.
defaultCardName O AN Descrição do produto bandeira padrão relacionado ao BIN.
cardholderName O AN Nome do portador do cartão utilizado.
aid O AN Aplicação do cartão utilizada durante a transação.
resultMessage O AN Mensagem com descrição do resultado.
authorizerResponse O AN Código de resposta da transação, proveniente da rede adquirente.
printReceipts O C Vias disponíveis para impressão. Valores possíveis:
  • VIA_NENHUMA;
  • VIA_CLIENTE;
  • VIA_ESTABELECIMENTO;
  • VIA_CLIENTE_E_ESTABELECIMENTO.
fullReceipt O AN Comprovente completo.
merchantReceipt O AN Comprovante diferenciado lojista.
cardholderReceipt O AN Comprovante diferenciado para o portador.
shortReceipt O AN Comprovante reduzido para o portador do cartão.
graphicReceiptExists O B Indica existência dos comprovantes no formato gráfico.
merchantGraphicReceipt O AN Comprovante gráfico, via do lojista.
cardholderGraphicReceipt O AN Comprovante gráfico, via do portador.
originalTransactionAmount O N Valor da transação original.
originalTransactionDateTime O AN Data/hora da transação original.
originalTransactionNsu O AN NSU original do host.
originalAuthorizationCode O AN Código de autorização original.
originalTerminalNsu O AN NSU local gerado na transação original.
pendingTransactionExists O B Indica a existência de transação pendente.
authorizationMode O C Modalidade da transação. Valores possíveis:
  • ON;
  • OFF.
paymentMode O C Modalidade de pagamento. Valores possíveis:
  • PAGAMENTO_CARTAO;
  • PAGAMENTO_DINHEIRO;
  • PAGAMENTO_CHEQUE;
  • PAGAMENTO_CARTEIRA_VIRTUAL.
walletUserId O C Identificação do portador de carteira virtual. Valores possíveis:
  • QRCODE;
  • CPF;
  • OUTROS.
uniqueId O AN Identificador único da transação armazenado no banco de dados.

3.3.3. Confirmação – Requisição

A tabela a seguir indica os parâmetros de resposta para uma confirmação:

Parâmetro Presença Formato Descrição
transactionStatus M C Status final da transação. Valores possíveis:
  • CONFIRMADO_AUTOMATICO (transação confirmada sem intervenção do usuário);
  • CONFIRMADO_MANUAL (transação confirmada a pedido do operador);
  • DESFEITO_MANUAL (transação desfeita a pedido do operador).
confirmationTransactionId M AN Identificador de confirmação para a transação (recebido na resposta da transação).

3.3.4. Resolução de Pendência – Requisição

A tabela a seguir indica os parâmetros de resposta para resolução de transação pendente:

Parâmetro Presença Formato Descrição
providerName M AN Provedor com o qual a transação está pendente.
merchantId M AN Identificador do estabelecimento com o qual a transação está pendente.
localNsu M AN Obtém o NSU local da transação pendente.
transactionNsu M AN Obtém o NSU do servidor TEF da transação pendente.
hostNsu M AN Obtém o NSU do provedor da transação pendente.

3.3.5. Dados Automação

Em todas operações do tipo "Transação", a Automação deve obrigatoriamente também informar seus dados como parâmetro.

Esses dados também são enviados como uma URI, porém em um Bundle separado, identificado com a chave "posData". Os seguintes parâmetros devem ser informados:

Parâmetro Presença Formato Descrição
posName M AN Nome da Automação.
posVersion M AN Versão da Automação.
posDeveloper M AN Nome da empresa desenvolvedora da Automação Comercial.
allowCashback M B Indica se a Automação suporta a funcionalidade de troco.
allowDiscount M B Indica se a Automação suporta a funcionalidade de desconto.
allowDifferentReceipts M B Indica se a Automação suporta a impressão de vias diferenciadas para o portador e o lojista.
allowShortReceipt M B Indica se a Automação suporta a impressão da via reduzida.
allowDueAmount O B Indica se a Automação suporta a utilização do saldo total do voucher para abatimento do valor da compra. Se não informado, assume como "falso".

3.3.6. Personalização

Visando fornecer uma experiência visual menos impactante para o usuário, a Automação Comercial pode customizar elementos de interface do cliente PayGo Integrado, de maneira que este tenha uma identidade visual o mais próximo possível da identidade visual da Automação.

Esses dados também são enviados como uma URI, porém em um Bundle separado, identificado com a chave "posCustomization". Os seguintes parâmetros devem ser informados:

Parâmetro Presença Formato Descrição
screenBackgroundColor O AN Cor de fundo de tela.
keyboardBackgroundColor O AN Cor de fundo do teclado.
toolbarBackgroundColor O AN Cor de fundo da barra de ferramentas.
fontColor O AN Cor da fonte dos textos.
editboxBackgroundColor O AN Cor de fundo da caixa de edição de texto.
releasedKeyColor O AN Cor das teclas do teclado virtual da aplicação, quando estiverem liberadas.
pressedKeyColor O AN Cor das teclas do teclado virtual da aplicação, quando estiverem pressionadas.
keyboardFontColor O AN Cor da fonte do teclado.
menuSeparatorColor O AN Cor do separador entre o título de um menu e as opções.
toolbarIcon O AN Ícone usado na barra de ferramentas.
font O AN Fonte utilizada no texto.

3.3.7. Exemplos

Venda

O exemplo a seguir mostra uma URI para uma requisição de venda, no valor de R$1,00:

app://payment/input?currencyCode=986&transactionId=1&amount=100&operation=VENDA

Dados Automação

O exemplo a seguir mostra uma URI de dados automação:

app://payment/posData?posDeveloper=PAYGO&posName=Automação&allowDueAmount=true&allowDiscount=true&allowCashback=true&allowShortReceipt=false&allowDifferentReceipts=true&posVersion=1.0.0

Personalização

Para personalizar a aplicação, as cores devem ser enviadas com o valor em hexadecimal, porém para as cores serem reconhecidas na URI, é necessário substituir o # por %23. O exemplo a seguir mostra uma URI de personalização:

app://payment/posCustomization?fontColor=%23000000&keyboardFontColor=%23000000&editboxBackgroundColor=%23FFFFFF&keyboardBackgroundColor=%23F4F4F4&screenBackgroundColor=%23F4F4F4&toolbarBackgroundColor=%232F67F4&menuSeparatorColor=%232F67F4&releasedKeyColor=%23dedede&pressedKeyColor=%23e1e1e1&editboxTextColor=%23000000

O tamanho do logo (toolbarIcon) enviado precisa ser menor que 100kb podendo ser nos formatos .pgn, .jpg e .bmp.

Para enviar a fonte utilizada no texto (font) e/ou o logo (toolbarIcon) através da URI, é necessário fazer a conversão deles para bytes e, em seguida, condificá-los usando o Base64. O exemplo abaixo, em linguagem Java, ilustra uma maneira de fazer essa conversão:

try {
    File file = (File)f.get("/sdcard/CaviarDreams.ttf");
    if (file == null) {
        return;
    }

    FileInputStream fis = new FileInputStream(file);
    ByteArrayOutputStream bos = new ByteArrayOutputStream();
    byte[] buf = new byte[1024];

    int readNum;
    while((readNum = fis.read(buf)) != -1) {
        bos.write(buf, 0, readNum);
    }

    byte[] bytes = bos.toByteArray();
    String value = Base64.encodeToString(bytes, 0);
} catch (Exception ex) {
    ex.printStackTrace();
}

Confirmação

O exemplo a seguir mostra uma URI para uma requisição de confirmação:

app://confirmation/confirmation?confirmationTransactionId=0000000000.0000.000000.0000.REDE-SUB&transactionStatus=CONFIRMADO_AUTOMATICO

Resolução de Pendência

O exemplo a seguir mostra uma URI para uma requisição de resolução de pendência:

app://resolve/pendingTransaction?merchantId=0000&providerName=REDECARD&hostNsu=000000&localNsu=0000&transactionNsu=0000000000

3.4. Fluxo Operacional

3.4.1. Transação

Devido ao fato de a operação de transação requerer interface com o usuário (para captura dos dados), a Intent deve ser entregue para uma Activity, que fará o processamento da interface.

Requisição

A requisição deve ser feita através do método startActivity. A Intent de parâmetro deve conter os seguintes parâmetros:

  • IntentAction e URI dos parâmetros transacionais;
  • Bundle Extra dos Dados Automação;
  • Bundle Extra da Personalização (se desejado pela Automação Comercial).
  • Bundle Extra do nome do pacote da aplicação, sob a chave "package", necessário para que o aplicativo PayGo Integrado consiga efetuar a devolutiva da resposta da transação.
  • Para iniciar corretamente a Activity, e não causar problemas de memory leak, a Intent deve conter as seguintes flags:
  • FLAG_ACTIVITY_NEW_TASK;
  • FLAG_ACTIVITY-CLEAR_TASK.

O exemplo abaixo, em linguagem Java, ilustra uma maneira de iniciar uma transação:

Intent transacao = new Intent("br.com.setis.payment.TRANSACTION", uri);
transacao.putExtra("DadosAutomacao", dadosAutomacao);
transação.putExtra("Personalizacao", personalizacao);
transacao.putExtra("package", getPackageName());
transacao.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
startActivity(transacao);

Resposta

Para receber a resposta da transação, a aplicação deve implementar um componente para o recebimento da Intent de resposta.

O exemplo abaixo ilustra a configuração necessária no Manifesto para o componente:

<intent-filter android:label="filter_app_payment">
    <action android:name="br.com.setis.interfaceautomacao.SERVICO"/>
     <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="app" android:host="payment" />
    <data android:scheme="app" android:host="resolve" />
</intent-filter>

3.4.2. Confirmação

Sempre que indicado pela resposta da transação, a Automação Comercial deve efetuar o processo de confirmação da transação. Este processo roda em segundo plano, dentro de um Broadcast Receiver do aplicativo PayGo Integrado, e não possui resposta. Para tal, a requisição deve ser efetuada com o método sendBroadcast.

A configuração da Intent de confirmação deve possuir os seguintes parâmetros:

  • IntentAction;
  • Bundle extra com a URI dos parâmetros transacionais;
  • Como a aplicação pode estar encerrada durante a execução da confirmação, deve ser incluída a seguinte flag:
  • FLAG_INCLUDE_STOPPED_PACKAGES

O exemplo abaixo, em linguagem Java, ilustra uma maneira de efetuar uma confirmação:

Intent transacao = new Intent();
transacao.setAction("br.com.setis.confirmation.TRANSACTION");
transacao.putExtra("uri", uri);
transacao.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
sendBroadcast(transacao);

3.4.3. Resolução de Pendência

Sempre que indicado na resposta da transação a existência de uma transação pendente, a Automação deve efetuar o processo para confirmar essa transação. Este processo roda em segundo plano, dentro de um Broadcast Receiver do aplicativo PayGo Integrado, e não possui resposta. Para tal, a requisição deve ser efetuada com o método sendBroadcast.

A configuração da Intent de resolução de pendência deve possuir os seguintes parâmetros:

  • IntentAction;
  • Bundle extra com a URI dos parâmetros da pendência;
  • Bundle extra com a URI dos parâmetros de confirmação;
  • Como a aplicação pode estar encerrada durante a execução desta transação, deve ser incluída a seguinte flag:
  • Intent.FLAG_INCLUDE_STOPPED_PACKAGES

O exemplo abaixo, em linguagem Java, ilustra uma maneira de efetuar uma resolução de pendência:

Intent transacao = new Intent();
transacao.setAction("br.com.setis.confirmation.TRANSACTION");
transacao.putExtra("uri", uriPendencia);
transacao.putExtra("Confirmacao", "app://resolve/confirmation?transactionStatus=CONFIRMADO_AUTOMATICO");
transacao.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
sendBroadcast(transacao);

About

Exemplo de integração por uri da automação com o Paygo Integrado.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Java 100.0%