申请退款API
最新更新时间：2022.08.29 版本说明
当交易发生之后一年内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付金额退还给买家，微信支付将在收到退款请求并且验证成功之后，将支付款按原路退还至买家账号上。
注意：
1、交易时间超过一年的订单无法提交退款
2、微信支付退款支持单笔交易分多次退款（不超50次），多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号
3、错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次
4、每个支付订单的部分退款次数不能超过50次
5、如果同一个用户有多笔退款，建议分不同批次进行退款，避免并发退款导致退款失败
6、申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口获取结果
7、一个月之前的订单申请退款频率限制为：5000/min
8、同一笔订单多次退款的请求需相隔1分钟
状态机
退款状态转变如下：
接口说明
适用对象：服务商
请求URL：https://api.mch.weixin.qq.com/v3/refund/domestic/refunds
请求方式：POST
接口频率：150qps
path 指该参数为路径参数
query 指该参数为URL参数
body 指该参数需在请求JSON传参
请求参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 子商户号 | sub_mchid | string[1, 32] | 是 | body子商户的商户号，由微信支付生成并下发。 示例值：1900000109 |
| 微信支付订单号 | transaction_id | string[1, 32] | 二选一 | body原支付交易对应的微信订单号 示例值：1217752501201407033233368018 |
| 商户订单号 | out_trade_no | string[6, 32] | body原支付交易对应的商户订单号 示例值：1217752501201407033233368018 |
|
| 商户退款单号 | out_refund_no | string[1, 64] | 是 | body商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。 示例值：1217752501201407033233368018 |
| 退款原因 | reason | string[1, 80] | 否 | body若商户传入，会在下发给用户的退款消息中体现退款原因 示例值：商品已售完 |
| 退款结果回调url | notify_url | string[8, 256] | 否 | body异步接收微信支付退款结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。 如果参数中传了notify_url，则商户平台上配置的回调地址将不会生效，优先回调当前传的这个地址。 示例值：https://weixin.qq.com |
| 退款资金来源 | funds_account | string[1,32] | 否 | body若传递此参数则使用对应的资金账户退款，否则默认使用未结算资金退款（仅对老资金流商户适用） 枚举值： AVAILABLE：可用余额账户 示例值：AVAILABLE |
| +金额信息 | amount | object | 是 | body订单金额信息 |
| +退款商品 | goods_detail | array | 否 | body指定商品退款需要传此参数，其他场景无需传递 |
请求示例
{
"sub_mchid": "1900000109",
"transaction_id": "1217752501201407033233368018",
"out_refund_no": "1217752501201407033233368018",
"reason": "商品已售完",
"notify_url": "https://weixin.qq.com",
"funds_account": "AVAILABLE",
"amount": {
"refund": 888,
"from": [
{
"account": "AVAILABLE",
"amount": 444
}
],
"total": 888,
"currency": "CNY"
},
"goods_detail": [
{
"merchant_goods_id": "1217752501201407033233368018",
"wechatpay_goods_id": "1001",
"goods_name": "iPhone6s 16G",
"unit_price": 528800,
"refund_amount": 528800,
"refund_quantity": 1
}
]
}
返回参数
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信支付退款单号 | refund_id | string[1, 32] | 是 | 微信支付退款单号 示例值：50000000382019052709732678859 |
| 商户退款单号 | 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] | 是 | 取当前退款单的退款入账方，有以下几种情况： 1）退回银行卡：{银行名称}{卡类型}{卡尾号} 2）退回支付用户零钱:支付用户零钱 3）退还商户:商户基本账户商户结算银行账户 4）退回支付用户零钱通:支付用户零钱通 示例值：招商银行信用卡0403 |
| 退款成功时间 | success_time | string[1, 64] | 否 | 退款成功时间，当退款状态为退款成功时有返回。 示例值：2020-12-01T16:18:12+08:00 |
| 退款创建时间 | create_time | string[1, 64] | 是 | 退款受理时间 示例值：2020-12-01T16:18:12+08:00 |
| 退款状态 | status | string[1, 32] | 是 | 退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往服务商平台-交易中心，手动处理此笔退款。 枚举值： SUCCESS：退款成功 CLOSED：退款关闭 PROCESSING：退款处理中 ABNORMAL：退款异常 示例值：SUCCESS |
| 资金账户 | funds_account | string[1, 32] | 否 | 退款所使用资金对应的资金账户类型 枚举值： UNSETTLED : 未结算资金 AVAILABLE : 可用余额 UNAVAILABLE : 不可用余额 OPERATION : 运营户 BASIC : 基本账户（含可用余额和不可用余额） 示例值：UNSETTLED |
| +金额信息 | amount | object | 是 | 金额详细信息 |
| +优惠退款信息 | promotion_detail | array | 否 | 优惠退款信息 |
返回示例
{
"refund_id": "50000000382019052709732678859",
"out_refund_no": "1217752501201407033233368018",
"transaction_id": "1217752501201407033233368018",
"out_trade_no": "1217752501201407033233368018",
"channel": "ORIGINAL",
"user_received_account": "招商银行信用卡0403",
"success_time": "2020-12-01T16:18:12+08:00",
"create_time": "2020-12-01T16:18:12+08:00",
"status": "SUCCESS",
"funds_account": "UNSETTLED",
"amount": {
"total": 100,
"refund": 100,
"from": [
{
"account": "AVAILABLE",
"amount": 444
}
],
"payer_total": 90,
"payer_refund": 90,
"settlement_refund": 100,
"settlement_total": 100,
"discount_refund": 10,
"currency": "CNY"
},
"promotion_detail": [
{
"promotion_id": "109519",
"scope": "SINGLE",
"type": "DISCOUNT",
"amount": 5,
"refund_amount": 100,
"goods_detail": [
{
"merchant_goods_id": "1217752501201407033233368018",
"wechatpay_goods_id": "1001",
"goods_name": "iPhone6s 16G",
"unit_price": 528800,
"refund_amount": 528800,
"refund_quantity": 1
}
]
}
]
}
错误码公共错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 系统超时 | 请不要更换商户退款单号，请使用相同参数再次调用API。 |
| 403 | USER_ACCOUNT_ABNORMAL | 退款请求失败 | 此状态代表退款申请失败，商户可自行处理退款。 |
| 403 | NOT_ENOUGH | 余额不足 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| 400 | PARAM_ERROR | 参数错误 | 请求参数错误，请重新检查再调用申请退款接口 |
| 404 | MCH_NOT_EXISTS | MCHID不存在 | 请检查MCHID是否正确 |
| 404 | RESOURCE_NOT_EXISTS | 订单号不存在 | 请检查你的订单号是否正确且是否已支付，未支付的订单不能发起退款 |
| 401 | SIGN_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求 |
| 429 | FREQUENCY_LIMITED | 频率限制 | 该笔退款未受理，请降低频率后重试 |
| 400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| 403 | NO_AUTH | 没有退款权限 | 此状态代表退款申请失败，请检查是否有该笔订单的退款权限 |