Retail Auth

Description

The Retail Auth function is used to obtain an authentication token which is needed for processing transactions.

Request

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

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

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

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());
           }
       }
);

Error Handling

Sample Bundle

"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"