Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Query Refund API

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.

Tips:

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.

API intro

Request Url: https://api.mch.weixin.qq.com/pay/refundquery

Request Method: POST

Certificate Requirements: No certificate is required.

Applicable Object: Common modeInstitutional mode

Request Parameters

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

Here is the sample code:


<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> 
    
{
JAVA示例代码
}
    

Return Data

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

Example:


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

Error Codes

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

Release notes

关闭
V1.0
2019.11.20
1. Query Refund API 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