Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Payment Result Notification API

Latest update time:2019.11.20 Release notes


After completing a payment, the WeChat payment system will send the relevant payment result and user information to the Merchant. When this happens, the Merchant’s backend will need to receive the result and return a reply to the WeChat payment system.

Tips:

1. When interacting with this API, if the WeChat payment system does not receive a response from the Merchant backend indicating success or timeout, the WeChat payment system will consider it as an unreceived notification and initiate further payment result notifications at a regular interval, such as 8 times in 30 minutes, so as to ensure successful receipt. However, the WeChat payment system cannot ensure successful receipt of payment notifications in every case. (Notification frequency: 15/15/30/180/1800/1800/1800/1800/3600s)


2. As payment result notifications may be sent from the WeChat payment system to the Merchant’s backend multiple times, a single payment result might be notified to the Merchant's backend multiple times. For this reason, the Merchant's system must be able to handle duplicate notifications properly.


3. The best practices for dealing with such case: when a notification is received and processed, the enclosed payment data should be checked first to confirm whether the payment result has previously been processed or not. If so, return the processed result; if no, proceed with processing the result first before returning. Before checking the payment data, a transaction lock shall be used for concurrency to prevent data corruption caused by transaction race conditions.


4. To avoid receiving fake notifications, merchants must verify the signature of the notification and check whether the order amount in the notification is the same with the one in merchant’s system.


API Intro

Request Url: This URL may be configured via notify_url, a parameter submitted via the 【Unified Order API】, If merchants can't open this URL, they will not be able to receive any notifications sent from the WeChat payment system.

Request Method: POST

Certificate Requirements: No certificate is required.

Developers can login to the merchant platform of WeChat Pay and join the API warning group.

Applicable Object: Common modeInstitutional mode

Request Parameters

Name ID Type Required Description
Return Status Code return_code String(16) Yes SUCCESS or FAIL
Specifies communicating label instead of transaction label. The status of a transaction is determined by the value of result_code.
Example: SUCCESS
Return Data return_msg String(128) No If not empty, this is the error description
Signature failure
Parameter format checking error
Example: Signature failure

If return_code is SUCCESS, return data will also include the following fields:

Name ID Type Required Description
Official Account ID appid String(32) Yes Specifies Official Account ID assigned by WeChat
Example: wx8888888888888888
Merchant ID mch_id String(32) Yes Specifies merchant ID assigned by WeChat Payment
Example: 1900000109
Sub Official Account ID sub_appid String(32) No Specifies an Official Account ID assigned by WeChat
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888
Sub  Merchant ID sub_mch_id String(32) Yes Specifies merchant ID assigned by WeChat Payment
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109
Device ID device_info String(32) No Specifies the terminal device ID assigned by WeChat Payment
Example: 013467007045764
Random String nonce_str String(32) Yes 32 characters or fewer
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm.
Example: C380BEC2BFD727A4B6845133519F3AD6
Sign Type sign_type String(32) No Currently HMAC-SHA256 and MD5 are supported, default is MD5. This field is only required when sign_type is HMAC-SHA256.
Example: HMAC-SHA256
Service Result result_code String(16) Yes SUCCESS or FAIL
Example: SUCCESS
Error Code error_code String(32) No The error code returned
Example: SYSTEMERROR
Error Code Description error_code_des String(128) No The detailed error description returned.
Example: System error
User Tag openid String(128) Yes The user id of the Payer provided by the WeChat system in OpenID format as unique tag on merchant’s appid. Also it is unique to each appid instance.
About how to get openid, please refer to get openid api.
Example: wxd930ea5d5a258f4f
Follows Official Account or not is_subscribe String(1) Yes  Specifies whether the payer follows the associated official account or not, with Y meaning ‘follows’ and N meaning ’not follows’.
Example: Y
Sub User Tag sub_openid String(128) No The user id of the Payer provided by the WeChat system in OpenID format as unique tag on merchant’s appid. Also it is unique to each appid instance.
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
About how to get sub_openid, please refer to get openid api.
Note: Only for Institutional mode
Example: wxd930ea5d5a258f4f
Follows Sub Official Account or not sub_is_subscribe String(1) No  Specifies whether the payer follows the associated official account or not, with Y meaning ‘follows’ and N meaning ’not follows’.
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: Y
Transaction Type trade_type String(16) Yes Set as JSAPI, NATIVE, or APP
Example: JSAPI
Payment Bank bank_type String(16) Yes Use strings for bank type. For more information, see attachments.
Example: CMC
Total Amount total_fee Int Yes Specifies the total amount for a transaction in cents. For more information, see Payment Amount.
Example: 100
Currency Type fee_type String(8) Yes ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type
Example: CNY
Cash Payment Amount cash_fee Int Yes Specifies the total amount of a transaction. For more information, see Payment Amount.
Example: 100
Cash Type cash_fee_type String(16) No Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type
Example: CNY
Specifies the number of a WeChat payment order transaction_id String(32) Yes Specifies the WeChat payment order id number
Example: 1217752501201407033233368018
Merchant Order Number out_trade_no String(32) Yes Specifies an order number created by a Merchants' system, which is consistent with request.
Example: 1212321211201407033568112322
Merchant's Data Package attach String(128) No Specifies merchant's data package, which is returned as it is.
Example: 123456
Payment End Time time_end String(14) Yes Specifies the time of completing payment in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10. For more information, see Time Protocol.
Example: 20141030133525
Exchange Rate rate_value String(16) Yes The value is 10 to the 8th power times of the exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000
Example: 650000000

Example:


<xml>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <attach><![CDATA[Payment Testing]]></attach>
   <bank_type><![CDATA[CFT]]></bank_type>
   <fee_type><![CDATA[CNY]]></fee_type>
   <is_subscribe><![CDATA[Y]]></is_subscribe>
   <mch_id><![CDATA[10000100]]></mch_id>
   <nonce_str><![CDATA[5d2b6c2a8db53831f7eda20af46e531c]]></nonce_str>
   <openid><![CDATA[oUpF8uMEb4qRXf22hE3X68TekukE]]></openid>
   <out_trade_no><![CDATA[1409811653]]></out_trade_no>
   <result_code><![CDATA[SUCCESS]]></result_code>
   <return_code><![CDATA[SUCCESS]]></return_code>
   <sign><![CDATA[B552ED6B279343CB493C5DD0D78AB241]]></sign>
   <sub_mch_id><![CDATA[10000100]]></sub_mch_id>
   <time_end><![CDATA[20140903131540]]></time_end>
   <total_fee>1</total_fee>
   <trade_type><![CDATA[JSAPI]]></trade_type>
   <transaction_id><![CDATA[1004400740201409030005092168]]></transaction_id>
</xml> 
							  
    
{
JAVA示例代码
}
    


Release notes

关闭
V1.0
2019.11.20
1. Payment Result Notification released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2019 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

Wechat Pay Global

ICP证

粤B1.B2-20090295