Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Deduction Result Notification API

Latest update time:2021.08.19 Release notes


Note:

1. 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.


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


API Intro

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

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3


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.)

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、5.Get the corresponding parameters nonce and associated_ data for the algorithm described in resource.algorithm (currently AEAD_AES_256_GCM).

3、6.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.

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

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

Callback Example

Payment Success Result Notification

{
	"id": "EV-2018022511223320873",
	"create_time": "20180225112233",
	"resource_type": "encrypt-resource",
	"event_type": "TRANSACTION.SUCCESS",
	"resource": {
		"algorithm": "AEAD_AES_256_GCM",
		"ciphertext": "...",
		"nonce": "...",
		"associated_data": "",
	}
}

List of decrypted resource objects:



{
	"mchid": "10000100",
	"appid": "wx2421b1c4370ec43b",
	"out_trade_no": "20150806125346",
	"transaction_id": "1008450740201411110005820873",
	"attach": "支付测试",
	"trade_type": "AUTH",
	"bank_type": "CCB_DEBIT",
	"success_time": "2018-06-08T10:34:56+08:00",
	"trade_state": "SUCCESS",
	"trade_state_desc": "支付成功",
	"merchant_category_code": "1011",
	"contract_id": "Wx15463511252015071056489715",
	"payer": {
		"openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
	},
	"amount": {
		"total": 528800,
		"currency": "HKD",
		"payer_total": 518799,
		"payer_currency": "CNY",
		"exchange_rate": {
			"type": "SETTLEMENT_RATE",
			"rate": 8000000
		}
	},
	"promotion_detail": [{
		"promotion_id": "109519",
		"name": "单品惠-6",
		"scope": "SINGLE",
		"type": "DISCOUNT",
		"amount": 1,
		"currency": "HKD",
		"activity_id": "931386",
		"wechatpay_contribute_amount": 1,
		"merchant_contribute_amount": 0,
		"other_contribute_amount": 0,
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"goods_remark": "商品备注",
			"quantity": 1,
			"price": 528800
		}]
	}]
}
                              

{
	"sp_mchid": "10000100",
	"sp_appid": "wx2421b1c4370ec43b",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346",
	"transaction_id": "1008450740201411110005820873",
	"attach": "支付测试",
	"trade_type": "AUTH",
	"bank_type": "CCB_DEBIT",
	"success_time": "2018-06-08T10:34:56+08:00",
	"trade_state": "SUCCESS",
	"trade_state_desc": "支付成功",
	"merchant_category_code": "1011",
	"contract_id": "Wx15463511252015071056489715",
	"payer": {
		"sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
	},
	"amount": {
		"total": 528800,
		"currency": "HKD",
		"payer_total": 518799,
		"payer_currency": "CNY",
		"exchange_rate": {
			"type": "SETTLEMENT_RATE",
			"rate": 8000000
		}
	},
	"promotion_detail": [{
		"promotion_id": "109519",
		"name": "单品惠-6",
		"scope": "SINGLE",
		"type": "DISCOUNT",
		"amount": 1,
		"currency": "HKD",
		"activity_id": "931386",
		"wechatpay_contribute_amount": 1,
		"merchant_contribute_amount": 0,
		"other_contribute_amount": 0,
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"goods_remark": "商品备注",
			"quantity": 1,
			"price": 528800
		}]
	}]
}
                              

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 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
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] No 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] No 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 No Returned after successful payment. Payer information, which is detailed below
Name Variable Name Type Required Description
User ID (directly connected merchant] openid string[1,128] Yes Openid of the user under the merchant’s appid
Note: Only forCommon mode
Example:M3pxb1Q9zNjWeS6o
User ID (service provider] sp_openid string[1,128] Yes User’s unique ID under the corresponding merchant sp_appid, returned only when sp_appid is passed in
Note: Only forInstitutional mode
Example:M2pxb1Q9WNjWeS6o
User ID (sub-merchant] sub_openid string[1,128] No User’s unique ID under sub_appid of the acquiring bank, returned only when sub_appid is passed in
Note: Only forInstitutional mode
Example:M2pxb1Q9zNjWeS61
+Order amount amount object No Returned after successful payment. Order amount information, which is detailed below
Name Variable Name Type Required Description
Order amount total int Yes Total order amount, in the minimum unit of currency, which must be an integer. For details, please refer to transaction amount
Example:888
User payment amount payer_total int Yes User's actual payment amount, in the minimum unit of currency, which must be an integer. For details, please refer to the transaction amount
Example:888
Currency of order price currency string[1,16] Yes Three letter code complying with the ISO 4217 standard
Example:CNY
User’s payment currency payer_currency string[1,16] Yes Three letter code complying with the ISO 4217 standard
Example:HKD
+ Exchange rate information exchange_rate object No Exchange rate information object, which is detailed below
Name Variable Name Type Required Description
Exchange rate type type string[1,32] No SETTLEMENT_RATE, namely, the exchange rate of the price currency and settlement currency
Example:SETTLEMENT_RATE
Exchange rate value rate int No The rate value is the eighth power of the exchange ratio multiplied by 10.
If the price currency is the same as the settlement currency and the exchange ratio is 1, then rate is 100000000;
If the price currency is different from the settlement currency, e.g., the exchange ratio of US dollar to RMB is 6.5, then rate is 650000000
Example:80000000
+ Scene information scene_info object No Returned after successful payment. Scene information object, which is detailed below
Name Variable Name Type Required Description
Merchant-end device ID device_id string[1,32] No Terminal device ID (customized by the merchant, e.g., a store No.)
Example:013467007045764
Merchant-end device IP address device_ip string[1,40] No The device IP address at the merchant side, accessed from the public network export IP address, supporting IPv6
Example:128.0.0.1
+ Promotion function promotion_detail object No Returned after successful payment. Promotion function information, which is detailed below
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] No Promotion name
Example:Single item discount-6
Promotion scope scope string[1,32] No GLOBAL - Global coupon
SINGLE - Single item discount
Example:SINGLE
Promotion type type string[1,32] No 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] No Batch ID configured on the WeChat merchant background
Example:931386
Amount contributed by WeChat wxpay_contribute_amount int No 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 No 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 No Amount contributed by other contributive parties
Example:5
+ List of goods goods_detail Array No Goods information, in the JSON format
Name Variable Name Type Required Description
Goods ID goods_id string[1,32] Yes Consisting of one or more of half-angle upper and lower case letters, digits, strikethrough, and underscore
Example:Goods ID
Goods remark goods_remark string[1,128] No A remark field, returned according to the original configuration; the field is set when coupon/discount is configured on the WeChat background
Example:1001
Goods discount amount discount_amount int Yes Total discount amount of a single item
Example:100
Goods quantity quantity int Yes Quantity of goods bought by the user
Example:1
Goods price price int Yes Unit: cent. If the merchant provides a discount, the unit price after the discount needs to be transmitted (for example, if the user uses the paper discount 100-50 issued by the mall for a RMB100 order, the unit price of the goods in the activity should be the original unit price minus 50)
Example:10000

Returned 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
{
"code": "ERROR_NAME",
"message": "ERROR_DESCRIPTION",
}


Release notes

close
V1.0
2021.08.18
1.Deduction Result Notification API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global