申请退款

更新时间：2026.05.21

1. 场景说明

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，网联将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。

注意：

1）交易时间超过一年的订单无法提交退款；

2）网联退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。

一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号。

3）请求频率限制：150qps，即每秒钟正常的申请退款请求次数不超过150次。错误或无效请求频

率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次。

4）每个支付订单的部分退款次数不能超过50次。

2. 接口说明

2.1 请求参数

字段名	变量名	是否必填	类型	示例值	描述
公众账号 ID	`appid`	是	`String(32)`	`wx8888888888888888`	微信分配的公众账号 ID。
商户号	`mch_id`	是	`String(32)`	`1900000109`	微信支付分配的商户号。
子商户公众账号 ID	`sub_appid`	否	`String(32)`	`wx8888888888888888`	微信分配的子商户公众账号 ID。
子商户号	`sub_mch_id`	是	`String(32)`	`1900000109`	微信支付分配的子商户号。
渠道商商户号	`channel_id`	是	`String(32)`	`19000001`	微信支付分配给收单服务商的 ID。
随机字符串	`nonce_str`	是	`String(32)`	`5K8264ILTKCH16CQ2502SI8ZNMTM67VS`	随机字符串，不长于 32 位。推荐随机数生成算法。
签名	`sign`	是	`String(512)`	`C380BEC2BFD727A4B6845133519F3AD6`	签名。
商户订单号	`out_trade_no`	是	`String(32)`	`12121217752501201407033233368010`	原交易的商户订单号，32 个字符以内、可包含字母、数字、下划线；需保证在商户端不重复。
网联 IDC 标识	`idc_flag`	是	`String(2)`	`10`	交易发往的网联条码支付 IDC 标识，具体规则见 4.8 网联条码支付 IDC 标识。
商户退款单号	`out_refund_no`	是	`String(64)`	`1217752501201407033233368018`	商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母同一退款单号多次请求只退一笔。
申请退款金额	`refund_fee`	是	`Int`	`100`	退款总金额，单位为分，只能为整数，可部分退款。
退款货币种类	`refund_fee_type`	否	`String(8)`	`CNY`	符合 ISO 4217 标准的三位字母代码，默认人民币：CNY。
退款原因	`refund_desc`	否	`String(80)`	`商品已售完`	若商户传入，会在下发给用户的退款消息中体现退款原因。
退款资金来源	`refund_account`	否	`String(30)`	`REFUND_SOURCE_RECHARGE_FUNDS`	仅针对老资金流商户使用。`REFUND_SOURCE_UNSETTLED_FUNDS`- 未结算资金退款（默认使用未结算资金退款）。`REFUND_SOURCE_RECHARGE_FUNDS`--- 可用余额退款。
退款结果通知 url	`notify_url`	否	`String(256)`	`https://weixin.qq.com/notify/`	异步接收网联退款结果通知的回调地址，通知 URL 必须为外网可访问的 url，不允许带参数。
收单机构商户编码	`sub_mch_no`	否	`String(32)`	`2537648901526`	收单机构商户编码
总金额	`total_fee`	是	`Int`	`888`	订单总金额，单位为分，只能为整数。

2.2 响应参数

字段名	变量名	是否必填	类型	示例值	描述
返回状态码	`return_code`	是	`String(16)`	`SUCCESS`	`SUCCESS/FAIL`。此字段是通信标识，非交易标识，交易是否成功需要查看 `result_code` 来判断。
返回信息	`return_msg`	否	`String(128)`	`签名失败`	返回信息，如非空，为错误原因。签名失败。参数格式校验错误。

当return_code为SUCCESS的时候，还会包括以下字段：

字段名	变量名	是否必填	类型	示例值	描述
业务结果	`result_code`	是	`String(16)`	`SUCCESS`	`SUCCESS/FAIL`。
错误代码	`err_code`	否	`String(32)`	`SYSTEMERROR`	-
错误代码描述	`err_code_des`	否	`String(128)`	`系统错误`	错误返回的信息描述。
公众账号 ID	`appid`	是	`String(32)`	`wx8888888888888888`	调用接口提交的公众账号 ID。
商户号	`mch_id`	是	`String(32)`	`1900000109`	调用接口提交的商户号。
子商户公众账号 ID	`sub_appid`	否	`String(32)`	`wx8888888888888888`	调用接口提交的子商户公众账号 ID。
子商户号	`sub_mch_id`	是	`String(32)`	`1900000109`	调用接口提交的子商户号。
随机字符串	`nonce_str`	是	`String(32)`	`5K8264ILTKCH16CQ2502SI8ZNMTM67VS`	网联返回的随机字符串。
签名	`sign`	是	`String(512)`	`C380BEC2BFD727A4B6845133519F3AD6`	网联返回的签名。
商户退款单号	`out_refund_no`	是	`String(64)`	`1217752501201407033233368018`	商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母，同一退款单号多次请求只退一笔。
网联退款单号	`refund_id`	是	`String(32)`	`1217752501201407033233368018`	网联退款单号。
申请退款金额	`refund_fee`	是	`Int`	`100`	退款总金额，单位为分，只能为整数，可部分退款。
货币种类	`refund_fee_type`	否	`String(8)`	`CNY`	符合 ISO 4217 标准的三位字母代码，默认人民币：`CNY`。
现金退款金额	`cash_refund_fee`	否	`Int`	`100`	现金退款金额，单位为分，只能为整数。
代金券退款总金额	`coupon_refund_fee`	否	`Int`	`100`	代金券退款金额`<=`退款金额，退款金额 - 代金券或立减优惠退款金额为现金。
优惠退款详情	`refund_detail`	否	`List`	-	优惠功能信息，使用 JSON 数组格式，详细说明见下文。

其中，refund_detail包含如下子域：

字段名	变量名	是否必填	类型	示例值	描述
券 ID	`promotion_id`	是	`String(32)`	`109519`	券或者立减优惠 id。
优惠范围	`scope`	否	`String(32)`	`SINGLE`	`GLOBAL`- 全场代金券；`SINGLE`- 单品优惠。
优惠类型	`type`	否	`String(32)`	`DISCOUNT`	`COUPON`- 代金券，需要走结算资金的充值型代金券（境外商户券币种与支付币种一致）；`DISCOUNT`- 优惠券，不走结算资金的免充值型优惠券（境外商户券币种与标价币种一致）。
优惠券退款额	`refund_amount`	否	`Int`	`5`	用户享受优惠的金额。
优惠券面额	`amount`	否	`Int`	`5`	用户享受优惠的金额。

3. 错误码

名称	描述	原因	解决方案
`SYSTEMERROR`	接口返回错误	系统超时	请不要更换商户退款单号，请使用相同参数再次调用 API。
`BIZERR_NEED_RETRY`	退款业务流程错误，需要商户触发重试来解决	并发情况下，业务被拒绝，商户重试即可解决	请不要更换商户退款单号，请使用相同参数再次调用 API。
`TRADE_OVERDUE`	订单已经超过退款期限	订单已经超过可退款的最大期限（支付后一年内可退款）	请选择其他方式自行退款
`ERROR`	业务错误	申请退款业务发生错误	该错误都会返回具体的错误原因，请根据实际返回做相应处理。
`USER_ACCOUNT_ABNORMAL`	退款请求失败	用户账号注销	此状态代表退款申请失败，商户可自行处理退款。
`INVALID_REQ_TOO_MUCH`	无效请求过多	连续错误请求数过多被系统短暂屏蔽	请检查业务是否正常，确认业务正常后请在 1 分钟后再来重试
`NOTENOUGH`	余额不足	商户可退余额不足	此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。
`INVALID_TRANSACTIONID`	无效 `transaction_id`	请求参数未按指引进行填写	请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败
`PARAM_ERROR`	参数错误	请求参数未按指引进行填写	请求参数错误，请重新检查再调用退款申请
`APPID_NOT_EXIST`	`APPID` 不存在	参数中缺少 `APPID`	请检查 `APPID` 是否正确
`MCHID_NOT_EXIST`	`MCHID` 不存在	参数中缺少 `MCHID`	请检查 `MCHID` 是否正确
`REQUIRE_POST_METHOD`	请使用 `post` 方法	未使用 `post` 传递参数	请检查请求参数是否通过 `post` 方法提交
`SIGNERROR`	签名错误	参数签名结果不正确	请检查签名参数和方法是否都符合签名算法要求
`XML_FORMAT_ERROR`	XML 格式错误	XML 格式错误	请检查 XML 参数格式是否正确
`FREQUENCY_LIMITED`	频率限制	2 个月之前的订单申请退款有频率限制	该笔退款未受理，请降低频率后重试

文档是否有帮助