申请退款
更新时间:2024.12.18当交易发生之后一年内(按支付成功时间+365天计算),由于用户或者商户原因需要退款时,商户可以通过申请退款接口将支付款退全额或部分还给用户。
注意:
1.一笔订单最多部分退款50次(多次部分退款需更换商户退款单号,间隔1分钟再调用)。
2.申请退款失败重试时请使用原商户退款单号,避免重复退款造成资损。
3.商户号维度调用成功频率限制150qps,错误或无效请求频率限制6qps。
4.申请退款接口返回成功仅代表退款单受理成功,具体退款结果以退款结果通知和查单退款返回为准。
5.一个月之前的订单申请退款如果返回报错"频率限制,1个月之前的订单请降低申请频率再重试",原参重试即可。
接口说明
支持商户:【普通商户】
请求方式:【POST】/v3/refund/domestic/refunds
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
body 包体参数
transaction_id 选填 string(32)
【微信支付订单号】微信支付分扣款单的唯一标识,非0元结单且支付分渠道扣款成功后支付成功回调和查询支付分订单返回的收款信息明细collection.details中包含该字段。
transaction_id和out_trade_no二选一填写,建议商户都通过transaction_id申请退款。
out_trade_no 选填 string(32)
【商户订单号】支付分轮询扣款时生成的商户订单号,只能通过使用transaction_id调用基础支付查单接口获取。
transaction_id和out_trade_no二选一填写,建议商户都通过transaction_id申请退款。
out_refund_no 必填 string(64)
【商户退款单号】商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|@ ,同一退款单号多次请求只退一笔。
reason 选填 string(80)
【退款原因】若商户传入了退款原因,该字段将显示在用户接收到的退款消息通知中。
注意:若订单部分退款且退款金额≤1元,则不会在退款消息中体现退款原因。
notify_url 选填 string(256)
【退款结果回调url】商户异步接收退款结果通知的回调地址,通知url必须为外网可访问的url,不能携带参数,如果申请退款参数中传了notify_url,则商户平台上配置的退款回调地址将不会生效,优先回调当前传的这个地址。需按照notify-url填写注意事项规范填写。
funds_account 选填 string
【退款资金来源】若传递此参数则使用对应的资金账户退款,否则默认使用未结算资金退款(仅对老资金流商户适用)
可选取值:
AVAILABLE: 仅对老资金流商户适用,指定从可用余额账户出资
amount 必填 object
【金额信息】订单金额信息
属性 | |
goods_detail 选填 array[GoodsDetail]
【退款商品】指定商品退款需要传此参数,其他场景无需传递
属性 | |
请求示例
|
应答参数
|
refund_id 必填 string(32)
【微信支付退款号】微信侧返回的退款单唯一标识,由数字组成,50或52开头。
out_refund_no 必填 string(64)
【商户退款单号】商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|@ ,同一退款单号多次请求只退一笔。
transaction_id 必填 string(32)
out_trade_no 必填 string(32)
【商户订单号】支付分轮询扣款时生成的商户订单号。
channel 必填 string
【退款渠道】本单资金实际的退款渠道。
可选取值:
ORIGINAL: 原路退款
BALANCE: 退回到余额
OTHER_BALANCE: 原账户异常退到其他余额账户
OTHER_BANKCARD: 原银行卡异常退到其他银行卡
user_received_account 必填 string(64)
【退款入账账户】
退款单入账方。
取值有以下几种情况
退回银行卡:{银行名称}{卡类型}{卡尾号}
退回支付用户零钱:支付用户零钱
退还商户:商户基本账户商户结算银行账户
退回支付用户零钱通:支付用户零钱通
退回支付用户银行电子账户:支付用户银行电子账户
退回支付用户零花钱:支付用户零花钱
退回用户经营账户:用户经营账户
退回支付用户来华零钱包:支付用户来华零钱包
退回企业支付商户:企业支付商户
success_time 选填 string(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秒。
create_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秒。
status 必填 string
【退款状态】退款单状态。
可选取值:
SUCCESS: 退款成功
CLOSED: 退款关闭
PROCESSING: 退款处理中
ABNORMAL: 退款异常,需商户平台手动处理,参考交易退款方法介绍。
funds_account 选填 string
【资金账户】退款所使用资金对应的资金账户类型
可选取值:
UNSETTLED: 未结算资金
AVAILABLE: 可用余额
UNAVAILABLE: 不可用余额
OPERATION: 运营户
BASIC: 基本账户(含可用余额和不可用余额)
ECNY_BASIC: 数字人民币基本账户
amount 必填 object
【金额信息】金额详细信息
属性 | |
promotion_detail 选填 array[object]
【优惠退款信息】代金券信息,当订单支付时,有使用代金券时,该字段将返回所使用的代金券信息。
属性 | |
应答示例
|
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | INVALID_REQUEST | 请求参数符合参数格式,但不符合业务规则 | 此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。 |
401 | SIGN_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求 |
403 | NO_AUTH | 没有退款权限 | 此状态代表退款申请失败,请检查是否有该笔订单的退款权限 |
403 | NOT_ENOUGH | 余额不足 | 此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。 |
403 | USER_ACCOUNT_ABNORMAL | 退款请求失败 | 此状态代表退款申请失败,商户可自行处理退款。 |
404 | MCH_NOT_EXISTS | MCHID不存在 | 请检查MCHID是否正确 |
404 | RESOURCE_NOT_EXISTS | 订单号不存在 | 请检查你的订单号是否正确且是否已支付,未支付的订单不能发起退款 |
429 | FREQUENCY_LIMITED | 频率限制 | 该笔退款未受理,请降低频率后重试 |
500 | SYSTEM_ERROR | 系统超时 | 请不要更换商户退款单号,请使用相同参数再次调用API。 |