Onboard Sub-merchant

Update Time：2025.01.07

The institution submits the sub-merchant information, and the WeChat Pay system creates a Sub-merchant ID for each sub-merchant.

Tips：

The header of requests of this API should contain the parameter Idempotency-Key, which is a unique key generated by the merchant side. The WeChat server uses this value to identify whether multiple retries are for the same request. The 64-bit field can contain letters and numbers.

1. API Intro

Applicable object： Institutional mode

Request URL：https://apihk.mch.weixin.qq.com/v3/global/merchants

Request method：POST

Path parameter is a path parameter.

Query parameter needs to be passed in the request URL.

Body parameter needs to be passed in the request JSON.

2. Request Parameters

Name

Variable Name

Type

Required

Description

Official Account ID

sp_appid

string[1,32]

Yes

Body Official Account ID assigned by WeChat
Example: wxd678efh567hg6787

Vendor ID

sp_mchid

string[1,32]

Yes

Body Specifies vendor ID assigned by WeChat Payment
Example: 1230000109

Merchant name

name

string[1,128]

Yes

Body Specifies the complete merchant entity name which must be exactly the same as your company's registered name in your company's official registration document issued by competent authorities, e.g. Business License, Certificate of Incorporation, Business Registration Certificate, etc.
Example: Merchant Name

Merchant shortname

shortname

string[1,64]

Yes

Body Specifies the brief merchant name, which will be shown to the consumers
Example: FS

Customer Service Phone Number.

office_phone

string[1,32]

Yes

Body Specifies the customer service phone number, which will be shown in the payment details page for the consumers.
Please prefix the phone number. See the appendix for prefixes.
Example: +86075586010000

Contact information

contact

object

Yes

Body Contact information object details is listed below

Contact information

Business category

business_category

int

Yes

Body Specifies the business category according to your business license, please refer to the business ID list of WeChat payment. see to Business Category
Example: 101

Channel number

channel_id

string[1,20]

Body The channel number created by the institution in the WeChat merchant management backend. Fill in the channel number (if any).
Example: 3200000001

Registered Country or Region

merchant_country_code

string[1,3]

Yes

Body The country where the submerchant was registered ,see to CountryCode
Example: 344

Merchant Type

merchant_type

string[1,10]

Yes

Body ENTERPRISE or INDIVIDUAL
If the merchant is a nature person or sole proprietor, please select INDIVIDUAL.
Example: ENTERPRISE

Registration Certificate Number

registration_certificate_number

string[1,50]

Yes

Body Company registration document No.
If the merchant is a nature person (INDIVIDUAL) , please provide the ID number of the director or principal.
If the merchant is a sole proprietor (INDIVIDUAL) , please provide the business registration certificate number of the sole proprietor.
Example: 5555-8888

Expiration Date of Registration Certificate

registration_certificate_date

string[1,10]

Yes

Body The expiration date of the company registration document.
The value should be expire date or “PERMANENT” , “N/A”, the date format should YYYY-MM-DD , such as 2020-10-16.
If the merchant is a nature person (INDIVIDUAL) , please provide the expiration date of the director or principal's ID.
If the merchant is a sole proprietor (INDIVIDUAL) , please provide the expiration date of business registration certificate.
Example: 2020-10-16

Copy of Registration Certificate

registration_certificate_copy

string[1,128]

Body The photocopy of the company registration document.
If the merchant is a nature person (INDIVIDUAL) , please provide the copy of the director or principal's ID.
If the merchant is a sole proprietor (INDIVIDUAL) , please provide the copy of business registration certificate.
The value should be the media ID returned by Uploading Image API.
Example: DsWXok2NqRliv2SDL42QoEmHIPs

Settlement Bank No.

settlement_bank_number

string[1,128]

Body Settlement bank account number (settlement bank information)
Example: 555588889999

Business information

business

object

Yes

Body Business information, the detail is listed below

Business information

Director information

director

object

Body Director information,
Specify this field only when the Merchant Type is ENTERPRISE （Not mandatory）
The detail is listed below

Director information

Principal information

principal

object

Body Principal information,
Specify this field only when the Merchant Type is INDIVIDUAL （Not mandatory）
The detail is listed below

Principal information

Apply for H5 payment authorization

apply_h5_payment

boolean

Apply for H5 payment authorization.
The values are true or false.
Example: true

H5 payment application info

h5_payment_apply_info

object

Body H5 payment application info.
Required when apply_h5_payment is true.

H5 payment application info

Request Example：

Onboarding sub-merchant only

1{
2		"sp_appid": "wx82ec4jy334ner1",
3		"sp_mchid": "2422128905",
4		"name": "Merchant name",
5		"shortname": "shortname",
6		"office_phone": "+86075586010000",
7		"contact": {
8			"email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
9			"name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
10			"phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
11		},
12		"business_category": 644,
13		"merchant_country_code": "344",
14		"merchant_type": "ENTERPRISE",
15		"registration_certificate_number": "519723407213085723",
16		"registration_certificate_date": "2022-06-03",
17		"settlement_bank_number": "559304578245298347923856",
18		"business": {
19			"business_type": "ONLINE",
20			"mcc": "5344",
21			"mini_program": "wx8888888888888888"
22		},
23		"director": {
24			"name": "Tom",
25			"number": "1234567890"
26	}
27}

Also apply for H5 payment

1{
2	  "sp_appid": "wx82ec4jy334ner1",
3	  "sp_mchid": "2422128905",
4	  "name": "Merchant name",
5	  "shortname": "Merchant shortname",
6	  "office_phone": "+86075586010000",
7	  "contact": {
8		"name": "yuhZiIh1C8x2UQ9FZY9ojV65HmpttQUSeOi3MdWy52ZoQUSpBUb52dJ+puGkzeGzjuXxJHbD0EGMDOfikdsAr7sqXhqfJexJKN7TSrwewbJqOEJ7fFjB3fqGVu6b/gfq6HduulBgaAlwZ5RcxpEVrAVM54mY3Z9HiX21fcqs65bti/QjEVCg0e1LlypKR3eqdW/XZi3q0gQ3hI0J9crA9OekIGc3M6OZ34aue5VdOd0PTCT99rIcI6N1VuapH2a7hY3fpgGAGxnYgNhUGsTgNoKso0pVCLEl0OlwvYCqmht3foyXtU/4WwwkpK8oFW1yQP3X7D1jXInEakWDFRAcUw==",
9		"phone": "XuafjSrgtiqsSzq4QdPEfrfspphyNnVSp9EKg9gM2/szy6ai+q5geSVE5VRRoQlVfiPYK/cFyTk009Cb8GDQilhL0X0HoxcBpcuRIaaW1+LOfMz0POAonG22yER/0486MhQrfNGaCb8QBTfeiIjZT2RPIpvTNyz6cESDV+Y1cD2JKOfK73MU3XKmgQz4mulb9sKdbNtGJV4wc03cR0Md/lnz9QnW5RulHu3bEwVRwtTSGJuMoZntkYhkn4KMRh/z93ri7wKd+DkIfIDMDTzvA2MUn4LW/PJtiKaNP5sOdpmpsw63kOsx5J32mTU7+0qz654MGayTFMW+fSgHBBNYVw==",
10		"email": "m+6RSfdEWSAZfrSfrP+FAPzh+jrFPQDPVCaslWwN3EdmsTliLvrUdcYnYuiILHpkZv1E6NNo592KOeznsDrKKWio00qfrurMhTAlneucHfU64yTvIsA6YqeBf8Uqfdad2BG0mYqbIn7AunnE2xqCoqS4W/lJPPROP7VU2/rFzkJx0KMInCo9FErktmN9nNQfhK5dpVis+YNv5SBQ7xSaVAUkTio4xNap1CWpVUIn8CjMgaSa7XJAOwNrNE6+ohU3pA/wlPALNIzYnNu/tktVYnuCm7yA+6wmCrzlWoIC68EgrzzaHZ6Yu59kvibfsMWerSkXRuYT9QNHN8Oe9MdcAQ=="
11	  },
12	  "business_category": 644,
13	  "merchant_country_code": "344",
14	  "merchant_type": "INDIVIDUAL",
15	  "registration_certificate_number": "5555-8888",
16	  "registration_certificate_date": "2025-08-27",
17	  "registration_certificate_copy": "w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs",
18	  "business": {
19		"business_type": "BOTH",
20		"website": "http://www.qq.com",
21		"store_address": "shenzhen nanshan tencent",
22		"mcc": "5045"
23	  },
24	  "apply_h5_payment": true,
25	  "h5_payment_apply_info": {
26		"website_url": "http://www.qq.com",
27		"domains": ["www.qq.com", "www.wechat.com"]
28  }
29}

3. encryption guide

Note on sensitive field encryption：

For parameters that contain sensitive information, such as contact information, a "field encryption" security mechanism is provided to make sure that the sensitive information can only be seen by the data recipient.

Encryption procedures

1、Perform the RSA encryption for the parameter values with the public key of the WeChat Pay Platform certificate. Use `RSAES-PKCS1-v1_5` as the filling scheme.

2、The encrypted ciphertext that is encoded with base64 is used as the value of the appropriate parameter in the request.

4. Response Parameters

Response for successful request:

Name	Variable Name	Type	Required	Description
Sub-merchant ID	sub_mchid	string[1,32]	Yes	Sub-merchant ID assigned by WeChat Pay Note:Only for Institutional mode Example: 1900000109
Verification status	verification_status	string[1,32]	Yes	Describe the review status of the sub-merchant: Under review: In the process of WeChat Pay review. The sub-merchant has no transaction authority and cannot initiate transactions (need to check the sub-merchant review status on the WeChat pay open platform, and transactions can only be made after the review is approved) Approved: WeChat Pay has passed the review, and sub-merchant can initiate normal transactions Example: Approved
Description	description	string[1,128]	No	Verification status description: Example: This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform.
H5 payment authorization state	h5_authorization_state	string[1,32]	No	Returned when apply_h5_payment is true; describe the H5 payment authorization state of the sub-merchant: APPROVED: H5 payment authorization already granted; UNAUTHORIZED: H5 payment authorization not granted, no H5 authorization application submitted; UNDER_REVIEW: H5 payment authorization application is currently under review; REJECTED: H5 payment authorization application has been rejected; UNDER_PUNISHMENT: H5 payment authorization has been applied and granted, but sub-merchant is currently being penalized; APPLICATION_FAILED: Failed to create the H5 payment authorization application. Example: APPROVED

Response for failed request:

Name

Variable Name

Type

Required

Description

Returned status code

code

string[1,32]

Yes

Error code. See the error code list for the enumerated values.

Returned information

message

string[1,256]

Yes

Returned message. It indicates the reason for the error if not empty.

Detailed error description

detail

object

It is returned when code is PARAM_ERROR. Details will be described below.

Detailed error description

Response Example:

SUCCESS（Approved）

1{
2		"sub_mchid": "20000100",
3		"verification_status": "Approved"
4}

SUCCESS（Under review）

1{
2		"sub_mchid": "20000100",
3		"verification_status": "Under Review",
4		"description": "This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform."
5}

ERROR

1{
2		"code": "INVALID_REQUEST",
3		"message": "Parameter format verification error",
4		"detail": {
5			"field": "#/properties/payer",
6			"value": "1346177081915535577",
7			"issue": "Does not match the ALLOF schema",
8			"location": "body"
9	}
10}

Also apply for H5 payment

1{
2	  "h5_authorization_state": "APPROVED",
3	  "sub_mchid": "20000100",
4	  "verification_status": "Approved"
5}

5. Error Codes

Error Message	Description	Solution
PARAM_ERROR	Req paramerror	For the specific parameter format, please see the relevant document.
SYSTEM_ERROR	System error please try again	System error. Re-initiate with the original parameters.
INVALID_REQUEST	Invaild request	Check your program according to the detailed description on the error returned by the API. You can view the specific details returned by the detail field.
INVALID_REQUEST	please add merchant by page	Log in to the merchant management backend to enter the sub-merchant information manually.
INVALID_REQUEST	business_code already exists	Define a unique identifier for different sub-merchants.
INVALID_REQUEST	Action has been taken against the merchant. The merchant is not allowed to request to enable H5 payment authorization.	Merchant payment permission has been penalized. Please contact the operation personnel to lift the penalty first.
INVALID_REQUEST	The submitted website or H5 payment domain name is at risk. Contact your BD for assistance.	The business website or H5 payment domain is blacklisted. Please contact the operation personnel to apply for an exemption.