Description
The Balance Enquiry function is used to obtain available funds on the card by means of swiping the card on the payment device.
Request
Sample Bundle
"authenticationKey": "e27b6ce6-78ba6-4y46-9953-5afr28f7cbeb",
"merchantID": "971234500000003",
"launchType": "BALANCE_ENQUIRY"
Parameters
The following table describes the parameters of the BALANCE_ENQUIRY 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
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
Sample Bundle
"resultDescription": "APPROVED",
"buildInfo": "Ecentric_DEBUG_Ecentric_INT",
"isReceiptDataAvailable": true,
"resultCode": "01",
"receiptBundle": {
"MERCHANT_REGION_CODE": "09",
"RC_ALT": "00",
"CASH_AMOUNT_CENTS": "0",
"SEQ_NO": "000",
"STATUS": "APPROVED",
"BUDGET_PERIOD": "0",
"CARD_TYPE": "",
"PAN_WITH_BIN": "478769******5035",
"MERCHANT_ID": "910100000000001",
"TIMESTAMP": "1753966909998",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "0",
"RC_DESCRIPTION": "Approved",
"ED_AC_COLLECTION_AMOUNT": "",
"EXTERNAL_INVOICE_GUID": "",
"CURRENT_BALANCE_CENTS"= "800000",
"REPLACEMENT_MERCHANT_ID": "",
"BATCH_NO": "000",
"AVAILABLE_BALANCE_FORMATTED" = "R 8000.00",
"ED_AC_RESPONSE_DESCRIPTION": "",
"AUTH_PROFILE": "0",
"ED_AC_DEBTOR_ID": "",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "206 31 SH 514402",
"TX_TYPE": "49",
"ACC_TYPE_DESC": "Default",
"ED_AC_DEBTOR_ID_TYPE": "",
"TIP_AMOUNT": "",
"AVAILABLE_BALANCE_CENTS" = "800000",
"CURRENCY_CODE": "0710",
"ED_AC_MAC_DATA": "",
"AUTH_CODE": "514402",
"RC": "00",
"AID": "",
"ATC": "",
"CRY": "",
"CVM": "none",
"PAN": "************5035",
"RRN": "",
"APSN": "",
"DATE": "2025-07-31T13:02:09.017+0000",
"STAN": "",
"NAME_ON_CARD": "GROENEWALD/CG.MR",
"AMOUNT_CENTS": "0",
"ABS_AMOUNT": "0.00",
"TOKEN": "",
"RECEIPT_NUMBER": "",
"EXTENDED_TRX_TYPE": "",
"TERMINAL_ID": "91000328",
"TX_TYPE_DESCRIPTION": "INQUIRY",
"EXTERNAL_TERMINAL_ID": "",
"FORMATTED_AMOUNT": "R 0.00",
"DESCRIPTION": "",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "",
"ED_AC_ACCOUNT_NUMBER": "",
"SURCHARGE_AMOUNT": "0.00",
"CURRENT_BALANCE_FORMATTED" = "R 8000.00",
"ED_AC_CONTRACT_NUMBER": "",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "478769",
"TRANSACTION_INFO": "20631SH514402",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "9001",
"RC_ISO_DESCRIPTION": "Approved or completed successfully",
"MERCHANT_CITY": "CAPE TOWN",
"MERCHANT_NAME": "THUMBZUP INT RETAIL",
"CUSTOMER_NAME": "",
"APP_VERSION": "",
"CARD_SEQ_NO": "0",
"APP_LABEL": "",
"INVOICE_NUM": "",
"ED_AC_RESPONSE_CODE": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"ED_AC_MAX_COLLECTION_AMOUNT": "",
"CARD_TRANSACTION_TYPE": "MAG",
"FORMATTED_CASH_AMOUNT": "R 0.00",
"CASH_AMOUNT": "0.00",
"RESULT_CODE": "00",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "false",
"PAN_HASH": "8fe154743df867956bfd585a16c634e2cd45663a08466eca046e06fd66170533",
"AMOUNT": "0.00",
"TIP_LABEL": "",
"DIGITS": "5035",
"CVM_ABSA": ""
},
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"launchType": "BALANCE_ENQUIRY",
"transactionUuid": "9c638bed-88b1-4a19-ac3c-f143dc2528e8",
"appVersion": "1.9.10",
"transactionAmount": "0",
Parameters
The following table describes the parameters of the BALANCE_ENQUIRY response message.
| PARAMETERS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| launchType | STRING | Echo of the launchType used to launch the Ecentric Payment App. | BALANCE_ENQUIRY |
| resultCode | STRING | Represents the result status of the intent call to the Ecentric Payment App ● 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 |
| merchantID | STRING | Echo of the merchantID used in the request. | 910100000000001 |
| merchantName | STRING | The name of the merchant that requested the transaction as stored at the bank. | Merchant A |
| transactionAmount | STRING | Approved total transactionAmount. | 1000 |
| transactionDescription | STRING | Echo of the transactionDescription used to launch the Ecentric Payment App. | 3rd party app desc |
| isReceiptDataAvailable | STRING | Boolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions. | true |
| receiptBundle | STRING | Consists of a sub-bundle of server parameters that can be used by the partner application to create a receipt. | See Sample ecentricBundle SALE Response. |
| appVersion | STRING | The software version currently running on the Ecentric Payment App. | 1.9.2 |
| externalSTAN | STRING | Echo of the systems trace number generated by some 3rd party ERP systems. | 123456 |
| externalRRN | STRING | Echo of the RRN generated by some 3rd party ERP systems. | ABCDEF123456 |
| externalTransactionGUID | STRING | Echo of the GUID that identifies a specific transaction generated by 3rd party ERP systems. | 2fdca02f-3cbe-4e8c-82ad-86a1a16b72e8 |
| externalInvoiceGUID | STRING | Echo of the GUID that identifies a particular invoice that may appear on more than one transaction. | 2fdca02f-3cbe-4e8c-82ad-86a1a16b72e9 |
| externalTransactionDateTime | STRING | Echo of the date and time the transaction was generated on the 3rd party ERP systems. Has the format of “yyyy-MM-dd'T'HH:mm:ss” | 2017-04-28T09:30:00 |
| externalTerminalId | STRING | Echo of the terminal identifier for device configured on the 3rd party ERP system. | 98100010 |
| transactionUuid | STRING | Echo of the Unique ID of a transaction. | bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc |
| terminalId | STRING | This is an automatically system-assigned terminalID of the payment terminal’s identity number, which can be used to assist with settlement information and is returned in BASE36 format. | 77012398 |
| latitude | STRING | Echo of geolocation identifier indicating the latitude position of the device. | -28.1619942 |
| longitude | STRING | Echo of geolocation identifier indicating the longitude position of the device. | 30.2350981 |
| accuracy | STRING | Echo of accuracy indicator of the geolocation. | |
| serialNumber | STRING | The serial number for the device that was used for the RETAIL_AUTH intent call. | PC05P2CG10036 |
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");
// 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
Sample Bundle
"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"