> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/accounts/query-submerchant-balance.md).

# Query Sub-Merchant Balance

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

#### Description: Query account balances for a sub-merchant across all currencies and account types in a single request.

## Request

#### Request Params Field Descriptions

| Field Name    | Type   | Required | Description                                                                                    |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| subMerchantId | string | Yes      | Sub-merchant identifier (minimum length 1).                                                    |
| accountType   | string | No       | Enum: `FUND_ACCOUNT` \| `VCC_ACCOUNT` \| `REFUND_ACCOUNT`. Omit to retrieve all account types. |
| currency      | string | No       | ISO 4217 currency code. Omit to retrieve all currencies.                                       |

## Example query

```
GET /v2/gc/accounts/balance/query?subMerchantId=10000002&accountType=FUND_ACCOUNT&currency=AUD
```

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                                                                            |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| code          | number | Response code.                                                                         |
| data          | array  | Array of account balance entries (one per matching account type/currency combination). |
| message       | string | Response message.                                                                      |
| neoResponseId | string | Unique NeoX response identifier.                                                       |

#### `data` array item fields:

| Field Name       | Type   | Description                                                         |
| ---------------- | ------ | ------------------------------------------------------------------- |
| subMerchantId    | string | Echoes the queried sub-merchant identifier.                         |
| accountNo        | string | Account number.                                                     |
| accountType      | string | Account type, e.g. `FUND_ACCOUNT`.                                  |
| currency         | string | ISO 4217 currency code.                                             |
| balance          | string | Total account balance (sum of available balance and frozen amount). |
| availableBalance | string | Available balance that can be used for transactions.                |
| frozenAmount     | string | Frozen amount that is temporarily unavailable.                      |

#### Response sample

Real captured example — note the query above filtered on `currency=AUD`, but the response returned the sub-merchant's other funded currencies (CNY, USD) instead; the endpoint does not appear to strictly filter by `currency` in every case, so don't assume the response is limited to the requested currency:

```json
{
    "code": 1,
    "data": [
        {
            "subMerchantId": "10000002",
            "accountNo": "85483204408000002",
            "accountType": "FUND_ACCOUNT",
            "currency": "CNY",
            "balance": "199.90",
            "availableBalance": "199.90",
            "frozenAmount": "0.00"
        },
        {
            "subMerchantId": "10000002",
            "accountNo": "85479876309000001",
            "accountType": "FUND_ACCOUNT",
            "currency": "USD",
            "balance": "1911.90",
            "availableBalance": "1911.90",
            "frozenAmount": "0.00"
        }
    ],
    "message": "Successful",
    "neoResponseId": "47acf9fc-95c0-497d-b5a1-517b46e87b25"
}
```

### Notes

* Requires Bearer token in the Authorization header (not a request signature — see the hint above about the difference from the upstream processor's own API).
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* `subMerchantId` is required; `accountType` and `currency` are optional filters, but as noted above the filtering behavior is not fully confirmed to be strict.
* `balance` equals `availableBalance` + `frozenAmount`.