Query Sub-Merchant Balance

Endpoint: GET /v2/gc/accounts/balance/query

Description: Query account balance for sub-merchants or platform merchants.

This API allows you to retrieve real-time balance information for sub-merchant and platform merchant accounts, including available balance and frozen amounts by currency and account type.

Request

Request Params Field Descriptions

Field Name	Type	Required	Description
subMerchantId	string(15)	Yes	Sub-merchant or platform merchant identifier.
accountType	string(32)	No	Account type filter.
currency	string(16)	No	Currency filter in ISO 4217 format (e.g. USD, EUR).

Optional Filters: Leave both accountType and currency empty to retrieve all balances across all account types and currencies for the specified sub-merchant.

accountType - Account Type Filter

Specifies which account type to query. Supported values:

Account Type	Description
FUND_ACCOUNT	Fund account for general operational balance.
VCC_ACCOUNT	Virtual Credit Card account balance.
REFUND_ACCOUNT	Refund account for processing refunds.

Behavior:

• Omit this field (or pass empty string): Query returns balances for all three account types.

• Specify a value (e.g., FUND_ACCOUNT): Query returns balances only for the specified account type.

Example: "accountType": "FUND_ACCOUNT"

currency - Currency Filter

ISO 4217 currency code to filter the balance query. Supported currencies include:

Currency Code	Currency Name
CNH	Offshore Renminbi (CNH)
USD	US Dollar
HKD	Hong Kong Dollar
EUR	Euro
GBP	British Pound Sterling
AUD	Australian Dollar
CAD	Canadian Dollar
JPY	Japanese Yen
SGD	Singapore Dollar
VND	Vietnamese Dong

Behavior:

• Omit this field (or pass empty string): Query returns balances for all available currencies.

• Specify a value (e.g., USD): Query returns balances only for the specified currency.

Example: "currency": "USD"

Request sample

{
  "subMerchantId": "SM-00098761",
  "accountType": "FUND_ACCOUNT",
  "currency": "USD"
}

Response

Response Field Descriptions

Field Name	Type	Description
code	string	Response code.
msg	string	Response message.
success	boolean	Indicates if the request was successful.
data	array	Array of query result data (one per account type/currency combination).

data object fields:

Field Name	Type	Description
accountNo	string(32)	Account number.
accountType	string(32)	Account type.
currency	string(3)	Currency code. See product documentation for supported currencies.
balance	string(13)	Total account balance (sum of available balance and frozen amount). Example: "200.05"
availableBalance	string(13)	Available balance that can be used for transactions. Example: "100.01"
frozenAmount	string(13)	Frozen amount that is temporarily unavailable. Example: "100.04"
time	string(20)	Balance query timestamp in format yyyy-MM-dd HH:mm:ss.

Response sample

{
  "code": "1",
  "msg": "Successful",
  "success": true,
  "data": [
    {
      "balance": "38.60",
      "accountType": "FUND_ACCOUNT",
      "accountNo": "11001413100166831",
      "currency": "CAD",
      "time": "2026-05-27 15:24:42",
      "availableBalance": "38.60",
      "frozenAmount": "0.00"
    },
    {
      "balance": "59.56",
      "accountType": "FUND_ACCOUNT",
      "accountNo": "11001413100166479",
      "currency": "USD",
      "time": "2026-05-27 15:24:42",
      "availableBalance": "59.56",
      "frozenAmount": "0.00"
    },
    {
      "balance": "152167.00",
      "accountType": "FUND_ACCOUNT",
      "accountNo": "11001413100166777",
      "currency": "VND",
      "time": "2026-05-27 15:24:42",
      "availableBalance": "152167.00",
      "frozenAmount": "0.00"
    }
  ]
}

Example cURL

curl -X POST "https://openapi.gptransfer.hk/yop-center/rest/v1.0/gpt/account/balance/query" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "subMerchantId": "SM-00098761",
    "accountType": "FUND_ACCOUNT",
    "currency": "USD"
  }'

Notes

• Requires signature verification.

• Use a valid subMerchantId for the target sub-merchant or platform merchant account.

• Omit accountType and currency to retrieve all balances across all account types and currencies.

• The balance field equals availableBalance + frozenAmount.

• Response timestamp reflects the exact moment the balance was queried.