最新更新时间：2022.09.01 版本说明
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账户上。
1. 交易时间超过一年的订单无法提交退款。
2. 微信支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号。
3. 请求频率限制：150qps，即每秒钟正常的申请退款请求次数不超过150次，单笔订单请求频率限制：1qpm，即单笔订单每分钟申请退款请求次数不超过1次。
4. 每个支付订单的部分退款次数不能超过50次。
5. 申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口获取结果。
6. 当二级商户退款账户余额不足时，可发起垫付退款，从电商平台指定账户垫付退款资金。当二级商户退款账户余额充足时，可把退款垫付的资金回补到电商平台账户。垫付退款需要向微信支付申请开通权限，开通权限时需要指定一个垫付出款账户。
适用对象：电商平台
请求URL：https://api.mch.weixin.qq.com/v3/ecommerce/refunds/apply
请求方式：POST
path指该参数为路径参数
query指该参数需在请求URL传参
body指该参数需在请求JSON传参
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 二级商户号 | sub_mchid | string[1,32] | 是 | body 微信支付分配二级商户的商户号。 示例值： 1900000109 |
| 电商平台APPID | sp_appid | string[1,32] | 是 | body 电商平台在微信公众平台申请服务号对应的APPID，申请商户功能的时候微信支付会配置绑定关系。 示例值：wx8888888888888888 |
| 二级商户APPID | sub_appid | string[1,32] | 否 | body 二级商户在微信申请公众号成功后分配的账户ID，需要电商平台侧配置绑定关系才能传参（即二级商户已绑定微信公众号时传入）。 示例值：wx8888888888888888 |
| 微信订单号 | transaction_id | string[1,32] | 二选一 | body 原支付交易对应的微信订单号。 示例值：1217752501201407033233368018 |
| 商户订单号 | out_trade_no | string[1,32] | body 原支付交易对应的商户订单号。 示例值：1217752501201407033233368018 |
|
| 商户退款单号 | out_refund_no | string[1,64] | 是 | body 商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@，同一退款单号多次请求只退一笔。 示例值：1217752501201407033233368018 |
| 退款原因 | reason | string[1,80] | 否 | body 若商户传入，会在下发给用户的退款消息中体现退款原因。 注意：若订单退款金额≤1元，且属于部分退款，则不会在退款消息中体现退款原因 示例值：商品已售完 |
| +订单金额 | amount | object | 是 | body 订单金额信息 |
| 退款结果回调url | notify_url | string[1,256] | 否 | body 异步接收微信支付退款结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。 如果参数中传了notify_url，则商户平台上配置的回调地址将不会生效，优先回调当前传的地址。 示例值：https://weixin.qq.com |
| 退款出资商户 | refund_account | string[1, 32] | 否 | body电商平台垫资退款专用参数。需先确认已开通此功能后，才能使用。若需要开通，请联系微信支付客服。 枚举值： REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付，需要向微信支付申请开通 REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值 注意： 若传入REFUND_SOURCE_PARTNER_ADVANCE，仅代表可以使用垫付退款，实际出款账户需以退款申请受理结果或查单结果为准。 示例值：REFUND_SOURCE_SUB_MERCHANT |
| 资金账户 | funds_account | string[1, 32] | 否 | body若订单处于待分账状态，且未指定垫资退款（即refund_account未指定为REFUND_SOURCE_PARTNER_ADVANCE），可以传入此参数，指定退款资金来源账户。当该字段不存在时，默认使用订单交易资金所在账户出款，即待分账时使用不可用余额的资金进行退款，已分账或无分账时使用可用余额的资金进行退款。 AVAILABLE：可用余额 示例值：AVAILABLE |
{
"sub_mchid": "1900000109",
"sp_appid": "wx8888888888888888",
"sub_appid": "wx8888888888888888",
"transaction_id": "1217752501201407033233368018",
"out_trade_no": "1217752501201407033233368018",
"out_refund_no": "1217752501201407033233368018",
"reason": "商品已售完",
"amount": {
"refund": 888,
"total": 888,
"currency": "CNY"
},
"notify_url": "https://weixin.qq.com",
"refund_account": "REFUND_SOURCE_SUB_MERCHANT"
}
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信退款单号 | refund_id | string[1,32] | 是 | 微信支付退款订单号。 示例值：1217752501201407033233368018 |
| 商户退款单号 | out_refund_no | string[1,64] | 是 | 商户系统内部的退款单号，商户系统内部唯一，同一退款单号多次请求只退一笔。 示例值：1217752501201407033233368018 |
| 退款创建时间 | create_time | string[1,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 |
| +订单金额 | amount | object | 是 | 订单金额信息 |
| +优惠退款详情 | promotion_detail | array | 否 | 优惠退款功能信息，discount_refund>0时，返回该字段 示例值：见示例 |
| 退款资金来源 | refund_account | string[1, 32] | 否 | 枚举值： REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付 REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值 示例值：REFUND_SOURCE_SUB_MERCHANT |
{
"refund_id": "1217752501201407033233368018",
"out_refund_no": "1217752501201407033233368018",
"create_time": "2018-06-08T10:34:56+08:00",
"amount": {
"refund": 888,
"payer_refund": 888,
"discount_refund": 888,
"currency": "CNY"
},
"promotion_detail": [
{
"promotion_id": "109518",
"scope": "SINGLE",
"type": "DISCOUNT",
"amount": 5,
"refund_amount": 100
},
{
"promotion_id": "109519",
"scope": "SINGLE",
"type": "DISCOUNT",
"amount": 5,
"refund_amount": 100
}
],
"refund_account": "REFUND_SOURCE_SUB_MERCHANT"
}
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 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 | USER_ACCOUNT_ABNORMAL | 用户账户异常或已注销，不能原路退回，请使用其他方式进行退款。 | 此状态代表退款申请失败，商户可自行处理退款。或前往服务商-交易中心，重新发起退款。 |
| 403 | NOT_ENOUGH | 余额不足 | 根据提示进行充值后重试。 |