> 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"`).