查询退款API
提交退款申请后, 通过调用该接口查询退款状态。退款有一定延时, 用零钱支付的退款20分钟内到账, 银行卡支付的退款3个工作日后重新查询退款状态。
注意
- 退款查询 API 可按以下两种不同方式查询:
- 通过微信支付退款单号查询退款；
- 通过商户退款单号查询退款。
- 两种不同查询方式返回结果相同
1. 通过微信支付退款单号查询退款
接口说明
适用对象: 电商平台
请求 URL: https://api.mch.weixin.qq.com/v3/ecommerce/refunds/id/{refund_id}
请求方式: POST
接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3
path 指该参数需在请求 URL 传参query 指该参数需在请求 JSON 传参
请求参数
| 变量 | 类型 | 必填 | 参数名/描述/示例值 |
|---|---|---|---|
| refund_id | string(32) | 是 | 微信退款单号 path 退款单的主键, 唯一定义此资源的标识。 |
| 50000000382019052709732678859 | |||
| sub_mchid | string(32) | 是 | 二级商户号 path 微信支付分配给二级商户的商户号。 |
| 1900000109 |
请求示例
URL https://api.mch.weixin.qq.com/v3/ecommerce/applyments/2000002124775691?sub_mchid=1900000109
2. 通过商户退款单号查询退款
接口说明
适用对象: 电商平台
请求 URL:https://api.mch.weixin.qq.com/v3/ecommerce/refunds/out-refund-no/{out_refund_no}
请求方式: GET
接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3
path 指该参数需在请求 URL 传参query 指该参数需在请求 JSON 传参
请求参数
| 变量 | 类型 | 必填 | 参数名/描述/示例值 |
|---|---|---|---|
| out_refund_no | string(32) | 是 | 商户退款单号 path 商户系统内部的退款单号, 商户系统内部唯一, 同一退款单号多次请求只退一笔。 |
| 1217752501201407033233368018 | |||
| sub_mchid | string(32) | 是 | 二级商户号 path 微信支付分配给二级商户的商户号。 |
| 1900000109 |
请求示例
返回参数
| 变量 | 类型 | 必填 | 参数名/描述/示例值 |
|---|---|---|---|
| refund_id | string(32) | 是 | 微信退款单号 微信支付退款订单号。 |
| 1217752501201407033233368018 | |||
| out_refund_no | string(64) | 是 | 商户退款单号 商户系统内部的退款单号, 商户系统内部唯一, 同一退款单号多次请求只退一笔。 |
| 1217752501201407033233368018 | |||
| transaction_id | string(32) | 是 | 微信订单号 微信支付交易订单号。 |
| 1217752501201407033233368018 | |||
| out_trade_no | string(32) | 是 | 商户订单号 返回的原交易订单号。 |
| 1217752501201407033233368018 | |||
| channel | string(16) | 否 | 退款渠道ORIGINAL: 原路退款 BALANCE: 退回到余额 OTHER_BALANCE: 原账户异常退到其他余额账户 OTHER_BANKCARD: 原银行卡异常退到其他银行卡 |
| ORIGINAL | |||
| user_received_account | string(64) | 否 | 退款入账账户取当前退款单的退款入账方。 退回银行卡: {银行名称}{卡类型}{卡尾号} 退回支付用户零钱: 支付用户零钱 退还商户: 商户基本账户、商户结算银行账户 退回支付用户零钱通: 支付用户零钱通 |
| 招商银行信用卡 0403 | |||
| success_time | string(64) | 否 | 退款成功时间, 遵循 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(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(16) | 是 | 退款状态, 枚举值:SUCCESS: 退款成功 REFUNDCLOSE: 退款关闭 PROCESSING: 退款处理中 ABNORMAL: 退款异常, 退款到银行发现用户的卡作废或者冻结了, 导致原路退款银行卡失败, 可前往【服务商平台—>交易中心】, 手动处理此笔退款 |
| SUCCESS | |||
| amount | object | 是 | +退款金额信息 订单退款金额信息 |
| promotion_detail | array | 否 | +营销详情 优惠退款信息 |
返回示例
正常示例
{
"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
}
]
}
错误码公共错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 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 | 请求受阻 | 此状态代表退款申请失败, 商户可根据具体的错误提示做相应的处理。 |
Feedback
Was this page helpful?
很高兴听到！ 请告诉我们，我们如何才能改善.
很遗憾听到这个消息。 请告诉我们，我们如何才能改善.
最后修改 April 12, 2020: 整理文档 (f36b91e)