应用场景

当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家账号上。
注意:
1、交易时间超过一年的订单无法提交退款;
2、微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号。
3、请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次
4、每个支付订单的部分退款次数不能超过50次
5、本接口支持单品优惠订单全额退款和单品优惠订单部分退款,推荐使用本接口,如果使用不支持单品优惠部分退款的历史接口,请看https://pay.weixin.qq.com/wiki/doc/api/jsapi_sl.php?chapter=9_4

接口地址

https://api.mch.weixin.qq.com/secapi/pay/refundv2

是否需要证书

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

请求参数

字段名变量名必填类型示例值描述
商品详情detail否String(6000)示例见下文退款包含的商品列表信息,全额退款可不传,必须按照规范上传,JSON格式,详见下文【退款包含的商品列表信息】
其他字段列表见

退款包含的商品列表信息detail字段列表说明:

字段名变量名必填类型示例值描述
商品列表goods_detail是String示例见下文商品信息,使用Json数组格式提交

商品列表goods_detail字段列表说明:

字段名变量名必填类型示例值描述
商品编码goods_id是String(32)商品编码由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
微信侧商品编码wxpay_goods_id否String(32)1001微信支付定义的统一商品编号(没有可不传)
商品名称goods_name否String(256)iPhone6s 16G商品的实际名称
商品退款金额refund_amount是int528800商品退款金额
商品退货数量refund_quantity是int1单品的退款数量
商品单价price是int528800单位为:分。如果商户有优惠,需传输商户优惠后的单价(例如:用户对一笔100元的订单使用了商场发的优惠券100-50,则活动商品的单价应为原单价-50)

detail字段值举例如下:
{
"goods_detail": [
{
"goods_id": "商品编码",
"wxpay_goods_id": "1001",
"goods_name": "iPhone6s 16G",
"refund_amount": 528800,
"refund_quantity": 1,
"price": 528800
},
{
"goods_id": "商品编码",
"wxpay_goods_id": "1001",
"goods_name": "iPhone6s 16G",
"refund_amount": 528800,
"refund_quantity": 1,
"price": 608800
}
]
}
提交退款数据举例如下:
wx2421b1c4370ec43b
10000100
6cefdb308e1e2e8aabd48cf79e546a02
https://weixin.qq.com/
1415701182
1415757673
1
1
{"goods_detail":[{"goods_id":"商品编码","wxpay_goods_id":"1001","goods_name":"iPhone6s
16G","refund_amount":528800,"refund_quantity":1,"price":528800},{"goods_id":"商品编码","wxpay_goods_id":"1001","goods_name":"iPhone6s
16G","refund_amount" ":528800,"refund_quantity":1,"price":608800}]}
FE56DD4AA85C0EECA82C35595A69E153

返回结果

字段名变量名必填类型示例值描述
返回状态码return_code是String(16)SUCCESSSUCCESS/FAIL
返回信息return_msg否String(128)签名失败返回信息,如非空,为错误原因
签名失败
参数格式校验错误

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

字段名变量名必填类型示例值描述
下单时传了version,返回参数会有差异,详情参考:《注意事项》
营销详情promotion_detail否String(6000)示例见下文营销详情列表,使返回值为Json格式

优惠活动promotion_detail字段列表说明:

字段名变量名必填类型示例值描述
券IDpromotion_id是String(32)109519券或者立减优惠id
优惠范围scope是String(32)SINGLEGLOBAL- 全场代金券
SINGLE- 单品优惠
优惠类型type是String(32)DISCOUNTCOUPON- 代金券,需要走结算资金的充值型代金券,(境外商户券币种与支付币种一致)
DISCOUNT- 优惠券,不走结算资金的免充值型优惠券,(境外商户券币种与标价币种一致
代金券退款金额refund_amount是int100代金券退款金额