基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(公共API)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
商家转账到零钱
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传
微信支付平台证书

查询单笔退款API

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


提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,建议在提交退款申请后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

请求示例


https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/1217752501201407033233368018

{
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
资金账户 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
手续费退款金额 refund_fee int 手续费退款金额,单位为分。
示例值:10
+优惠退款信息 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 签名错误 请检查签名参数和方法是否都符合签名算法要求




技术咨询

文档反馈