Latest update time：2024.03.07 Release notes
Entering the sub merchant information to the system.
Request Url: https://api.mch.weixin.qq.com/secapi/mch/addInstitutionsub
Request method:POST
Certificate Requirements：Yes
Applicable object:Institutional mode
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Official Account ID | app_id | string(32) | Yes | Specifies Official Account ID assigned
by WeChat Example：wxd678efh567hg6787 |
| Vendor ID | mch_id | string(32) | Yes | Specifies vendor ID assigned by
WeChat Payment Example：1230000109 |
| Signature | sign | string(32) | Yes | Specifies a signature. Note:Default 'MD5',only support 'MD5' Example：C380BEC2BFD727A4B6845133519F3AD6 |
| Channel ID | channel_id | string(20) | No | Get from WeChat business platform(pay.wechat.com/cn) Example：12343234 |
| Merchant name | merchant_name | string(128) | Yes | 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 | merchant_shortname | string(64) | Yes | Specifies the brief merchant name, which will be shown to the consumers Example：FS |
| Institution Merchant id | merchant_remark | string(20) | Yes | The information noted by the institution for the merchant can be the merchant number in the institution system Example：2020052501 |
| 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 If the merchant is a nature person or sole proprietor, please select INDIVIDUAL. Example：ENTERPRISE |
| Business Category | business_category | string(3) | Yes | Specifies the business category according to your business license, please refer to the business ID list of WeChat payment. see to Business Category Example：644 |
| 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. 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(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. 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(128) | No | 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 |
| 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： |
| 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 |
| 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. 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 names | 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"] |
<xml>
<mch_id>1230000109</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>
<settlement_bank_number><![CDATA[55558888]]></settlement_bank_number>
<sign><![CDATA[C47005DF5722D862EFF30E7B8964AE17]]></sign>
</xml>| 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 |
| 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 |
| 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 |
| Verification status | verification_status | string(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(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(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 |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<result_code><![CDATA[SUCCESS]]></result_code>
<sign><![CDATA[2FB58D2C8CF07E2097D628FA10F05287]]></sign>
<sub_mch_id><![CDATA[013467007045764]]></sub_mch_id>
<verification_status><![CDATA[Approved]]></verification_status>
</xml>Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证