Integration Overview

Communication between the customer application (MPOS) and the Ecentric payment application is done using explicit Android intents.

Intent Parameters

The Android intent needs to set the following parameters:

PARAMETER	VALUE
packageName	com.ecentric.ecentricpay
className	com.ecentric.ecentricpay.MainActivity

All data is passed as extended data inside the ecentricBundle and returned data as ecentricApplicationResponse

Below is a simplified Java implementation to create the intent request:

    Intent intent = new Intent();
    intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
  	dataBundle.putString("merchantID", "YourMerchantID");
    intent.putExtra("ecentricBundle", dataBundle);

Returned resultCode

To determine if a request was a success or not, the returned resultCode inside the ecentricApplicationResponse bundle needs to be inspected. Here is a summary of the possible values:

Result Code	Meaning	Retail Auth	Sale	QR Code Payment	Deposit	Refund	Card Query	Balance Enquiry	Transaction Search
00	Completed	X					X
01	Successful		X	X	X	X		X	X
02	Declined		X	X	X	X		X	X
03	Aborted		X	X	X	X	X	X
04	Error	X	X	X	X	X	X	X	X

Error Bundle

If there was an error in the execution of the intent, an error bundle will be included in the response with extra information.

PARAMETER	DESCRIPTION	EXAMPLE
errorType	Type of error, e.g. AUTHENTICATION / TRANSACTION / OTHER. If value is "AUTHENTICATION" the application needs to get a new auth token using the Retail Auth call.	AUTHENTICATION
message	A friendly message that can be used for debugging or displayed to user	Merchant number 0003456 not found

"errorBundle": [
    "errorType": "AUTHENTICATION"
    "message": "Merchant number 123456 not found.\nServer reference: 1234-1053-6265"
  ]

Sample Code

A complete Android example to send and process an sale request.

// Function to start the intent
private void doSale() {
    Intent intent = new Intent();
   	intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "SALE");
  	dataBundle.putString("merchantID", "910100000000001")
    dataBundle.putString("authenticationKey", "received_authenticationKey");
    dataBundle.putLong("transactionAmount", 1000); // amount in cents
  
    intent.putExtra("ecentricBundle", dataBundle);
    try {
        intentLauncher.launch(intent);
    } catch (Exception e) {
        Log.e(TAG, "Error launching intent: " + e);
    }
}

// Process the received response bundle
private final ActivityResultLauncher<Intent> intentLauncher = registerForActivityResult(
       new ActivityResultContracts.StartActivityForResult(),
       result -> {
           if (result.getResultCode() == Activity.RESULT_OK) {
               Intent data = result.getData();
               if (data != null) {
                   Bundle responseBundle = new Bundle(data.getBundleExtra("ecentricApplicationResponse"));
                   String resultCode = responseBundle.getString("resultCode");
                 		// Determine if the transaction was successfully executed using returned resultCode
                   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   if (responseBundle.get("errorBundle") != null) {
                       Bundle errorBundle = new Bundle(responseBundle.getBundle("errorBundle"));
                   }
               }
           } else {
               Log.e(TAG, "Received error resultCode: " + result.getResultCode());
           }
       }
);