# Balance Inquiry (/global/en/docs/Terminal/FinancialServices/Balance-Inquiry)

## Balance Inquiry

This interface is used to query the available balance of a cardholder account or payment account.\
It is typically applied to prepaid cards, stored-value cards, bank cards, or some e-wallets.\
Main functions include:\
1.Check Account Balance: Retrieve the current available balance or overdraft limit.\
2.Pre-Transaction Check: Before initiating a payment or pre-authorization, check the balance to ensure sufficient funds.\
3.Support Risk Control: Can be used to control transaction amounts, restrict payment types, or check account status.\
Key notes:\
1.The query only returns balance-related information and does not affect fund flow.\
2.Returned fields may vary depending on the issuer or channel; please parse the response according to the actual data.\
3.Some channels or account types may not support balance inquiry; confirm support before calling the interface.

#### Balance Inquiry Request

**BalanceInquiryParam**

**accountReference** *string*

Reference of the account to query.

**accountType** *enum*

Type of cardholder account used for the transaction.

**Possible enum values**

- `CRDT` — "Credit card account."
- `CDBT` — "Debit card account."
- `EBTCS` (U.S. Only) — "Electronic Benefit Transfer (EBT) Cash Sale."
- `EBTCW` (U.S. Only) — "Electronic Benefit Transfer (EBT) Cash Withdrawal"
- `EBTF` (U.S. Only) — "Electronic Benefit Transfer (EBT) Food Stamp."
- `EBTC` (U.S. Only) — "Electronic Benefit Transfer (EBT) Cash Card"

#### Balance Inquiry Response

**BalanceInquiryResult**

**recipientPartyIdentification** *string* — Required

Unique identification of the partner that is the recipient of the message exchange.\
For example, the POS SN

**response** *enum* — Required

Result of the requested transaction.

**Possible enum values**

- `SUCC` — "Success.\nProcessing OK. Information related to the result of the processing is contained in other parts of the response message."
- `FAIL` — "Failure.\nProcessing of the request fails for various reasons."
- `PART` — "Partial Approved.\nThe service was partially completed. Use the Message Status service to query the final transaction status."

**responseReason** *string*

Detail of the response. This field will be gradually replaced by respReason in future versions.

**Possible enum values**

- `ABRT` — "Aborted.\nThe initiator of the request has sent an abort message request, which was accepted and processed."
- `BUSY` — "Busy.\nThe system is busy, try later."
- `CANC` — "Cancel.\nThe user has aborted the transaction on the PED keyboard, for instance during PIN entering."
- `DEVO` — "DeviceOut.\nDevice out of order."
- `WPIN` — "WrongPIN.\nThe user has entered the PIN on the PED keyboard and the verification fails."
- `NHOS` — "UnreachableHost.\nAcquirer or any host is unreachable or has not answered to an online request, so is considered as temporary unavailable.\nDepending on the Sale context, the request could be repeated(to be compared with \\"Refusal\\")"
- `UNVS` — "UnavailableService.\nThe service is not available (not implemented, not configured, protocol version too old…)."
- `UNVD` — "UnavailableDevice.\nThe hardware is not available (absent, not configured…)"
- `REFU` — "Refusal.\nThe transaction is refused by the host or by the local rules associated to the card or the POI."
- `TNFD` — "NotFound.\nThe transaction is not found (e.g. for a reversal or a repeat)."
- `WIPG` — "InProgress.\nThe transaction is still in progress and then the command cannot be processed."

**additionalResponseInformation** *string*

Additional information to be logged for further examination.

**respReason** *string*

Custom status field returned in the transaction result.

**Transaction parameters**

When you receive the terminal result through the SDK callback interface and **BalanceInquiryResult.response = SUCC**, you can obtain additional transaction details (including reference numbers returned by the payment channel) to support your business requirements.

The following fields are defined, and the availability of each field depends on the capabilities provided by the payment application.

**currentBalance** *string* — Required

Balance of a payment account.

**transactionDateTime** *timestamp* — Required

Transaction time.
timestamp: A particular point in the progression of time in a calendar year expressed in the yyyyMMddHHmmss format.

**currency** *enum*

Currency associated with the transaction.\
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html).

**maskedPAN** *string*

Masked card number.

**cardBrand** *string*

Brand of the card.\
For example: Visa, MasterCard, CUP, JCB, DinersClub, AmericaExpress.

**cashierIdentification** *string*

Identification of the cashier who carried out the transaction.

**merchantIdentification** *string*

Merchant identification.

**merchantIdentificationName** *string*

Merchant name.

**poiIdentificationId** *string*

Identification of the POI.\
For example: Terminal ID.

**poiTransactionIdentification** *string*

POI identification of the transaction in an unambiguous way.

```java
BalanceInquiryParam balanceInquiryParam = BalanceInquiryParam.newBuilder()
        .build();
RetailerManager.provideFinancialService()
        .newBalanceInquiryExchange(balanceInquiryParam)
        .startAsyncExchange(new Exchange.RetailerSDKCallback<BalanceInquiryResult>() {
            @Override
            public void onError(int code, String msg) {
                Logger.e(TAG,"failed: " + code + ", " + msg);
            }

            @Override
            public void onResult(BalanceInquiryResult result) {
                Logger.e(TAG,"result: " + GsonUtils.toJson(result));
            }
        });
```