Balance Enquiry
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.
Note:Every balance enquiry request needs to include Authentication
Balance Enquiry Request
POST
The following API call types are available for a balance enquiry, ensure to make use of the correct endpoint.
| API CALL TYPES | ENDPOINT |
|---|---|
| Asynchronous | /v/1/payment/async |
| Synchronous | /v/1/payment/sync |
Example: Balance Enquiry
BODY
The following is an example of a BALANCE_ENQUIRY request body
{
"launchType": "BALANCE_ENQUIRY",
"merchantID": "merchantID",
"posId": "posId",
"serialNumber": "serialNumber"
}String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";
JSONObject requestBody = new JSONObject();
requestBody.put("launchType", "BALANCE_ENQUIRY");
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);
// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "payment/sync")
.headers(headers)
.body(requestBody.toString());
HttpResponse<JsonNode> response = request.asJson();# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
--url "$API_URL/payment/sync" \
--header "X-pos-id: POS-STORE123-TERM01" \
--header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
--header "X-tu-random: $RANDOM_VAL" \
--header "X-tu-serial: $SERIAL_NUMBER" \
--header "X-tu-date: $TU_DATE" \
--header "User-Agent: $USER_AGENT" \
--header "Content-Type: application/json" \
--data "{
\"launchType\": \"BALANCE_ENQUIRY\",
\"merchantID\": \"$MERCHANT_ID\",
\"posId\": \"POS-STORE123-TERM01\",
\"serialNumber\": \"$SERIAL_NUMBER\",
}" \
)Request Body Fields
The following table describes the REQUIRED request body fields of the BALANCE_ENQUIRY request message.
| FIELD | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| REQUIRED | |||
| launchType | STRING | Must be “BALANCE_ENQUIRY”. Used for launching POSBuddy Cloud to process a balance enquiry. | 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. | 910100000000001 |
| posId | STRING | The POS ID is a unique identifier for the originating Point of Sale terminal. In multi-terminal environments, each device requires a distinct alphanumeric identifier (e.g., POS1, POS2, CHECKOUT_A). | POS-STORE123-TERM01 |
| serialNumber | STRING | The serial number of the target payment terminal for this payment request. | PC05P2CG10036 |
Balance Enquiry Response
Result Codes
| RESULTCODE | DESCRIPTION |
|---|---|
| 01 | Successful transaction |
| 02 | Declined transaction |
| 03 | Aborted transaction |
| 04 | Error occurred with the transaction |
API Call Types
Note:Please take note of the tables below around the API Call Type that is being used and the response type that can be expected per API Call Type.
| API CALL TYPES | RESPONSE TYPE | DESCRIPTION |
|---|---|---|
| Asynchronous | Webhook | If the POS is making use of the Asynchronous REST API call, the POS will receive a JSON BODY response for a balance enquiry request, however the JSON BODY response will just be a confirmation that POSBuddy cloud received the request. Once the balance enquiry is finalised on the terminal, a webhook callback is sent to the POS to confirm the transaction outcome. The webhook ismandatory when making use of Asynchronous REST API calls. Please refer to the Webhook section to set up webhooks. |
| Synchronous | JSON BODY | If the POS is making use of the Synchronous REST API call, the POS will receive a JSON BODY response for a balance enquiry request. The POS has the option to also receive a webhook response for the balance enquiry request, however this is optional. |
Example: Balance Enquiry
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
BODY
The following is an example of a BALANCE_ENQUIRY response body the POS Application will receive.
{
"resultDescription": "APPROVED",
"buildInfo": "Ecentric",
"isReceiptDataAvailable": true,
"resultCode": "01",
"receiptBundle": { Please see receipt bundle section
},
"merchantID": "770000000000123",
"serialNumber": "PF5544544664",
"posId": "POS-STORE123-TERM01",
"launchType": "BALANCE_ENQUIRY",
"transactionUuid": "bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc",
"appVersion": "1.9.2",
"transactionAmount": 0
}Response Body Fields
The following table describes the response body fields of the BALANCE_ENQUIRY response message.
| FIELDS | TYPE | DESCRIPTION | EXAMPLE |
|---|---|---|---|
| launchType | STRING | Echo of the launchType used in the POSBuddy Cloud request. | BALANCE_ENQUIRY |
| buildInfo | STRING | Metadata that identifies the specific software build running on the payment device. | com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT] |
| 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 |
| transactionAmount | LONG | Approved total transactionAmount. | 1000 |
| 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 Receipt Bundle Section |
| appVersion | STRING | The software version currently running on the Ecentric Payment App. | 1.9.2 |
| transactionUuid | STRING | Echo of the Unique ID of a transaction. | bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc |
| serialNumber | STRING | The serial number for the device that was used for the RETAIL_AUTH intent call. | PC05P2CG10036 |
| posId | STRING | Echo of the posId present in the request. | POS-STORE123-TERM01 |
Example: Errors
The following table contains typical errors that might occur and how to handle these errors:
| ERROR MESSAGE | SOLUTION |
|---|---|
| Incorrect merchantID/ not present | Ensure that you have entered the correct merchantID. |
| posId is not present | Ensure that you include the posId in your request. |
| serialNumber not present | Ensure that you include the serialNumber in you request. |
| Terminal <serial_number> is offline | Ensure the requested terminal is turned on and has established a valid connection to POSBuddy Cloud. |
| launchType not present | Ensure you provide the launchType “BALANCE_ENQUIRY” |
BODY
The following is an example of a BALANCE_ENQUIRY ERROR response body that the POS Application will receive.
{
"resultDescription": "ERROR",
"errorBundle": {
"description": "ERROR",
"reference": "",
"errorType": "TRANSACTION",
"message": "Error communicating with server"
},
"buildInfo": "Ecentric_DEBUG_Ecentric_INT",
"isReceiptDataAvailable": "false",
"resultCode": "04",
"merchantID": "910100000000001",
"serialNumber": "PC05P2CG10036",
"posId": "POS-STORE123-TERM01",
"launchType": "BALANCE_ENQUIRY",
"appVersion": "1.9.8"
}Updated about 1 month ago
