微信交易退款查询接口

    1. 提交退款申请后,通过调用该接口查询退款状态。
    2. 退款有一定延时,用零钱支付的退款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