Query All Refunds

Update Time:2025.03.03

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.

Tips:

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

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


1. API intro

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/refunds

Request method: GET

 

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

Name

Variable Name

Type

Required

Description

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:

Name

Variable Name

Type

Required

Description

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

Refund order list

data

array

Yes

Returned refund list. For more information, see the description below.

Refund order list

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:

Name

Variable Name

Type

Required

Description

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

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

Error Message

Description

Solution

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.

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.