跳转到内容
Cheeli 文档
返回官网

微信交易退款查询

  1. 提交退款申请后，通过调用该接口查询退款状态。

  2. 退款有一定延时，用零钱支付的退款20分钟内到账，银行卡支付的退款3个工作日后重新查询退款状态。

一、请求地址

https://kf.fw199.com/gateway/partner/pay/wx/personal/refund/query

二、请求参数

参数名类型必填说明示例
appidString必填合作伙伴Id
timestampString必填时间戳请求时的时间，unixtime格式
tppay_trade_noString2选1微信交易号，支付成功回调时返回的tppay_trade_no。微信交易号，和蜂巢交易号不能同时为空
quickpay_trade_noString2选1蜂巢交易号，支付成功回调时返回的quickpay_trade_no。微信交易号，和蜂巢交易号不能同时为空
refund_idString必填微信退款单号，发起退款接口返回的refund_id3214312412412
signString必填签名对各参数使用提供的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_idstring(32)true**【微信支付退款订单号】** 微信支付退款订单订单号
out_refund_nostring(64)true**【商户退款单号】** 商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。
transaction_idstring(32)true**【微信支付交易订单号】** 微信支付交易订单号
out_trade_nostring(32)true**【商户原交易订单号】** 返回的原交易订单号
channelstring(16)false**【退款渠道】** ORIGINAL—原路退款
BALANCE—退回到余额
OTHER_BALANCE—原账户异常退到其他余额账户
OTHER_BANKCARD—原银行卡异常退到其他银行卡
user_received_accountstring(64)false**【退款入账账户】** 取当前退款单的退款入账方
1）退回银行卡：{银行名称}{卡类型}{卡尾号}
2）退回支付用户零钱:支付用户零钱
3）退还商户:商户基本账户商户结算银行账户
4）退回支付用户零钱通:支付用户零钱通
5）退回支付用户银行电子账户:支付用户银行电子账户
6）退回支付用户零花钱:支付用户零花钱
7）退回用户经营账户:用户经营账户
8）退回支付用户来华零钱包:支付用户来华零钱包
9）退回企业支付商户:企业支付商户
10）退回支付用户小金罐:支付用户小金罐
11）退回支付用户分付:支付用户分付
12）退回微银通:{银行名称}微银通
success_timestring(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_timestring(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秒。
statusstring(16)true**【退款状态】** 退款状态：
SUCCESS—退款成功
CLOSED—退款关闭。
PROCESSING—退款处理中
ABNORMAL—退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往商户平台（pay.weixin.qq.com）-交易中心，手动处理此笔退款。
amountobjecttrue**【退款金额】** 退款金额信息
amount.refundintegertrue**【退款金额】** 退款金额，单位为分，只能为整数，不能超 过原订单支付金额
amount.fromarray[object]false**【退款出资账户及金额】** 退款出资的账户类型及金额信息
amount.from.accountstring(32)true**【出资账户类型】** 下面枚举值多选一。
枚举值：
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
amount.from.amountintegertrue**【出资金额】** 对应账户出资金额
amount.payer_refundintegertrue**【用户退款金额】** 退款给用户的金额，不包含所有优惠券金额
amount.discount_refundintegerfalse**【优惠退款金额】** 优惠券的退款金额，原支付单的优惠按比例退款
amount.currencystring(16)false**【货币类型】** 符合ISO4217标准的三位字母代码，目前只支持人民币：CNY
amount.advanceintegerfalse**【垫付金额】** 电商平台垫付的金额
promotion_detailarray[object]false**【营销详情】** 优惠退款信息
promotion_detail.promotion_idstring(32)true**【券ID】** 券或者立减优惠id
promotion_detail.scopestring(32)true**【优惠范围】** GLOBAL- 全场代金券
SINGLE- 单品优惠
promotion_detail.typestring(32)true**【优惠类型】** COUPON- 代金券，需要走结算资金的充值型代金券
DISCOUNT- 优惠券，不走结算资金的免充值型优惠券
promotion_detail.amountintegertrue**【优惠券面额】** 用户享受优惠的金额（优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ）
promotion_detail.refund_amountintegertrue**【优惠退款金额】** 代金券退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为现金，说明详见代金券或立减优惠
refund_accountstring(32)false**【退款出资商户】** REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付
REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值
注意：申请退款时可能会出现暂未扣除退款资金的情况，此时不返回本字段，需继续查单确认。
funds_accountstring(32)false**【资金账户】** UNSETTLED : 未结算资金
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
OPERATION : 运营户
BASIC : 基本账户（含可用余额和不可用余额）
ECNY_BASIC : 数字人民币基本账户