📘
Note:
The balance enquiry function is currently only available for Gift Cards.

What is a Balance Enquiry?

A balance enquiry is a way to check the remaining funds available on a card. Since many cards are preloaded or topped up with a set amount, it's useful to verify the current balance before making a transaction.

How Does a Balance Enquiry Work?

Process Description:

Step 1:

The MPOS will initiate a BALANCE_ENQUIRY request, the BALANCE_ENQUIRY request will be sent to the Ecentric Payment App.

Step 2:

The Ecentric Payment App will process the card details and forward the BALANCE_ENQUIRY request to the Ecentric Server.

Step 3:

The Ecentric Server will validate the card bin.

Note: If the card bin is not whitelisted, the Ecentric Server will return and error to the Ecentric Payment App.

Step 4:

Once the card bin has been validated the Ecentric Server will return the BALANCE_ENQUIRY response to the Ecentric Payment App.

Step 5:

The Ecentric Payment App will then forward the BALANCE_ENQUIRY response to the MPOS App.

Step 6:

The MPOS App will then have access to the card details and balance.

Request

Sample Bundle

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

"authenticationKey": "e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb",
"merchantID": "971234500000003",
"launchType": "BALANCE_ENQUIRY"

Parameters

The following table describes the parameters of the BALANCE_EQUIRY request message.

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “BALANCE_ENQUIRY” Used for launching the Ecentric Payment App to perform a card query.	BALANCE_ENQUIRY
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
authenticationKey	STRING	The authentication token that was generated by the server on a successful auth call to the Ecentric Payment App	e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb

Sample Code

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

*See Sample Code BALANCE_ENQUIRY Response for the intentLauncher function

private void doBalance_Enquiry() {
   Intent intent = new Intent();
   intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
   Bundle dataBundle = new Bundle();
   dataBundle.putString("launchType", "BALANCE_ENQUIRY");
   dataBundle.putString("merchantID", "910100000000001");
   dataBundle.putString("authenticationKey", "received_authenticationKey");
   
   intent.putExtra("ecentricBundle", dataBundle);
   try {
       intentLauncher.launch(intent);
   } catch (Exception e) {
       Log.e(TAG, "Error launching intent: " + e);
   }
}

Response

📘
Note:
The following is only applicable for Gift Cards.
Within the Receipt Bundle Section look for the following fields to assist with the balance enquiry response.

AVAILABLE_BALANCE_CENTS AND AVAILABLE_BALANCE_FORMATTED

CURRENT_BALANCE_CENTS AND CURRENT_BALANCE_FORMATTED

Sample Bundle

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

Receipt Bundle Section

  "adjustAmount": 0,
  "appVersion": "2.2.0",
  "buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_TEST]",
  "cashAmount": 0,
  "isReceiptDataAvailable": true,
  "launchType": "DEPOSIT",
  "merchantID": "910100000000001",
  "outstandingAmount": 0,
  "posId": "",
  "receiptBundle": { Please see receipt bundle section
  },
  "resultCode": "01",
  "resultDescription": "APPROVED",
  "serialNumber": "PC05P2CG10036",
  "transactionAmount": 0,
  "transactionLinkIdentifier": "",
  "transactionUuid": "cd14a381-32a7-4dfd-92f6-d73f7324055d",
  "txType": "BALANCE_ENQUIRY"

Parameters

The following table describes the parameters of the BALANCE_ENQUIRY response message.

PARAMETERS	TYPE	DESCRIPTION	EXAMPLE
adjustAmount	LONG	N/A for Balance Enquiry	0
appVersion	STRING	The software version currently running on the Ecentric Payment App.	2.0.0
buildInfo	STRING	Metadata that identifies the specific software build running on the payment device.	com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]
cashAmount	LONG	N/A for Balance Enquiry	0
isReceiptDataAvailable	STRING	Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.	true
launchType	STRING	Echo of the launchType used to launch the Ecentric Payment App.	BALANCE_ENQUIRY
merchantID	STRING	Echo of the merchantID used in the request.	910100000000001
outstandingAmount	LONG	N/A for Balance Enquiry	0
posId	STRING	N/A for Companion API Integrations
receiptBundle	STRING	Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.	See Receipt Bundle Section
resultCode	STRING	Represents the final outcome of the query. ● 01: SUCCESSFUL ● 02: DECLINED ● 03: ABORTED ● 04: ERROR	01
resultDescription	STRING	A user readable representation of the above resultCode i.e. Approved for resultCode 01. If the bank or switch approves or declines the transaction, the response description is included in this field.	APPROVED
serialNumber	STRING	The serial number for the device that was used for the RETAIL_AUTH intent call.	PC05P2CG10036
transactionAmount	LONG	Approved total transactionAmount.	1000
transactionLinkIdentifier	STRING	N/A for Balance Enquiry
transactionUuid	STRING	Echo of the Unique ID of a transaction.	bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
txType	STRING	Transaction type	DEPOSIT

Sample Code

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

When the response is returned the calling app needs to override the onActivityResult() method and can be done as follows:

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

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.
authenticationKey is invalid	When your authenticationKey is invalid, you will receive an error message indicating that the authenticationKey is invalid, a RETAIL_AUTH request needs to be done to obtain a valid authenticationKey.

Sample Bundle

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

"resultDescription": "ERROR",
"errorBundle": {
    "description": "ERROR",
    "reference": "",
    "errorType": "COMMS",
    "message": "Error communicating with server"
},
"buildInfo": "Ecentric_DEBUG_Ecentric_INT",
"resultCode": "0",
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"launchType": "BALANCE_ENQUIRY",
"appVersion": "1.9.8"