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.
1. API intro
Applicable object: Common mode Institutional mode
Request URL: https://apihk.mch.weixin.qq.com/v3/global/refunds/id/{refund_id}
OR
https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/{out_refund_no}
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.
2. Request Parameters
|
Merchant ID | mchid | string[1,32] | Yes | Query Merchant ID assigned by WeChat Pay
Note: Only for Common mode
Example: 1900000109 |
Sub-merchant ID | sub_mchid | string[1,32] | Yes | Query Merchant ID assigned to sub-merchants by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109 |
Institution's Merchant ID | sp_mchid | string[1,32] | Yes | Body Merchant ID assigned to merchants by WeChat Pay
Note: Only for Institutional mode
Example: 1900000100 |
WeChat Pay refund order No. | refund_id | string[1,32] | choose one to submit | Path WeChat Pay refund order No.
Example: 1217752501201407033233368018 |
Merchant refund No. | out_refund_no | string[1,64] | Path Returned refund order No.
Example: 1217752501201407033233368018 |
Request Example
WeChat Pay refund order No
1https://apihk.mch.weixin.qq.com/v3/global/refunds/id/50201308462021060109285031309?sp_mchid=126464383&sub_mchid=426157911
Merchant refund No
1https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/TK88s610005?sp_mchid=126464383&sub_mchid=426157911
3. Response Parameters
Response for successful request:
|
WeChat Pay refund order No. | id | string[1,32] | choose one to submit | WeChat Pay refund order No.
Example: 1217752501201407033233368018 |
Merchant refund No. | out_refund_no | string[1,64] | Returned refund order No.
Example: 1217752501201407033233368018 |
WeChat Pay transaction order No. | transaction_id | string[1,32] | Yes | WeChat Pay transaction order No.
Example: 1217752501201407033233368018 |
Original merchant transaction order No. | out_trade_no | string[1,64] | Yes | The returned original transaction order No.
Example: 1217752501201407033233368018 |
Refund channel | channel | string[1,16] | No | ORIGINAL：Refund to the paying account
BALANCE：Refund to the balance
OTHER_BALANCE：Refund to other balance accounts in case of original account error
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[1,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 use
Example: China Merchants Bank Credit Card 0403 |
Refund source | fund_source | string[1,30] | No | REFUND_SOURCE_UNSETTLED_FUNDS：Refund with unsettled funds (default)
REFUND_SOURCE_RECHARGE_FUNDS：Refund with available balance
Example: REFUND_SOURCE_UNSETTLED_FUNDS
Note: This field is not applicable to the Funds Distribution business. |
Refund completion time | success_time | string[1,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[1,64] | Yes | Refund acceptance time
Example: 2018-06-08T10:34:56+08:00 |
Refund status | status | string[1,16] | Yes | Refund status:
SUCCESS：Refund successful
REFUNDCLOSE：Refund closed
PROCESSING：Refund in process
ABNORMAL: The refund is abnormal. When the refund is made to the bank, the user’s card is found to be invalid or frozen, which leads to the failure of the original bank card refund. You can go to [Service Provider Platform -> Transaction] to manually process the refund
Example: SUCCESS |
Refund amount | amount | object | Yes | Information on the refund amount. For more information, see the description below. |
 | Refund amount | | |
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[1,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[1,16] | Yes | Three-letter code in accordance with ISO 4217. Example: CNY | Settlement Currency Refund Amount | settlement_refund | int | Yes | The refund amount corresponding to the merchant's settlement currency, the smallest unit of the currency, which can only be an integer. Example: 888 | Settlement Currency | settlement_currency | string[1,16] | Yes | Settlement currency, a three-letter code that conforms to the ISO 4217 standard, see the currency type on the currency list. Example: HKD | Exchange rate | exchange_rate | object | Yes | Exchange rate information | | Exchange rate | | |
Exchange rate type | type | string[1,16] | No | When the priced currency and the settlement currency are the same, type="USERPAYMENT_RATE", i.e. the exchange rate between the [original payment] priced currency and the payment currency.
When the priced currency and the settlement currency are different, type="SETTLEMENT_RATE", i.e. the exchange rate between the priced currency and the settlement 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 ratio is 6.5, then rate=650000000. Example: 8000000 |
|
| Refund Source & Amount | from | array | No | This parameter is used to specify the fund source and amount for cross-border funds-distribution orders.
If this parameter is not specified for a funds-distribution order, the refund will be made from the undistributed refundable balance of the order by default, and the shortfall will be made up by the advance refund amount.
The specific fund source and amount are subject to the "from" field in the response parameter.This parameter applies to usage scenarios meeting the following conditions: The order is a cross-border funds-distribution order. Do not specify this parameter for non-cross-border orders.
Parameter passing needs to meet the following conditions: The sum of the fund amount from the advance refundable balance and the fund amount from the undistributed refundable balance of the order is equal to the refund amount; The fund sources cannot be duplicated.
If any of the above conditions are not met, an error will be returned. | | Refund Source & Amount | | |
Fund Source | fund_source | string[1,32] | Yes | The source of the refund, which can be any of the enumerated values below.
Enumerated values:
FUNDS_REFUNDABLE_BALANCE : Advance refundable balance
ORDER_REFUNDABLE_BALANCE : Undistributed refundable balance Example：ORDER_REFUNDABLE_BALANCE | Fund Amount | amount | int | Yes | The amount funded from a source, which can only be an integer in the smallest unit of currency. Example：888 |
|
|
|
|
Discount refund details | detail | array | No | Discount refund info. For more information, see the description below. |
| Discount refund details | | |
Voucher ID | promotion_id | string[1,32] | Yes | Voucher or discount ID Example: 109519 | Discount range | scope | string[1,32] | No | GLOBAL- All-item voucher
SINGLE- Single-item discount Example: SINGLE | Discount type | type | string[1,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 amount for which the user enjoys a discount (Voucher amount = Amount contributed by WeChat + Amount contributed by the merchant + Amount contributed by others) Example: 5 | Voucher refund amount | refund_amount | int | No | Voucher amount refunded proportionally Example: 5 | Currency type | currency | string[1,16] | Yes | Three-letter code in accordance with ISO 4217. Example: CNY |
|
|
Response for failed request:
|
Returned status code | code | string[1,32] | Yes | Error code. See the error code list for the enumerated values. |
Returned information | message | string[1,256] | Yes | Returned message. It indicates the reason for the error if not empty. |
Detailed error description | detail | object | No | It is returned when code is PARAM_ERROR. Details will be described below. |
| Detailed error description | | |
The location of incorrect parameter | field | string[1,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. | Value of the incorrect parameter | value | string[1,256] | Yes | Value of the incorrect parameter | Cause of error | issue | string[1,256] | Yes | Cause of error | Location of the incorrect parameter | location | string[1,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 |
|
|
Response Example:
No Accounts Order Return Example
1{
2 "id": "50202002642022072801898085012",
3 "out_refund_no": "20220724trade003refund001",
4 "transaction_id": "4200000010202207280683365840",
5 "out_trade_no": "20220724trade003",
6 "channel": "ORIGINAL",
7 "status": "SUCCESS",
8 "recv_account": "China Merchants Bank Credit Card 0403",
9 "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
10 "success_time": "2022-07-28T15:44:24+08:00",
11 "create_time": "2022-07-28T15:44:07+08:00",
12 "amount": {
13 "refund": 500,
14 "currency": "CNY",
15 "payer_refund": 250,
16 "payer_currency": "CNY",
17 "settlement_refund": 578,
18 "settlement_currency": "HKD",
19 "exchange_rate": {
20 "type": "SETTLEMENT_RATE",
21 "rate": 86500000
22 }
23 },
24 "detail": [
25 {
26 "promotion_id": "11006096615",
27 "scope": "GLOBAL",
28 "type": "COUPON",
29 "amount": 500,
30 "refund_amount": 250,
31 "currency": "CNY"
32 }
33 ]
34}Accounts Order Return Example
1{
2 "id": "50201702652022072801898085013",
3 "out_refund_no": "20220724trade004refund001",
4 "transaction_id": "4200000002202207282853224734",
5 "out_trade_no": "20220724trade004",
6 "channel": "ORIGINAL",
7 "status": "SUCCESS",
8 "recv_account": "China Merchants Bank Credit Card 0403",
9 "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
10 "success_time": "2022-07-28T15:52:15+08:00",
11 "create_time": "2022-07-28T15:51:57+08:00",
12 "amount": {
13 "refund": 500,
14 "currency": "CNY",
15 "payer_refund": 250,
16 "payer_currency": "CNY",
17 "settlement_refund": 578,
18 "settlement_currency": "HKD",
19 "exchange_rate": {
20 "type": "SETTLEMENT_RATE",
21 "rate": 86490000
22 },
23 "from": [
24 {
25 "fund_source": "ORDER_REFUNDABLE_BALANCE",
26 "amount": 300
27 },
28 {
29 "fund_source": "FUNDS_REFUNDABLE_BALANCE",
30 "amount": 200
31 }
32 ]
33 },
34 "detail": [
35 {
36 "promotion_id": "11006096908",
37 "scope": "GLOBAL",
38 "type": "COUPON",
39 "amount": 500,
40 "refund_amount": 250,
41 "currency": "CNY"
42 }
43 ]
44}Exception Example
1{
2 "code": "INVALID_REQUEST",
3 "message": "Parameter format verification error",
4 "detail": {
5 "field": "#/properties/payer",
6 "value": "1346177081915535577",
7 "issue": "Not in line with ALLOF schema",
8 "location": "body"
9 }
10}
4. Error Codes
|
SYSTEM_ERROR | Errors returned from the API | Try call the API again. |
INVALID_REQUEST | Invalid request | Check your program based on the error message returned by the API. |
RESOURCE_NOT_EXISTS | Record not found | Record not found. Modify the parameter and try again. |
REFUND_NOT_EXIST | 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, only this error code is returned. |
INVALID_TRANSACTION_ID | 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 | Request parameter was not properly filled in as instructed. | 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. |
SIGN_ERROR | Signature error | Check if signature parameters and methods meet the algorithm requirements. |
