Query Account Balance

Retrieve the current balance for each currency held in the merchant's account. Supports filtering by currency and balance type, including normal balances, same-name top-up balances, budget balances, and overflow balances.
Request Parameters
currenciesarray
Filter by currency. Each element is a 3-letter ISO 4217 currency code (e.g., USD, EUR). If omitted, all currencies are returned. See Data Types.
balanceTypesarray
Filter by balance type. If omitted, defaults to NORMAL_BALANCE. See BalanceType on the Balance overview page.
budgetAccountIdstring
Budget account ID. Required when balanceTypes contains BUDGET_BALANCE.
Response Parameters
resultResult
API call result. See Result.
balancesarray
List of balance items, one per currency and balance type combination. Maximum 500 elements.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parameters existCheck that each element in `currencies` is a valid ISO 4217 code and provide `budgetAccountId` when `balanceTypes` contains `BUDGET_BALANCE`.
ACCOUNT_NOT_EXISTFAccount does not existThe merchant account (or the sub-merchant specified by the `account-id` header) does not exist. Verify the account identifier.
USER_NOT_EXISTFUser does not existThe user associated with the request does not exist. Verify your authentication credentials and the `account-id` header.
CONTRACT_CHECK_FAILFThe contract check has failedThe merchant contract does not cover balance query. Contact support to verify the contract scope.
AUTHORIZATION_NOT_EXISTFThe authorization does not existNo valid authorization found for the target account. Complete the authorization flow first.
UNKNOWN_EXCEPTIONUUnknown exception occurredThe result is unknown. Retry with the same parameters, or query again later.
Definition
POST /api/open/v1/balances/query
Request
{
"currencies": [
  "USD"
],
"balanceTypes": [
  "SAME_NAME_TOP_UP_BALANCE",
  "BUDGET_BALANCE"
],
"budgetAccountId": "BUDGET_20240001"
}
Response
{
"result": {
  "resultStatus": "S",
  "resultCode": "SUCCESS",
  "resultMessage": "success"
},
"balances": [
  {
    "currency": "USD",
    "availableAmount": {
      "value": 100000,
      "currency": "USD"
    },
    "frozenAmount": {
      "value": 30000,
      "currency": "USD"
    },
    "balanceType": "SAME_NAME_TOP_UP_BALANCE"
  },
  {
    "currency": "USD",
    "availableAmount": {
      "value": 50000,
      "currency": "USD"
    },
    "frozenAmount": {
      "value": 0,
      "currency": "USD"
    },
    "balanceType": "BUDGET_BALANCE"
  }
]
}