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 TYPESENDPOINT
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.

FIELDTYPEDESCRIPTIONEXAMPLE
REQUIRED
launchTypeSTRINGMust be “BALANCE_ENQUIRY”.
Used for launching POSBuddy Cloud to process a balance enquiry.
BALANCE_ENQUIRY
merchantIDSTRINGThe 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
posIdSTRINGThe 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
serialNumberSTRINGThe serial number of the target payment terminal for this payment request.PC05P2CG10036

Balance Enquiry Response

Result Codes

RESULTCODEDESCRIPTION
01Successful transaction
02Declined transaction
03Aborted transaction
04Error 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 TYPESRESPONSE TYPEDESCRIPTION
AsynchronousWebhook

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.

SynchronousJSON 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.

Receipt Bundle Section

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

FIELDSTYPEDESCRIPTIONEXAMPLE
launchTypeSTRINGEcho of the launchType used in the POSBuddy Cloud request.BALANCE_ENQUIRY
buildInfoSTRINGMetadata that identifies the specific software build running on the payment device.com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_UAT]
resultCodeSTRINGRepresents the result status of the intent call to the Ecentric Payment App
● 01: SUCCESSFUL
● 02: DECLINED
● 03: ABORTED
● 04: ERROR
01
resultDescriptionSTRINGA 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
merchantIDSTRINGEcho of the merchantID used in the request.910100000000001
transactionAmountLONGApproved total transactionAmount.1000
isReceiptDataAvailableSTRINGBoolean indicating whether a receiptBundle object is available. Will always be included for approved or declined transactions.true
receiptBundleSTRINGConsists of a sub-bundle of server parameters that can be used by the partner application to create a receipt.See Receipt Bundle Section
appVersionSTRINGThe software version currently running on the Ecentric Payment App.1.9.2
transactionUuidSTRINGEcho of the Unique ID of a transaction.bdf9d0af-17b3-48ca-8a0b-37dc52bf49bc
serialNumberSTRINGThe serial number for the device that was used for the RETAIL_AUTH intent call.PC05P2CG10036
posIdSTRINGEcho 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 MESSAGESOLUTION
Incorrect merchantID/ not presentEnsure that you have entered the correct merchantID.
posId is not presentEnsure that you include the posId in your request.
serialNumber not presentEnsure that you include the serialNumber in you request.
Terminal <serial_number> is offlineEnsure the requested terminal is turned on and has established a valid connection to POSBuddy Cloud.
launchType not presentEnsure 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"
}

Did this page help you?