微信交易退款查询接口
- 提交退款申请后,通过调用该接口查询退款状态。
- 退款有一定延时,用零钱支付的退款20分钟内到账,银行卡支付的退款3个工作日后重新查询退款状态。
二、请求地址:
https://kf.fw199.com/gateway/partner/pay/wx/personal/refund/query
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| appid | String | 必填 | 合作伙伴Id | |
| timestamp | String | 必填 | 时间戳 | 请求时的时间,unixtime格式 |
| tppay_trade_no | String | 2选1 | 微信交易号,支付成功回调时返回的tppay_trade_no。 | 微信交易号,和蜂巢交易号不能同时为空 |
| quickpay_trade_no | String | 2选1 | 蜂巢交易号,支付成功回调时返回的quickpay_trade_no。 | 微信交易号,和蜂巢交易号不能同时为空 |
| refund_id | String | 必填 | 微信退款单号,发起退款接口返回的refund_id | 3214312412412 |
| sign | String | 必填 | 签名 | 对各参数使用提供的AppSecret进行签名,签名逻辑具体实现见示例代码 |
请求示例
@Test
public void WxSFTRefundQueryPayTrade() throws Exception {
String wxRefundId = "50300707362026061809160445877";
String tppayTradeNo = "4200003183202606177661617607";
Map<String, String> data = new HashMap<String, String>();
data.put("appid", Config.AppId);
Long timestamp = System.currentTimeMillis() / 1000;
data.put("timestamp", timestamp.toString());
data.put("tppay_trade_no",tppayTradeNo );
data.put("refund_id",wxRefundId );
data.put("sign", Utils.Sign(data, Config.AppSecret));
String result = doHttpRequest(Config.WXPersonalRefundQueryTradeUrl, data);
System.out.println(result);
}
三、接口返回结果:
{
"code": 0,
"message": "ok",
"data": {
"refund_id": "50300707362026061809160445877",
"out_refund_no": "20260618111828209827",
"transaction_id": "4200003183202606177661617607",
"out_trade_no": "20260617173139961160",
"channel": "ORIGINAL",
"user_received_account": "支付用户零钱",
"success_time": "2026-06-18T11:18:32+08:00",
"create_time": "2026-06-18T11:18:29+08:00",
"status": "SUCCESS",
"amount": {
"refund": 10,
"payer_refund": 10,
"currency": "CNY"
},
"refund_account": "REFUND_SOURCE_SUB_MERCHANT",
"funds_account": "AVAILABLE"
},
"trace_id": "da4a1cb1-dd0b-42dc-aa0e-a98721e396d6"
}
四、返回参数说明
返回字段中code为0表示成功,非0失败,失败的话message会有失败原因。成功的话, data会有以下字段。
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| refund_id | string(32) | true | 【微信支付退款订单号】 微信支付退款订单订单号 |
| out_refund_no | string(64) | true | 【商户退款单号】 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。 |
| transaction_id | string(32) | true | 【微信支付交易订单号】 微信支付交易订单号 |
| out_trade_no | string(32) | true | 【商户原交易订单号】 返回的原交易订单号 |
| channel | string(16) | false | 【退款渠道】 ORIGINAL—原路退款 BALANCE—退回到余额 OTHER_BALANCE—原账户异常退到其他余额账户 OTHER_BANKCARD—原银行卡异常退到其他银行卡 |
| user_received_account | string(64) | false | 【退款入账账户】 取当前退款单的退款入账方 1)退回银行卡:{银行名称}{卡类型}{卡尾号} 2)退回支付用户零钱:支付用户零钱 3)退还商户:商户基本账户商户结算银行账户 4)退回支付用户零钱通:支付用户零钱通 5)退回支付用户银行电子账户:支付用户银行电子账户 6)退回支付用户零花钱:支付用户零花钱 7)退回用户经营账户:用户经营账户 8)退回支付用户来华零钱包:支付用户来华零钱包 9)退回企业支付商户:企业支付商户 10)退回支付用户小金罐:支付用户小金罐 11)退回支付用户分付:支付用户分付 12)退回微银通:{银行名称}微银通 |
| success_time | string(64) | false | 【退款成功时间】 退款成功时间,退款状态status为SUCCESS(退款成功)时,返回该字段。遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。 |
| create_time | string(64) | true | 【退款创建时间】 退款受理时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。 |
| status | string(16) | true | 【退款状态】 退款状态: SUCCESS—退款成功 CLOSED—退款关闭。 PROCESSING—退款处理中 ABNORMAL—退款异常,退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。 |
| amount | object | true | 【退款金额】 退款金额信息 |
| amount.refund | integer | true | 【退款金额】 退款金额,单位为分,只能为整数,不能超 过原订单支付金额 |
| amount.from | array[object] | false | 【退款出资账户及金额】 退款出资的账户类型及金额信息 |
| amount.from.account | string(32) | true | 【出资账户类型】 下面枚举值多选一。 枚举值: AVAILABLE : 可用余额 UNAVAILABLE : 不可用余额 |
| amount.from.amount | integer | true | 【出资金额】 对应账户出资金额 |
| amount.payer_refund | integer | true | 【用户退款金额】 退款给用户的金额,不包含所有优惠券金额 |
| amount.discount_refund | integer | false | 【优惠退款金额】 优惠券的退款金额,原支付单的优惠按比例退款 |
| amount.currency | string(16) | false | 【货币类型】 符合ISO4217标准的三位字母代码,目前只支持人民币:CNY |
| amount.advance | integer | false | 【垫付金额】 电商平台垫付的金额 |
| promotion_detail | array[object] | false | 【营销详情】 优惠退款信息 |
| promotion_detail.promotion_id | string(32) | true | 【券ID】 券或者立减优惠id |
| promotion_detail.scope | string(32) | true | 【优惠范围】 GLOBAL- 全场代金券 SINGLE- 单品优惠 |
| promotion_detail.type | string(32) | true | 【优惠类型】 COUPON- 代金券,需要走结算资金的充值型代金券 DISCOUNT- 优惠券,不走结算资金的免充值型优惠券 |
| promotion_detail.amount | integer | true | 【优惠券面额】 用户享受优惠的金额(优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ) |
| promotion_detail.refund_amount | integer | true | 【优惠退款金额】 代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠 |
| refund_account | string(32) | false | 【退款出资商户】 REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付 REFUND_SOURCE_SUB_MERCHANT : 二级商户,默认值 注意:申请退款时可能会出现暂未扣除退款资金的情况,此时不返回本字段,需继续查单确认。 |
| funds_account | string(32) | false | 【资金账户】 UNSETTLED : 未结算资金 AVAILABLE : 可用余额 UNAVAILABLE : 不可用余额 OPERATION : 运营户 BASIC : 基本账户(含可用余额和不可用余额) ECNY_BASIC : 数字人民币基本账户 |
文档更新时间: 2026-06-18 14:34 作者:admin