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.
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:15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - in total 24h4m)
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.
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
| 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 |
| 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(32) | 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 |
<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>
| Field Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Return Status Code | return_code | string(16) | Yes |
Set to SUCCESS or FAIL Specifies communicating label instead of transaction label.
The status of the transaction is determined by the value of the result_code field. Example：SUCCESS |
| Return Data | return_msg | string(128) | No | If not empty, this is the error description. If not empty,
this is the error description Signature Failure Parameter format checking error Example：Signature Failure |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
</xml>
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证