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}  

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.