Embedded SDK Integration

Version History

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:

1. Go to Menu -> Settings -> Generate Ecom/TOP Merchant Keys -> Select TPN -> Generate

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 (opens in a new tab)

• 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.3.66.7-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 of your project

 
dependencies{
  implementation'com.denovo:topliteapp:1.7.5.0'
  implementationfiles('libs/SoftPos-v1.3.66.7-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

This API is used on every new install of App, cache clear, data clear of your application, check whether session data are available or not. If not, then call the register device API. To do create an instance of Top Service class and call the register device() method to invoke device registration process. Please do flow the below flowchart diagram.

Request Parameters

Response Parameters

Snippet Code

 
ToPServicetopService=newToPService(Activityactivity);//showprogressdialogheretopService.registerDevice(tpn,
merchantCode,
newToPService.onRegistrationListener(overridepublicvoidonRegisterSuccess(JSONObjectsuccessObject){
  //dismissprogressdialoghere//samplesuccessresponse{
    “message”: “Registrationdonesuccessfully”,
    “session_key”: “xxxxxxxxxxxxxxxxxxxxxx”,
    “auth_token”: “xxxxxxxxxxxxxxxxxxxxxx”,
    “session_created_timestamp”: ”1672038767”“session_expire_time”: “86400”
  }
}publicvoidonRegisterError(JSONObjecterrorObject){
  //dismissprogressdialoghere//sampleerrorresponse{
    “error_code”: “403”,
    “error_message”: “InvalidTPN”
  }
}@overridePublicvoidonProcess(Stringmessage){
  //updateprogressdialogmessagehere
}
});
 

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.

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

Response Parameters

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

Response Parameters

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

Response Parameters

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.

Request Parameters

Response Parameters

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 devsupport@denovosystem.com with any questions or suggestions.