Signing and Termination Result Callback

Update Time：2025.01.07

Tips：

● The same notification may be sent to the merchant system multiple times. The merchant system must be able to process duplicate notifications properly. First check the status of the corresponding business data when receiving a notification for processing, and determine whether the notification has been processed. If not, the notification should be processed; if it has been processed, the success result should be returned. Before status checking and processing of the business data, a data lock should be used to implement concurrency control and avoid data confusion caused by function reentry.

● The merchant system must perform signature verification for the content of the notification, and verify whether the data fields of the notification are consistent with those of the merchant side, thus preventing a "false notification" caused by data leakage and capital loss.

1. API Intro

Applicable object: Common mode Institutional mode

Request URL: The notification path of the signing result is the success_notify_url field uploaded by the signing interface merchant; the termination result notification path is the termination callback address provided by the merchant when applying for the deduction permission and deduction template ID. The address must be an HTTPS protocol address. If the link cannot be accessed, the merchant will not receive the notification from WeChat. The notification URL must be a URL that is directly accessible and cannot carry parameters. For example: notify_url: http://pay.weixin.qq.com/wxpay/123456789

Request method: POST

2. Notification Rules

When the contract is signed or terminated successfully (no notification is sent if it fails), WeChat will asynchronously notify the merchant of the relevant contract signing and termination information. The merchant needs to receive and handle the notification and return a response. The notification result data will be encrypted to ensure security. The merchant needs to decrypt the notification data before getting the result data.

When interacting with the background notification, if the response received by WeChat from the merchant is not success or timed out, WeChat thinks the notification fails. WeChat will periodically resend the notification according to the specified policy to maximize the success rate of the notification, but WeChat does not guarantee final success of the notification. (The notification frequency is 15/15/30/180/1800/1800/1800/1800/3600 seconds.)

3. Notification Message

The notifications of contract signing and termination results access the notification URL set by the merchant using the POST method, and the notification data is transmitted through the request body (BODY) in the JSON format. The data in the notification includes the details about the encrypted payment result.

The procedure of how to decrypt the notification data is described as follows.

1、Obtain the merchant's notification key from the merchant platform and record it as key.
2、For the algorithm described in `resource.algorithm` (which is AEAD_AES_256_GCM), obtain the corresponding `parameters nonce` and `associated_data`.
3、Decrypt the `resource.ciphertext` with `key`, `nonce`, and `associated_data` to obtain the resource object in JSON form.

Note: A For the information on the API of the algorithm `AEAD_AES_256_GCM`, 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` is less than 16 bytes or may be empty ero.

4. Request Parameters

Name	Variable Name	Type	Required	Description
Notification ID	id	string[1,32]	Yes	The unique notification ID Example: EV-2018022511223320873
Notification creation time	create_time	string[1,64]	Yes	Notification creation time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. Example: 2018-06-08T10:34:56+08:00
Notification type	event_type	string[1,32]	Yes	Type of the notification, which is PAPAY.SIGN for the signing success notification, and PAPAY.TERMINATE for the terminating success notification. Example: PAPAY.TERMINATE
Notification data type	resource_type	string[1,32]	Yes	The type of the notification resource data. The type of resource data for a successful payment notification is encrypt-resource. Example: encrypt-resource
Notification data	resource	object	Yes	Resource data of a notification

5. Notification Signature

Encryption does not guarantee that the notification request comes from wechat pay. Wechat pay will sign the notification sent to the merchant and put the signature value in the Wechatpay-Signature of Notification's HTTP header. The merchant should verify the signature to confirm that the request is from wechat pay, not other third parties. For the algorithm of signature verification, please refer to 【Wechat Pay API V3 Signature Scheme】

Signing and Termination Result Notification

1{
2    "id":"EV-2018022511223320873",
3    "create_time":"20180225112233",
4    "resource_type":"encrypt-resource",
5    "event_type":"PAPAY.TERMINATE",
6    "resource" : {
7        "algorithm":"AEAD_AES_256_GCM",
8        "ciphertext": "...",
9        "nonce": "...",
10        "associated_data": ""
11    }
12}

List of decrypted resource objects:

Scenario 1:Common mode

1{
2	"mchid": "10000091",
3	"out_contract_code": "100001256",
4	"plan_id": 123,
5	"contract_id": "Wx15463511252015071056489715",
6	"appid": "wxcbda96de0b165486",
7	"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
8	"contract_termination_mode": "USER",
9	"operate_time ": "2015-09-01T10:00:00+08:00 "
10}

Scenario 2:Service Provide Mode/Institution Mode

1{
2	"sp_mchid": "10000091",
3	"sub_mchid": "10000097",
4	"out_contract_code": "100001256",
5	"plan_id": 123,
6	"contract_id": "Wx15463511252015071056489715",
7	"sp_appid": "wxcbda96de0b165486",
8	"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
9	"contract_termination_mode": "USER",
10	"operate_time": "2015-09-01T10:00:00+08:00"
11}

6. Signing and Termination Result Parameters

Name	Variable Name	Type	Required	Description
Merchant ID	mchid	string[1,32]	Yes	Merchant ID assigned by WeChat Pay Note: Only for Common mode Example: 1900000109
APPID	appid	string[1,32]	Yes	APPID corresponding to the mobile app applied for by the merchant on the WeChat Open Platform Note: Only for Common mode Example: wx8888888888888888
Merchant ID of the service provider	sp_mchid	string[1,32]	Yes	The institution's merchant ID allocated by WeChat Pay Note: Only for Institutional mode Example: 10000098
Sub-merchant ID	sub_mchid	string[1,32]	Yes	Sub-merchant ID allocated by WeChat Pay Note: Only for Institutional mode Example: 10000097
Organization APPID	sp_appid	string[1,32]	Yes	APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform Note: Only for Institutional mode Example: wxcbda96de0b165486
Contracted merchant APPID	sub_appid	string[1,32]	No	APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform Note: Only for Institutional mode Example: wxcbda96de0b165484
Signed contract No.	out_contract_code	string[1,32]	Yes	Signed contract No. Example: 100001256
Template ID	plan_id	int	Yes	When a merchant applies for deduction permission to WeChat Pay, WeChat Pay will allocate a unique deduction template ID to the merchant Example: 123
Auto-debit contract ID	contract_id	string[1,32]	Yes	Auto-debit contract ID returned by WeChat after successful signing Example: Wx15463511252015071056489715
User ID under the merchant’s appid	openid	string[1,16]	Yes	Openid of the user under the merchant’s appid Example: ouFhd5X9s9WteC3eWRjXV3lea123
Time of operation	operate_time	string[1,16]	Yes	Time of operation Example: 2015-09-01T10:00:00+08:00
Time of contract expiration	contract_expire_time	string[1,64]	No	Time of contract expiration Example: 2015-09-01T10:00:00+08:00
Termination mode of the contract	termination_mode	string[1,16]	No	When state is TERMINATED, the value indicates the termination mode of the contract USER-Terminated by the user MERCHANT-Terminated by the merchant API PLATFORM-Terminated by the merchant platform Example: USER

7. Response Result

After the merchant's backend has properly processed the notification, HTTP status code 200 or 204 needs to be returned. No specific content is required for 204.If other HTTP status codes are returned, WeChat Pay will deem the notification as a failure, and will send the notification regularly by following the aforesaid policies.

Note：If the merchant's backend fails to process a response, WeChat Pay will record the response message. It is recommended to return in the following format.

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

Scenario 1:Common mode

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

Scenario 2:Service Provide Mode/Institution Mode

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