Deduction Result Notification

Update Time：2025.01.07

After the deduction is completed, wechat will send the relevant payment results and user information to the merchant in the form of data flow.

Note:

● 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 link is set through the notify_url parameter submitted in [Deduction to Place Order]. If the link cannot be accessed, the merchant will not receive the notification from WeChat. 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. Example: notify_url: “http://pay.weixin.qq.com/wxpay/pay.action"

Request method: POST

2. Notification Rules

After the deduction, WeChat will send the relevant payment result and user information to the merchant in the form of data stream. The merchant needs to receive and process the information, and return the response according to the document specifications. 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 deduction result notification accesses 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、Get the corresponding parameters nonce and associated_ data for the algorithm described in resource.algorithm (currently AEAD_AES_256_GCM).
3、Use key, nonce, and associated_data to decrypt the data ciphertext resource.ciphertext and get the resource object in the JSON form.

Note: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 zero.

4. Request Parameters

Name	Variable Name	Type	Required	Description
Notification ID	id	string[1,36]	Yes	The unique notification ID Example：f7c34059-0f2d-5b32-ba33-a42dks0597c5
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 TRANSACTION.SUCCESS for the payment success notification Example：TRANSACTION.SUCCESS
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】

Payment Success Result Notification

1{
2	"id": "f7c34059-0f2d-5b32-ba33-a42dks0597c5",
3	"create_time": "20180225112233",
4	"resource_type": "encrypt-resource",
5	"event_type": "TRANSACTION.SUCCESS",
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": "10000100",
3	"appid": "wx2421b1c4370ec43b",
4	"out_trade_no": "20150806125346",
5	"transaction_id": "1008450740201411110005820873",
6	"attach": "Custom data",
7	"trade_type": "AUTH",
8	"bank_type": "CCB_DEBIT",
9	"success_time": "2018-06-08T10:34:56+08:00",
10	"trade_state": "SUCCESS",
11	"trade_state_desc": "Payment failed. Please order again to make payment",
12	"merchant_category_code": "1011",
13	"contract_id": "Wx15463511252015071056489715",
14	"payer": {
15		"openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
16	},
17	"amount": {
18		"total": 528800,
19		"currency": "HKD",
20		"payer_total": 518799,
21		"payer_currency": "CNY",
22		"exchange_rate": {
23			"type": "SETTLEMENT_RATE",
24			"rate": 8000000
25		}
26	},
27	"promotion_detail": [{
28		"promotion_id": "109519",
29		"name": "Single item discount-6",
30		"scope": "SINGLE",
31		"type": "DISCOUNT",
32		"amount": 1,
33		"currency": "HKD",
34		"activity_id": "931386",
35		"wechatpay_contribute_amount": 1,
36		"merchant_contribute_amount": 0,
37		"other_contribute_amount": 0,
38		"goods_detail": [{
39			"goods_id": "iphone6s_16G",
40			"goods_remark": "1001",
41			"quantity": 1,
42			"price": 528800
43		}]
44	}]
45}

Scenario 2:Service Provide Mode/Institution Mode

1{
2	"sp_mchid": "10000100",
3	"sp_appid": "wx2421b1c4370ec43b",
4	"sub_mchid": "20000100",
5	"out_trade_no": "20150806125346",
6	"transaction_id": "1008450740201411110005820873",
7	"attach": "Custom data",
8	"trade_type": "AUTH",
9	"bank_type": "CCB_DEBIT",
10	"success_time": "2018-06-08T10:34:56+08:00",
11	"trade_state": "SUCCESS",
12	"trade_state_desc": "Payment failed. Please order again to make payment",
13	"merchant_category_code": "1011",
14	"contract_id": "Wx15463511252015071056489715",
15	"payer": {
16		"sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
17	},
18	"amount": {
19		"total": 528800,
20		"currency": "HKD",
21		"payer_total": 518799,
22		"payer_currency": "CNY",
23		"exchange_rate": {
24			"type": "SETTLEMENT_RATE",
25			"rate": 8000000
26		}
27	},
28	"promotion_detail": [{
29		"promotion_id": "109519",
30		"name": "Single item discount-6",
31		"scope": "SINGLE",
32		"type": "DISCOUNT",
33		"amount": 1,
34		"currency": "HKD",
35		"activity_id": "931386",
36		"wechatpay_contribute_amount": 1,
37		"merchant_contribute_amount": 0,
38		"other_contribute_amount": 0,
39		"goods_detail": [{
40			"goods_id": "iphone6s_16G",
41			"goods_remark": "1001",
42			"quantity": 1,
43			"price": 528800
44		}]
45	}]
46}

6. Payment Success Notification 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]

APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform
Note: Only for Institutional mode
Example：wxcbda96de0b165484

Merchant order No.

out_trade_no

string[1,32]

Yes

Returned merchant order No.
Example：1217752501201407033233368018

WeChat Pay order No.

transaction_id

string[1,32]

Yes

WeChat Pay order No.
Example：10000097

Merchant data

attach

string[1,127]

Additional data, returned in the query API and payment notification without any changes; this field is used for the custom order data carried by the merchant
Example：Custom data

Transaction type

trade_type

string[1,16]

Yes

Deduction payment
Example：AUTH

Paying bank

bank_type

string[1,32]

Returned after successful payment. Bank type is a bank ID of string type. For the list of specific values, please refer to bank type
CMC and other bank card types in the Chinese mainland
WPHK: payment by Hong Kong Wallet
Example：WPHK

Payment completion time

success_time

string[1,64]

Yes

Payment completion time, in the rfc3339 format, e.g., 2018-06-08T10:34:56+08:00 indicates 10:34:56 a.m. on June 8, 2018 of Beijing time
Example：2018-06-08T10:34:56+08:00

Transaction state

trade_state

string[1,32]

Yes

SUCCESS — Payment success
REFUND — Transfer to refund
NOTPAY — Not paid
CLOSED — Closed
PAYERROR — Payment failed
USERPAYING — payment in progress
Example：SUCCESS

Transaction state description

trade_state_desc

string[1,256]

Yes

Description of the current order status and guidance for the next operation
Example：Payment failed. Please order again to make payment

Merchant category code (MCC]

merchant_category_code

string[1,16]

Yes

Merchant category code
Example：1011

Auto-debit contract ID

contract_id

String

Yes

Auto-debit contract ID returned by WeChat after successful signing
Example：Wx15463511252015071056489715

Payer

payer

object

Body Returned after successful payment. Payer information, which is detailed below

Payer

Order amount

amount

object

Body Returned after successful payment. Order amount information, which is detailed below

Order amount

Scene information

scene_info

object

Body Returned after successful payment. Scene information object, which is detailed below

Scene information

Promotion function

promotion_detail

array

Body Returned after successful payment. Promotion function information, which is detailed below

Promotion function

Name

Variable Name

Type

Required

Description

Coupon ID

promotion_id

string[1,32]

Yes

Coupon/discount or price reduction ID

Example:109519

Promotion name

name

string[1,64]

Promotion name

Example:Single item discount-6

Promotion scope

scope

string[1,32]

GLOBAL - Global coupon
SINGLE - Single item discount

Example:SINGLE

Promotion type

type

string[1,32]

COUPON - Coupon, a recharge coupon that generates capital flow (the coupon currency of overseas merchants is the same as the payment currency)
DISCOUNT - Discount, a recharge discount that does not generate capital flow (the discount currency of overseas merchants is the same as the price currency)

Example:DISCOUNT

Discount amount

amount

int

Yes

Amount of discount enjoyed by the user

Example:5

Discount currency

currency

string[1,16]

Yes

Three letter code complying with the ISO 4217 standard

Example:HKD

Activity ID

activity_id

string[1,32]

Batch ID configured on the WeChat merchant background

Example:931386

Amount contributed by WeChat

wxpay_contribute_amount

int

Specifically referring to the discount created by the WeChat Pay merchant platform; the mount contributed is equal to the total amount of the discount

Example:0

Amount contributed by the merchant

merchant_contribute_amount

int

Specifically referring to the discount created by the merchant; the mount contributed is equal to the total amount of the discount

Example:0

Other contributed amount

other_contribute_amount

int

Amount contributed by other contributive parties

Example:5

List of goods

goods_detail

array

Goods information, in the JSON format

List of goods

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}