Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Query All Refunds API

Latest update time:2020.04.30 Release notes


After submitting a refund request, check the refund status by calling this API. There may be a delay in refund. The refund paid by balance will be received within 20 minutes. For refunds paid by bank cards, check the refund status after 3 business days.

Note:

1. This API is applicable to multiple partial refunds of the original transaction. You can view all refund details under the original transaction.

2. The transaction_id in the URL refers to the value of the original WeChat Pay order No. out_trade_no refers to the original merchant order No., either of which is called.


API intro

Request URL: https://api.mch.weixin.qq.com/hk/v3/refunds

Request method: GET

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3


path parameter is a path parameter.

query parameter needs to be passed in the request URL.

body parameter needs to be passed in the request JSON.

Request Parameters

Name Variable Name Type Required Description
WeChat Pay order No. transaction_id string(32) Choose one path WeChat order No. corresponding to the original payment transaction
Example:1217752501201407033233368018
Merchant order No. out_trade_no string(32) path Order No. corresponding to the original payment transaction
Example:1217752501201407033233368018
Merchant ID mchid string(32) Yes query Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example:1900000109
Sub-merchant ID sub_mchid string(32) Yes query Merchant ID assigned to sub-merchants by WeChat Pay
Note: Only forInstitutional mode
Example:1900000109
Institution's Merchant ID sp_mchid string(32) Yes query Merchant ID assigned to merchants by WeChat Pay
Note: Only forInstitutional mode
Example:1900000100
Record the start position offset int Yes query Paging function. Start position
Example:0
Number of transactions on each page count int Yes query Paging feature. Number of returned results per page. The maximum is 20.
Example:10

For example:



https://api.mch.weixin.qq.com/hk/v3/refunds?transaction_id=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109


https://api.mch.weixin.qq.com/hk/v3/refunds?out_trade_no=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109

    
{
JAVA示例代码
}
    

Returned Result

Response for failed request

Name Variable Name Type Required Description
Returned status code code string(32) Yes Error code. See the error code list for the enumerated values.
Example:INVALID_REQUEST
Returned information message string(256) Yes Returned message. It indicates the reason for the error if not empty.
Example:Parameter format verification error
+ Detailed error description detail object No It is returned when code is PARAM_ERROR. Details will be described below.
Name Variable Name Type Required Description
Location of the incorrect parameter field string(256) Yes If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter.
If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Example:#/properties/payer
Value of the incorrect parameter value string(256) Yes Value of the incorrect parameter
Example:1346177081915535577
Cause of error issue string(256) Yes Cause of error
Example:It is different from ALLOF schema
Location of the incorrect parameter location string(256) No body:The incorrect parameter is in the JSON for request body
url:The incorrect parameter is in the request URL
query:The incorrect parameter is in the querystring of the request
Example:body

Response for successful request

Name Variable Name Type Required Description
WeChat Pay transaction order No. id string(32) Yes WeChat Pay transaction order No.
Example:1217752501201407033233368018
Merchant ID mchid string(32) Yes Merchant ID assigned by WeChat Pay
Note: Only forCommon mode
Example:1900000109
Sub-merchant ID sub_mchid string(32) Yes Merchant ID assigned to sub-merchants by WeChat Pay
Note: Only forInstitutional mode
Example:1900000109
Institution's Merchant ID sp_mchid string(32) Yes Merchant ID assigned to merchants by WeChat Pay
Note: Only forInstitutional mode
Example:1900000100
Original merchant transaction order No. out_trade_no string(64) Yes The returned original transaction order No.
Example: 1217752501201407033233368018
+ Order amount amount object Yes Information on the original order amount. For more information, see the description below.
Name Variable Name Type Required Description
Order amount total int Yes The total order amount. The minimum unit of the currency can only be an integer. See "Payment amount" for details.
Example:888
Currency type currency string(16) No Three-letter code in accordance with ISO 4217
Example:CNY
User's payment amount payer_total int Yes The actual amount paid by the user. The minimum unit of the currency can only be an integer. See "Payment amount" for details.
Example:888
Payment currency payer_currency string(16) Yes Three-letter code in accordance with ISO 4217
Example:CNY
+ Refund order list data array Yes Returned refund list. For more information, see the description below.
Name Variable Name Type Required Description
WeChat refund No. id string(32) Yes WeChat Pay refund No.
Example:1217752501201407033233368018
Merchant refund No. out_refund_no string(64) Yes Returned refund order No.
Example:1217752501201407033233368018
Refund channel channel string(16) No ORIGINAL:Refund to the paying account
BALANCE:Refund to the balance
OTHER_BALANCE:Refund to other accounts if there is something wrong with the original account.
OTHER_BANKCARD:Refund to other bank cards if there is something wrong with the original bank card.
Example:ORIGINAL
Refund receiving account recv_account string(64) No Refund receiving party of the current refund order
1)Refund to bank cards:
{Bank name}{Card type}{Last numbers of the bank card}
2)Refund to the balance of the paying use:
The balance of the paying user
3)Refund to the Mini Fund of the paying user:
The Mini Fund of the paying user
Example:China Merchants Bank Credit Card 0403
Refund source fund_source string(30) No REFUND_SOURCE_UNSETTLED_FUNDS:Refund with unsettled funds (default)
REFUND_SOURCE_RECHARGE_FUNDS:Refund with available balance
Example:REFUND_SOURCE_UNSETTLED_FUNDS
Refund completion time success_time string(64) No Refund completion time, which is returned when the refund status is successful.
Example:2018-06-08T10:34:56+08:00
Refund creation time create_time  string(64) Yes Refund acceptance time
Example:2018-06-08T10:34:56+08:00
Refund status status string(16) Yes Refund status:
SUCCESS:Refund successful
REFUNDCLOSE:Refund closed
PROCESSING:Refund in process
Example:SUCCESS
+ Refund amount amount object Yes Information on the refund order amount. For more information, see the description below.
Name Variable Name Type Required Description
Refund amount refund int Yes Refund amount. The minimum unit of the currency can only be an integer. The refund amount cannot exceed the original order amount. If a voucher was used, the backend will refund proportionally.
Example:888
Currency type currency string(16) No Three-letter code in accordance with ISO 4217.
Example:CNY
Refund amount to user payer_refund int Yes The amount refunded to the user, excluding all voucher amount.
Example:888
Payment currency payer_currency string(16) Yes Three-letter code in accordance with ISO 4217.
Example:CNY
+ Exchange rate exchange_rate object  Yes Exchange rate information
Name Variable Name Type Required Description
Exchange rate type type string(16) No When the priced currency and the payment currency are the same, type="SETTLEMenT_RATE", i.e. the exchange rate between the [real-time] priced currency and the settlement currency.
When the priced currency and the payment currency are different, type="USERPAYMenT_RATE", i.e. the exchange rate between the [original payment] priced currency and the payment currency.
Example:SETTLEMenT_RATE
Exchange rate value rate int No The rate value is the exchange rate multiplied by the 8th power of 10.
If the exchange ratio is 1, then rate=100000000.
If the exchange rate is 6.5, then the exchange rate value is 650,000,000.
Example:8000000
+ Refund_detail refund_detail object No Refund_detail,see the description below.
Name Variable Name Type Required Description
Voucher ID promotion_id string(32) Yes Voucher or discount ID
Example:109519
Discount range scope string(32) No

GLOBAL:All-item voucher
SINGLE:Single-item discount
Example:SINGLE

Discount type type string(32) No COUPON:Vouchers, which are a kind of top-up vouchers that require fund settlement (the voucher currency of overseas merchants is the same as the payment currency).
DISCOUNT:Discount vouchers, which are a kind of top-up-free discount vouchers that require no fund settlement (the voucher currency of overseas merchants is the same as the priced currency).
Example:DISCOUNT
Discount voucher price amount int No The discount amount
Example:5
Voucher refund amount refund_amount int No Voucher amount refunded proportionally
Example:5
Currency type currency string(16) Yes Three-letter code in accordance with ISO 4217.
Example:CNY
Total number of refunds under the order total_num int Yes Total number of refunds under the order
Example:0
Number of refund orders returned this time current_total_num int Yes Number of refund orders returned this time
Example: 10

For example:

{
    "id": "1008450740201411110005820873",
    "sp_mchid": "10000100",
    "sub_mchid": "20000100",
    "out_trade_no": "20150806125346",
    "amount" : {
        "total": 528800,
        "currency":"HKD",
        "payer_total": 518799,
        "payer_currency": "HKD",
    },
    "total_num": 1,
    "current_total_num": 1,
    "data": [
        {
            "id": "2008450740201411110000174436",
            "out_refund_no": "R20150806125346",
            "channel": "ORIGINAL",
            "amount": {
                "refund": 50,
                "currency": "CNY",
                "payer_refund": 49,
                "payer_currency": "HKD",
                "exchange_rate" : {
                    "type": "SETTLEMenT_RATE",
                    "rate": 8000000
                }
            },
            "status": "SUCCESS",
            "recv_account": "China Merchants Bank Credit Card 0403",
            "fund_source": "REFUND_SOURCE_RECHARGE_FUNDS",
            "success_time": "2018-06-08T10:34:56+08:00",
            "create_time": "2018-06-08T10:34:56+08:00",
            "detail": [
                {
                    "promotion_id":"109519",
                    "scope":"GLOBAL",
                    "type":"COUPON",
                    "amount": 1,
                    "refund_amount": 1,
                    "currency": "HKD"
                }
            ]
        }
    ]
}

{
"code":"INVALID_REQUEST",
"message":"Parameter format verification error",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"It is different from ALLOF schema",
    "location":"body"
   }
}

SYSTEMERROR

Name Description Solution
SYSTEMERROR Errors returned from the API Try call the API again.
REFUNDNOTEXIST Failed to view the refund order Check whether the order No. and the order status (e.g. unpaid and paid but not refunded) are correct. If there is no refund order under the order, this error code is returned, and no other information will be returned.
INVALID_TRANSACTIONID Invalid transaction_id Invalid request parameter. Check whether the original transaction No. exists and whether the API for initiating payment transaction returns failure.
PARAM_ERROR Invalid parameter Invalid request parameter. Re-check the parameter and then call the refund request again.
APPID_NOT_EXIST APPID does not exist. Check whether APPID is correct.
MCHID_NOT_EXIST MCHID does not exist. Check whether MCHID is correct.
REQUIRE_POST_METHOD Use post method. Check whether the request parameter is submitted via post method.
SIGNERROR Signature error Check if signature parameters and methods meet the algorithm requirements.
XML_FORMAT_ERROR Incorrect XML format Check whether the format of the XML parameter is correct.


Release notes

close
V1.0
2020.04.30
1. Viewing All Refunds API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global