最新更新时间：2023.06.06 版本说明
提交退款申请后，通过调用该接口查询退款状态。该查询服务提供两种查询方式（两种查询方式返回结果一致）：
方式1：通过微信支付退款单号查询退款；
方式2：通过商户退款单号查询退款。
● 退款有一定延时，用零钱支付的退款20分钟内到账，银行卡支付的退款3个工作日后重新查询退款状态。
适用对象：电商平台
请求URL：https://api.mch.weixin.qq.com/v3/ecommerce/refunds/id/{refund_id}
请求方式：GET
path指该参数为路径参数
query指该参数需在请求URL传参
body指该参数需在请求JSON传参
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信退款单号 | refund_id | string[1,32] | 是 | path
退款单的主键，唯一定义此资源的标识。 示例值： 50000000382019052709732678859 |
| 二级商户号 | sub_mchid | string[1,32] | 是 | query 微信支付分配给二级商户的商户号。 示例值：1900000109 |
https://api.mch.weixin.qq.com/v3/ecommerce/refunds/id/50000000382019052709732678859?sub_mchid=1900000109
适用对象：电商平台
请求URL：https://api.mch.weixin.qq.com/v3/ecommerce/refunds/out-refund-no/{out_refund_no}
请求方式：GET
path指该参数为路径参数
query指该参数需在请求URL传参
body指该参数需在请求JSON传参
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 商户退款单号 | out_refund_no | string[1,64] | 是 | path
商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔。 示例值： 1217752501201407033233368018 |
| 二级商户号 | sub_mchid | string[1,32] | 是 | query 微信支付分配给二级商户的商户号。 示例值：1900000109 |
https://api.mch.weixin.qq.com/v3/ecommerce/refunds/out-refund-no/1217752501201407033233368018?sub_mchid=1900000109
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信退款单号 | refund_id | string[1,32] | 是 | 微信支付退款订单号。 示例值：1217752501201407033233368018 |
| 商户退款单号 | out_refund_no | string[1,64] | 是 | 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔。 示例值：1217752501201407033233368018 |
| 微信订单号 | transaction_id | string[1,32] | 是 | 微信支付交易订单号。 示例值： 1217752501201407033233368018 |
| 商户订单号 | out_trade_no | string[1,32] | 是 | 返回的原交易订单号。 示例值： 1217752501201407033233368018 |
| 退款渠道 | channel | string[1,16] | 是 | ORIGINAL：原路退款 BALANCE：退回到余额 OTHER_BALANCE：原账户异常退到其他余额账户 OTHER_BANKCARD：原银行卡异常退到其他银行卡 示例值： ORIGINAL |
| 退款入账账户 | user_received_account | string[1,64] | 是 | 取当前退款单的退款入账方。 退回银行卡：{银行名称}{卡类型}{卡尾号} 退回支付用户零钱：支付用户零钱 退还商户：商户基本账户、商户结算银行账户 退回支付用户零钱通：支付用户零钱通 示例值： 招商银行信用卡0403 |
| 退款成功时间 | success_time | string[1,64] | 否 | 退款成功时间，退款状态status为SUCCESS（退款成功）时，返回该字段。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。 示例值： 2018-06-08T10:34:56+08:00 |
| 退款创建时间 | create_time | string[1,64] | 是 | 1、退款受理时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。 2、当退款状态为退款成功时返回此字段。 示例值：2018-06-08T10:34:56+08:00 |
| 退款状态 | status | string[1,16] | 是 | 退款状态，枚举值： SUCCESS：退款成功 CLOSED：退款关闭 PROCESSING：退款处理中 ABNORMAL：退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往【服务商平台—>交易中心】，手动处理此笔退款 示例值：SUCCESS |
| +退款金额信息 | amount | object | 是 | 订单退款金额信息 |
| +营销详情 | promotion_detail | array | 否 | 优惠退款信息，discount_refund>0时，返回该字段 |
| 退款出资商户 | refund_account | string[1, 32] | 否 | 电商平台垫资退款专用参数。需先确认已开通此功能后，才能使用。若需要开通，请联系微信支付客服。 枚举值： REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付，需要向微信支付申请开通 REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值 注意：若传入REFUND_SOURCE_PARTNER_ADVANCE，仅代表可以使用垫付退款，实际出款账户需以退款申请受理结果或查单结果为准。 示例值：REFUND_SOURCE_SUB_MERCHANT |
| 资金账户 | funds_account | string[1, 32] | 否 | 若订单处于待分账状态，可以传入此参数，指定退款资金来源账户。当该字段不存在时，默认使用订单交易资金所在账户出款，即待分账时使用不可用余额的资金进行退款，已分账或无分账时使用可用余额的资金进行退款。 AVAILABLE：可用余额 示例值：AVAILABLE |
{
"refund_id": "1217752501201407033233368018",
"out_refund_no": "1217752501201407033233368018",
"transaction_id": "1217752501201407033233368018",
"out_trade_no": "1217752501201407033233368018",
"channel": "ORIGINAL",
"user_received_account": "招商银行信用卡0403",
"success_time": "2018-06-08T10:34:56+08:00",
"create_time": "2018-06-08T10:34:56+08:00",
"status": "SUCCESS",
"amount": {
"refund": 888,
"payer_refund": 888,
"discount_refund": 888,
"currency": "CNY"
},
"promotion_detail": [
{
"promotion_id": "109519",
"scope": "SINGLE",
"type": "DISCOUNT",
"amount": 5,
"refund_amount": 100
}
],
"refund_account": "REFUND_SOURCE_SUB_MERCHANT",
"funds_account": "UNSETTLED"
}
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 接口返回错误 | 请不要更换商户退款单号，请使用相同参数再次调用API。 |
| 404 | RESOURCE_NOT_EXISTS | 订单不存在 | 请检查订单号是否正确且是否已支付，未支付的订单不能发起退款 |
| 400 | PARAM_ERROR | 参数错误 | 请求参数错误，请重新检查再调用退款申请 |
| 429 | FREQUENCY_LIMITED | 频率限制 | 该笔退款未受理，请降低频率后重试 |
| 403 | NO_AUTH | 没有退款权限 | 此状态代表退款申请失败，请检查是否有退这笔订单的权限 |
| 401 | SIGN_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求 |
| 400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| 400 | MCH_NOT_EXISTS | 商户号不存在 | 请检查商户号是否正确 |
| 403 | REQUEST_BLOCKED | 请求受阻 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |