WeChat Pay Open Platform

返回上一层 Home / Onboard Sub Merchant / Modify Sub-merchant API

Modify Sub-merchant API

Latest update time：2024.03.27 Release notes

This api is used to update the existing information of sub merchants

Tips：

Compared to Onboarding API, field "merchant_remark" is deleted while field "sub_mch_id" is added.

API intro

Request Url: https://api.mch.weixin.qq.com/secapi/mch/modifyInstitutionsub

Request method:POST

Certificate Requirements：Yes

Applicable object:Institutional mode

Parameter Settings

Name	ID	Type	Required	Description
Official Account ID	app_id	string(32)	Yes	Specifies Official Account ID assigned by WeChat Note：The value of this field cannot be modified Example：wxd678efh567hg6787
Vendor ID	mch_id	string(32)	Yes	Specifies vendor ID assigned by WeChat Payment Note：The value of this field cannot be modified Example：1230000109
Sub_mch_id	sub_mch_id	string(32)	Yes	The unique merchant identification for the institution Note：The value of this field cannot be modified Example：013467007045764
Signature	sign	string(32)	Yes	Specifies a signature. For more information Signature Algorithm. Example：C380BEC2BFD727A4B6845133519F3AD6
Merchant name	merchant_name	string(128)	Yes	Specifies the complete merchant entity name Example：Fruit Store
Channel ID	channel_id	string(20)	No	Get from WeChat business platform(pay.wechat.com/cn) Example：12343234
Merchant shortname	merchant_shortname	string(64)	Yes	Specifies the brief merchant name, which will be shown to the consumers Example：FS
Registered Country or Region	merchant_country_code	string(3)	Yes	The country where the company was registered, see to CountryCode Example：344
Merchant Type	merchant_type	string(10)	Yes	ENTERPRISE or INDIVIDUAL Example：ENTERPRISE
Business Category	business_category	string(3)	Yes	Specifies the business category, please refer to the business ID list of WeChat payment. see to Business Category Example：344
MCC	mcc	string(4)	Yes	Mcc code, see to MCC code Example：4214
Registration Certificate Number	registration_certificate_number	string(50)	Yes	Company registration document No. Required when Merchant Type is ENTERPRISE. Example：5555-8888
Expiration Date of Registration Certificate	registration_certificate_date	string(10)	Yes	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. Required when Merchant Type is ENTERPRISE. Example：2020-10-16
Copy of Registration Certificate	registration_certificate_copy	string(128)	No	The photocopy of the company registration document. The value should be the media ID returned by Uploading Image API. Example：w7yQFawBtja5uEdm
Business type	business_type	string(7)	Yes	There are three business types: ONLINE, OFFLINE or BOTH Example：BOTH
Download link of APP	app_download	string(128)	Yes/No	The download link of merchant’s APP. app_download, bus_website，office_account, mini_program choose one field to submit if business type is ONLINE or BOTH Example：https://download.qq.com
Business website	business_website	string(128)	Yes/No	The business website, app_download, bus_website，office_account, mini_program choose one field to submit if business type is ONLINE or BOTH Example：https://www.qq.com
Official account	office_account	string(128)	Yes/No	Merchant’s official account. app_download, bus_website，office_account, mini_program choose one field to submit if business type is ONLINE or BOTH Example：wx8888888888888888
Mini Program	mini_program	string(128)	Yes/No	Merchant’s mini program. app_download, bus_website，office_account, mini_program choose one field to submit if business type is ONLINE or BOTH Example：wx8888888888888888
Store address	store_address	string(128)	Yes/No	Store address, required if business type is OFFLINE or BOTH Example：10F World Finance Centre (South Office), 11 Canton Road, Tsim Sha Tsui, Hong Kong
Store photos	store_photos	string(1024)	No	Store photos, the value should be at least 3 media IDs, which is returned by Uploading Image API. Multiple images are submitted in JSON format. Required if business type is OFFLINE or BOTH(Not mandatory) Example：["ySdrQ_p2Jgs","ySdVr5RdEI","yS2xjJdSjsKM"]
Director Name	director_name	string(128)	No	Director name. Specify this field only when the secondary merchant type is ENTERPRISE(Not mandatory). Example：Bob Zhang
Director ID Number	director_id_number	string(128)	No	Director's ID number. Specify this field only when the secondary merchant type is ENTERPRISE.(Not mandatory). Example：5555-8888
Principal Name	principal_name	string(128)	No	Principal name. Specify this field only when the secondary merchant type is INDIVIDUAL.(Not mandatory). Example：Bob Zhang
Principal ID Number	principal_id_number	string(128)	No	Principal's ID number. Specify this field only when the secondary merchant type is INDIVIDUAL.(Not mandatory). Example：5555-8888
Customer Service Phone Number.	office_phone	string(32)	Yes	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
Full Name	contact_name	string(64)	Yes	Specifies the contact person’s name. Example：Bob Zhang
Mobile Phone No.	contact_phone	string(32)	Yes	Specifies the mobile phone number of the merchant for any urgent issues. Please prefix the phone number. See the appendix for prefixes. Example：+8613633334444
Email	contact_email	string(256)	Yes	Specifies the contact email of the merchant. Example：test@test.com
Settlement Bank No.	settlement_bank_number	string(128)	No	Settlement bank account number (settlement bank information) Example：555588889999
Apply for H5 payment authorization	apply_h5_payment	string(4)	No	Apply for H5 payment authorization? The values are YES or NO. If you already have H5 payment authorization but need to modify the H5 payment domain names, please fill in as YES. Example：YES
H5 business website URL	h5_website_url	string(128)	Yes/No	Required when apply_h5_payment is YES. Includes the sub-merchant's main business, goods/services and their prices, and website for offline orders from users. Example：https://qq.com
H5 payment domain name	h5_domains	string(512)	Yes/No	Required when apply_h5_payment is YES. Domain name from which H5 payment will be launched; up to 5; submit in json array format. Note: The new list of domain names submitted will overwrite the existing list of payment domain names. Example：["www.qq.com","www.weixin.com"]

Example：

<xml> 				
 <mch_id>1230000109</mch_id>
 <mch_id>12345678</mch_id>
 <app_id><![CDATA[wx7bc98d929da735fe]]></app_id>
 <merchant_name><![CDATA[Merchant name]]></merchant_name>
 <merchant_shortname><![CDATA[ABC]]></merchant_shortname>
 <office_phone><![CDATA[075586010000]]></office_phone>
 <business_category><![CDATA[343]]></business_category>
 <merchant_remark><![CDATA[202012041]]></merchant_remark>
 <merchant_country_code><![CDATA[344]]></merchant_country_code>
 <contact_name><![CDATA[bob]]></contact_name>
 <contact_phone><![CDATA[+8618688886666]]></contact_phone>
 <contact_email><![CDATA[test@tencent.com]]></contact_email>
 <merchant_type><![CDATA[INDIVIDUAL]]></merchant_type>
 <registration_certificate_number><![CDATA[5555-8888]]></registration_certificate_number>
 <registration_certificate_date><![CDATA[2025-08-27]]></registration_certificate_date>
 <registration_certificate_copy><![CDATA[w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs]]></registration_certificate_copy>
 <business_type><![CDATA[BOTH]]></business_type>
 <business_website><![CDATA[http://www.qq.com]]></business_website>
 <store_address><![CDATA[First Street]]></store_address>
 <mcc><![CDATA[5045]]></mcc>
 <apply_h5_payment><![CDATA[YES]]></apply_h5_payment>
 <h5_website_url><![CDATA[http://www.qq.com]]></h5_website_url>
 <h5_domains><![CDATA[["www.qq.com","www.weixin.com"]]]></h5_domains>
 <sign><![CDATA[C47005DF5722D862EFF30E7B8964AE17]]></sign>
</xml>

    
｛
JAVA示例代码
｝

Return Data

Name	ID	Type	Required	Description
Return Status Code	return_code	string(16)	Yes	SUCCESS or FAIL Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field. Example：SUCCESS
Return Data	return_msg	string(128)	No	If not empty, the returned info is the error description. Signature failure Parameter format checking error Example：Signature failure

If return_code is SUCCESS, return data will also include the following fields:

Name	ID	Type	Required	Description
Service Result	result_code	string(32)	Yes	SUCCESS/FAIL Example：FAIL
Error Code	err_code	string(32)	No	Please refer to the error code list Example：INVALID_REQUEST
Error Code Description	err_code_des	string(128)	No	Describes result data Example：System error
Signature	sign	string(32)	Yes	Specifies a signature. For more information Signature Algorithm. Example：C380BE7519F3AD6
Sub-Merchant ID	sub_mch_id	string(32)	Yes	Specifies the sub merchant ID by WeChat Example：013467007045764
H5 payment authorization state	h5_authorization_state	string(32)	No	Returned when apply_h5_payment is YES; 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

Example：

<xml> 
 <return_code><![CDATA[SUCCESS]]></return_code>     
 <return_msg><![CDATA[OK]]></return_msg>     
 <result_code><![CDATA[SUCCESS]]></result_code> 
 <sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>     
 <sub_mch_id><![CDATA[013467007045764]]></sub_mch_id>    
</xml>

<xml> 
 <return_code><![CDATA[SUCCESS]]></return_code>     
 <return_msg><![CDATA[OK]]></return_msg>     
 <result_code><![CDATA[SUCCESS]]></result_code> 
 <sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>     
 <sub_mch_id><![CDATA[013467007045764]]></sub_mch_id>    
 <verification_status>CDATA[Approved]]></verification_status>    
 <h5_authorization_state>CDATA[APPROVED]]></h5_authorization_state>    
</xml>

Error Codes

Name	Description	Reason	Solution
INVALID_REQUEST	HTTP GET method not supported	Use POST method. Check and call again.	Debugging by developer
INVALID_REQUEST	Invalid XML format	Invalid XML format. Check and call again.
SIGNERROR	Signature validation	Signature validation failed. Check and try again.
INVALID_REQUEST	Use UTF-8 character encoding	XXX does not use UTF-8 character encoding. Check and try again. E.g. Domain name for Official Account Payment is not using UTF-8 character encoding. Check and try again.
PARAM_ERROR	Character length limit reached	XXX has invalid input. Check and submit again.	Automated checks and filters
PARAM_ERROR	Regular Validation	XXX has invalid format. Check and try again.	Automated checks and filters
INVALID_REQUEST	Entry permissions	No permissions. Check and try again.	Check permissions
INVALID_REQUEST	Certificate Required	Retrieving serial number of client certificate failed Retrieving?Distinguished Name (DN) field from client certificate failed Certificate validation failed. Check and try again.	Check certificate
INVALID_REQUEST	Inappropriate term(s) validation is required for Contacts, and vendor's short name, and vendor's full name	System error occurred during validation of vendor information. Try to call again. System error occurred during validation of vendor information. Try to call again. Input field contains inappropriate term(s). Check and input again. Input field contains inappropriate term(s) that do not comply with the service rules. Check and input again. Company cannot access WeChat Pay due to a violation. Contact Customer Service for more details. Company cannot access WeChat Pay via the application channel due to agreement protection. Contact Customer Service for more details. Input field contains inappropriate term(s) that do not comply with the service rules. Check and input again.	Automated checks and filters
SYSTEMERROR	System error occurred when creating a sub-vendor	System error occurred when creating a sub-vendor. Try again later.	Contact WeChat Pay Support
INVALID_REQUEST	Apply for H5 payment failed	The sub-merchant has not pass the review and cannot be modified.	Please be patient and wait for the approval before submitting again.
INVALID_REQUEST	Apply for H5 payment failed	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	Apply for H5 payment failed	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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Onboarding Sub-Merchant API

Modify Sub-merchant API

Tips：

API intro

Parameter Settings

Example：

Return Data

Example：

Error Codes

Release notes