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
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
|
WeChat Pay order No. | transaction_id | string[1,32] | Choose one | Query WeChat order No. corresponding to the original payment transaction
Example: 1217752501201407033233368018 |
Merchant order No. | out_trade_no | string[1,32] | Query Order No. corresponding to the original payment transaction
Example: 1217752501201407033233368018 |
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 |
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 |
Request Example
WeChat Pay order No
1https://apihk.mch.weixin.qq.com/v3/global/refunds?transaction_id=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109
Merchant order No
1https://apihk.mch.weixin.qq.com/v3/global/refunds?out_trade_no=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109
3. Response Parameters
Response for successful request:
|
WeChat Pay transaction order No. | id | string[1,32] | Yes | WeChat Pay transaction order No.
Example: 1217752501201407033233368018 |
Merchant ID | mchid | string[1,32] | Yes | Merchant ID assigned by WeChat Pay
Note: Only for Common mode
Example: 1900000109 |
Sub-merchant ID | sub_mchid | string[1,32] | Yes | 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 | Merchant ID assigned to merchants by WeChat Pay
Note: Only for Institutional mode
Example: 1900000100 |
Original merchant transaction order No. | out_trade_no | string[1,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. |
 | Order amount | | |
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[1,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[1,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. |
| Refund order list | | |
WeChat refund No. | refund_id | string[1,32] | choose one to submit | WeChat Pay refund No. Example: 1217752501201407033233368018 | Merchant refund No. | out_refund_no | string[1,64] | Returned refund 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 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[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 user 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 Example: SUCCESS | Refund amount | amount | object | Yes | Information on the refund order 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 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 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 |
|
|
|
| Refund_detail | detail | array | No | Refund_detail,see the description below. | | Refund_detail | | |
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 discount amount 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 |
|
|
|
|
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 |
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": "4200000010202207280683365840",
3 "sp_mchid": "999952224",
4 "sub_mchid": "999968479",
5 "out_trade_no": "20220724trade003",
6 "amount": {
7 "total": 1000,
8 "currency": "CNY",
9 "payer_total": 500,
10 "payer_currency": "CNY"
11 },
12 "total_num": 2,
13 "current_total_num": 2,
14 "data": [
15 {
16 "id": "50202002642022072801898085011",
17 "out_refund_no": "20220724trade003",
18 "channel": "ORIGINAL",
19 "status": "SUCCESS",
20 "recv_account": "China Merchants Bank Credit Card 0403",
21 "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
22 "success_time": "2022-07-28T15:43:11+08:00",
23 "create_time": "2022-07-28T15:42:40+08:00",
24 "amount": {
25 "refund": 500,
26 "currency": "CNY",
27 "payer_refund": 250,
28 "payer_currency": "CNY",
29 "settlement_refund": 578,
30 "settlement_currency": "HKD",
31 "exchange_rate": {
32 "type": "SETTLEMENT_RATE",
33 "rate": 86500000
34 }
35 },
36 "detail": [
37 {
38 "promotion_id": "11006096615",
39 "scope": "GLOBAL",
40 "type": "COUPON",
41 "amount": 500,
42 "refund_amount": 250,
43 "currency": "CNY"
44 }
45 ]
46 },
47 {
48 "id": "50202002642022072801898085012",
49 "out_refund_no": "20220724trade003refund001",
50 "channel": "ORIGINAL",
51 "status": "SUCCESS",
52 "recv_account": "China Merchants Bank Credit Card 0403",
53 "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
54 "success_time": "2022-07-28T15:44:24+08:00",
55 "create_time": "2022-07-28T15:44:07+08:00",
56 "amount": {
57 "refund": 500,
58 "currency": "CNY",
59 "payer_refund": 250,
60 "payer_currency": "CNY",
61 "settlement_refund": 578,
62 "settlement_currency": "HKD",
63 "exchange_rate": {
64 "type": "SETTLEMENT_RATE",
65 "rate": 86500000
66 }
67 },
68 "detail": [
69 {
70 "promotion_id": "11006096615",
71 "scope": "GLOBAL",
72 "type": "COUPON",
73 "amount": 500,
74 "refund_amount": 250,
75 "currency": "CNY"
76 }
77 ]
78 }
79 ]
80}Accounts Order Return Example
1{
2 "id": "4200000002202207282853224734",
3 "sp_mchid": "999952224",
4 "sub_mchid": "999968479",
5 "out_trade_no": "20220724trade004",
6 "amount": {
7 "total": 1000,
8 "currency": "CNY",
9 "payer_total": 500,
10 "payer_currency": "CNY"
11 },
12 "total_num": 1,
13 "current_total_num": 1,
14 "data": [{
15 "id": "50201702652022072801898085013",
16 "out_refund_no": "20220724trade004refund001",
17 "channel": "ORIGINAL",
18 "status": "SUCCESS",
19 "recv_account": "China Merchants Bank Credit Card 0403",
20 "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
21 "success_time": "2022-07-28T15:52:15+08:00",
22 "create_time": "2022-07-28T15:51:57+08:00",
23 "amount": {
24 "refund": 500,
25 "currency": "CNY",
26 "payer_refund": 250,
27 "payer_currency": "CNY",
28 "settlement_refund": 578,
29 "settlement_currency": "HKD",
30 "exchange_rate": {
31 "type": "SETTLEMENT_RATE",
32 "rate": 86490000
33 },
34 "from": [{
35 "fund_source": "ORDER_REFUNDABLE_BALANCE",
36 "amount": 300
37 },
38 {
39 "fund_source": "FUNDS_REFUNDABLE_BALANCE",
40 "amount": 200
41 }
42 ]
43 },
44 "detail": [{
45 "promotion_id": "11006096908",
46 "scope": "GLOBAL",
47 "type": "COUPON",
48 "amount": 500,
49 "refund_amount": 250,
50 "currency": "CNY"
51 }]
52 }]
53}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, this error code is returned, and no other information will be 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 | 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. |
SIGN_ERROR | Signature error | Check if signature parameters and methods meet the algorithm requirements. |
