Get Account Balance

Endpoint: GET /v2/gc/accounts/query

Description: Query the balance and available balance of a merchant account for a given currency.

Endpoint Selection:

• Use this endpoint to query a single account balance for a specific currency (the currency parameter is required).

• Use the Query Sub-Merchant Balance API when you need to retrieve balances across all currencies and account types for a sub-merchant in a single request — no currency filter required.

Request

Request Params Field Descriptions

Field Name	Type	Required	Description
currency	string	Yes	ISO 4217 currency code of the account to query (e.g. USD, EUR, HKD).
accountType	string	No	Account category. Enum: FUND_ACCOUNT | VCC_ACCOUNT | REFUND_ACCOUNT.
subMerchantId	string	No	Sub-merchant ID. Required when querying the balance of a specific sub-merchant.
accountBusinessType	string	No	Further filters the account by its business type when multiple accounts exist for the same currency.

Response

Response Field Descriptions

Field Name	Type	Description
code	number	Response code.
state	number	State of the response.
data	object	Account balance details.
message	string	Response message.
neoResponseId	string	Unique NeoX response identifier.

data object fields:

Field Name	Type	Description
accountNo	string	Account number associated with the queried currency and account type.
accountType	string	Account category returned (e.g. FUND_ACCOUNT).
currency	string	ISO 4217 currency code of the account.
balance	number	Total account balance, including frozen amounts.
availableBalance	number	Balance available for immediate use.
frozenAmount	number	Amount currently frozen (e.g. pending transactions).
time	date string	Timestamp of the balance snapshot (ISO 8601 format).

Response sample

{
  "code": 1,
  "state": 2,
  "data": {
    "accountNo": "GC-10094326060-USD",
    "accountType": "FUND_ACCOUNT",
    "currency": "USD",
    "balance": 50000.00,
    "availableBalance": 47500.00,
    "frozenAmount": 2500.00,
    "time": "2024-08-15T09:30:00Z"
  },
  "message": "Successful",
  "neoResponseId": "de7750c5-772e-4136-ac78-62c57a106cce"
}

Example cURL

curl -X GET "https://{base_url_openapi}/v2/gc/accounts/balance?currency=USD&accountType=FUND_ACCOUNT" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en"

Notes

• Requires Bearer token in the Authorization header.

• The Accept-Language header can be used to specify the response language (Support: "vi", "en").

• The currency parameter is required; all other query parameters are optional filters.

• Use accountType to differentiate between fund, virtual credit card, and refund account balances when the merchant holds multiple account types in the same currency.

• balance includes frozen funds; use availableBalance for the spendable amount.