提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,用零钱支付的退款20分钟内到账,银行卡支付的退款3个工作日后重新查询退款状态。
1. 接口说明
请求URL:https://apihk.mch.weixin.qq.com/v3/global/refunds
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 | 是 | 原支付订单金额信息,详细说明见下文 |
 | 订单金额 | | |
订单金额 | total | int | 是 | 订单总金额,币种的最小单位,只能为整数,详见支付金额 示例值:888 | 货币类型 | currency | string[1,16] | 否 | 符合 ISO 4217 标准的三位字母代码 示例值:CNY | 用户支付金额 | payer_total | int | 是 | 用户实际支付金额,币种的最小单位,只能为整数,详见支付金额 示例值:888 | 支付币种 | payer_currency | string[1,16] | 是 | 符合ISO 4217标准的三位字母代码 示例值:CNY |
|
|
退款单列表 | data | array | 是 | 返回的退款列表,详细说明见下文 |
 | 退款单列表 | | |
微信退款单号 | id | 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 | 是 | 汇率信息 |  | 汇率 | | |
汇率类型 | type | string[1,16] | 否 | 标价币种和支付币种一致时,type="SETTLEMENT_RATE",即【实时】标价币种和结算币种的汇率; 标价币种和支付币种不一致,type="USERPAYMENT_RATE",即【原支付】标价币种和支付币种的汇率示例值:SETTLEMENT_RATE | 汇率值 | rate | int | 否 | rate值是兑换比例乘以10的8次方, 如果兑换比例是1,则rate=100000000; 如果兑换比例为6.5,则rate=650000000示例值:8000000 |
|
| 退款出资来源及金额 | from | array | 否 | 跨境分账订单传递此参数指定出资来源及金额; 分账订单如果不传此参数,则默认优先从订单未分可退余额出资退款,不足部分由可垫付退款额度补足,具体出资来源及金额需要根据返回参数中 from 字段确认。 此参数使用场景需要满足以下条件: 1、订单属于跨境分账订单,非跨境订单请不要传递此参数。 参数传递需要满足条件: 1、可垫付退款余额出资金额和订单未分可退余额出资金额之和等于退款金额; 2、出资来源不能重复。 上述任一条件不满足将返回错误。 |  | 退款出资来源及金额 | | |
出资来源 | fund_source | string[1,32] | 是 | 退款出资来源,下面枚举值多选一。 枚举值: FUNDS_REFUNDABLE_BALANCE : 可垫付退款余额 ORDER_REFUNDABLE_BALANCE : 订单未分可退余额 示例值:FUNDS_REFUNDABLE_BALANCE | 出资金额 | amount | int | 是 | 对应出资来源金额(币种的最小单位,只能为整数) 示例值:888 |
|
|
|
| 优惠退款详情 | detail | array | 否 | 优惠退款功能信息,详细说明见下文 |  | 优惠退款详情 | | |
券ID | promotion_id | string[1,32] | 是 | 券或者立减优惠id 示例值:109519 | 优惠范围 | scope | string[1,32] | 否 | GLOBAL:全场代金券 SINGLE:单品优惠 示例值:SINGLE | 优惠类型 | type | string[1,32] | 否 | COUPON:代金券,需要走结算资金的充值型代金券,(境外商户券币种与支付币种一致) DISCOUNT:优惠券,不走结算资金的免充值型优惠券,(境外商户券币种与标价币种一致 示例值:DISCOUNT | 优惠券面额 | amount | int | 否 | 用户享受优惠的金额 示例值:5 | 优惠券退款额 | refund_amount | int | 否 | 按比例退款的优惠券金额 示例值:5 | 货币类型 | currency | string[1,16] | 是 | 符合ISO 4217标准的三位字母代码 示例值:CNY |
|
|
|
|
订单总退款次数 | total_num | int | 是 | 订单总退款次数 示例值:0 |
本次返回退款单数 | current_total_num | int | 是 | 本次返回退款单数 示例值: 10 |
异常返回
|
返回状态码 | code | string[1, 32] | 是 | 错误码,枚举值见错误码列表 示例值:INVALID_REQUEST |
返回信息 | message | string[1, 256] | 是 | 返回信息,如非空,为错误原因 示例值:参数格式校验错误 |
详细的错误描述 | detail | object | 否 | 当code为PARAM_ERROR时返回,详细说明见下 |
 | 详细的错误描述 | | |
指示错误参数的位置 | field | string[1, 256] | 是 | 当错误参数位于请求body的JSON时,填写指向参数的JSON Pointer 当错误参数位于请求的url或者querystring时,填写参数的变量名 示例值:#/properties/payer | 错误参数的值 | value | string[1, 256] | 是 | 错误参数的值 示例值:1346177081915535577 | 具体错误原因 | issue | string[1, 256] | 是 | 具体错误原因 示例值:与ALLOF schema不符 | 错误参数的位置 | location | string[1, 256] | 否 | body:错误参数位于请求body的JSON中 url:错误参数位于请求url中 query:错误参数位于请求的querystring中 示例值:body |
|
|
返回示例

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