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.
Reference of the account to query.
Type of cardholder account used for the transaction.
Unique identification of the partner that is the recipient of the message exchange.
For example, the POS SN
Result of the requested transaction.
Detail of the response. This field will be gradually replaced by respReason in future versions.
Additional information to be logged for further examination.
Custom status field returned in the transaction result.
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.
Balance of a payment account.
Transaction time. timestamp: A particular point in the progression of time in a calendar year expressed in the yyyyMMddHHmmss format.
Currency associated with the transaction.
Three-letter ISO currency code.
Masked card number.
Brand of the card.
For example: Visa, MasterCard, CUP, JCB, DinersClub, AmericaExpress.
Identification of the cashier who carried out the transaction.
Merchant identification.
Merchant name.
Identification of the POI.
For example: Terminal ID.
POI identification of the transaction in an unambiguous way.
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));
}
});using System;
using PayExplorerConnect;
public void HandleBalanceInquiryError(int code, string message)
{
Console.WriteLine($"Error: {code}, Message: {message}");
}
public void HandleBalanceInquiryResult(BalanceInquiryResult result)
{
Console.WriteLine($"Response: {result.Response}");
}
public string StartBalanceInquiry()
{
BalanceInquiryParam param = new BalanceInquiryParam.Builder()
.Build();
string exchangeId = RetailerManager
.ProvideFinancialService()
.NewBalanceInquiryExchange(param)
.StartAsyncExchange(
HandleBalanceInquiryResult,
HandleBalanceInquiryError);
return exchangeId;
}#import <PayExplorerConnect/RetailerManager.h>
#import <PayExplorerConnect/BalanceInquiryParam+Builder.h>
BalanceInquiryParam *params = [BalanceInquiryParam makeWithBuilder:^(BalanceInquiryParamBuilder *builder) {
builder.accountReference(@"123456");
builder.accountType(CardAccountTypeCodeCDBT);
}];
[[RetailerManager sharedManager] balanceInquiry:params block:^(NSString *exchangeId) {
// Save the exchange ID to track this request.
} result:^(id result, NSInteger errcode, NSString *msg) {
if (errcode != 0 && result == nil) {
// Handle request error.
return;
}
BalanceInquiryResult *balanceResult = (BalanceInquiryResult *)result;
// Handle balance inquiry result.
}];