Authorization Result Notification

Update Time：2025.01.07

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）

Authorization Result Notification

Latest update time：2023.12.05 Release notes

Notes:

● The same notification may be sent to the merchant system multiple times. The merchant system must be able to process repeated notifications properly. We recommend that the system first check the status of the business data after receiving a notification to verify whether the notification has been processed. If yes, the system directly returns a success result; if not, the system processes the notification. Before the status check, the system can lock the business data for concurrency control to avoid data confusion caused by reentrant functions.

Attention: The merchant system must verify the signature of the result notification and whether the notification content is consistent with the information on the merchant system to prevent losses caused by "false notifications" due to data leakage.

1. API Intro

Applicable object： Institutional mode Service Provider Mode

API rules：The URL is set by the notify_url parameter of the Create Authorization Application. 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. Example: success_notify_url: "https://pay.weixin.qq.com/wxpay/pay.action"

Request method：POST

2. Notification Rules

After a web payment request is reviewed, WeChat sends the review result and the request information to the merchant. The merchant needs to process the received notification data and return a response according to the document specifications. For security concern, the notification data is encrypted, so the merchant needs to decrypt it first.

If the response received by WeChat is not success or the response from the merchant times out, WeChat considers the notification a failure and will send the notification again based on certain policies to maximize the success rate. However, WeChat does not guarantee a successful notification. The callback is performed at a tiered frequency of 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h with a total of 24h4m.

3. Notification Messages

The review result notification is sent to the notification URL set by the merchant with the POST method and transmitted in the request body in JSON format. The notification data contains encrypted payment result details.

The following describes how to decrypt the certificate:

(1) Obtain the merchant's key from the merchant platform and record it as "key".
(2) Obtain the parameters nonce and associated_data based on the algorithm described in resource.algorithm (which is AEAD_AES_256_GCM).
(3) Decrypt the resource.ciphertext with key, nonce, and associated_data to get the resource object in JSON format.

Note: For the API information of the AEAD_AES_256_GCM algorithm, see rfc5116. The length of the key used for WeChat Pay is 32 bytes, the length of the random string nonce is 12 bytes, and the length of the associated_data value is less than 16 bytes or may be zero.

4. Request Parameters

Name	Variable Name	Type	Required	Description
Notification ID	id	string[1,36]	Yes	Unique ID of the notification. Example: f7c34059-0f2d-5b32-ba33-a42dks0597c5
Notification creation time	create_time	string[1,64]	Yes	The time when the notification was created. It is in rfc3339 format. For example, 2018-06-08T10:34:56+08:00 indicates 10:34:56 Beijing time on June 8, 2018. Example: 2018-06-08T10:34:56+08:00
Notification type	event_type	string[1,32]	Yes	Notification type. The type of an approval notification is APPLYMENT_STATE.APPROVED. Example: APPLYMENT_STATE.APPROVED
Notification data type	resource_type	string[1,32]	Yes	The type of the notification resource data. The type of resource data for an approval notification is applyment. Example: applyment
Callback summary	summary	string[1,64]	Yes	Callback summary. Example: Web payment authorization request notification
Notification data	resource	object	Yes	Resource data of the notification.

5. Notification Signature

Even if a notification is encrypted, it cannot be confirmed that the notification comes from WeChat. WeChat will sign the notification sent to the merchant and place the signature value in the HTTP header Wechatpay-Signature of the notification. The merchant should verify the signature to make sure that the request comes from WeChat rather than a third party. For information on the signature verification algorithm, see 《WeChat Pay API V3 Signature Verification》。

Review result notification

1{
2    "id":"f7c34059-0f2d-5b32-ba33-a42dks0597c5",
3    "create_time":"2019-12-12T16:54:38+08:00",
4    "resource_type":"applyment",
5    "event_type":"APPLYMENT_STATE.APPROVED",
6    "summary":"Web payment authorization request notification",
7    "resource":{
8        "original_type":"applyment",
9        "algorithm":"AEAD_AES_256_GCM",
10        "ciphertext":"xxx",
11        "associated_data":"applyment",
12        "nonce":"j9g1wAzF9Xn1"
13     }
14}

A resource object obtained after the merchant decrypts the "resource" object

JSON

1{
2  "applyment_id": 100000,
3  "applyment_state": "PENDING",
4  "applyment_type": "APPLY_FOR_PAYMENT_AUTHORITY",
5  "business_description": "Founded in November 1998, Tencent is an Internet-based platform company that uses technology to enrich the lives of Internet users and assist enterprises with digital upgrade.Our mission is "Value for Users, Tech for Good".",
6  "company_register_cert": "6uqyGjvHzOhsLleGFQVRF",
7  "domains": ["qq.com"],
8  "notify_url": "https://pay.weixin.qq.com/wxpay/pay.action",
9  "audit_reject_detail": "The merchant's certificate does not meet requirements.",
10  "sub_mchid": "2491935631",
11  "transaction_limit_type": "UN_LAUNCHED_WEBSITE_LIMIT",
12  "website_business_page_pics": ["6uqyGjvHzOhsLleGFQVRF"],
13  "website_homepage_pics": ["6uqyGjvHzOhsLleGFQVRF"],
14  "website_state": "HAS_LAUNCHED",
15  "website_url": "https://qq.com"
16}

6. Review Result Notification Parameters

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
Web payment domain	domains	array	Yes	The domain that pulls web payment. Example: ["qq.com"]
Company profile and business description	business_description	string[1, 500]	No	This field is required when NO_LIMIT is selected for transaction_limit_type. Example: Founded in November 1998, Tencent is an Internet-based platform company that uses technology to enrich the lives of Internet users and assist enterprises with digital upgrade. Our mission is "Value for Users, Tech for Good".
Certificate of incorporation	company_register_cert	string[1, 128]	No	This field is required when NO_LIMIT is selected for transaction_limit_type. Example: 6uqyGjvHzOhsLleGFQVRF
Limit type	transaction_limit_type	string	Yes	Web payment limit type. Valid values: UN_LAUNCHED_WEBSITE_LIMIT: The payment limit for a website not launched. Limited Quota: ①1000 CNY/day/person if touched the transaction limit of the H5 payment, this customer couldn't pay to this sub-merchant through H5 channel on this day （re-accumulate in the next day） ② 50000 CNY/day/sub-merchant if touched the transaction limit of the H5 payment, this sub-merchant couldn't recevie money through H5 channel on this day（re-accumulate in the next day） NORMAL_LIMIT: The payment limit authorized when the information is incomplete. This value is used by default if this field is not specified. Limited Quota： ①50000 CNY/day/person,if touched the payment limit of the H5 payment limited quota, this customer couldn't pay to this sub-merchant through H5 channel on this day （re-accumulate in the next day） ② 500000 CNY/day/sub-merchant, if touched the payment limit of the H5 payment limited quota, this sub-merchant couldn't recevie money through H5 channel on this day （re-accumulate in the next day） NO_LIMIT: No payment limit. Example: UN_LAUNCHED_WEBSITE_LIMIT
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"]
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
Sub-merchant's website URL	website_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
Application ID	applyment_id	int	Yes	Unique ID of the H5 authorization application. Example: 100000
Rejection reason	audit_reject_detail	string[1, 500]	No	The reason why the request is rejected. Example: The merchant's certificate does not meet requirements.
Request status	applyment_state	string	Yes	Web payment request status. 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
Request type	applyment_type	string	Yes	Web payment request type. Valid values: APPLY_FOR_PAYMENT_AUTHORITY: The request for web payment authorization. APPLY_FOR_RELIEVE_LIMITED: The request for web payment limit removal. Example: APPLY_FOR_PAYMENT_AUTHORITY
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. Example: https://pay.weixin.qq.com/wxpay/pay.action

7. Notification Response

Name	Variable Name	Type	Required	Description
Returned status code	code	string[1,32]	Yes	For more information, see the returned status code description below. Example: SUCCESS
Returned message	message	string[1,256]	No	Returned message, which presents the cause of the error. Example: System error

Scenario 1: Success example

1200
2{
3	"code": "SUCCESS",
4	"message": "OK"
5}

Scenario 2: Failure example 200

1{
2    "code": "SYSTEM_ERROR",
3    "message": "System error"
4}