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

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,JPY,AUD,SGD,CHF,NZD	Not specified	Supports cross-border collection and local collection in listed currencies.

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

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

Request sample

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

materialInfoJson is conditionally required in the response payload: when materialCode is not empty, materialInfoJson must also be non-empty.

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

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

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

curl -X POST "https://{base_url_openapi}/v2/gc/virtual-accounts" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -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").