What is Retail Auth Validation?

A Retail Auth request is performed to obtain the authentication token that is needed by the merchant to perform transactions.

Before any card transactions can be processed, the user of the Ecentric Payment App must be authenticated and provide an auth token for each payment request.

This process of authentication is referred to as Retail Auth.

To authenticate the user and obtain an auth code, the MPOS App must request an auth code from the Ecentric Payment App via an Android Intent interface, and store the auth code response in a session for subsequent card processing requests on the Ecentric Payment App.

How Does Retail Auth Validation Work?

The diagram below shows an example of how the Retail Auth and Companion APP (Hereafter known as the MPOS App), works together with Payment App (Hereafter known as the Ecentric's Payment App), and Transaction Processor (Here after known as Ecentric's Server).

Retail Auth validation flow — Retail Auth Validation Flow

Process Description:

Step 1:
The MPOS App must initiate a RETAIL_AUTH request, which is sent to the Ecentric Payment App.

Step 2:
The Ecentric Payment App will receive, and send the RETAIL_AUTH request to the Ecentric Server.

Step 3:
The Ecentric Server will perform an Authentication step.

Step 4:
If the Authentication step is successful, the server will generate the Authentication token.

Step 5:
The Authentication token is sent back to the Ecentric Payment App.

Step 6:
The Ecentric Payment App passes the Authentication token to the MPOS App.

Step 7:
The MPOS App will store the Authentication token, and use this token for all future transactions.

Retail Auth Tutorial Video

Request

Sample Bundle

The following is an example of a RETAIL_AUTH request bundle that the MPOS Application will request.

"launchType": "RETAIL_AUTH"
"merchantID": "981230000000123"
"accessKey": "W8PMBBQZHKF566DN8UB7"
"secretKey": "rGrAvFub4b56rtMRdpN/XuH+PESlvrb8c6LTHd"

Parameters

The following table describes the parameters of the RETAIL_AUTH validation request message:

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “RETAIL_AUTH”. Used for launching the Ecentric Payment App to obtain an auth token.	RETAIL_AUTH
merchantID	STRING	The merchant ID assigned to the merchant. The merchant ID will always be the same ID for a specific merchant. To be provided by Ecentric.	776543200000123
secretKey	STRING	To be treated as sensitive information. To be provided by Ecentric.	t689vFub4b45MRdpN/XuH+PESlvrb8c6LTHd
accessKey	STRING	To be treated as sensitive information. To be provided by Ecentric.	86BBQZTR34KTPMD75NL87

Sample Code

The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Payment App to initiate a RETAIL_AUTH request message.

*See Sample Code RETAIL_AUTH Response for the intentLauncher function

private void doRetailAuth() {
    Intent intent = new Intent();
    intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
    Bundle dataBundle = new Bundle();
    dataBundle.putString("launchType", "RETAIL_AUTH");
  	dataBundle.putString("merchantID", "YourMerchantID");
    dataBundle.putString("secretKey", "merchantSecretKey");
    dataBundle.putString("accessKey", "merchantAccessKey");

    intent.putExtra("ecentricBundle", dataBundle);
    try {
        intentLauncher.launch(intent);
    } catch (Exception e) {
        Log.e(TAG, "Error launching intent: " + e);
   }
}

Response

Sample Bundle

The following is an example of a RETAIL_AUTH response bundle that the MPOS Application will receive.

  "launchType": "RETAIL_AUTH"
  "resultCode": "00"
  "resultDescription": "COMPLETED"
  "authenticationKey": "bea282b3-d2aa-4b47-be92-05e0853cc502"
  "buildInfo": "Ecentric"
  "terminalId": "77012398"
  "merchantID": "770000000000123"
  "merchantUsername": ""
  "serialNumber": "PC05P2CG10036"
  "merchantName": "Istore"
  "appVersion": "2.0.0"

Parameters

The following table describes the parameters of the RETAIL_AUTH validation response message:

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	RETAIL_AUTH
resultCode	STRING	Represents the result status of the retail auth intent call: ● 00: COMPLETED ● 04: ERROR	00
merchantID	STRING	The merchant ID assigned to the merchant.	770000000000123
authenticationKey	STRING	The authentication token that was generated by the server on a successful RETAILAUTH request to the Ecentric Payment App. _The authenticationKey needs to be stored for subsequent card processing requests on the Ecentric Payment App.	bea282b3-d2aa-4b47-be92-05e0853cc502
terminalID	STRING	A terminal identifier for device that was used for the RETAIL_AUTH intent call.	77012398
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036
resultDescription	STRING	A description of the authentication response, e.g ● COMPLETED ● APPROVED ● DECLINED ● ABORT ● ERROR	COMPLETED
merchantName	STRING	The name of the merchant that requested the transaction as stored at the bank.	Merchant A
appVersion	STRING	The software version currently running on the Ecentric Payment App.	1.9.2

Sample Code

The following code needs to be implemented by the MPOS Application to recover the RETAIL_AUTH outcome and resume the MPOS App flow accordingly.

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 launchType = responseBundle.getString("launchType");
                   String resultCode = responseBundle.getString("resultCode");
                   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   if (success && launchType.matches("RETAIL_AUTH")) {
                       authenticationKey = responseBundle.getString("authenticationKey");
                   }

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

📘
Note
It is strongly recommended to only request an auth token once and not before every transaction.
The only reason to request a new token is if a transaction fails with "errorType": "AUTHENTICATION" in the error bundle.

Error Handling

The following table contains typical errors that might occur and how to handle these errors:

ERROR MESSAGE	SOLUTION
Incorrect merchantID	Ensure that you have entered the correct merchantID.
Device is linked to another store	The device needs to be delinked from the current store on the retail portal and linked to the correct store on the retail portal.
accessKey is invalid	Ensure that you have entered the correct accessKey
secretKey is invalid	Ensure that you have entered the correct secretKey

Sample Bundle

The following is an example of a RETAIL_AUTH ERROR response bundle that the MPOS Application will receive.

"resultDescription": "ERROR",
"errorBundle": {
    "description": "ERROR",
    "reference": "",
    "errorType": "AUTHENTICATION",
    "message": "Invalid Secret Key or access Key supplied.\nServer reference: 0605-1153-w6vw"
  },
 "buildInfo": "Ecentric_DEBUG_Ecentric_UAT",
 "resultCode": "04",
 "merchantID": "910100000000001",
 "serialNumber": "PC05P2CG10036",
 "launchType": "RETAIL_AUTH",
 "appVersion": "1.9.7"

What is Retail Auth Validation?

How Does Retail Auth Validation Work?

The diagram below shows an example of how the Retail Auth and Companion APP (Hereafter known as the MPOS App), works together with Payment App (Hereafter known as the Ecentric's Payment App), and Transaction Processor (Here after known as Ecentric's Server).

Retail Auth Tutorial Video

Request

Sample Bundle

Parameters

Sample Code

Response

Sample Bundle

Parameters

Sample Code

📘Note

Error Handling

Sample Bundle

📘
Note