Versão 1.00 (05 mar 2021)
| 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. |
3. Especificação - Integração Direta
O objetivo deste documento é especificar a integração direta de aplicativos de Automação Comercial, com o aplicativo PayGo Integrado para a plataforma Android.
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).
A figura abaixo ilustra a arquitetura do aplicativo PayGo Integrado:
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.
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.TRANSACTIONJá as operações de Confirmação/Resolução de pendência devem ser acionadas através do seguinte Intent Action:
br.com.setis.confirmation.TRANSACTIONA 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.SERVICOTodos 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).
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:
|
<path> |
Indica a origem da operação:
|
<query> |
Contém os parâmetros da requisição/resposta, no formato "<chave>=<valor>". Os parâmetros são separados pelo caractere '&'. |
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).
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:
|
| 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:
|
| finType | O | C | Tipo de financiamento. Valores possíveis:
|
| paymentMode | O | C | Modalidade de pagamento. Valores possíveis:
|
| 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). |
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:
|
| 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:
|
| providerName | O | AN | Nome do provedor. |
| cardType | O | C | Tipo de cartão. Valores possíveis:
|
| 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:
|
| 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:
|
| paymentMode | O | C | Modalidade de pagamento. Valores possíveis:
|
| walletUserId | O | C | Identificação do portador de carteira virtual. Valores possíveis:
|
| uniqueId | O | AN | Identificador único da transação armazenado no banco de dados. |
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:
|
| confirmationTransactionId | M | AN | Identificador de confirmação para a transação (recebido na resposta da transaçã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. |
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". |
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. |
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=VENDAO 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.0Para 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=%23000000O 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();
}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_AUTOMATICOO 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=0000000000Devido 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.
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);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>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);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);