Android Deep Linking Integration
Version History
Version | Date | Author(s) | Reviewer(s) | Approver(s) | Remarks |
1.7.0 | 21.01.2023 | Sridhar | Pradeep Kumar Arige | Venkataramana | Initial version |
1.7.4.1 | 16.06.2023 | Gunasekaran | Pradeep Kumar Arige | Venkataramana | Initial version |
1.7.4.7 | 22.12.2023 | Gunasekaran | Pradeep Kumar Arige | Venkataramana | Initial version |
Introduction
iPOS Systems mission is to provide the payment industry with a unique, agnostic offering of secured terminal products. Our cloud systems, cloud-based back office applications, inventory control apps and custom payment software are innovative and unique in the industry. iPOS Systems value-added features set new standards for vendors, contributing down the value chain of resellers, merchants and their patrons.
Purpose
The purpose of the TOP SDK API document is to provide detailed information of iPOSGo Tap on Phone Solution.
Overview
This section provides an overview of the Tap on Phone implementation guide for Android app developers.
Tap-On-Phone a.k.a Tap-To-Phone is a technology that converts an Android phone to a payment device. This technology is governed by the PCI-CPOC standard. The solution uses the NFC capability of the phone to read contact less cards and process the transaction in EMV mode.
The solution involves libraries that are certified by PCI approved labs. The user interface, screen flow and branding part are also certified and verified by approved labs. The SDK includes all such certified components so that mobile applications that are using this SDK can go to market very quickly. Mobile application developers can have full control of their application until payment is initiated. At that point, the SDK takes over and completes the transaction. Once the transaction is processed the SDK reports back to the calling application using call back functions.
The TOP API provides programmatic access to contactless transaction. In designing the API, our goal was to make it simple, intuitive, and predictable. We do our best to adhere to common open and widely accepted standards, including REST for access, JSON format for the data and Basic Authentication and Authorization. This API assumes a good working knowledge of the payment application UI, concepts and terminology.
Use this guide to complete the technical integrations required to implement Tap on Phone on Android phones.
High-level Integration flow
The following is a high-level overview to enable Tap on Phone on a merchant device, the App uses the iPOSgo SDK to initialize a ToPService and access its features.
- The App creates an instance object of ToPService class and calls the topService.registerDevice() method of the iPOSgo sdk. The request includes registration details such as the TPN, Merchant code and registration listener. The registerDevice() method will sends the registration payload to the iPOSgo backend system to authenticate the device.
- On successful of device registration, sdk will returns onRegisterListener.OnRegisterSuccess() method with json object(message, session key, server key, session created timestamp and session expiry in seconds.) else it will return onRegisterListener.onRegisterError() method with error code and message( Invalid TPN, Invalid Access code, Invalid device etc.,)
- The App stores the successful response in the App SharedPreference or database to validate on transaction time.
- On every new transaction App should check the session data.
- Get the session key and expiry from App database and validate it.
- If device session key is not expired, then call API methods of the iPOSgo sdk.
- If API request and response is successful, sdk will returns respective listener object which contains success or error data.
- The App stores the success or response in the App database or backend system.
Pre-requisites & Configuration
Before you get started with your implementation, read the Tap on Phone integration overview to learn about integration and required configuration.
TOP SDK and API Keys
Please contact the business entity or login to iPOS portal to access TPN, Merchant Code and Auth Token for sandbox environment.
TPN
It’s a 12digit Numeric code which is assigned to each device.
Merchant Code
It’s a 12digit Numeric code which is assigned to each TPN.
Note: TPN and Merchant code is used to access the TOP SDK authentication.
Auth Token
It’s a JWT authentication token which is assigned to each merchant.
Note: TPN and Auth Token is used to access the Void, Refund and Batch Settlement API’s.
To access the TOP SDK or API Keys login to the iPOS Systems portal:
2. To access TOP SDK APIs with the TPN and Merchant Code please refer this document sections device register, perform transaction, tip adjustment, batch settlement and reports API’s.
3. To access Void, Refund and Batch Settlement API’s use TPN and Auth Token please refer the below
4. To implement direct Void, Refund and Batch Settlement APIs please refer the below process:
Go to Menu -> Developer Central IPOS Transact -> API Document
Installation setup
Android Studio IDE:
https://developer.android.com/studio
Supported Devices & Versions:
- Android OS 8.1 and later versions
- NFC compatibility devices
Configuration
Add SDK libraries(*.aar) into your existing Android project “libs” folder.
SoftPos-v1.2.6.11-Debug_Test.aar
NOTE: If your project does not already have a “libs” folder, create one in the root of the project by right clicking the project and choosing “New” and then “Folder.
Add below line in gradle.properites in the root folder of your project, to support the legacy in the SDK.
android.enableJetifier = true
Add below lines in build.gradle or setting.gradle of your project
allprojects {
repositories {
jcenter()
flatDir {
dirs 'libs'
}
maven {
url "s3://denovo-android.s3.amazonaws.com"
credentials(AwsCredentials) {
accessKey "AKIA26XMFQBITA36GRDR"
secretKey "JZdZ3BoK7V2ZpFr8iZtZ3g2oGKX/oVgDVqpJRNvy"
}
}
}
}
Add below lines in build.gradle of your project
dependencies {
...
implementation 'com.denovo:topliteapp:1.7.4.7'
implementation files('libs/SoftPos-v1.2.6.11-Debug_Test.aar')
}
Permissions
The Prerequisite permissions which need to be used in manifest file
Add the following line tool:replace inside the <application> tag, which will avoid the manifest merge errors
<application
android:name="YOUR_APPLICATION_CLASS"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
...
tool:replace="android:allowBackup,android:roundIcon,android:theme">
<activity/>
</application>
Refer the image attachment
Proguard-rules.pro
Add below lines in proguard-rules.pro of your project
-keepattributes Signature
-keep class sun.misc.* { *; }
-keepattributes Exceptions, Signature, InnerClasses
-keep class com.google.gson.stream.** { *; }
-keep class com.cardtek.softpos.**{*;}
-keep class vhbgotabuuowoix.**{*;}
-keep class com.denovo.app.top.**{*;
Add Paycore library into the project
Add the paycore library in the integrator app as shown in the below images
Ask Location Run-Time Permission Dialog
Add the Location run-time permission on your application level, like shown below
Device Register API
Fig: Register Device Flowchart diagram
Request Parameters
Parameter name | Description | Sample |
TPN | It’s a Unique 12digit code. This value is unique for each merchant. | 123456789012 |
Merchant Code | A unique code is generated and assigned to each merchant | 210987654321 |
registrationListener | Create an instance object & pass the object or create Anonymous callback to receive response. | OnRegistrationListener registrationListener = new OnRegistrationListener (); or new OnRegistrationListener ({ //@override methods }); |
Response Parameters:
Parameter name | Description | Sample Value |
message | Status message is shown when session key generated successfully. | Registration done successfully |
session_key | Session Key is used to access the sub sequent of iPOSgo sdk API’s. So, this key must be maintained across the application. | ff8c2759-ba8e-4abe-a4a7-9f6d116194e9 |
auth_token | Auth Token is used to interact with iPOSgo backend system to do the void, batch settlement, etc., | API access Token |
session_created_timestamp | Session Key created timestamp in milliseconds is used to validate the session key expiry | 1672038767 |
session_expiry_in_ millseconds | This will indicate that the session key expiry time in milliseconds. Default expiry is 24hrs. | 86400000 |
Snippet code:
ToPService topService = new ToPService(Activity activity);
//show progress dialog here
topService.registerDevice(tpn, merchantCode, new ToPService .onRegistrationListener(
override
public void onRegisterSuccess (JSONObject successObject) {
//dismiss progress dialog here
// sample success response
{
“message”: “Registration done successfully”,
Perform Transaction API
This api is used to accept a contactless EMV transactions. Calling this API will trigger the SDK to enable NFC for a contactless communication between the payment card and device. On successful card read, SDK will send and process transaction.
Fig: Perform Transaction Flow diagram
To perform the transaction API app needs to pass a JSON object(contains amount, type), Session key, custom object(HashMap), transaction listener as input parameters. we will get the response on asynchronous transaction listener methods.
Request parameters
Parameter Name | Description | Sample Value |
inputObject | Pass the raw JSON data | { “type”: “SALE”, Or { “type”: “REFUND”, Or { “type”: “VOID” } |
sessionKey | Pass the Session key which received on successful registration. | ff8c2759-ba8e-4abe-a4a7-9f6d116194e9 |
onTransactionListener | Create an instance object & pass the object or create Anonymous callback to receive response. | new onTransactionListener(); or new onTransactionListener({ }); |
Response Parameters
Method Name | Description | Sample Value |
onTransactionSuccess | On successful transaction, it returns response as JSON data which have all the transaction details. | { “status”: “Approved”, “last_4_digits”: “1234”, “transaction_title”: “SALE”, “transaction_type”: “1”, “transaction_mode”: “1”, “transaction_id”: “000001”, “invoice_no”: “000002”, “amount_paid”: “20.00”, “card_type”: “MASTERCARD”, “mask_pan”: “**************5678”, “date”: “2022-07-06”, “time”: “13:05:22”, } |
onTransactionError | If transaction get any error, it returns the response as JSON data which have the appropriate error message. | { “status”: “declined”, “message”: “Card limit exceeds” } |
Snippet Code
ToPService topService = new ToPService(Activity activity);
topService.performTransaction(inputObject, sessionKey, new ToPService.OnTransactionListener{
@Override
public void onTransactionSuccess (JSONObject successObject){
// sample success response
{
“status”: “Approved”,
“last_4_digits”: “1234”,
“transaction_title”: “SALE”,
“transaction_type”: “1”,
“transaction_mode”: “1”,
“transaction_id”: “000001”,
“invoice_no”: “000002”,
“amount_paid”: “20.00”,
“card_type”: “MASTERCARD”,
“mask_pan”: “**************5678”,
“date”: “2022-07-06”,
“time”: “13:05:22”,
}
}
@override
public void onTransactionError (JSONObject errorObject) {
// sample error response
{
“status”: “declined”,
“message”: “Card limit exceeds”
}
}
@override
Public void onRegisterNeeded(JSONObject errorObject){
//sample error response
{
“error_code”:”960”,
“message”:”Session key is expired,To authenticate,please re-intiate device registration api”
}
}
});
Batch Settlement API
A batch is a group of transactions that have been processed but have yet to be settled. When a transaction is approved, it is added to the batch. When a batch hasn’t been settled yet, it is called an open batch, and transactions in the batch can still be voided and reversed if needed.
Request parameters
Parameter Name | Description | Sample Value |
sessionKey | Pass the Session key which received on successful registration. | ff8c2759-ba8e-4abe-a4a7-9f6d116194e9 |
onBatchListener | Create an instance object & pass the object or create Anonymous callback to receive response. | new onBatchListener (); or new onBatchListener ({ }); |
Response Parameters
Method Name | Description | Sample Value |
onBatchSuccess | Status message is shown when batch settlement done successfully. | |
onBatchError | Status message is shown when batch settlement getting error. |
Snippet Code
ToPService topService = new ToPService(Activity activity);
topService.batchSettlement (sessionKey, new ToPService. onBatchListener {
@Override
public void onBatchSuccess(String success){
// sample success response
}
@override
public void onBatchError(String errorObject) {
// sample error response
}
@override
Public void onRegisterNeeded(JSONObject errorObject){
//sample error response
{
“error_code”:”960”,
“message”:”Session key is expired,To authenticate,please re-intiate device registration api”
}
}
});
Tip Adjustment API
This method is used to add tip amount for the existing transactions and, we can get the summary of adjust tipped transactions.
Request parameters
Parameter Name | Description | Sample Value |
sessionKey | Pass the Session key which received on successful registration. | ff8c2759-ba8e-4abe-a4a7-9f6d116194e9 |
onTipListener | Create an instance object & pass the object or create Anonymous callback to receive response. | new onTipListener (); or new onTipListener ({ }); |
Response Parameters
Method Name | Description | Sample Value |
onTipSuccess | Status message is shown when tip adjustment done successfully. | |
onTipError | Status message is shown when tip adjustment getting error. |
Snippet Code
ToPService topService = new ToPService(Activity activity);
topService.tipAdjustment (sessionKey, new ToPService.onTipListener {
@Override
public void onTipSuccess(String success){
// sample success response
}
@override
public void onTipError(String errorObject) {
// sample error response
}
});
Reports API
The Transaction Detail Report gives a breakdown of transactions entered on a specified reporting period and includes information of the transactions.
Fig: Report flow diagram
Request parameters
Parameter Name | Description | Sample Value |
sessionKey | Pass the Session key which received on successful registration. | ff8c2759-ba8e-4abe-a4a7-9f6d116194e9 |
onReportListener | Create an instance object & pass the object or create Anonymous callback to receive response. | new onReportListener (); or new onReportListener ({ }); |
Response Parameters
Method Name | Description | Sample Value |
onReportSuccess | Status message is shown, once reports get displayed successfully. | |
onReportError | Status message is shown when reports not displayed. |
Snippet Code
ToPService topService = new ToPService(Activity activity);
topService.showReport (sessionKey, new ToPService.onReportListener {
@Override
public void onReportSuccess(String success){
// sample success response
}
@override
public void onReportError(String error) {
// sample error response
}
});
Go Live Requirements
Following are the Go Live Activities:
- Replace Production environment sdk versions in application build gradle.
Help
Email us directly at [email protected] with any questions or suggestions.
