应用场景
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。
| 交易时间超过一年的订单无法提交退款； 微信支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号。 请求频率限制：150qps，即每秒钟正常的申请退款请求次数不超过150次 每个支付订单的部分退款次数不能超过50次 本接口支持单品优惠订单全额退款和单品优惠订单部分退款，推荐使用本接口，如果使用不支持单品优惠部分退款的历史接口，请看申请退款接口文档
|
|
接口地址
https://api.mch.weixin.qq.com/secapi/pay/refundv2
https://api2.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 | 是 | int | 528800 | 商品退款金额 | 商品退货数量 | refund_quantity | 是 | int | 1 | 单品的退款数量 | 商品单价 | price | 是 | int | 528800 | 单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的优惠券100-50，则活动商品的单价应为原单价-50) |
|
|
|
|
其他字段列表见 申请退款API（普通商户） 申请退款API（服务商） |
1{
2"goods_detail": [
3{
4"goods_id": "商品编码",
5"wxpay_goods_id": "1001",
6"goods_name": "iPhone6s 16G",
7"refund_amount": 528800,
8"refund_quantity": 1,
9"price": 528800
10},
11{
12"goods_id": "商品编码",
13"wxpay_goods_id": "1001",
14"goods_name": "iPhone6s 16G",
15"refund_amount": 528800,
16"refund_quantity": 1,
17"price": 608800
18}
19]
20}1<xml>
2<appid>wx2421b1c4370ec43b</appid>
3<mch_id>10000100</mch_id>
4<nonce_str>6cefdb308e1e2e8aabd48cf79e546a02</nonce_str>
5<notify_url>https://weixin.qq.com/</notify_url>
6<out_refund_no>1415701182</out_refund_no>
7<out_trade_no>1415757673</out_trade_no>
8<refund_fee>1</refund_fee>
9<total_fee>1</total_fee>
10<transaction_id></transaction_id>
11<detail>{"goods_detail":[{"goods_id":"商品编码","wxpay_goods_id":"1001","goods_name":"iPhone6s
1216G","refund_amount":528800,"refund_quantity":1,"price":528800},{"goods_id":"商品编码","wxpay_goods_id":"1001","goods_name":"iPhone6s
1316G","refund_amount" ":528800,"refund_quantity":1,"price":608800}]}</ detail>
14<sign>FE56DD4AA85C0EECA82C35595A69E153</sign>
15</xml>返回结果
|
返回状态码 | return_code | 是 | String(16) | SUCCESS | SUCCESS/FAIL |
返回信息 | return_msg | 否 | String(128) | 签名失败 | 返回信息，如非空，为错误原因
签名失败
参数格式校验错误 |
以下字段在return_code为SUCCESS的时候有返回
|
其他字段列表见 申请退款API（普通商户） 申请退款API（服务商） 下单时传了version，返回参数会有差异，详情参考：《注意事项》 |
营销详情 | promotion_detail | 否 | String(6000) | 示例见下文 | 营销详情列表，使返回值为Json格式 |
| 优惠活动promotion_detail字段列表说明： | | |
券ID | promotion_id | 是 | String(32) | 109519 | 券或者立减优惠id | 优惠范围 | scope | 是 | String(32) | SINGLE | GLOBAL- 全场代金券
SINGLE- 单品优惠 | 优惠类型 | type | 是 | String(32) | DISCOUNT | COUPON- 代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致）
DISCOUNT- 优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致 | 代金券退款金额 | refund_amount | 是 | int | 100 | 代金券退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为现金，说明详见代金券或立减优惠 | 商品列表 | goods_detail | 否 | String | 见下文 | 商品信息，使用Json格式 | | 商品列表goods_detail字段列表说明： | | |
商品编码 | goods_id | 是 | String(32) | 商品编码 | 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 | 优惠退款金额 | refund_amount | 是 | int | 528800 | 优惠退款金额 | 商品退货数量 | refund_quantity | 是 | int | 1 | 单品的退货数量 | 商品单价 | price | 是 | int | 528800 | 单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的优惠券100-50，则活动商品的单价应为原单价-50) |
|
|
|
|
1{
2"promotion_detail":[
3{
4"promotion_id":"109519",
5"scope":"SINGLE",
6"type":"DISCOUNT",
7"refund_amout":5,
8"goods_detail":[
9{
10"goods_id":"a_goods1",
11"refund_quantity":7,
12"price":1,
13"refund_amount":4
14},
15{
16"goods_id":"a_goods2",
17"refund_quantity":1,
18"price":2,
19"refund_amount":1
20}
21]
22}
23]
24}1<xml>
2<return_code><![CDATA[SUCCESS]]></return_code>
3<return_msg><![CDATA[OK]]></return_msg>
4<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
5<mch_id><![CDATA[10000100]]></mch_id>
6<nonce_str><![CDATA[NfsMFbUFpdbEhPXP]]></nonce_str>
7<sign><![CDATA[B7274EB9F8925EB93100DD2085FA56C0]]></sign>
8<result_code><![CDATA[SUCCESS]]></result_code>
9<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
10<out_trade_no><![CDATA[1415757673]]></out_trade_no>
11<out_refund_no><![CDATA[1415701182]]></out_refund_no>
12<refund_id><![CDATA[2008450740201411110000174436]]></refund_id>
13<refund_channel><![CDATA[]]></refund_channel>
14<total_fee>1</total_fee >
15<refund_fee>1</refund_fee>
16<cash_fee>1</cash_fee >
17<promotion_detail>{"promotion_detail":[{"promotion_id":"109519","scope":"SINGLE","type":"DISCOUNT","refund_amout":5,"goods_detail":[{"goods_id":"a_goods1","refund_quantity":7,"price":1,"refund_amount":4},{"goods_id":"a_goods2","refund_quantity":1,"price":2,"refund_amount":1}]}]}</promotion_detail>
18</xml>错误码
|
ERROR | 单品存在不同的单价，建议走整单退 | 退款请求参数中goods_id出现不同单价 | 1、下单时，同一个goods_id，其price应该相同
2、退款时把goods_id相同且price不同的单品分别进行退款 |
单品金额超过订单金额，请全额退款 | 退款单品金额超过订单金额 | 1、下单时，商户所传的单品信息goods_detail，满足单品纪录的unit_price * quantity的总和等于amount.total
2、检查退款时传入的订单金额与单品金额是否有误 |
goods_id出现多次，建议调整退单品参数或者全额退 | 指定退款的单品，不能出现重复，未满足业务规则 | 退款请求时把单品做合并 |
请使用全额退款 | 该笔订单不支持单品部分退，请使用全额退款 | 请使用全额退款 |
输入的金额较低无法退款成功，建议将本订单进行整单退款。 | 输入的金额较低无法退款 | 建议将本订单进行整单退款 |
商品编码不存在于订单中 | 退款单品只能是订单下单时传入goods_id的单品 | 只能退下单时传入的单品 |
SYSTEMERROR | 接口返回错误 | 系统超时 | 请用相同参数再次调用API |
INVALID_TRANSACTIONID | 无效transaction_id | 请求参数未按指引进行填写 | 请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败（明确错误，请勿重试） |
PARAM_ERROR | 参数错误 | 请求参数未按指引进行填写 | 请求参数错误，请重新检查再调用退款申请（明确错误，请勿重试） |
APPID_NOT_EXIST | APPID不存在 | 参数中缺少APPID | 请检查APPID是否正确（明确错误，请勿重试） |
MCHID_NOT_EXIST | MCHID不存在 | 参数中缺少MCHID | 请检查MCHID是否正确（明确错误，请勿重试） |
APPID_MCHID_NOT_MATCH | appid和mch_id不匹配 | appid和mch_id不匹配 | 请确认appid和mch_id是否匹配 |
REQUIRE_POST_METHOD | 请使用post方法 | 未使用post传递参数 | 请检查请求参数是否通过post方法提交（明确错误，请勿重试） |
SIGNERROR | 签名错误 | 参数签名结果不正确 | 请检查签名参数和方法是否都符合签名算法要求（明确错误，请勿重试） |
XML_FORMAT_ERROR | XML格式错误 | XML格式错误 | 请检查XML参数格式是否正确（明确错误，请勿重试） |
TRADE_OVERDUE | 订单已经超过退款期限 | 订单已经超过可退款的最大期限(支付后一年内可退款) | 请选择其他方式自行退款（明确错误，请勿重试） |
USER_ACCOUNT_ABNORMAL | 退款请求失败 | 用户账号注销 | 此状态代表退款申请失败，商户可自行处理退款。（明确错误，请勿重试） |
ORDERNOTEXIST | 订单号不存在 | 缺少有效的订单号 | 请检查你的订单号是否正确且是否已支付，未支付的订单不能发起退款（明确错误，请勿重试） |
CERT_ERROR | 证书校验错误 | 请检查证书是否正确，证书是否过期或作废。 | 请检查证书是否正确，证书是否过期或作废。（明确错误，请勿重试） |
REFUND_FEE_MISMATCH | 订单金额或退款金额与之前请求不一致，请核实后再试 | 订单金额或退款金额与之前请求不一致，请核实后再试 | 订单金额或退款金额与之前请求不一致，请核实后再试（明确错误，请勿重试） |
INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。（明确错误，请勿重试） |
