Signing and Termination Result Callback API
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 |
| Name |
Variable Name |
Type |
Required |
Description |
| Encryption algorithm type |
algorithm |
string[1,32] |
Yes |
The algorithm that encrypts the payment result data. Only AEAD_AES_256_GCM is supported.
Example: AEAD_AES_256_GCM |
| Data ciphertext |
ciphertext |
string[1,1048576] |
Yes |
The ciphertext of the payment result encoded with Base64 |
| Additional data |
associated_data |
string[1,16] |
No |
Additional data used for encryption |
| Random string |
nonce |
string[1,32] |
Yes |
The random string used for encryption |
|
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】
{
"id":"EV-2018022511223320873",
"create_time":"20180225112233",
"resource_type":"encrypt-resource",
"event_type":"PAPAY.TERMINATE",
"resource" : {
"algorithm":"AEAD_AES_256_GCM",
"ciphertext": "...",
"nonce": "...",
"associated_data": ""
}
}
List of decrypted resource objects:
{
"mchid": "10000091",
"out_contract_code": "100001256",
"plan_id": 123,
"contract_id": "Wx15463511252015071056489715",
"appid": "wxcbda96de0b165486",
"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
"contract_termination_mode": "USER",
"operate_time ": "2015-09-01T10:00:00+08:00 "
}
{
"sp_mchid": "10000091",
"sub_mchid": "10000097",
"out_contract_code": "100001256",
"plan_id": 123,
"contract_id": "Wx15463511252015071056489715",
"sp_appid": "wxcbda96de0b165486",
"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
"contract_termination_mode": "USER",
"operate_time": "2015-09-01T10:00:00+08:00"
}
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 forCommon 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 forCommon 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 forInstitutional mode
Example: 10000098 |
| Sub-merchant ID |
sub_mchid |
string[1,32] |
Yes |
Sub-merchant ID allocated by WeChat Pay
Note: Only forInstitutional 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 forInstitutional 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 forInstitutional 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 |
200
{
"code": "SUCCESS",
"message": "OK"
}
{
"code": "SYSTEM_ERROR",
"message": "ERROR"
}
