Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Onboard Sub-Merchant

Endpoint: POST /v2/gc/sub-merchants/onboarding

Description: Submit a KYC/KYB onboarding application for a new sub-merchant so it can collect funds through the platform.

This API submits onboarding details for a sub-merchant, including company profile, KYC files, and key natural-person role information.

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. Enum: COMPANY, INSTITUTION.

mobile

string

Yes

Contact mobile number of the sub-merchant.

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

Incorporation certificate number of the company.

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

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.

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 (maximum 10). See merchantNetinPersons object item fields below.

kycFiles

array

Yes

List of KYC/KYB document file paths. Each element is a path returned by the File Upload API (POST /v2/gc/files/upload). See Merchant Qualification Materials by Registration Region.

notifyUrl

string

No

Merchant-hosted callback URL to receive asynchronous onboarding status notifications.

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

serviceCategory must match the selected industryCategory. If any secondary code belongs to a different primary industry, onboarding validation will fail.

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. Enum: ADMIN, SHAREHOLDER, DIRECTOR, LEGAL_PERSON.

idDetailCode

string

Yes

Identity document type/detail code (for example, PASSPORT, NATIONAL_ID).

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 for this person (required for SHAREHOLDER).

accountOpenMethod

string

No

Account opening method.

accountOpenFilePath

string

No

Supporting file path for account opening method.

Validate all type combinations before submission. DIRECTOR and LEGAL_PERSON cannot coexist in the same request.

merchantNetinPersons type rules and validation

  • type enum values:

    • ADMIN: Administrator (required)

    • SHAREHOLDER: Shareholder (at least 1 required; multiple are allowed)

    • DIRECTOR: Director (at least 1 required for enterprises in Hong Kong, China and other overseas countries/regions)

    • LEGAL_PERSON: Legal representative (required and only 1 for enterprises in Mainland China)

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

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.

Request sample

Response

Response Field Descriptions

Field Name
Type
Description

code

number

Response code.

state

number

State of the response.

data

object

Onboarding application result.

message

string

Response message.

neoResponseId

string

Unique NeoX response identifier.

data object fields:

Field Name
Type
Description

requestId

string

Echoes the merchant-supplied requestId.

merchantId

string

NeoX merchant identifier for the parent merchant.

subMerchantId

string

NeoX identifier assigned to the newly onboarded sub-merchant.

status

string

Current onboarding status. Enum: PROCESS, SUCCESS, FAILED.

errCode

string

Error code if the onboarding application failed; empty on success.

errMsg

string

Human-readable error description if the application failed; empty on success.

Response 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 requestId for each request to avoid duplicate submissions.

  • The request body must be in JSON format.

  • All kycFiles entries must be path values returned by the File Upload API (POST /v2/gc/files/upload).

  • This is an asynchronous operation. The final onboarding result is delivered via the SUB_MERCHANT webhook and can also be polled using Get Sub-Merchant Onboarding Status (GET /v2/gc/sub-merchants/onboarding/{requestId}).

PreviousSub-Merchant Management APIsNextGet Sub-Merchant Onboarding Status

Last updated

Was this helpful?