> 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/sub-merchants/api-onboard-sub-merchant.md).
# Onboard Sub-Merchant
#### Endpoint: POST /v2/gc/sub-merchants/onboard
#### Description: Submit a KYC/KYB onboarding application for a new sub-merchant so it can collect funds through the platform.
{% hint style="info" %}
This API submits onboarding details for a sub-merchant, including company profile, KYC files, and key natural-person role information.
{% endhint %}
## Request
#### Request Body Field Descriptions (JSON)
| Field Name | Type | Required | Description |
| ------------------------------ | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId | string(64) | Yes | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency. |
| userType | string | Yes | Type of business entity. Default `COMPANY` |
| mobile | string(16) | Yes | Contact mobile number of the sub-merchant. |
| mobileAreaCode | string(16) | No | Mobile country/area calling code (e.g. `84`). |
| email | string(64) | Yes | Contact email address of the sub-merchant. |
| regCountry | string(16) | Yes | Country of registration in ISO 3166-1 alpha-3 format (e.g. `HKG`, `SGP`, `USA`). |
| englishName | string(256) | Yes | English name of the company or institution. |
| incorporationCertNo | string(64) | Yes | - Mainland China enterprises: Fill in the Unified Social Credit Code.
- Hong Kong, China enterprises: Fill in the first 8 digits of the Business Registration Certificate number.
- Enterprises from other countries or regions: Fill in the Company Registration Number issued by the local government or registration authority.
|
| createDate | date string | Yes | Date the company was incorporated (YYYY-MM-DD). |
| effectiveDate | date string | Yes | Effective date of the incorporation certificate (YYYY-MM-DD). |
| expiryDate | date string | Yes | Expiry date of the incorporation certificate. If it is long-term, you can fill in: 9999-12-31 |
| (YYYY-MM-DD). | | | |
| regAddress | string(512) | Yes | Registered address of the company. |
| businessCountry | string | Yes | Primary country of business operations in ISO 3166-1 alpha-3 format. |
| businessAddress | string(512) | Yes | Primary business address of the company.
Format: Chinese characters, English letters, numbers, spaces, and special characters are supported: / - ? : ( ) . , ' + ’
Line breaks are not supported.
|
| companyType | string | Yes | Legal form of the company. Enum: `LIMITED_COMPANY`, `BUSINESS_PARTNERSHIP`, `OTHER`. |
| website | string(256) | Yes | Company website URL. |
| industryCategory | string | Yes | Primary industry category. Must match `serviceCategory` (secondary category) mapping. Supported enums are listed in industry details below. |
| serviceCategory | array | Yes | Secondary service category code list. Only values mapped under the selected `industryCategory` are allowed. |
| businessRegion | array | Yes | List of regions where the sub-merchant conducts business. |
| employeeRank | string | Yes | Employee headcount band. Enum: `A`, `B`, `C`, `D`. |
| salesVolumeRank | string | No | Annual sales tier (in USD). Enum: `A`, `B`, `C`, `D`, `E`, `F`, `G`. |
| wealthSource | array | No | Sources of wealth. Enum: `BUSINESS_INCOME`,`INVESTMENT_INCOME`,`FINANCING`,`ASSET_SALE`,`BENEFICIARY`,`OTHER` |
| fundsSource | array | No | Estimated funding sources. Enum: `BUSINESS_INCOME`, `INVESTMENT_INCOME`, `FINANCING`, `ASSET_SALE`, `BENEFICIARY`, `OTHER`. |
| otherFundsSource | string(20) | No | Required when `fundsSource` includes `OTHER`. |
| merchantNetinPersons | array (max 10 items) | Yes | List of key persons associated with the sub-merchant. See `merchantNetinPersons` object item fields below. |
| kycFiles | array | Yes | List of KYC/KYB documents. Each element is an object (`{type, path}`), where `path` is the value of `fileName` returned by the File Upload API (`POST /v2/gc/files/upload`). See [Merchant Qualification Materials by Registration Region](https://github.com/neopayvn/neox-gitbook-documents-v2/tree/main/global-collections/integration/sub-merchants/merchant-qualification-materials-by-registration-region.md). |
| webhookUrl | string | No | Merchant-hosted callback URL to receive the `SUBMERCHANT_ONBOARDING_RESULT` webhook for this sub-merchant. See [Webhook](/docs/global/global-collections/integration/sub-merchants/webhook.md). |
| enRegAddress | string(512) | No | Company Registered Address (English). Required when `regCountry` is `CHN` or `HKG`. Format: English letters, numbers, spaces, and `/ - ? : ( ) . , '`. |
| businessRegCertNo | string(8) | No | Business Registration Certificate Number. Required (8 digits) when `regCountry` is `HKG`. |
| otherWealthSource | string(20) | No | Other Source of Wealth. Required when `wealthSource` includes `OTHER`. |
| sourceType | string | No | Request source channel. Enum: `PORTAL`, `API`. |
| businessEffectiveDate | date string | No | Business Registration Certificate Effective Date. Required when `regCountry` is `HKG`. |
| businessExpiryDate | date string | No | Business Registration Certificate Expiry Date. Required when `regCountry` is `HKG`. |
| enBusinessAddress | string(512) | No | Business Address (English). Required when `regCountry` is `CHN` or `HKG`. Format: English letters, numbers, spaces, and `/ - ? : ( ) . , ' + ’`. |
| nameUsed | string(128) | No | Company former/used name. |
| appStoreImageFilePath | string(256) | No | App developer backend screenshot file path. Required when `industryCategory` is `SOFTWARE_SERVICE`. |
| appDownloadUrl | string(256) | No | App download link in the app store (must be a valid `http`/`https` URL). Required when `industryCategory` is `SOFTWARE_SERVICE`. |
| franchiseLicenseName | string | No | Franchise license name. For payment institution companies. See enum details below. |
| franchiseLicenseNum | string(64) | No | Franchise license number. For payment institution companies. |
| franchiseBiz | array | No | Franchise business content/scope. For payment institution companies. See enum details below. |
| regulatorName | string | No | Regulatory authority name. For payment institution companies. See enum details below. |
| franchiseLicenseEffectiveDate | date string | No | Franchise license acquisition date. For payment institution companies. |
| franchiseLicenseExpiryDate | date string | No | Franchise license validity expiry date. For payment institution companies. |
| companyIsListed | string | No | Is the company listed? Enum: `YES`, `NO`. If `YES`, `exchangeName` is required. |
| exchangeName | string | No | Exchange name. Required when `companyIsListed` is `YES`. See enum details below. |
| parentCompanyExist | string | No | Does a parent company exist? Enum: `YES`, `NO`. If `YES`, `parentCompanyIsListed` is required. |
| parentCompanyIsListed | string | No | Is the parent company listed? Enum: `YES`, `NO`. Required when `parentCompanyExist` is `YES`. If `YES`, `parentCompanyExchangeName`, `parentCompanyRegulatorRegion`, and `parentCompanyRegulatorName` are required. |
| parentCompanyExchangeName | string | No | Parent company exchange name. Required when `parentCompanyIsListed` is `YES`. See enum details below. |
| controlledByFinalParentCompany | string | No | Does the parent company belong to a regulated financial institution? Enum: `YES`, `NO`. |
| parentCompanyRegulatorRegion | string | No | Parent company regulatory authority country/region (ISO 3166-1 alpha-3). Required when `parentCompanyIsListed` is `YES`. |
| parentCompanyRegulatorName | string | No | Parent company regulatory authority name. Required when `parentCompanyIsListed` is `YES`. See enum details below. |
| byGptSalesRank | string | No | Estimated monthly average transaction volume via GPT. See enum details below. |
| supplyServiceType | array | No | Service type(s) provided. Enum: `FX`, `PAYMENT`, `OTHER`. |
| supplyServiceTypeOther | string | No | Other service type. Required when `supplyServiceType` includes `OTHER`. |
| feeBear | string | No | Fee bearer. Enum: `SUB_MERCHANT`, `PARENT_MERCHANT`. Default `SUB_MERCHANT`. |
{% hint style="warning" %}
The field that carries the async-result callback URL for this endpoint is **`webhookUrl`**
{% endhint %}
industryCategory details
* Name: Industry category (primary)
* Type: `string(64)`
* Required: Yes
* Description: Primary industry classification used to identify the merchant's main industry category.
* Validation rule: `industryCategory` must correspond to `serviceCategory`. Only secondary categories supported under the selected primary category are allowed.
| Enum Value | Industry Name |
| ------------------------------- | ---------------------------------- |
| `EC` | E-commerce trade |
| `AIR_TRAVEL` | Air travel |
| `EDUCATION` | Education services |
| `PSP` | Payment service provider |
| `AD_SERVICE` | Advertising services |
| `COMMUNICATION_SERVICE` | Communication services |
| `CONVENTION_EXHIBITION_SERVICE` | Convention and exhibition services |
| `SOFTWARE_SERVICE` | Software services |
| `GENERAL_TRADE` | General trade |
| `MARKET_PURCHASE` | Market procurement trade |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation |
{% hint style="warning" %}
`serviceCategory` must match the selected `industryCategory`. If any secondary code belongs to a different primary industry, onboarding validation will fail.
{% endhint %}
serviceCategory mapping by industryCategory
| Primary Category Code | Primary Category Name | Secondary Service Code | Secondary Service Name |
| -------------------------- | ---------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_OTHER` | Other |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_EXPRESS` | Express service |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_WAREHOUSE` | Warehouse service |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_LAND` | Land transportation service |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_AIR` | Air transportation service |
| `LOGISTICS_TRANSPORTATION` | Logistics and transportation | `LOGISTICS_TRANSPORTATION_SEA` | Sea transportation service |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_OTHER` | Other |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_VEHICLES_AUTO_PARTS` | Vehicles, machinery, and auto parts |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_E_CIGARETTE_VAPE` | E-cigarettes and vaping devices |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_MINERAL_ENERGY` | Minerals and energy products |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_METALS_MATERIALS` | Metals and raw materials |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_DAILY_OFFICE_SUPPLIES` | Daily and office supplies |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_FOOD_BEVERAGE` | Food and beverages |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_FURNITURE_LAMP` | Furniture and lighting |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_3C_PRODUCTS` | 3C digital and home appliances |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_BABY_PRODUCTS` | Baby products |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_ELECTRON` | Electronics industry (for example, electronic components) |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_CHEMICAL` | Chemical and plastic products |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_MEDICINE` | Medicine and medical devices |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_BEAUTY_MAKEUP` | Beauty and cosmetics |
| `MARKET_PURCHASE` | Market procurement trade | `MARKET_PURCHASE_CLOTHING_BAGS` | Clothing and bags |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_OTHER` | Other |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_VEHICLES_AUTO_PARTS` | Vehicles, machinery, and auto parts |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_E_CIGARETTE_VAPE` | E-cigarettes and vaping devices |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_MINERAL_ENERGY` | Minerals and energy products |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_METALS_MATERIALS` | Metals and raw materials |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_DAILY_OFFICE_SUPPLIES` | Daily and office supplies |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_FOOD_BEVERAGE` | Food and beverages |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_FURNITURE_LAMP` | Furniture and lighting |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_3C_PRODUCTS` | 3C digital and home appliances |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_BABY_PRODUCTS` | Baby products |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_ELECTRON` | Electronics industry (for example, electronic components) |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_CHEMICAL` | Chemical and plastic products |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_MEDICINE` | Medicine and medical devices |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_BEAUTY_MAKEUP` | Beauty and cosmetics |
| `GENERAL_TRADE` | General trade | `GENERAL_TRADE_CLOTHING_BAGS` | Clothing and bags |
| `EC` | E-commerce trade | `EC_CLOTHING_BAGS` | Clothing and bags |
| `EC` | E-commerce trade | `EC_BEAUTY_MAKEUP` | Beauty and cosmetics |
| `EC` | E-commerce trade | `EC_MEDICINE` | Medicine and medical devices |
| `EC` | E-commerce trade | `EC_CHEMICAL` | Chemical and plastic products |
| `EC` | E-commerce trade | `EC_ELECTRON` | Electronics industry (for example, electronic components) |
| `EC` | E-commerce trade | `EC_BABY_PRODUCTS` | Baby products |
| `EC` | E-commerce trade | `EC_3C_PRODUCTS` | 3C digital and home appliances |
| `EC` | E-commerce trade | `EC_FURNITURE_LAMP` | Furniture and lighting |
| `EC` | E-commerce trade | `EC_FOOD_BEVERAGE` | Food and beverages |
| `EC` | E-commerce trade | `EC_DAILY_OFFICE_SUPPLIES` | Daily and office supplies |
| `EC` | E-commerce trade | `EC_METALS_MATERIALS` | Metals and raw materials |
| `EC` | E-commerce trade | `EC_MINERAL_ENERGY` | Minerals and energy products |
| `EC` | E-commerce trade | `EC_E_CIGARETTE_VAPE` | E-cigarettes and vaping devices |
| `EC` | E-commerce trade | `EC_VEHICLES_AUTO_PARTS` | Vehicles, machinery, and auto parts |
| `EC` | E-commerce trade | `EC_OTHER` | Other |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_GAME` | Game application developer |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_LIVE_BROADCAST` | Live streaming, voice chat, and social application developer |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_VIDEO_AUDIO` | Video, audio, and content-tool application developer |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_VIRTUAL_RECHARGE` | Virtual product recharge |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_APPLICATION_PUBLISHER` | Application publisher |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_AD` | Advertising traffic monetization |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_STREAM` | Streaming video production |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_SUBSCRIBE_SERVICE_PLATFORM` | Subscription service platform |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_CLOUD_SERVICE_PROVIDER` | Cloud service provider |
| `SOFTWARE_SERVICE` | Software services | `SOFTWARE_SERVICE_OTHER` | Other |
| `EDUCATION` | Education services | `EDUCATION_STUDY_ABROAD_SERVICE` | Study abroad services |
| `EDUCATION` | Education services | `EDUCATION_ONLINE` | Online education |
| `EDUCATION` | Education services | `EDUCATION_OTHER` | Other |
| `AD_SERVICE` | Advertising services | `AD_SERVICE_MARKET` | Advertising marketing services |
| `AD_SERVICE` | Advertising services | `AD_SERVICE_OTHER` | Other |
| `PSP` | Payment service provider | `PSP_IMPORT_EXPORT` | Import and export trade |
| `PSP` | Payment service provider | `PSP_EC` | E-commerce platform |
| `PSP` | Payment service provider | `PSP_DTCS` | Independent and self-built websites |
| `PSP` | Payment service provider | `PSP_SALARY_FAMILY_REMIT` | Salary and family-support remittance |
| `PSP` | Payment service provider | `PSP_SERVICE_TRADE` | Service trade (flight, hotel, education, etc.) |
| `PSP` | Payment service provider | `PSP_OTHER` | Other |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_OTHER` | Other |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_TICKET_COMPANY` | Ticketing company |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_CAR_RENTAL_COMPANY` | Car rental company |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_OTA` | Online travel agency |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_HOTEL` | Hotel group |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_TICKET_AGENCY` | Air ticket agency |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_AIRLINE` | Airline |
| `AIR_TRAVEL` | Air travel | `AIR_TRAVEL_TRAVEL_AGENCY_TMC` | Travel agency or TMC |
salesVolumeRank enumeration
* Name: Annual sales
* Type: `string(8)`
* Required: No
* Description: Annual sales tier (in USD)
* Note: Converted from HKD and rounded to whole numbers (in millions of USD).
| Value | Description |
| ----- | ------------------------------ |
| `A` | Below 7 million USD |
| `B` | 7 million to 26 million USD |
| `C` | 26 million to 64 million USD |
| `D` | 64 million to 128 million USD |
| `E` | 128 million to 385 million USD |
| `F` | 385 million to 641 million USD |
| `G` | Above 641 million USD |
wealthSource enumeration
* Name: Sources of wealth
* Type: `array`
* Required: No
* Description: Sources of wealth
| Value | Description |
| ------------------- | ------------------------ |
| `BUSINESS_INCOME` | Business revenue |
| `INVESTMENT_INCOME` | Investment income |
| `FINANCING` | Internal group financing |
| `ASSET_SALE` | Income from asset sales |
| `BENEFICIARY` | From beneficiaries |
| `OTHER` | Other |
fundsSource enumeration
* Name: Estimated funding sources
* Type: `array`
* Required: No
* Description: Estimated funding sources
| Value | Description |
| ------------------- | ------------------------ |
| `BUSINESS_INCOME` | Business revenue |
| `INVESTMENT_INCOME` | Investment income |
| `FINANCING` | Internal group financing |
| `ASSET_SALE` | Income from asset sales |
| `BENEFICIARY` | From beneficiaries |
| `OTHER` | Other |
otherFundsSource field details
* Name: Other funding source
* Type: `string(20)`
* Required: No
* Description: Required when the estimated funding source is `OTHER`.
merchantNetinPersons details
#### `merchantNetinPersons` object item fields:
| Field Name | Type | Required | Description |
| ------------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Personnel type. ADMIN - Administrator (Required)
SHAREHOLDER - Shareholder (At least 1)
DIRECTOR - Director (At least 1 for overseas enterprises)
LEGAL\_PERSON - Legal Person (Required and only 1 for Mainland China)
|
| idDetailCode | string(64) | Yes | Identity document type/detail code (for example, `PASSPORT`). |
| licenceFrontUrl | string(256) | No | File path/URL of the front side of the identity document. |
| licenceBackUrl | string(256) | No | File path/URL of the back side of the identity document. |
| name | string(128) | Yes | Full legal name of the person. |
| idNumber | string(64) | Yes | Identity document number. |
| birthDate | date string | Yes | Date of birth (recommended format: `YYYY-MM-DD`). |
| idAddress | string | Yes | Address shown on the identity document. Use only standard letters, numbers, spaces, and common punctuation characters. Special characters are not supported. |
| effectiveDate | date string | Yes | Effective date of the identity document. |
| expiryDate | date string | Yes | Expiry date of the identity document. |
| address | string(512) | Yes | Current residential/contact address of the person. |
| country | string | Yes | Nationality/country code in ISO 3166-1 alpha-3 format. |
| shareholderRatio | string(10) | No | Shareholding ratio (percentage, no `%` sign). Required when `type=SHAREHOLDER` or `type=DIRECTOR`. At least one shareholder must have a shareholding ratio >= 25 |
| accountOpenMethod | string | No | Account opening method. Required when `type` is `DIRECTOR` or `LEGAL_PERSON`. |
| accountOpenFilePath | string(256) | No | Supporting file path for the account opening method. Required when `type` is `DIRECTOR` or `LEGAL_PERSON`. |
| citizenship | string(32) | No | Citizenship/nationality code of the person. |
#### `merchantNetinPersons` type rules and validation
* Person count limits:
* Minimum 3 person entries are required.
* Maximum 10 person entries are allowed.
* Region-specific minimum role combinations:
* Enterprises in Mainland China: at least 1 `ADMIN`, 1 `SHAREHOLDER`, and 1 `LEGAL_PERSON`.
* Enterprises in Hong Kong, China and other overseas countries/regions: at least 1 `ADMIN`, 1 `SHAREHOLDER`, and 1 `DIRECTOR`.
* Validation behavior:
* `DIRECTOR` and `LEGAL_PERSON` are mutually exclusive in a single submission.
* `shareholderRatio` is required when `type=SHAREHOLDER`.
* The same natural person can hold multiple roles. If one person holds multiple roles, submit that person's information once per role (for example, 3 separate entries for 3 roles).
franchiseLicenseName enumeration
* Name: Franchise license name
* Type: `string`
* Required: No
* Description: For payment institution companies.
| Value |
| ---------------------------------------------- |
| `The_Payment_Business_License` |
| `Major_Payment_Institution` |
| `Authorised_Payment_Institution` |
| `Fund_Transfer_Business_Operator_Registration` |
| `Independent_Remittance_Dealer_Registration` |
| `Electronic_Money_Payment_Institutions` |
| `Money_Service_Business_Registration_CA` |
| `Money_Service_Business_Registration_US` |
| `Money_Service_Operator_License` |
franchiseBiz enumeration
* Name: Franchise business content/scope
* Type: `array`
* Required: No
* Description: For payment institution companies.
| Value | Description |
| ------------------------ | --------------------- |
| `Bank_Card_POS_Business` | Bank card acquiring |
| `Mobile_Payment` | Mobile payment |
| `Internet_Payment` | Internet payment |
| `Issuance_Prepaid_Cards` | Prepaid card issuance |
| `Seller_Money_Orders` | Sale of money orders |
| `Remittance_Service` | Remittance service |
| `Money_Changing_Service` | Currency exchange |
regulatorName / parentCompanyRegulatorName enumeration
* Name: Regulatory authority name
* Type: `string`
* Required: No
* Description: Used by both `regulatorName` and `parentCompanyRegulatorName`. For payment institution companies.
| Value |
| ------------------------------------------------------- |
| `Monetary_Authority_of_Singapore` |
| `Thai_Ministry_of_Finance` |
| `Peoples_Bank_of_China` |
| `Financial_Transactions_Reports_Analysis_Centre_Canada` |
| `Commission_Surveillance_SecteurFinancier` |
| `Lietuvos_Bankas` |
| `Financial_Conduct_Authority` |
| `Kanto_Local_Finance_Bureau` |
| `Australian_Transaction_Reports_Analysis_Centre` |
| `Financial_Crimes_Enforcement_Network` |
| `Customs_Excise_HK` |
exchangeName / parentCompanyExchangeName enumeration
* Name: Exchange name
* Type: `string`
* Required: No
* Description: Used by both `exchangeName` (required when `companyIsListed` is `YES`) and `parentCompanyExchangeName` (required when `parentCompanyIsListed` is `YES`).
| Value |
| ----------------------------------------------- |
| `Shanghai_Stock_Exchange` |
| `Shenzhen_Stock_Exchange` |
| `Wiener_Börse_AG` |
| `TSX_Inc` |
| `Tokyo_Stock_Exchange_Inc` |
| `Stock_Exchange_Thailand` |
| `Stock_Exchange_Hong_Kong_Limited` |
| `Philippine_Stock_Exchange_Inc` |
| `NASDAQ_Stock_Market_LLC` |
| `Société_Bourse_Luxembourg` |
| `Sociedad_Rectora_Bolsa_Valores_Madrid` |
| `SIX_Swiss_Exchange_AG` |
| `Singapore_Exchange_Securities_Trading_Limited` |
| `Oslo_Bors_ASA` |
| `Osaka_Securities_Exchange` |
| `NZX_Limited` |
| `NYSE_Amex_LLC` |
| `New_York_Stock_Exchange_LLC` |
| `NationalStockExchange_India_Limited` |
| `NASDAQ_OMX_Stockholm_AB` |
| `NASDAQ_OMX_Helsinki_Ltd` |
| `NASDAQ_OMX_Copenhagen_AS` |
| `Nagoya_Stock_Exchange_Inc` |
| `Montreal_Exchange_Inc` |
| `London_Stock_Exchange` |
| `Korea_Exchange_Inc` |
| `Euronext_Paris_SA` |
| `Euronext_Brussels_NV` |
| `Euronext_Amsterdam_NV` |
| `Deutsche_Börse_AG` |
| `Bursa_Malaysia_Securities_Berhad` |
| `Borsa_Italiana` |
| `BSE_Limited` |
| `ASX_Limited` |
byGptSalesRank enumeration
* Name: Estimated monthly average transaction volume via GPT
* Type: `string`
* Required: No
* Note: Values are HKD-denominated bands.
| Value | Description |
| ----- | ------------------------- |
| `A` | Below 1 million |
| `B` | 1 million to 10 million |
| `C` | 10 million to 50 million |
| `D` | 50 million to 100 million |
| `E` | 100 million to 1 billion |
| `F` | Above 1 billion |
{% hint style="success" %}
Before submitting, validate type coverage and count rules in `merchantNetinPersons`, and ensure all referenced file paths in `kycFiles` are returned by the file upload API.
{% endhint %}
#### Request sample
```json
{
"requestId": "1785378822666",
"userType": "COMPANY",
"mobile": "0912345002",
"email": "contact002@testcompany.vn",
"regCountry": "VNM",
"englishName": "Example Trading API 02",
"incorporationCertNo": "0123456789",
"createDate": "2022-10-22",
"effectiveDate": "2022-10-10",
"expiryDate": "9999-12-31",
"regAddress": "123 Example St, Hanoi",
"businessCountry": "VNM",
"businessAddress": "123 Example St, Hanoi",
"companyType": "LIMITED_COMPANY",
"website": "https://example.com",
"industryCategory": "EC",
"serviceCategory": ["EC_CLOTHING_BAGS"],
"businessRegion": ["VNM", "USA"],
"employeeRank": "B",
"salesVolumeRank": "B",
"wealthSource": ["BUSINESS_INCOME"],
"fundsSource": ["BUSINESS_INCOME"],
"merchantNetinPersons": [
{"type": "ADMIN", "name": "Nguyen Van A", "idDetailCode": "PASSPORT", "idNumber": "P1234567", "birthDate": "1990-01-01", "idAddress": "Hanoi", "effectiveDate": "2020-01-01", "expiryDate": "2030-01-01", "address": "Hanoi", "country": "VNM"},
{"type": "SHAREHOLDER", "name": "Tran Thi B", "idDetailCode": "PASSPORT", "idNumber": "P7654321", "birthDate": "1985-05-05", "idAddress": "HCMC", "effectiveDate": "2020-01-01", "expiryDate": "2030-01-01", "address": "HCMC", "country": "VNM", "shareholderRatio": "30"},
{"type": "DIRECTOR", "name": "Le Van C", "idDetailCode": "PASSPORT", "idNumber": "P1112223", "birthDate": "1980-03-03", "idAddress": "Hanoi", "effectiveDate": "2020-01-01", "expiryDate": "2030-01-01", "address": "Hanoi", "country": "VNM", "shareholderRatio": "30"}
],
"kycFiles": [{"type": "BUSINESS_LICENSE", "path": "/uploads/bl.pdf"}],
"mobileAreaCode": "84",
"webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76"
}
```
### Response
#### Response Field Descriptions
| Field Name | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------- |
| code | number | Response code. |
| data | object | Onboarding application result. |
| message | string | Response message. |
| neoResponseId | string | Unique NeoX response identifier (not present on every response). |
#### `data` object fields:
| Field Name | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Internal sub-merchant record identifier assigned by the platform. |
| requestId | string | Echoes the merchant-supplied `requestId`. |
| status | string | Current sub-merchant status. Observed value: `SUB_MERCHANT_STATUS`: `INIT`, `PENDING`, `PROCESSING`, `APPROVED`, `SUPPLEMENT_SUBMITTED`, `WAIT_SUPPLEMENT`, `REJECTED`. |
#### Response sample
```json
{
"code": 1,
"data": {
"id": "f697ef4a2cea49a5ba81ca719535a682",
"requestId": "1785378822666",
"status": "PENDING"
},
"message": "Successful"
}
```
### 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. All `kycFiles` entries must be `fileName` returned by the File Upload API (`POST /v2/gc/files/upload`).
* This is an asynchronous operation. The final onboarding result is delivered via the [`SUBMERCHANT_ONBOARDING_RESULT` webhook](/docs/global/global-collections/integration/sub-merchants/webhook.md) (sent to `webhookUrl` if supplied) and can also be polled using [Get Sub-Merchant Onboarding Status](/docs/global/global-collections/integration/sub-merchants/get-sub-merchant-onboarding-status.md) (`GET /v2/gc/sub-merchants`).