查询所有退款

更新时间:2025.03.03

提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,用零钱支付的退款20分钟内到账,银行卡支付的退款3个工作日后重新查询退款状态。

注意:

  • 该接口适合原交易发生多笔部分退款的情况,查询原交易下所有的退款详情。


1. 接口说明

 

适用对象:直连模式机构模式

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

请求方式: GET

 

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

商户号

mchid

string[1,32]

Query 微信支付分配的商户号
注意:仅适用于直连模式
示例值:1900000109

子商户号

sub_mchid

string[1,32]

Query 微信支付分配的子商户号
注意:仅适用于机构模式
示例值:1900000109

机构商户号

sp_mchid

string[1,32]

Query 微信支付分配的机构商户号
注意:仅适用于机构模式
示例值:1900000100

微信支付订单号

transaction_id

string[1,32]

二选一

Query 微信支付订单号
示例值:1217752501201407033233368018

商户订单号

out_trade_no

string[1,32]

Query 商户订单号
示例值:1217752501201407033233368018

记录起始位置

offset

int

Query 分页功能,起始位置
示例值:0

每页笔数

count

int

Query 分页功能,每页返回记录数,最大值限制为20
示例值:10

请求示例

微信支付订单号查单

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

商户订单号查单

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

3. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付交易订单号

id

string[1,32]

微信支付交易订单号
示例值:1217752501201407033233368018

商户号

mchid

string[1,32]

微信支付分配的商户号
注意:仅适用于直连模式
示例值:1900000109

子商户号

sub_mchid

string[1,32]

微信支付分配的子商户号
注意:仅适用于机构模式
示例值:1900000109

机构商户号

sp_mchid

string[1,32]

微信支付分配的机构商户号
注意:仅适用于机构模式
示例值:1900000100

商户原交易订单号

out_trade_no

string[1,64]

返回的原交易订单号。
示例值: 1217752501201407033233368018

订单金额

amount

object

原支付订单金额信息,详细说明见下文

订单金额

退款单列表

data

array

返回的退款列表,详细说明见下文

退款单列表

订单总退款次数

total_num

int

订单总退款次数
示例值:0

本次返回退款单数

current_total_num

int

本次返回退款单数
示例值: 10

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

错误码,枚举值见错误码列表
示例值:INVALID_REQUEST

返回信息

message

string[1, 256]

返回信息,如非空,为错误原因
示例值:参数格式校验错误

详细的错误描述

detail

object

当code为PARAM_ERROR时返回,详细说明见下

详细的错误描述

返回示例

无分账订单返回示例

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": "招商银行借记卡0416",
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": "招商银行借记卡0416",
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    ]

分账订单返回示例

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": "招商银行借记卡0416",
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}

异常示例

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

4. 错误码

错误码

描述

解决方案

SYSTEM_ERROR

接口返回错误

请尝试再次掉调用API。

REFUND_NOT_EXIST

退款订单查询失败

请检查订单号是否有误以及订单状态是否正确,如:未支付、已支付未退款,如果订单下没有退款单,则会返回此错误码,其他信息是不返回的

BIZERR_NEED_RETRY

无效transaction_id

请求参数错误,检查原交易号是否存在或发起支付交易接口返回失败

PARAM_ERROR

参数错误

请求参数错误,请检查参数再调用退款申请

APPID_NOT_EXIST

APPID不存在

请检查APPID是否正确

MCHID_NOT_EXIST

MchID不存在

请检查MchID是否正确

REQUIRE_POST_METHOD

请使用post方法

请检查请求参数是否通过post方法提交

SIGN_ERROR

签名错误

请检查签名参数和方法是否都符合签名算法要求

 

 

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.