应用场景

当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家账号上。
注意:
1、交易时间超过一年的订单无法提交退款
2、微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号
3、请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次
4、每个支付订单的部分退款次数不能超过50次
5、如果同一个用户有多笔退款,建议分不同批次进行退款,避免并发退款导致退款失败
6、申请退款接口的返回仅代表业务的受理情况,具体退款是否成功,需要通过退款查询接口获取结果。
7、一个月之前的订单申请退款频率限制为:5000/min

状态机

退款状态转变如下:

接口地址

接口链接:https://api.mch.weixin.qq.com/secapi/pay/refund

是否需要证书

请求需要双向证书。 详见证书使用

请求参数

字段名变量名必填类型示例值描述
公众账号IDappid是String(32)wx8888888888888888微信分配的公众账号ID(企业号corpid即为此appid)
商户号mch_id是String(32)1900000109微信支付分配的商户号
签名类型sign_type否String(32)HMAC-SHA256签名类型,目前支持HMAC-SHA256和MD5,默认为MD5
微信支付订单号transaction_id二选一String(32)1217752501201407033233368018微信生成的订单号,在支付通知中有返回
商户订单号out_trade_noString(32)1217752501201407033233368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-|*@ ,且在同一个商户号下唯一。
transaction_id、out_trade_no二选一,如果同时存在优先级:transaction_id> out_trade_no
商户退款单号out_refund_no是String(64)1217752501201407033233368018商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
退款原因refund_desc否String(80)商品已售完
若商户传入,会在下发给用户的退款消息中体现退款原因
注意:若订单退款金额≤1元,且属于部分退款,则不会在退款消息中体现退款原因
退款资金来源refund_account否String(30)REFUND_SOURCE_RECHARGE_FUNDS
仅针对老资金流商户使用
REFUND_SOURCE_UNSETTLED_FUNDS---未结算资金退款(默认使用未结算资金退款)
REFUND_SOURCE_RECHARGE_FUNDS---可用余额退款
退款结果通知urlnotify_url否String(256)https://weixin.qq.com/notify/
异步接收微信支付退款结果通知的回调地址,通知URL必须为外网可访问的url,不允许带参数
公网域名必须为https,如果是走专线接入,使用专线NAT IP或者私有回调域名可使用http
如果参数中传了notify_url,则商户平台上配置的回调地址将不会生效。

举例如下:
wx2421b1c4370ec43b
10000100
6cefdb308e1e2e8aabd48cf79e546a02
1415701182
1415757673
1
1
4006252001201705123297353072
FE56DD4AA85C0EECA82C35595A69E153

返回结果

字段名变量名必填类型示例值描述
返回状态码return_code是String(16)SUCCESS
SUCCESS/FAIL
此字段是通信标识,表示接口层的请求结果,并非退款状态。
返回信息return_msg是String(128)OK
当return_code为FAIL时返回信息为错误原因 ,例如
签名失败
参数格式校验错误

以下字段在return_code为SUCCESS的时候有返回

字段名变量名必填类型示例值描述
业务结果result_code是String(16)SUCCESS
SUCCESS/FAIL
SUCCESS退款申请接收成功,结果通过退款查询接口查询
FAIL 提交业务失败
错误代码err_code否String(32)SYSTEMERROR列表详见错误码列表
错误代码描述err_code_des否String(128)系统超时结果信息描述
公众账号IDappid是String(32)wx8888888888888888微信分配的公众账号ID
商户号mch_id是String(32)1900000109微信支付分配的商户号
随机字符串nonce_str是String(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位
微信支付订单号transaction_id是String(32)4007752501201407033233368018微信订单号
商户订单号out_trade_no是String(32)33368018商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-|*@ ,且在同一个商户号下唯一。
商户退款单号out_refund_no是String(64)121775250商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
微信退款单号refund_id是String(32)2007752501201407033233368018微信退款单号
退款金额refund_fee是int100退款总金额,单位为分,可以做部分退款
应结退款金额settlement_refund_fee否int100去掉非充值代金券退款金额后的退款金额,退款金额=申请退款金额-非充值代金券退款金额,退款金额