查询单笔退款API

最新更新时间:2021.05.28 版本说明


提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,建议在提交退款申请后1分钟发起查询退款状态,一般来说零钱支付的退款5分钟内到账,银行卡支付的退款1-3个工作日到账。

接口说明

适用对象:服务商

请求URL:https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/{out_refund_no}

请求方式:GET


path 指该参数为路径参数

query 指该参数为URL参数

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
商户退款单号 out_refund_no string[1, 64] path商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
示例值:1217752501201407033233368018
子商户号 sub_mchid string[1, 32] query子商户的商户号,由微信支付生成并下发。
示例值:1900000109

请求示例


https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/1217752501201407033233368018?sub_mchid=1900000109

{
JAVA示例代码
}

返回参数

参数名 变量 类型[长度限制] 必填 描述
微信支付退款单号 refund_id string[1, 32] 微信支付退款单号
示例值:50000000382019052709732678859
商户退款单号 out_refund_no string[1, 64] 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
示例值:1217752501201407033233368018
微信支付订单号 transaction_id string[1, 32] 微信支付交易订单号
示例值:1217752501201407033233368018
商户订单号 out_trade_no string[1, 32] 原支付交易对应的商户订单号
示例值:1217752501201407033233368018
退款渠道 channel string[1, 16] 枚举值:
ORIGINAL:原路退款
BALANCE:退回到余额
OTHER_BALANCE:原账户异常退到其他余额账户
OTHER_BANKCARD:原银行卡异常退到其他银行卡
示例值:ORIGINAL
退款入账账户 user_received_account string[1, 64] 取当前退款单的退款入账方,有以下几种情况:
1)退回银行卡:{银行名称}{卡类型}{卡尾号}
2)退回支付用户零钱:支付用户零钱
3)退还商户:商户基本账户商户结算银行账户
4)退回支付用户零钱通:支付用户零钱通
示例值:招商银行信用卡0403
退款成功时间 success_time string[1, 64] 退款成功时间,当退款状态为退款成功时有返回。
示例值:2020-12-01T16:18:12+08:00
退款创建时间 create_time string[1, 64] 退款受理时间
示例值:2020-12-01T16:18:12+08:00
退款状态 status string[1, 32] 退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往服务商平台-交易中心,手动处理此笔退款。
枚举值:
SUCCESS:退款成功
CLOSED:退款关闭
PROCESSING:退款处理中
ABNORMAL:退款异常
示例值:SUCCESS
示例值:SUCCESS
资金账户 funds_account string[1, 32] 退款所使用资金对应的资金账户类型
枚举值:
UNSETTLED : 未结算资金
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
OPERATION : 运营户
BASIC : 基本账户(含可用余额和不可用余额)
示例值:UNSETTLED
+金额信息 amount object 金额详细信息
参数名 变量 类型[长度限制] 必填 描述
订单金额 total int 订单总金额,单位为分
示例值:100
退款金额 refund int 退款标价金额,单位为分,可以做部分退款
示例值:100
+退款出资账户及金额 from array 退款出资的账户类型及金额信息
参数名 变量 类型[长度限制] 必填 描述
出资账户类型 account string[1, 32] 下面枚举值多选一。
枚举值:
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
示例值:AVAILABLE
出资金额 amount int 对应账户出资金额
示例值:444
用户支付金额 payer_total int 现金支付金额,单位为分,只能为整数
示例值:90
用户退款金额 payer_refund int 退款给用户的金额,不包含所有优惠券金额
示例值:90
应结退款金额 settlement_refund int 去掉非充值代金券退款金额后的退款金额,单位为分,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
示例值:100
应结订单金额 settlement_total int 应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额,单位为分
示例值:100
优惠退款金额 discount_refund int 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠,单位为分
示例值:10
退款币种 currency string[1, 16] 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。
示例值:CNY
+优惠退款信息 promotion_detail array 优惠退款信息
参数名 变量 类型[长度限制] 必填 描述
券ID promotion_id string[1, 32] 券或者立减优惠id
示例值:109519
优惠范围 scope string[1, 32] 枚举值:
GLOBAL-全场代金券
SINGLE-单品优惠
示例值:SINGLE
优惠类型 type string[1, 32] 枚举值:
COUPON-代金券,需要走结算资金的充值型代金券
DISCOUNT-优惠券,不走结算资金的免充值型优惠券
示例值:DISCOUNT
优惠券面额 amount int 用户享受优惠的金额(优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ),单位为分
示例值:5
优惠退款金额 refund_amount int 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为用户支付的现金,说明详见代金券或立减优惠,单位为分
示例值:100
+商品列表 goods_detail array 优惠商品发生退款时返回商品信息
参数名 变量 类型[长度限制] 必填 描述
商户侧商品编码 merchant_goods_id string[1, 32] 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
示例值:1217752501201407033233368018
微信侧商品编码 wechatpay_goods_id string[1, 32] 微信支付定义的统一商品编号(没有可不传)
示例值:1001
商品名称 goods_name string[1, 256] 商品的实际名称
示例值:iPhone6s 16G
商品单价 unit_price int 商品单价金额,单位为分
示例值:528800
商品退款金额 refund_amount int 商品退款金额,单位为分
示例值:528800
商品退货数量 refund_quantity int 单品的退款数量
示例值:1

返回示例


{
  "refund_id": "50000000382019052709732678859",
  "out_refund_no": "1217752501201407033233368018",
  "transaction_id": "1217752501201407033233368018",
  "out_trade_no": "1217752501201407033233368018",
  "channel": "ORIGINAL",
  "user_received_account": "招商银行信用卡0403",
  "success_time": "2020-12-01T16:18:12+08:00",
  "create_time": "2020-12-01T16:18:12+08:00",
  "status": "SUCCESS",
  "funds_account": "UNSETTLED",
  "amount": {
    "total": 100,
    "refund": 100,
    "from": [
      {
        "account": "AVAILABLE",
        "amount": 444
      }
    ],
    "payer_total": 90,
    "payer_refund": 90,
    "settlement_refund": 100,
    "settlement_total": 100,
    "discount_refund": 10,
    "currency": "CNY"
  },
  "promotion_detail": [
    {
      "promotion_id": "109519",
      "scope": "SINGLE",
      "type": "DISCOUNT",
      "amount": 5,
      "refund_amount": 100,
      "goods_detail": {
        "merchant_goods_id": "1217752501201407033233368018",
        "wechatpay_goods_id": "1001",
        "goods_name": "iPhone6s 16G",
        "unit_price": 528800,
        "refund_amount": 528800,
        "refund_quantity": 1
      }
    }
  ]
}
                    

http://2323weixin.qq.com
                    

错误码公共错误码

状态码 错误码 描述 解决方案
500 SYSTEM_ERROR 系统超时 请不要更换商户退款单号,请使用相同参数再次调用API。
400 PARAM_ERROR 参数错误 请求参数错误,请检查参数再调用退款查询
404 MCH_NOT_EXISTS MCHID不存在 请检查MCHID是否正确
404 RESOURCE_NOT_EXISTS 退款单查询失败 请检查退款单号是否有误以及订单状态是否正确,如:未支付、已支付未退款
401 SIGN_ERROR 签名错误 请检查签名参数和方法是否都符合签名算法要求




技术咨询

文档反馈