Latest update time：2019.11.20 Release notes
After submitting Submit Refund, this API can be called to check the refund status. After submitting a refund, there may be a delay in processing the refund: 20 minutes for refunding to Balance and 3 working days for refunding to a bank card.
1. Please use the merchant refund number for refund query once the partial refund is more than 20 times for one order.
2. If one order has been partial refunded more than 10 times, the query refund result will only return the top 10 records in default. If merchants want to return the other partial refund records, parameter “offset” could be used to get the other records.
Request Url: https://api.mch.weixin.qq.com/pay/refundquery
Request Method: POST
Certificate Requirements: No certificate is required.
Applicable Object: Common modeInstitutional mode
Note: All subscripts such as $n are started from 0.
| 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 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 field is only required when sign_type is HMAC-SHA256 Example：HMAC-SHA256 |
| WeChat Order Number | transaction_id | String(28) | Choose one to submit | Specifies the WeChat payment order id number Example: 1217752501201407033233368018 |
| Merchant Order Number | out_trade_no | String(32) | Specifies an internal order number created by the Merchant’s system Example： 1217752501201407033233368018 |
|
| Merchant Refund Number | out_refund_no | String(32) | Merchant Refund Number Example： 1217752501201407033233368018 |
|
| WeChat Refund Number | refund_id | String(28) | WeChat Refund Number This field will supply the refund_id, out_refund_no, out_trade_no, or transaction_id. Their priority is as shown below: refund_id >out_refund_no >transaction_id >out_trade_no Example： 1217752501201407033233368018 |
|
| Offset value | offset | int | NO | The offset value when partial refund records are more than 10 Example: 10 |
<xml>
<appid>wx2421b1c4370ec43b</appid>
<mch_id>10000100</mch_id>
<nonce_str>0b9f35f484df17a732e537c37708d1d0</nonce_str>
<out_refund_no>1217752501201407033233368018 </out_refund_no>
<out_trade_no>1415757673</out_trade_no>
<refund_id>1217752501201407033233368018</refund_id>
<transaction_id>1217752501201407033233368018</transaction_id>
<sign>66FFB727015F450D167EF38CCC549521</sign>
</xml>
| 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. 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 |
|---|---|---|---|---|
| Service Result | result_code | String(16) | Yes | SUCCESS or FAIL SUCCESS indicates that Submit Refund is received successfully. The refund result can be queried via the Query Refund API. FAIL Example： SUCCESS |
| Error Code | err_code | String(32) | No | For more information, please refer to error code list Example： SYSTEMERROR |
| Error Description | err_code_des | String(32) | No | Describes result data Example： System error |
| 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 | 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(28) | Yes | 32 characters or fewer Example： 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| Signature | sign | String(64) | Yes | Specifies a signature. For more information, see Signature Algorithm. Example： C380BEC2BFD727A4B6845133519F3AD6 |
| WeChat Order Number | 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 internal order number created by the Merchant’s system Example： 1217752501201407033233368018 |
| Total Amount | total_fee | int | Yes | Specifies the total order amount expressed in cents and must be an integer. For more information, see Payment Amount Example： 100 |
| Order 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： GBP |
| 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 Example： 100 |
| Payment Currency Type | cash_fee_type | String(8) | No | Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type. Example： CNY |
| Total refund count | total_refund_count | int | No | The total refund records count for the current transaction, will only return when offset is submitted Example： 5 |
| Refund Count | refund_count | int | Yes | Specifies returned recorded refund counts Example： 1 |
| Merchant Refund Number | out_refund_no_$n | String(32) | Yes | Merchant Refund Number $n is the subscript, starting from 0. e.g: out_refund_no_$0 Example： 1217752501201407033233368018 |
| WeChat Refund Number | refund_id_$n | String(32) | Yes | WeChat Refund Number $n is the subscript, starting from 0. e.g: refund_id_$0 Example： 1217752501201407033233368018 |
| Refund Channel | refund_channel_$n | String(16) | No | ORIGINAL: Refund to original payment account BALANCE: Refund to Balance OTHER_BALANCE: Refund to balance of other WeChat account since the original account is abnormal OTHER_BANKCARD: Refund to other bank card since the original bank card is abnormal $n is the subscript, starting from 0. e.g: refund_channel_$0 Example： ORIGINAL |
| Refund Amount | refund_fee_$n | int | Yes | Specifies the total refund amount expressed in cents and must be an integer. For more information, see Payment Amount A refund can be processed as multiple partial refunds. $n is the subscript, starting from 0. e.g: refund_fee_$0 Example： 100 |
| Refund Status | refund_status_$n | String(16) | Yes | Refund Status: SUCCESS: Refunded successfully REFUNDCLOSE: Refund closed PROCESSING: Refund is pending $n is the subscript, starting from 0. e.g: refund_status_$0 Example： SUCCESS |
| Account Received Refund | refund_recv_accout_$n | String(64) | Yes | The account which finally received the refund: 1.Back to bankcard: {bank name}{bank type}{tail numbers} 2.Back to balance: 支付用户零钱 3.Back to merchant 商户基本账户Merchants’ basic account 商户结算银行账户Merchants’ bank account $n is the subscript, starting from 0. e.g: refund_recv_accout_$0 Note:Chinese is the API return value Example： 招商银行信用卡0403 |
| Refund Success Time | refund_success_time_$n | String(20) | No | Refund success time, only returned when the refund the successfully complete. $n is the subscript, starting from 0. e.g: refund_success_time_$0 Example： 2016-07-25 15:26:26 |
| Exchange Rate | rate | 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>
<mch_id><![CDATA[10000100]]></mch_id>
<nonce_str><![CDATA[TeqClE3i0mvn3DrK]]></nonce_str>
<out_refund_no_0><![CDATA[1415701182]]></out_refund_no_0>
<out_trade_no><![CDATA[1415757673]]></out_trade_no>
<refund_count>1</refund_count>
<refund_fee_0>1</refund_fee_0>
<refund_id_0><![CDATA[2008450740201411110000174436]]></refund_id_0>
<refund_status_0><![CDATA[PROCESSING]]></refund_status_0>
<result_code><![CDATA[SUCCESS]]></result_code>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<sign><![CDATA[1F2841558E233C33ABA71A961D27561C]]></sign>
<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
</xml>
| Name | Description | Reason | Solution |
|---|---|---|---|
| SYSTEMERROR | API return error | System timed out | Try to call the API again |
| REFUNDNOTEXIST | Failed to query refund | The refund number is wrong or the order status is not in the refund process | Please check whether the refund number or transaction ID is correct or whether the order is paid or in refund process. |
| 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 parameters and call the Submit Refund API again. |
| APPID_NOT_EXIST | APPID DOES NOT EXIST | No APPID in this parameter | Check whether provided APPID is correct |
| MCHID_NOT_EXIST | MCHID DOES NOT EXIST | No MCHID in this parameter | Check whether 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 via POST method | Check whether data is submitted by POST method |
| SIGNERROR | Signature error | Incorrect signature result | Check whether signature parameter and method comply with signature algorithm requirements |
| XML_FORMAT_ERROR | INVALID XML FORMAT | INVALID XML FORMAT | Check whether XML parameters are in correct format |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证