> 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/virtual-accounts/api-create-virtual-account.md).

# Create Virtual Account

#### Endpoint: POST /v2/gc/virtual-accounts

#### Description: Apply for a new multi-currency collection (virtual) account for receiving cross-border funds. A virtual bank account opened by NeoPay for users.

{% hint style="info" %}
A virtual account is a receiving account opened by NeoPay for users to collect funds by supported country/region, currency, and business scenario.
{% endhint %}

## Request

#### Request Body Field Descriptions (JSON)

| Field Name                        | Type   | Required               | Description                                                                                                                                                                                                                                                      |
| --------------------------------- | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId                         | string | Yes                    | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency.                                                                                                                                                                                 |
| vaRegCountry                      | string | Yes                    | Country/region of registration for the virtual account in ISO 3166-1 alpha-3 format. See [VA capabilities by country/region](#va-capabilities-by-country-region) below for supported values and constraints.                                                     |
| [applyUse](#applyuse-enumeration) | string | Yes                    | Intended use of the virtual account. See [`applyUse` enumeration](#applyuse-enumeration) and [VA capabilities by country/region](#va-capabilities-by-country-region) for country-specific availability.                                                          |
| currency                          | string | Yes                    | Currency or comma-separated list of currencies in ISO 4217 format (e.g. `"USD"` or `"USD,EUR,HKD"`).                                                                                                                                                             |
| bankCode                          | string | No                     | Preferred bank code for account opening. Leave empty to let the system assign automatically.                                                                                                                                                                     |
| subMerchantId                     | string | No                     | NeoX sub-merchant identifier if this virtual account belongs to a sub-merchant.                                                                                                                                                                                  |
| webhookUrl                        | string | No                     | Merchant-hosted callback URL to receive asynchronous virtual account status notifications (`VA_SUPPLEMENT_REQUIRED` / `VA_CREATION_RESULT` / `VA_MATERIAL_SUPPLEMENT` — see [Webhook](/docs/global/global-collections/integration/virtual-accounts/webhook.md)). |
| remark                            | string | No                     | Free-text remark for the virtual account application.                                                                                                                                                                                                            |
| expiredTime                       | string | No                     | Application expiry time. If not set, the platform default applies.                                                                                                                                                                                               |
| holderId                          | string | No                     | Identifier of the account holder entity.                                                                                                                                                                                                                         |
| materialId                        | string | No                     | Material submission ID referencing a prior material submission. Must be a value returned by the [Supplement Virtual Account Material](/docs/global/global-collections/integration/virtual-accounts/api-supplement-virtual-account-material.md) API.              |
| [payType](#paytype-details)       | string | Conditionally required | Required when `vaRegCountry` is one of `HKG`/`USA`/`LUX`/`DEU`/`DNK`/`GBR` and `applyUse=PLATFORM_INDEPENDENT_WEBSITE`. See [`payType` details](#paytype-details) below.                                                                                         |
| [shopType](#shoptype-details)     | string | Conditionally required | Required when `applyUse` is `PLATFORM` or `PLATFORM_INDEPENDENT_WEBSITE`. Value must match the supported `shopType` list for the selected `vaRegCountry` + `applyUse` combination. See [`shopType` details](#shoptype-details) below.                            |
| applyBankCode                     | string | No                     | Preferred receiving-bank code, relevant only when `vaRegCountry=NGA`. Enum: `Paga` \| `Wema` \| `FCMB` \| `Fidelity Bank`.                                                                                                                                       |
| extraInfo                         | object | No                     | Additional information as key-value pairs. Contents vary by `vaRegCountry` and `applyUse`.                                                                                                                                                                       |

{% hint style="info" %}
The field that carries the async-result callback URL for this endpoint is **`webhookUrl`**.
{% endhint %}

#### `applyUse` enumeration

* Name: Intended use of the virtual account
* Type: `string`
* Required: Yes
* Description: Indicates the business scenario used for virtual account application.

| Value                          | Description                              |
| ------------------------------ | ---------------------------------------- |
| `PLATFORM`                     | Platform business scenario               |
| `PLATFORM_INDEPENDENT_WEBSITE` | Platform independent website scenario    |
| `ADVERTISING`                  | Advertising scenario                     |
| `B2B`                          | Business-to-business collection scenario |
| `SERVICE_LOGISTICS`            | Service logistics scenario               |
| `SERVICE_AVIATION_TRAVEL`      | Service aviation and travel scenario     |
| `SERVICE_SOFTWARE`             | Software service scenario                |

{% hint style="warning" %}
Validate `vaRegCountry`, `currency`, `applyUse`, and `shopType` against the matrix below before submitting requests.
{% endhint %}

<details>

<summary><strong>Important: VA capabilities by country/region</strong></summary>

#### Capability matrix

| vaRegCountry                       | currency                                        | applyUse (applicable enums)                                                                                                          | Notes                                                                                                                                                                               |
| ---------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HKG`                              | `USD,EUR,HKD,CNH,GBP,CAD,AUD,JPY,SGD`           | `PLATFORM`, `PLATFORM_INDEPENDENT_WEBSITE`, `ADVERTISING`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                     | Supports multi-currency cross-border collection and HKD local collection.                                                                                                           |
| `USA`                              | `USD`                                           | `PLATFORM`, `PLATFORM_INDEPENDENT_WEBSITE`, `ADVERTISING`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                            | Supports USD local collection (single currency).                                                                                                                                    |
| `LUX`                              | `EUR,AUD,GBP,DKK,HKD,CNH,SEK,USD`               | `PLATFORM_INDEPENDENT_WEBSITE`, `ADVERTISING`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                                 | Supports multi-currency cross-border collection and EUR local collection.                                                                                                           |
| `DEU`                              | `EUR,AUD,GBP,DKK,HKD,CNH,SEK,USD`               | `PLATFORM_INDEPENDENT_WEBSITE`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                                                | Supports multi-currency cross-border collection and EUR local collection.                                                                                                           |
| `DNK`                              | `EUR,AUD,GBP,DKK,HKD,CNH,SEK,USD`               | Not specified                                                                                                                        | Supports multi-currency cross-border collection and EUR local collection.                                                                                                           |
| `GBR`                              | `GBP`                                           | Not specified                                                                                                                        | Supports local collection (single currency).                                                                                                                                        |
| `NGA`                              | `NGN`                                           | `PLATFORM`, `PLATFORM_INDEPENDENT_WEBSITE`, `ADVERTISING`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`, `SERVICE_SOFTWARE` | Supports NGN capability set as listed.                                                                                                                                              |
| `KEN`                              | `KES`                                           | `ADVERTISING`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`, `SERVICE_SOFTWARE`                                             | Country-specific single-currency capability.                                                                                                                                        |
| `VNM`                              | `VND`                                           | `B2B`                                                                                                                                | Country-specific single-currency capability.                                                                                                                                        |
| `MYS`                              | `MYR`                                           | `B2B`, `SERVICE_AVIATION_TRAVEL`                                                                                                     | Country-specific single-currency capability.                                                                                                                                        |
| `KOR`                              | `KRW`                                           | `ADVERTISING`, `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                                                                 | Country-specific single-currency capability.                                                                                                                                        |
| `IDN`                              | `IDR`                                           | Not specified                                                                                                                        | Country-specific single-currency capability.                                                                                                                                        |
| `PHL`                              | `PHP`                                           | Not specified                                                                                                                        | Country-specific single-currency capability.                                                                                                                                        |
| `ARE`                              | `AED`                                           | Not specified                                                                                                                        | Country-specific single-currency capability.                                                                                                                                        |
| `GHA`                              | `GHS`                                           | Not specified                                                                                                                        | Country-specific single-currency capability.                                                                                                                                        |
| `AUS`                              | `AUD`                                           | `B2B`, `SERVICE_LOGISTICS`, `SERVICE_AVIATION_TRAVEL`                                                                                | Supports AUD local collection (single currency).                                                                                                                                    |
| `MEX`                              | `MXN`                                           | `B2B`, `SERVICE_LOGISTICS`, `ADVERTISING`                                                                                            | Supports MXN local collection (single currency). Single transaction limit: approximately 600,000 USD.                                                                               |
| `HKG` (local single-currency mode) | `HKD`, `USD`, `EUR`, `CNH`, `GBP`, `CAD`, `AUD` | Not specified                                                                                                                        | Confirmed via frontend `HKG_SINGLE_CURRENCIES` constant — explicitly **excludes `JPY` and `SGD`** for single-currency `applyUse` scenarios (those two are HKG multi-currency-only). |

</details>

{% hint style="warning" %}
`CHF`/`NZD` are not part of the confirmed frontend constant (`HKG_SINGLE_CURRENCIES`) for this scenario, and `JPY`/`SGD` are multi-currency-only. If your integration relies on `CHF`/`NZD`/`JPY`/`SGD` for a single-currency HKG virtual account, confirm directly with the NeoX integration team before relying on this table.
{% endhint %}

#### `shopType` details

{% hint style="info" %}
`shopType` is required when `applyUse` is `PLATFORM` or `PLATFORM_INDEPENDENT_WEBSITE`. The value must be selected from the supported list for the specific `vaRegCountry` + `applyUse` combination.
{% endhint %}

<details>

<summary><strong>Supported <code>shopType</code> by country/region and usage scenario</strong></summary>

1. If `vaRegCountry=HKG` and `applyUse=PLATFORM`, supported `shopType` values are: `AppStore`, `GooglePlay`, `FacebookAudienceNetwork`, `GoogleAdMob`, `TopOn`, `Vungle`, `InMobi`, `BIGOAds`, `Unity`, `ironSource`, `Pangle`, `AppLovin`, `TENCENTADNETWORK`.
2. If `vaRegCountry=USA` and `applyUse=PLATFORM`, supported `shopType` values are: `AppStore`, `GooglePlayUSA`, `GoogleAdmobUSA`, `FacebookAudienceNetworkUSA`, `GoogleAdSense`, `Steam`, `Amazon`.
3. If `vaRegCountry` is one of `HKG`, `USA`, `LUX`, `DEU`, `DNK`, `GBR` and `applyUse=PLATFORM_INDEPENDENT_WEBSITE`, supported `shopType` values are: `Shopline`, `Shopyy`, `Shoplaza`, `Shopify`, `IndependentStationOther`.

</details>

#### `payType` details

{% hint style="info" %}
`payType` is required when `vaRegCountry` is one of `HKG`, `USA`, `LUX`, `DEU`, `DNK`, `GBR` and `applyUse` is `PLATFORM_INDEPENDENT_WEBSITE`.
{% endhint %}

<details>

<summary><strong>Supported <code>payType</code> for independent website platform scenarios</strong></summary>

* Type: `string(64)`
* Required condition: Required for independent website platform scenarios where `vaRegCountry` is `HKG`, `USA`, `LUX`, `DEU`, `DNK`, or `GBR` and `applyUse=PLATFORM_INDEPENDENT_WEBSITE`.

| Enum value | Display meaning |
| ---------- | --------------- |
| `Paypal`   | Paypal          |
| `Stripe`   | Stripe          |
| `Checkout` | Checkout        |
| `Square`   | Square          |
| `Nuvei`    | Nuvei           |
| `Ayden`    | Ayden           |
| `Other`    | Other           |

</details>

<details>

<summary><strong><code>shopType</code> enumeration reference</strong></summary>

| Enum value                   | Display meaning                 |
| ---------------------------- | ------------------------------- |
| `AppStore`                   | AppStore                        |
| `GooglePlay`                 | Google Play                     |
| `FacebookAudienceNetwork`    | Facebook Audience Network       |
| `GoogleAdMob`                | Google AdMob                    |
| `TopOn`                      | TopOn                           |
| `Vungle`                     | Vungle                          |
| `InMobi`                     | InMobi                          |
| `BIGOAds`                    | BIGOAds                         |
| `Unity`                      | Unity                           |
| `ironSource`                 | ironSource                      |
| `Pangle`                     | Pangle                          |
| `AppLovin`                   | AppLovin                        |
| `TENCENTADNETWORK`           | TENCENT AD NETWORK              |
| `GooglePlayUSA`              | Google Play (USA)               |
| `GoogleAdmobUSA`             | Google AdMob (USA)              |
| `FacebookAudienceNetworkUSA` | Facebook Audience Network (USA) |
| `GoogleAdSense`              | Google AdSense                  |
| `Steam`                      | Steam                           |
| `Shopline`                   | Shopline                        |
| `Shopyy`                     | Shopyy                          |
| `Shoplaza`                   | Shoplaza                        |
| `Shopify`                    | Shopify                         |
| `IndependentStationOther`    | Other independent site          |
| `Amazon`                     | Amazon                          |

</details>

#### Additional constraints

* For API-initiated virtual account applications, `IDR`, `PHP`, `VND`, and `MYR` virtual accounts only support merchants whose registered addresses are in Mainland China or Hong Kong, China.
* If multiple currencies are provided in `currency`, preserve the platform-defined currency ordering and do not reorder manually.

{% hint style="success" %}
Before submitting a request, confirm `vaRegCountry`, `currency` order, `applyUse`, `shopType`, and `payType` are all valid in the sections above.
{% endhint %}

#### Request sample

This is a real captured request (not a fabricated illustrative example):

```json
{
    "requestId": "1785407163122",
    "vaRegCountry": "HKG",
    "applyUse": "B2B",
    "currency": "USD,EUR,HKD,CNH,GBP,CAD,AUD,JPY,SGD",
    "subMerchantId": "10000002",
    "remark": "docs",
    "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76"
}
```

### Response

#### Response Field Descriptions

| Field Name    | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| code          | number | Response code.                      |
| data          | object | Virtual account application result. |
| message       | string | Response message.                   |
| neoResponseId | string | Unique NeoX response identifier.    |

{% hint style="warning" %}
There is no `state` field in the response envelope. The `data` object on **create** is also intentionally small — it does not return `vaNumber`, bank details, `materialCode`/`materialInfoJson`, etc. at creation time. Those only appear later, via [Get Detail Virtual Account](/docs/global/global-collections/integration/virtual-accounts/get-detail-virtual-account.md) or the webhooks below.
{% endhint %}

#### `data` object fields:

| Field Name | Type   | Description                                                                                                                                                                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id         | string | NeoX identifier for this virtual account application. Use this value in all subsequent API calls (Get Detail, Supplement Material) that reference this application.                                                                                |
| requestId  | string | Echoes the merchant-supplied `requestId`.                                                                                                                                                                                                          |
| status     | string | Application status immediately after creation. Real captured observed value: `INIT`. See [Get Detail Virtual Account](/docs/global/global-collections/integration/virtual-accounts/get-detail-virtual-account.md) for the fuller status lifecycle. |

`materialInfoJson` is not returned by this endpoint — it is only present on Get Detail Virtual Account and in the `VA_SUPPLEMENT_REQUIRED` webhook. See [`materialInfoJson` structure](/docs/global/global-collections/integration/virtual-accounts/webhook.md#materialinfojson-structure) in the Webhook page for its field layout and an example value.

#### Response sample

Real captured response, corresponding to the request above:

```json
{
    "code": 1,
    "data": {
        "id": "ff2f112d687a4dc98ec33788c8e63b60",
        "requestId": "1785407163122",
        "status": "INIT"
    },
    "message": "Successful",
    "neoResponseId": "94440818-4037-4bd1-b46a-3a3ab94faafd"
}
```

To retrieve the assigned bank details, supplementary-material requirements, or final approval status, call [Get Detail Virtual Account](/docs/global/global-collections/integration/virtual-accounts/get-detail-virtual-account.md) with this `id`, or listen for the `VA_SUPPLEMENT_REQUIRED` / `VA_CREATION_RESULT` webhooks (see [Webhook](/docs/global/global-collections/integration/virtual-accounts/webhook.md)).

### Notes

* Requires Bearer token in the Authorization header.
* The Accept-Language header can be used to specify the response language (Support: "vi", "en").
* Use a unique `requestId` for each request to avoid duplicate submissions.
* The request body must be in JSON format.
* When [Get Detail Virtual Account](/docs/global/global-collections/integration/virtual-accounts/get-detail-virtual-account.md) shows a non-empty `materialCode`, the application requires supplementary KYC material. Call [Supplement Virtual Account Material](/docs/global/global-collections/integration/virtual-accounts/api-supplement-virtual-account-material.md) (`POST /v2/gc/virtual-accounts/supplement`) with the details indicated by `materialCode`/`materialInfoJson`.
* This is an asynchronous operation. The final result (account opened with `vaNumber` and bank info) is delivered via the `VA_CREATION_RESULT` webhook (see [Webhook](/docs/global/global-collections/integration/virtual-accounts/webhook.md)) and can also be polled using [Get Detail Virtual Account](/docs/global/global-collections/integration/virtual-accounts/get-detail-virtual-account.md) (`GET /v2/gc/virtual-accounts`).
* The `currency` field accepts a single ISO 4217 code (e.g. `"USD"`) or a comma-separated list (e.g. `"USD,EUR,HKD"`) on the **request**. On the **response** (Get Detail), `currency` comes back as an array, not a comma-joined string.