Account Balances

The Account Balance APIs retrieve merchant account balances by currency. You can query a single currency or request an overview across all available currencies.

Setup

Before calling account services, complete Account Service Setup.

Balance Query

The Balance Query API returns balance details for a specified currency.

POST

Request Parameters

Parameter	Type	Length	Required	Signed	Description
requestId	String	/	Yes	No	Unique request ID for idempotency and request tracing.
requestTime	Long	/	Yes	No	Request timestamp in milliseconds. The timestamp must be within 10 minutes of the server time.
currency	String	/	Yes	No	Currency code, for example USD or EUR.

Response

Name	Type	Description
code	String	Response code.
message	String	Response message.
data	Object	Balance details.
└currency	String	Currency code.
└withdrawableBalance	String	Withdrawable balance.
└availableBalance	String	Available balance.
└fundOnHold	String	Funds that are on hold or in transit.
└depositBalance	String	Deposit balance.
└totalBalance	String	Total balance, including available, on-hold, and deposit amounts.
└status	String	Account status.

API Example

Request

{
  "requestId": "REQ-BAL-20260423-0001",
  "requestTime": 1776931200000,
  "currency": "USD"
}

Response

{
  "code": "200",
  "message": "success",
  "data": {
    "currency": "USD",
    "withdrawableBalance": "1000.00",
    "availableBalance": "1500.00",
    "fundOnHold": "300.00",
    "depositBalance": "200.00",
    "totalBalance": "2000.00",
    "status": "ACTIVE"
  }
}

Balance Overview Query

The Balance Overview Query API returns a balance summary for all currencies and can provide a converted total amount by displayCurrency.

POST

Request Parameters

Parameter	Type	Length	Required	Signed	Description
requestId	String	/	Yes	No	Unique request ID for idempotency and request tracing.
requestTime	Long	/	Yes	No	Request timestamp in milliseconds. The timestamp must be within 10 minutes of the server time.
displayCurrency	String	/	No	No	Display currency used for amount conversion. Defaults to USD when omitted.

Response

Name	Type	Description
code	String	Response code.
message	String	Response message.
data	Object	Balance overview.
└totalAmount	String	Total amount converted to the display currency.
└displayCurrency	String	Display currency. Defaults to USD.
└currencyBalances	Array	Balance summary by currency.
└currency	String	Currency code.
└withdrawableBalance	String	Withdrawable balance.
└availableBalance	String	Available balance.
└fundOnHold	String	Funds that are on hold or in transit.
└depositBalance	String	Deposit balance.
└totalBalance	String	Total balance, including available, on-hold, and deposit amounts.
└status	String	Account status.

API Example

Request

{
  "requestId": "REQ-BAL-20260423-0002",
  "requestTime": 1776931200000,
  "displayCurrency": "USD"
}

Response

{
  "code": "200",
  "message": "success",
  "data": {
    "totalAmount": "5000.00",
    "displayCurrency": "USD",
    "currencyBalances": [
      {
        "currency": "USD",
        "withdrawableBalance": "1000.00",
        "availableBalance": "1500.00",
        "fundOnHold": "300.00",
        "depositBalance": "200.00",
        "totalBalance": "2000.00",
        "status": "ACTIVE"
      },
      {
        "currency": "EUR",
        "withdrawableBalance": "2000.00",
        "availableBalance": "2500.00",
        "fundOnHold": "500.00",
        "depositBalance": "0.00",
        "totalBalance": "3000.00",
        "status": "ACTIVE"
      }
    ]
  }
}

Best Practices

1. Generate a unique requestId for each request to support tracing and duplicate prevention.
2. Use a millisecond requestTime, and keep your server clock synchronized.
3. Reconcile balance snapshots with account transaction records regularly.