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)
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
applyUse enumerationName: Intended use of the virtual account
Type:
stringRequired: Yes
Description: Indicates the business scenario used for virtual account application.
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
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 detailsshopType 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
If
vaRegCountry=HKGandapplyUse=PLATFORM, supportedshopTypevalues are:AppStore,GooglePlay,FacebookAudienceNetwork,GoogleAdMob,TopOn,Vungle,InMobi,BIGOAds,Unity,ironSource,Pangle,AppLovin,TENCENTADNETWORK.If
vaRegCountry=USAandapplyUse=PLATFORM, supportedshopTypevalues are:AppStore,GooglePlayUSA,GoogleAdmobUSA,FacebookAudienceNetworkUSA,GoogleAdSense,Steam,Amazon.If
vaRegCountryis one ofHKG,USA,LUX,DEU,DNK,GBRandapplyUse=PLATFORM_INDEPENDENT_WEBSITE, supportedshopTypevalues are:Shopline,Shopyy,Shoplaza,Shopify,IndependentStationOther.
payType details
payType detailspayType 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
vaRegCountryisHKG,USA,LUX,DEU,DNK, orGBRandapplyUse=PLATFORM_INDEPENDENT_WEBSITE.
Paypal
Paypal
Stripe
Stripe
Checkout
Checkout
Square
Square
Nuvei
Nuvei
Ayden
Ayden
Other
Other
shopType enumeration reference
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, andMYRvirtual 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
Response
Response Field Descriptions
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:
data object fields: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 detailsmaterialInfoJson 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:
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
materialInfoJson example valueResponse sample
Example cURL
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
requestIdfor each request to avoid duplicate submissions.The request body must be in JSON format.
When the response
statusisINIT, 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 bymaterialCodeandmaterialInfoJson.This is an asynchronous operation. The final result (account opened with
vaNumberand bank info) is delivered via theVIRTUAL_ACCOUNTwebhook and can also be polled usingGet Detail Virtual Account(GET /v2/gc/virtual-accounts/{virtualAccountRequestId}).The
currencyfield accepts a single ISO 4217 code (e.g."USD") or a comma-separated list (e.g."USD,EUR,HKD").
Last updated
Was this helpful?