查询所有退款

更新时间：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. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付交易订单号

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

是

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

退款单列表

参数名

变量

类型

必填

描述

微信退款单号

string[1,32]

是

微信支付退款单号
示例值：1217752501201407033233368018

商户退款单号

out_refund_no

string[1,64]

是

返回的退款订单号。
示例值：1217752501201407033233368018

退款渠道

channel

string[1,16]

否

ORIGINAL：原路退款
BALANCE：退回到余额
OTHER_BALANCE：原账户异常退到其他余额账户
OTHER_BANKCARD：原银行卡异常退到其他银行卡
示例值：ORIGINAL

退款入账账户

recv_account

string[1,64]

否

取当前退款单的退款入账方
1）退回银行卡：
{银行名称}{卡类型}{卡尾号}
2）退回支付用户零钱:
支付用户零钱
3）退回支付用户零钱通:
支付用户零钱通
示例值：招商银行信用卡0403

退款资金来源

fund_source

string[1,30]

否

REFUND_SOURCE_UNSETTLED_FUNDS：未结算资金退款（默认使用未结算资金退款）
REFUND_SOURCE_RECHARGE_FUNDS：可用余额退款
示例值：REFUND_SOURCE_UNSETTLED_FUNDS
备注：该字段不适用于分账业务。

退款成功时间

success_time

string[1,64]

否

退款成功时间，当退款状态为退款成功时有返回。
示例值：2018-06-08T10:34:56+08:00

退款创建时间

create_time

string[1,64]

是

退款受理时间
示例值：2018-06-08T10:34:56+08:00

退款状态

status

string[1,16]

是

退款状态：
SUCCESS：退款成功
REFUNDCLOSE：退款关闭
PROCESSING：退款处理中
ABNORMAL：退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往【服务商平台—>交易中心】，手动处理此笔退款
示例值：SUCCESS

退款金额

amount

object

是

退款单金额信息，详细说明见下文

退款金额

参数名

变量

类型

必填

描述

退款金额

refund

int

是

退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额，如果有使用券，后台会按比例退。
示例值：888

货币类型

currency

string[1,16]

否

符合ISO 4217标准的三位字母代码
示例值：CNY

用户退款金额

payer_refund

int

是

退款给用户的金额，不包含所有优惠券金额
示例值：888

支付币种

payer_currency

string[1,16]

是

符合ISO 4217标准的三位字母代码
示例值：CNY

结算币种退款金额

settlement_refund

int

是

商户结算币种所对应的退款金额，币种的最小单位，只能为整数
示例值：888

结算币种

settlement_currency

string[1,16]

是

结算币种，符合ISO 4217标准的三位字母代码，币种列表详见币种类型
示例值：HKD

汇率

exchange_rate

object

是

汇率信息

汇率

退款出资来源及金额

from

array

否

跨境分账订单传递此参数指定出资来源及金额；
分账订单如果不传此参数，则默认优先从订单未分可退余额出资退款，不足部分由可垫付退款额度补足，具体出资来源及金额需要根据返回参数中 from 字段确认。
此参数使用场景需要满足以下条件：
1、订单属于跨境分账订单，非跨境订单请不要传递此参数。
参数传递需要满足条件：
1、可垫付退款余额出资金额和订单未分可退余额出资金额之和等于退款金额；
2、出资来源不能重复。
上述任一条件不满足将返回错误。

退款出资来源及金额

优惠退款详情

detail

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	签名错误	请检查签名参数和方法是否都符合签名算法要求