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.27 Release notes

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


Pathparameter is a path parameter.
Queryparameter needs to be passed in the request URL.
Bodyparameter 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
Name Variable Name Type Required Description
Full Name name string[1,64] Yes Specifies the contact person’s name.
Show: Encryption is required for this field, please refer to the field encryption guide
Example: Bob Zhang
Mobile Phone No. phone string[1,32] Yes Specifies the mobile phone number of the merchant for any urgent issues. Please prefix the phone number. See the appendix for prefixes.
Show: Encryption is required for this field, please refer to the field encryption guide
Example: +8613633334444
Email email string[1,256] Yes Specifies the contact email of the merchant.
Show: Encryption is required for this field, please refer to the field encryption guide
Example: test@test.com
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] No 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] No 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] No Body Settlement bank account number (settlement bank information)
Example: 555588889999
Business information business object Yes Body Business information, the detail is listed below
Name Variable Name Type Required Description
Business type business_type string[1,7] Yes There are three business types:ONLINE,
OFFLINE or BOTH
Example: BOTH
Download link of APP app_download string[1,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 website string[1,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[1,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[1,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[1,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[1,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: ["1beSM1UtWFrTTtCNYOrlllzaoIwc-RjARO-AP_QprCc", "1beSM1UtWFrTTtCNYOrlliXeq8spgRNG46iLYGMaeqc", "1beSM1UtWFrTTtCNYOrllooH4tOjn3F-NKYa_K6dAV8"]
MCC mcc string[1,4] Yes Mcc code, see to Merchant category codes
Example: 4214
Director information director object No Body Director information,
Specify this field only when the Merchant Type is ENTERPRISE (Not mandatory)
The detail is listed below
Name Variable Name Type Required Description
Director Name name string[1,128] No Director name. Specify this field only when the Merchant Type is ENTERPRISE (Not mandatory).
Example: Bob
Director ID Number number string[1,128] No Director's ID number. Specify this field only when the Merchant Type is ENTERPRISE (Not mandatory)
Example: 5555-8888
Principal information principal object No Body Principal information,
Specify this field only when the Merchant Type is INDIVIDUAL (Not mandatory)
The detail is listed below
Name Variable Name Type Required Description
Principal Name name string[1,128] No Principal's ID number. Specify this field only when the Merchant Type is INDIVIDUAL (Not mandatory)
Example: Bob
Principal ID Number number string[1,128] No Principal's ID number. Specify this field only when the Merchant Type is INDIVIDUAL (Not mandatory)
Example: 5555-8888
Apply for H5 payment authorization apply_h5_payment boolean No Apply for H5 payment authorization.
The values are true or false.
Example: true
H5 payment application info h5_payment_apply_info object No Body H5 payment application info.
Required when apply_h5_payment is true.
Name Variable Name Type Required Description
H5 business website URL website_url string[1,128] Yes/No Required when apply_h5_payment is true. 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 domains array Yes/No Required when apply_h5_payment is true. 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"]

Request Eample:

{
		"sp_appid": "wx82ec4jy334ner1",
		"sp_mchid": "2422128905",
		"name": "Merchant name",
		"shortname": "shortname",
		"office_phone": "+86075586010000",
		"contact": {
			"email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
			"name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
			"phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
		},
		"business_category": 644,
		"merchant_country_code": "344",
		"merchant_type": "ENTERPRISE",
		"registration_certificate_number": "519723407213085723",
		"registration_certificate_date": "2022-06-03",
		"settlement_bank_number": "559304578245298347923856",
		"business": {
			"business_type": "ONLINE",
			"mcc": "5344",
			"mini_program": "wx8888888888888888"
		},
		"director": {
			"name": "Tom",
			"number": "1234567890"
	}
}
  
{
	  "sp_appid": "wx82ec4jy334ner1",
	  "sp_mchid": "2422128905",
	  "name": "Merchant name",
	  "shortname": "Merchant shortname",
	  "office_phone": "+86075586010000",
	  "contact": {
		"name": "yuhZiIh1C8x2UQ9FZY9ojV65HmpttQUSeOi3MdWy52ZoQUSpBUb52dJ+puGkzeGzjuXxJHbD0EGMDOfikdsAr7sqXhqfJexJKN7TSrwewbJqOEJ7fFjB3fqGVu6b/gfq6HduulBgaAlwZ5RcxpEVrAVM54mY3Z9HiX21fcqs65bti/QjEVCg0e1LlypKR3eqdW/XZi3q0gQ3hI0J9crA9OekIGc3M6OZ34aue5VdOd0PTCT99rIcI6N1VuapH2a7hY3fpgGAGxnYgNhUGsTgNoKso0pVCLEl0OlwvYCqmht3foyXtU/4WwwkpK8oFW1yQP3X7D1jXInEakWDFRAcUw==",
		"phone": "XuafjSrgtiqsSzq4QdPEfrfspphyNnVSp9EKg9gM2/szy6ai+q5geSVE5VRRoQlVfiPYK/cFyTk009Cb8GDQilhL0X0HoxcBpcuRIaaW1+LOfMz0POAonG22yER/0486MhQrfNGaCb8QBTfeiIjZT2RPIpvTNyz6cESDV+Y1cD2JKOfK73MU3XKmgQz4mulb9sKdbNtGJV4wc03cR0Md/lnz9QnW5RulHu3bEwVRwtTSGJuMoZntkYhkn4KMRh/z93ri7wKd+DkIfIDMDTzvA2MUn4LW/PJtiKaNP5sOdpmpsw63kOsx5J32mTU7+0qz654MGayTFMW+fSgHBBNYVw==",
		"email": "m+6RSfdEWSAZfrSfrP+FAPzh+jrFPQDPVCaslWwN3EdmsTliLvrUdcYnYuiILHpkZv1E6NNo592KOeznsDrKKWio00qfrurMhTAlneucHfU64yTvIsA6YqeBf8Uqfdad2BG0mYqbIn7AunnE2xqCoqS4W/lJPPROP7VU2/rFzkJx0KMInCo9FErktmN9nNQfhK5dpVis+YNv5SBQ7xSaVAUkTio4xNap1CWpVUIn8CjMgaSa7XJAOwNrNE6+ohU3pA/wlPALNIzYnNu/tktVYnuCm7yA+6wmCrzlWoIC68EgrzzaHZ6Yu59kvibfsMWerSkXRuYT9QNHN8Oe9MdcAQ=="
	  },
	  "business_category": 644,
	  "merchant_country_code": "344",
	  "merchant_type": "INDIVIDUAL",
	  "registration_certificate_number": "5555-8888",
	  "registration_certificate_date": "2025-08-27",
	  "registration_certificate_copy": "w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs",
	  "business": {
		"business_type": "BOTH",
		"website": "http://www.qq.com",
		"store_address": "shenzhen nanshan tencent",
		"mcc": "5045"
	  },
	  "apply_h5_payment": true,
	  "h5_payment_apply_info": {
		"website_url": "http://www.qq.com",
		"domains": ["www.qq.com", "www.wechat.com"]
  }
}

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 forInstitutional 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 No It is returned when code is PARAM_ERROR. Details will be described below.
Name Variable Name Type Required Description
The location of incorrect parameter field string[1,256] Yes If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Value of the incorrect parameter value string[1,256] Yes Value of the incorrect parameter
Cause of error issue string[1,256] Yes Cause of error
Location of the incorrect parameter location string[1,256] No body: The incorrect parameter is in the JSON for request body
url: The incorrect parameter is in the request URL
query: The incorrect parameter is in the querystring of the request

Response Example:

{
		"sub_mchid": "20000100",
		"verification_status": "Approved"
}
{
		"sub_mchid": "20000100",
		"verification_status": "Under Review",
		"description": "This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform."
}
{
		"code": "INVALID_REQUEST",
		"message": "Parameter format verification error",
		"detail": {
			"field": "#/properties/payer",
			"value": "1346177081915535577",
			"issue": "Does not match the ALLOF schema",
			"location": "body"
	}
}
{
	  "h5_authorization_state": "APPROVED",
	  "sub_mchid": "20000100",
	  "verification_status": "Approved"
}

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.


    Page Navigation

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

置顶