Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Onboard Sub-Merchant API

Latest update time:2024.03.07 Release notes


Entering the sub merchant information to the system.

API intro

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

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
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:"["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.
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"]

Example:

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

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

Example:

<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>
<xml>
 <return_code><![CDATA[SUCCESS]]></return_code>
 <return_msg><![CDATA[OK]]></return_msg>
 <result_code><![CDATA[SUCCESS]]></result_code>
 <sign><![CDATA[EA89C5EA10D672044BA3527A9F4D291D]]></sign>
 <sub_mch_id><![CDATA[013467007045764]]></sub_mch_id>
 <verification_status><![CDATA[Under Review]]></verification_status>
 <description><![CDATA[This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform.]]></description>
<xml>
<xml>
 <return_code><![CDATA[FAIL]]></return_code>
 <return_msg><![CDATA[The registration_certificate_date does not conform to the requirements. Please refer to the applicable regulations.]]></return_msg>
<xml>
					<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>
 <h5_authorization_state><![CDATA[APPROVED]]></h5_authorization_state>
</xml>

Release notes

关闭
V1.3
2023.9.13
1. increase fields : Apply for H5 payment authorization; H5 business website URL; H5 payment domain names; office_phone; 2. increase return fields : H5 payment authorization state; 3. increase error code: INVALID_REQUEST; INVALID_REQUEST;
V1.2
2023.6.20
1. Update fields : merchant_name; business_category; registration_certificate_copy; office_phone; verification_status
V1.1
2020.12.04
1. Added fields including merchant_country_code, merchant_type, mcc, registration_certificate_number,registration_certificate_date, registration_certificate_copy, business_type, app_download, business_website, office_account, mini_program, store_address, store_photos, director_name, director_id_number, principal_name, principal_id_number, settlement_bank_number.
Deleted fileds including website and merchant_introduction
V1.0
2019.12.22
1. Onborading Sub Merchant API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global