Prerequisites for Executing a TAP Transaction via the SDK

• Purchase the Tap On Phone module only.
• At this stage, the feature supports Android devices only.
• Register the Finpad device with the Israel Payments Association (S.B.A.).
• Android: the device must include NFC.
• Android: location services must be enabled.
• Android: make sure that Developer options are disabled.

Overview of the TAP Payment Process

1. When the application is launched for the first time:
   1. Call the CardCom API to obtain the details and register the endpoint device.
   2. Register the device with the SDK using RegisterDevice.
2. For each payment transaction:
   1. Call the device to perform a credit card payment (NIS 100), using the response received in step 1.a.
   2. Receive the device response and send it to the CardCom API.

Note:

The RegisterDevice response received in step 1 is valid for a limited period. Step 1 must be performed periodically; the registration validity period is returned when the function is called.

Installing the SDK in the Application

1. Make sure that the application has the following permissions:

<uses-permission android:name="android.permission.NFC" />

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-feature android:name="android.hardware.nfc" android:required="false" />

1. Add the SDK to the application.

We will provide the files. Add them under dependencies:

implementation "com.denovo:topliteapp-PROD:3.0.1.2"
implementation files("../libs/CardCom-v1.2.16-Release_Prod.aar")

Step 1.a: Call the CardCom API to Obtain Details and Register the Endpoint Device

Device registration request

Response

Step 1.b: Register the Device with the SDK Using RegisterDevice

Register the device by calling topService.registerDevice. See the example below.

Call parameters:

Parameters received in onRegisterSuccess:

When the session_key expires, register the device again. The registration is valid while session_created_timestamp + session_expire_time is later than the current date.

Parameters received in onRegisterError:

We recommend displaying the error message and error code to the user for troubleshooting.

Example request:

ToPService topService = new ToPService(Activity activity);

topService.registerDevice(tpn, merchantCode, new ToPService.onRegistrationListener() {

    @Override
    public void onProcess(String message) {
        // UPDATE PROGRESS DIALOG message HERE
    }

    @Override
    public void onRegisterSuccess(JSONObject successObject) {
        // DISMISS PROGRESS DIALOG HERE

        // sample success response
        // {
        //   "message": "Registration done successfully",
        //   "session_key": "xxxxxxxxxxxxxxxxxxxxxx",
        //   "auth_token": "xxxxxxxxxxxxxxxxxxxxxx",
        //   "session_created_timestamp": "1672038767",
        //   "session_expire_time": "86400"
        // }
    }

    @Override
    public void onRegisterError(JSONObject errorObject) {
        // DISMISS PROGRESS DIALOG HERE

        // sample error response
        // {"error_code": "403", "error_message": "Invalid TPN"}
    }
});

Step 1.b: Perform the Payment on the Device

Call topService.performTransaction.

Response:

Example payment request:

{
  "type": "REFUND" / "SALE",
  "amount": "1.00",
  "lang": "iw",
  "CustomObject": {
    "CustomerName": "Test Test",
    "CustomerEmail": "test@test.test",
    "PhoneNumber": "9999999999",
    "HolderID": "999999999",
    "AllowFullCardNumberInResponse": true,
    "SapakMutavNumber": "123456",
    "NumberOfPayments": 1,
    "CreditType": 1
  }
}

ToPService topService = new ToPService(Activity activity);

topService.performTransaction(inputObject, sessionKey, new ToPService.OnTransactionListener() {
    @Override
    public void onTransactionResponse(JSONObject successObject) {
        // response_code: '00' means a successful transaction;
        // any other value means that the transaction failed
    }

    @Override
    public void onTransactionError(JSONObject errorObject) {
        // sample error response
        // {"error_code": "21", "message": "Transaction Cancelled"}
    }

    @Override
    public void onRegisterNeeded(JSONObject errorObject) {
        // sample error response
        // {
        //   "error_code": "990",
        //   "message": "Session key is expired, To authenticate, please re-initiate device registration api"
        // }
    }
});

Calling the CardCom Server to Register the Transaction—Step 2.b

Request

Response

Note: If a communication error occurs, send the request again.

If an error is received, the card will not be charged. Display a failed-payment message.

Afterward, register the physical device through the API and register successful transactions according to the following interface:

TapTransactions Interface Overview