> 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 | Yes | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency. |
| userType | string | Yes | Type of business entity. Default `COMPANY` |
| mobile | string | Yes | Contact mobile number of the sub-merchant. |
| mobileAreaCode | string | No | Mobile country/area calling code (e.g. `84`). |
| email | string | Yes | Contact email address of the sub-merchant. |
| regCountry | string | Yes | Country of registration in ISO 3166-1 alpha-3 format (e.g. `HKG`, `SGP`, `USA`). |
| englishName | string | Yes | English name of the company or institution. |
| incorporationCertNo | string | 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 | Yes | Registered address of the company. |
| businessCountry | string | Yes | Primary country of business operations in ISO 3166-1 alpha-3 format. |
| businessAddress | string | 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 | Yes | Company website URL. |
| industryCategory | string(64) | 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(8) | 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 | 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). |
{% 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 | Yes | Identity document type/detail code (for example, `PASSPORT`). |
| licenceFrontUrl | string | No | File path/URL of the front side of the identity document. |
| licenceBackUrl | string | No | File path/URL of the back side of the identity document. |
| name | string | Yes | Full legal name of the person. |
| idNumber | string | Yes | Identity document number. |
| birthDate | 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 | string | Yes | Effective date of the identity document. |
| expiryDate | string | Yes | Expiry date of the identity document. |
| address | string | Yes | Current residential/contact address of the person. |
| country | string | Yes | Nationality/country code in ISO 3166-1 alpha-3 format. |
| shareholderRatio | string | 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 | No | Supporting file path for the account opening method. Required when `type` is `DIRECTOR` or `LEGAL_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).
{% 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`).