Latest update time：2019.11.20 Release notes
For a period after a payment transaction has been completed and a refund is required by either the Payer or Merchant, the Merchant can refund the Payer via this API. After the WeChat payment system receives and verifies the refund request successfully, the Payer will be refunded with the request refund amount (less than or equal to the original payment amount) according to the refund rules.
1. Orders that have been completed for more than one year cannot be submitted for refund.
2. A refund for a transaction can be processed in the form of multiple partial refunds. In this case, the original order number is required and multiple refund numbers must be set. The total refund amount cannot exceed the original payment amount.
If the refund request is failed, please use the same out_refund_no for retrying.
1. Request frequency limit: 150qps, which means normal refund requests should be less than 150 times per secon.
2. Error or invalid request frequency limit: 6 qps, which means error or invalid refund requests should be less than 6 times per second.
partial refund for one order should be less than 50 times.
Request Url: https://api.mch.weixin.qq.com/secapi/pay/refund
Request Method: POST
Certificate Requirements: Two-way certificate is required.
Applicable Object: Common modeInstitutional mode
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Official Account ID | appid | String(32) | Yes | Specifies an 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 Sub 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 Sub 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 |
| Random string | nonce_str | String(32) | Yes | 32 characters or fewer. For more information, see Random String Algorithm . 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 parameter must be submitted if HMAC-SHA256 is chosen Example: HMAC-SHA256/MD5 |
| WeChat Order Number | transaction_id | String(32) | Choose one to submit | Specifies the WeChat payment order id number. Example: 1217752501201407033233368018 |
| Merchant Order Number | out_trade_no | String(32) | out_trade_no is an internal order number within the merchant’s system. transaction_id will be used over out_trade_no if they are both provided by the merchant. Example: 1217752501201407033233368018 |
|
| Merchant Refund Number | out_refund_no | String(32) | Yes | Specifies the internal refund number, which is unique in the system. A single transaction can be processed as multiple partial refunds, with the total sum of the partial refunds being equal to the original one. Example: 1217752501201407033233368018 |
| Total Amount | total_fee | int | Yes | Specifies the total order amount. The units are expressed in cents and must be an integer. For more information, see Payment Amount. Example: 100 |
| Refund Amount | refund_fee | int | Yes | Specifies the total refund amount for a transaction. The units are expressed in cents and shall be an integer. |
| Currency Type | refund_fee_type | String(8) | No | ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Currency Type. Example: USD |
| Refund Reason | refund_desc | String(80) | No | It will inform the shoppers the refund reason once merchants submit this field value. Example: Products sold out |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<sub_mch_id><![CDATA[452532745]]></sub_mch_id>
<nonce_str><![CDATA[0ScvLJ2uasseqcoQ]]></nonce_str>
<sign><![CDATA[2457A269C435031EB2F2E0EE531DABDD]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<transaction_id><![CDATA[4200001126202109090793359667]]></transaction_id>
<out_trade_no><![CDATA[1678371718207313]]></out_trade_no>
<out_refund_no><![CDATA[REF16001202]]></out_refund_no>
<refund_id><![CDATA[50201409582021110313317567694]]></refund_id>
<refund_channel><![CDATA[]]></refund_channel>
<refund_fee>1</refund_fee>
<coupon_refund_fee>0</coupon_refund_fee>
<total_fee>1</total_fee>
<cash_fee>7</cash_fee>
<fee_type><![CDATA[EUR]]></fee_type>
<coupon_refund_count>0</coupon_refund_count>
<cash_refund_fee>7</cash_refund_fee>
<refund_fee_type><![CDATA[EUR]]></refund_fee_type>
<cash_fee_type><![CDATA[CNY]]></cash_fee_type>
<cash_refund_fee_type><![CDATA[CNY]]></cash_refund_fee_type>
</xml>
Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.
| 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 |
When return_code is SUCCESS, return data will also include the following fields:
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Result Code | result_code | String(16) | Yes | SUCCESS/FAIL 1. SUCCESS: Receives refund application successfully. To get refund status, calling Query Refund API is required. 2. FAIL: Submitting refund application failed. Example: SUCCESS |
| Error Code | err_code | String(32) | No | For more information, please refer to error code list. Example: SYSTEMERROR |
| Error Code Description | err_code_des | String(32) | No | Describes result data. Example: System timed out |
| Official Account ID | appid | String(32) | Yes | The Official Account ID submitted when calling the interface Example: wx8888888888888888 |
| Merchant ID | mch_id | String(32) | Yes | The Merchant ID submitted when calling the interface Example: 1900000109 |
| Sub Official Account ID | sub_appid | String(32) | No | The Sub Official Account ID submitted when calling the interface 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 | The Sub Merchant ID submitted when calling the interface Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note: Only for Institutional mode Example: 1900000109 |
| 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: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| WeChat Order Number | transaction_id | String(32) | Yes | Specifies the WeChat payment order id Example：1217752501201407033233368018 |
| Merchant Order Number | out_trade_no | String(32) | Yes | Specifies the order number created within the Merchants' system, which is consistent with request. Example：1217752501201407033233368018 |
| Merchant Refund Number | out_refund_no | String(32) | Yes | Merchant Refund Number. |
| WeChat Refund Number | refund_id | String(32) | Yes | WeChat Refund Number. |
| Refund Amount | refund_fee | int | Yes | Specifies the total refund amount expressed in cents and must be an integer. Example: 100 |
| Currency Type | refund_fee_type | String(8) | Yes | ISO-4217 standard compliant and be described by three characters based code. The refund currency type must be same with the bid currency type. For more information, see Section 4.2 Currency Type. |
| Total Amount | total_fee | int | Yes | Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Payment Amount. Example：100 |
| Order Currency Type | fee_type | String(8) | No | 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 cash payment amount expressed in cents and must be an integer. For more information, see Payment Amount. |
| Currency Type | cash_fee_type | String(8) | Yes | Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Section 4.2 Currency Type. |
| Cash Refund Amount | cash_refund_fee | int | Yes | Specifies the cash refund amount expressed in cents and must be an integer. For more information, see Payment Amount. |
| Cash Refund Currency Type | cash_refund_fee_type | String(8) | No | Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type. |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<nonce_str><![CDATA[NfsMFbUFpdbEhPXP]]></nonce_str>
<sign><![CDATA[B7274EB9F8925EB93100DD2085FA56C0]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
<out_trade_no><![CDATA[1415757673]]></out_trade_no>
<out_refund_no><![CDATA[1415701182]]></out_refund_no>
<refund_id><![CDATA[2008450740201411110000174436]]></refund_id>
<refund_fee>1</refund_fee>
<cash_refund_fee_type><![CDATA[CNY]]></cash_refund_fee_type>
</xml>
| Name | Description | Reason | Solution |
|---|---|---|---|
| SYSTEMERROR | API return error | System timed out | Call this API again using the same parameters |
| BIZERR_NEED_RETRY | internal error | internal error caused by concurrency | Please retry with the same parameter and do not change the out_refund_no |
| TRADE_OVERDUE | Beyond refund period | The longest refund period of one order is 365 days | Please find another way to refund |
| ERROR | Business error | Business error when initiate refund | The detailed reason will return |
| USER_ACCOUNT_ABNORMAL | Refund request failed | User’s account cancelled | This error code means refund request failed, merchants need to handle the refund by themselves |
| INVALID_REQ_TOO_MUCH | Invalid request count reaches the limit | There are too much invalid requests | Please check whether your system is working well |
| NOTENOUGH | Not enough unsettled fund for refund | There is not enough unsettled fund for refund | This error code means refund request failed, merchants need to recall the refund API once there is enough unsettled fund, or retry it continuously |
| INVALID_TRANSACTIONID | Invalid transaction_id | Requested parameters are not correct | Incorrect request parameters. Check whether the original transaction ID exists or whether data failed to be returned from the payment interface. |
| PARAM_ERROR | Parameter error | Requested parameters are not correct | Incorrect request parameters. Check the parameters and call the Submit Refund API again. |
| APPID_NOT_EXIST | APPID DOES NOT EXIST | No APPID in this parameter | Check whether the provided APPID is correct |
| MCHID_NOT_EXIST | MCHID DOES NOT EXIST | No MCHID in this parameter | Check whether the provided MCHID is correct |
| APPID_MCHID_NOT_MATCH | appid does not match mch_id | appid does not match mch_id | Check whether appid belongs to the associated mch_id |
| REQUIRE_POST_METHOD | Use post method | Data is not transferred by post | Check whether data is submitted by POST method |
| SIGNERROR | Signature error | Incorrect signature result | Check whether the signature parameter and method complies with signature algorithm requirements |
| XML_FORMAT_ERROR | INVALID XML FORMAT | INVALID XML FORMAT | Check whether XML parameters are in the correct format |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证