Retail Auth

Description

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

Request

Sample Bundle

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

Parameters

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

Sample Bundle

  "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

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