查询退款API

更新时间：2024.11.18

应用场景

提交退款申请后，通过调用该接口查询退款状态。退款有一定延时，用零钱支付的退款20分钟内到账，银行卡支付的退款3个工作日后重新查询退款状态。

注意

本接口支持查询单品优惠相关退款信息，且仅支持按微信退款单号或商户退款单号查询，若继续调用老查询退款接口，请看查询退款接口文档
请求频率限制：300qps，即每秒钟正常的退款查询请求次数不超过300次
错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款查询请求不超过6次

接口地址

https://api.mch.weixin.qq.com/pay/refundqueryv2

https://api2.mch.weixin.qq.com/pay/refundqueryv2(备用域名)见跨城冗灾方案

是否需要证书

不需要。

请求参数

字段名	变量名	必填	类型	示例值	描述
字段列表见查询退款API（普通商户）查询退款API（服务商）单品优惠仅支持商户退款单号（out_refund_no）、微信退款单号（refund_id）查单，不支持商户订单号、微信订单号查询

字段名

变量名

必填

类型

示例值

描述

字段列表见

查询退款API（普通商户）

查询退款API（服务商）

单品优惠仅支持商户退款单号（out_refund_no）、微信退款单号（refund_id）查单，不支持商户订单号、微信订单号查询

举例如下：

1<xml>
2<appid>wx2421b1c4370ec43b</appid>
3<mch_id>10000100</mch_id>
4<nonce_str>0b9f35f484df17a732e537c37708d1d0</nonce_str>
5<out_refund_no>123456789</out_refund_no>
6<sub_mch_id>1900000109</sub_mch_id>
7<sign>66FFB727015F450D167EF38CCC549521</sign>
8</xml>

返回数据

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

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

字段名	变量名	必填	类型	示例值	描述
其他字段列表见查询退款API（普通商户）查询退款API（服务商）下单时传了version，返回参数会有差异，详情参考：《注意事项》
营销详情	promotion_detail	否	String(6000)	示例见下文	营销详情列表，使返回值为Json格式

字段名

变量名

必填

类型

示例值

描述

其他字段列表见

查询退款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)

promotion_detail字段值举例如下：

1{
2"promotion_detail":[
3{
4"promotion_id":"109519",
5"scope":"SINGLE",
6"type":"DISCOUNT",
7"refund_amount":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<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
3<mch_id><![CDATA[10000100]]></mch_id>
4<nonce_str><![CDATA[TeqClE3i0mvn3DrK]]></nonce_str>
5<out_refund_no><![CDATA[1415701182]]></out_refund_no>
6<out_trade_no><![CDATA[1415757673]]></out_trade_no>
7<refund_fee>3</refund_fee>
8<refund_id><![CDATA[2008450740201411110000174436]]></refund_id>
9<refund_status><![CDATA[PROCESSING]]></refund_status>
10<promotion_detail><![CDATA[{"promotion_detail":[{"promotion_id":"109519","scope":"SINGLE","type":"DISCOUNT","refund_amount":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>
11<result_code><![CDATA[SUCCESS]]></result_code>
12<return_code><![CDATA[SUCCESS]]></return_code>
13<return_msg><![CDATA[OK]]></return_msg>
14<sign><![CDATA[1F2841558E233C33ABA71A961D27561C]]></sign>
15<refund_recv_accout><![CDATA[1F2841558E233C33ABA71A961D27561C]]></refund_recv_accout>
16<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
17<cash_refund_fee><![CDATA[90]]></cash_refund_fee>
18</xml>

错误码

名称	描述	原因	解决方案
SYSTEMERROR	接口返回错误	系统超时	请用相同参数再次调用API
REFUNDNOTEXIST	退款订单查询失败	订单号错误或订单状态不正确	请检查订单号是否有误以及订单状态是否正确，如：未支付、已支付未退款
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参数格式是否正确

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服