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.

A virtual account is a receiving account opened by NeoPay for users to collect funds by supported country/region, currency, and business scenario.

Request

Request Body Field Descriptions (JSON)

Field Name	Type	Required	Description
requestId	string(32)	Yes	Merchant-generated unique request ID (UUID recommended). Used for idempotency.
vaRegCountry	string(32)	Yes	Country/region of registration for the virtual account in ISO 3166-1 alpha-3 format. See VA capabilities by country/region below for supported values and constraints.
applyUse	string	Yes	Intended use of the virtual account. See applyUse enumeration and VA capabilities by country/region for country-specific availability.
currency	string(256)	Yes	Currency or comma-separated list of currencies in ISO 4217 format (e.g. "USD" or "USD,EUR,HKD").
subMerchantId	string(32)	Conditional	NeoX sub-merchant identifier if this virtual account belongs to a sub-merchant. Optional in general; required when the merchant operates in PSP mode.
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).
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(32)	No	Identifier of the account holder entity.
materialId	string(64)	No	Material submission ID referencing a prior material submission. Must be a value returned by the Supplement Virtual Account Material API.
payType	string	No	Required when vaRegCountry is one of HKG/USA/LUX/DEU/DNK/GBR and applyUse=PLATFORM_INDEPENDENT_WEBSITE. See payType details below.
shopType	string	No	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 below.
applyBankCode	string(32)	No	Preferred bank code for account opening. Leave empty to let the system assign automatically. When vaRegCountry=NGA, must be one of: Paga | Wema | FCMB | Fidelity Bank.
extraInfo	object	No	Additional information as key-value pairs. Contents vary by vaRegCountry and applyUse.

The field that carries the async-result callback URL for this endpoint is webhookUrl.

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

Validate vaRegCountry, currency, applyUse, and shopType against the matrix below before submitting requests.

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, 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).

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.

shopType details

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.

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

payType is required when vaRegCountry is one of HKG, USA, LUX, DEU, DNK, GBR and applyUse is PLATFORM_INDEPENDENT_WEBSITE.

Supported payType for independent website platform scenarios

• Type: string

• 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.

Before submitting a request, confirm vaRegCountry, currency order, applyUse, shopType, and payType are all valid in the sections above.

Request sample

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

{
    "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.

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 or the webhooks below.

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 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 in the Webhook page for its field layout and an example value.

Response sample

Real captured response, corresponding to the request above:

{
    "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 with this id, or listen for the VA_SUPPLEMENT_REQUIRED / VA_CREATION_RESULT webhooks (see Webhook).

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 shows a non-empty materialCode, the application requires supplementary KYC material. Call Supplement Virtual Account Material (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) and can also be polled using Get Detail Virtual Account (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.