> 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 matrix below for supported values and constraints. |
| applyUse | string | Yes | Intended use of the virtual account. See `applyUse` enumeration and VA capabilities matrix 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. |
| notifyUrl | string | No | Merchant-hosted callback URL to receive asynchronous virtual account status notifications. |
| 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 API. |
| payType | string | No | Accepted payment type(s) for this virtual account. |
| shopType | 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. |
| extraInfo | object | No | Additional information as key-value pairs. Contents vary by `vaRegCountry` and `applyUse`. |
#### `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 %}
Important: VA capabilities by country/region
#### 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`,`JPY`,`AUD`,`SGD`,`CHF`,`NZD` | Not specified | Supports cross-border collection and local collection in listed currencies. |
#### `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 %}
Supported shopType by country/region and usage scenario
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`.
#### `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 %}
Supported payType for independent website platform scenarios
* 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 |
shopType enumeration reference
| 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 |
#### 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
```json
{
"requestId": "d4e5f6a7-8901-4b23-c456-789012345678",
"vaRegCountry": "HKG",
"applyUse": "B2B",
"currency": "USD,EUR,HKD",
"notifyUrl": "https://merchant.example.com/webhooks/virtual-account",
"remark": "B2B collection account for HK operations",
"subMerchantId": "SM-00098761",
"extraInfo": {}
}
```
### Response
#### Response Field Descriptions
| Field Name | Type | Description |
| ------------- | ------ | ----------------------------------- |
| code | number | Response code. |
| state | number | State of the response. |
| data | object | Virtual account application result. |
| message | string | Response message. |
| neoResponseId | string | Unique NeoX response identifier. |
#### `data` object fields:
| Field Name | Type | Description |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| virtualAccountRequestId | string | NeoX identifier for this virtual account application. Use this value in all subsequent API calls that reference this application. |
| status | string | Current application status. Enum: `INIT` (supplementary material required), `PROCESSING` (under review). |
| materialCode | string | Code indicating the type of supplementary material required. Returned only when `status` is `INIT`. |
| materialInfoJson | string | Supplementary material information (JSON string, max 256 chars in the raw field). Required when `materialCode` is not empty; returns the specific fields that must be supplemented. |
| vaNumber | string | Assigned virtual account number. Populated after the account is approved. |
| vaName | string | Assigned virtual account name. Populated after the account is approved. |
| vaArea | string | Geographic area or jurisdiction of the virtual account. Populated after the account is approved. |
| currency | string | Currency or currencies associated with the virtual account. Populated after the account is approved. |
| openBankCode | string | Code of the bank where the virtual account is held. Populated after the account is approved. |
| openBankName | string | Name of the bank where the virtual account is held. Populated after the account is approved. |
| openBankAddress | string | Address of the bank where the virtual account is held. Populated after the account is approved. |
| openBankSwiftCode | string | SWIFT/BIC code of the bank where the virtual account is held. Populated after the account is approved. |
| openBankBranchCode | string | Branch code of the bank where the virtual account is held. Populated after the account is approved. |
| localBankRouteNo | string | Local bank routing number (e.g. ABA for the US, sort code for the UK). Populated after the account is approved. |
#### `materialInfoJson` details
{% hint style="info" %}
`materialInfoJson` is conditionally required in the response payload: when `materialCode` is not empty, `materialInfoJson` must also be non-empty.
{% endhint %}
materialInfoJson structure
* Type: `string(256)` in the response field, containing a JSON array string.
* Purpose: Returns the exact supplemental fields that must be provided via the Supplement Virtual Account Material API.
Each element in the parsed JSON array may include:
| Key | Meaning |
| --------------------------- | ---------------------------------------------------------- |
| `paramName` | Supplementary field name/key. |
| `paramTitle` | Human-readable field meaning/title. |
| `valueRequired` | Whether the field is mandatory. |
| `validatorRuleMap.dataType` | Validation regex/rule for the field value. |
| `validatorRuleMap.length` | Length constraint, usually JSON text with `min` and `max`. |
#### `materialInfoJson` example value
```json
[
{
"paramName": "listed",
"paramTitle": "Is listed company",
"valueRequired": true
},
{
"paramName": "stateOwnedEnterprised",
"paramTitle": "Is state-owned enterprise",
"valueRequired": true
},
{
"paramName": "foreignOwnedEnterprised",
"paramTitle": "Is foreign-owned enterprise",
"valueRequired": true
},
{
"paramName": "enterpriseSubjectTypeFirst",
"paramTitle": "Enterprise subject type level 1",
"valueRequired": true
},
{
"paramName": "enterpriseSubjectTypeSecond",
"paramTitle": "Enterprise subject type level 2",
"valueRequired": true
},
{
"paramName": "regAddressEng",
"paramTitle": "Registered address (English)",
"valueRequired": true,
"validatorRuleMap": {
"dataType": "^[A-Za-z0-9/\\-?:()., '+]+$",
"length": "{\"min\":0,\"max\":200}"
}
},
{
"paramName": "bizAddressEng",
"paramTitle": "Business address (English)",
"valueRequired": true,
"validatorRuleMap": {
"dataType": "^[A-Za-z0-9/\\-?:()., '+]+$",
"length": "{\"min\":0,\"max\":200}"
}
}
]
```
#### Response sample
```json
{
"code": 1,
"state": 2,
"data": {
"virtualAccountRequestId": "VA-20240301-00012345",
"status": "PROCESSING",
"materialCode": "",
"materialInfoJson": "",
"vaNumber": "",
"vaName": "",
"vaArea": "",
"currency": "",
"openBankCode": "",
"openBankName": "",
"openBankAddress": "",
"openBankSwiftCode": "",
"openBankBranchCode": "",
"localBankRouteNo": ""
},
"message": "Successful",
"neoResponseId": "ac23ea1c-98db-4ed6-b927-7e7692ef2f69"
}
```
## Example cURL
```bash
curl -X POST "https://{base_url_openapi}/v2/gc/virtual-accounts" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "Accept-Language: en" \
-d '{
"requestId": "d4e5f6a7-8901-4b23-c456-789012345678",
"vaRegCountry": "HKG",
"applyUse": "B2B",
"currency": "USD,EUR,HKD",
"notifyUrl": "https://merchant.example.com/webhooks/virtual-account",
"remark": "B2B collection account for HK operations",
"extraInfo": {}
}'
```
### 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 the response `status` is `INIT`, the application requires supplementary KYC material. Call the Supplement Virtual Account Material API (`POST /v2/gc/virtual-accounts/{virtualAccountRequestId}/supplement-material`) with the details indicated by `materialCode` and `materialInfoJson`.
* This is an asynchronous operation. The final result (account opened with `vaNumber` and bank info) is delivered via the `VIRTUAL_ACCOUNT` webhook and can also be polled using `Get Detail Virtual Account` (`GET /v2/gc/virtual-accounts/{virtualAccountRequestId}`).
* The `currency` field accepts a single ISO 4217 code (e.g. `"USD"`) or a comma-separated list (e.g. `"USD,EUR,HKD"`).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.neox.vn/docs/global/global-collections/integration/virtual-accounts/api-create-virtual-account.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.