Product Capability API Dictionary Interface Rules Access Specification FAQs Terms Update Log

Payments
- Quick Pay
- Native Payment
- JSAPI Payment
- In-App Payment
- Mini Program Payment
- H5 Payment
- Auto-Debit Payment
Funding Products
- Funds Distribution(Transaction)
- Funds Distribution(Operate)
- Funds Distribution(Refund)
- Funds Distribution(Bill and Fund)
Other Products
- Merchant Onboard
- H5 Payment Authorization Application
- Customs Declaration

Create Domain Modification Application

Update Time：2025.01.07

This API is used to initiate a web payment domain modification request for the institution/service provider and sub-merchants.

Note：

Due to product iteration, the H5 payment authorization can be applied for using the Merchant Onboarding interface.

For more information, please refer to:

Merchant Onboarding（Introduction）
Merchant Onboarding（Preparation）
Merchant Onboarding（Development Guidelines）
Merchant Onboarding（APIs）

1. API Intro

Applicable object： Institutional mode Service Provider Mode

API rules：https://apihk.mch.weixin.qq.com/v3/global/merchant/h5/permission/domain/applications

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
Sub-merchant ID	sub_mchid	string[1, 32]	No	Body ID of a sub-merchant under the current institution/service provider. If this field is not specified, the web payment domain of the merchant is modified. Example: 2491935631
Web payment domain	domains	array	Yes	Body The domain that pulls web payment. Note that the submitted domain list will overwrite the original effective domain list. Example: ["qq.com"]
Sub-merchant's website URL	website_url	string[1, 128]	Yes	Body The URL of the website on which the sub-merchant's business categories, products/services and prices are displayed and users can Example: https://qq.com
Website business page screenshot	website_business_page_pics	array	No	Body This field is required when the website is not launched. The value is a media ID, which can be obtained via the image upload API Example: ["6uqyGjvHzOhsLleGFQVRF"]
Website homepage screenshot	website_homepage_pics	array	No	Body This field is required when the website is not launched. The value is a media ID, which can be obtained via the image upload API Example: ["6uqyGjvHzOhsLleGFQVRF"]
Sub-merchant's website status	website_state	string	No	Body The status of the sub-merchant's website. Valid values: HAS_LAUNCHED: The website has been launched. This value is used by default if this field is not specified. UN_LAUNCHED: The website is not launched. Example: HAS_LAUNCHED
Callback API provided by merchants to receive review results	notify_url	string[1, 128]	No	Body The HTTPS protocol is required. If the URL cannot be accessed, the merchant will not receive any WeChat notifications. The notification URL must be directly accessible without any parameters. For more information, please refer to Domian Modification Result Notification Example: https://pay.weixin.qq.com/wxpay/pay.action
Merchant request ID	out_applyment_id	string[6, 32]	Yes	Body Internal request ID in the merchant system. The request ID can only contain numbers, letters, underscores (_), hyphens (-), and asterisks (*), and is unique under the same merchant ID. Example: 123456

Request example

JSON

1{
2  "domains": ["qq.com"],
3  "notify_url": "https://pay.weixin.qq.com/wxpay/pay.action",
4  "sub_mchid": "2491935631",
5  "website_business_page_pics": ["6uqyGjvHzOhsLleGFQVRF"],
6  "website_homepage_pics": ["6uqyGjvHzOhsLleGFQVRF"],
7  "website_state": "HAS_LAUNCHED",
8  "website_url": "https://qq.com",
9  "out_applyment_id": "123456"
10}

3. Response Parameters

Response for a successful request

Name	Variable Name	Type	Required	Description
Sub-merchant ID	sub_mchid	string[1, 32]	Yes	ID of the sub-merchant under the current institution/service provider. Example: 2491935631
Sub-merchant's website status	website_state	string	Yes	The status of the sub-merchant's website. Valid values: HAS_LAUNCHED: The website has been launched. UN_LAUNCHED: The website is not launched. Example: HAS_LAUNCHED
Web payment domain	domains	array	Yes	The domain that pulls web payment. Note that the submitted domain list will overwrite the original effective domain list. Example: qq.com
Sub-merchant's website URL	webiste_url	string[1, 128]	Yes	The URL of the website on which the sub-merchant's business categories, products/services and prices are displayed and users can place orders. Example: https://qq.com
Website business page screenshot	website_business_page_pics	array	No	This field is required when the website is not launched. The value is a media ID, which can be obtained via the image upload API Example: ["6uqyGjvHzOhsLleGFQVRF"]
Website homepage screenshot	website_homepage_pics	array	No	This field is required when the website is not launched. The value is a media ID, which can be obtained via the image upload API Example: ["6uqyGjvHzOhsLleGFQVRF"]
Application ID	applyment_id	int	Yes	Unique ID of the H5 authorization application. Example: 1000000
Rejection reason	audit_reject_detail	string[1, 500]	No	The reason why the request is rejected. Example: Illegal content of website homepage screenshot
Request status	applyment_state	string	No	The status of the web payment domain modification request. Valid values: PENDING: The request is not created. Query again later or check whether the submission is normal. UNDER_REVIEW: The request is created and under review. APPROVED: The request is approved. REJECTED: The request is rejected. See audit_reject_detail for the rejection reason. Example: PENDING
Callback API provided by merchants to receive review results	notify_url	string[1, 128]	No	The HTTPS protocol is required. If the URL cannot be accessed, the merchant will not receive any WeChat notifications. The notification URL must be directly accessible without any parameters. For more information, please refer to Domian Modification Result Notification Example: https://pay.weixin.qq.com/wxpay/pay.action
Merchant request ID	out_applyment_id	string[6, 32]	Yes	Internal request ID in the merchant system. The request ID can only contain numbers, letters, underscores (_), hyphens (-), and asterisks (*), and is unique under the same merchant ID. Example: 123456

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.

Detailed error description

Response Example:

SUCCESS

1{
2   "applyment_id": 1000000,
3  "applyment_state": "PENDING",
4  "audit_reject_detail": "Illegal content of website homepage screenshot",
5  "domains": ["qq.com"],
6  "notify_url": "https://pay.weixin.qq.com/wxpay/pay.action",
7  "sub_mchid": "2491935631",
8  "webiste_url": "https://qq.com",
9  "website_business_page_pics": ["6uqyGjvHzOhsLleGFQVRF"],
10  "website_homepage_pics": ["6uqyGjvHzOhsLleGFQVRF"],
11  "out_applyment_id": "123456",
12  "website_state": "HAS_LAUNCHED"
13}

ERROR

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

4. Error Codes

Error Codes	Error Message	Description	Solution
500	SYSTEM_ERROR	System error	Call the API again later with the same parameters.
429	FREQUENCY_LIMIT_EXCEED	Frequency limit, please try it later	Frequency limit, please try it later
400	INVALID_REQUEST	No permission for H5 payment and cannot modify the H5 domain name.	Please complete the H5 payment authorization application first and then initiate the call again.
400	PARAM_ERROR	The website has not launched. Upload the business page screenshot.	Please re-initiate the call after uploading a screenshot of the business website.
400	INVALID_REQUEST	There is missing merchant basic information, such as merchant certificate number, contact, and email. Log in to the merchant platform to modify the information and try again. (Institution portal: Institutional Merchant Platform; service provider portal: Service Merchant Platform	Merchant information is missing. Please visit the corresponding link to supplement and resubmit.
400	INVALID_REQUEST	Merchant certificate expired. Log in to the merchant platform to update the information and try again. (Institution portal: Institutional Merchant Platform; service provider portal: Service Merchant Platform)	Merchant certificate has expired. Please visit the corresponding link to make the necessary changes and resubmit.
400	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.
400	INVALID_REQUEST	The parent-child relationship is invalid. Check if the sub-merchant belongs to the service provider.	The parent-child merchant relationship cannot be established. Please verify and try again.
400	PARAM_ERROR	The website has not launched. Upload the website homepage screenshot.	Please upload the screenshot of the homepage and try again.
400	PARAM_ERROR	Upload the Company Registration Certificate, Company Introduction and Description of the Business.	Please upload the company registration certificate, company introduction, and business description and try again.