查询退款

更新时间:2024.12.05

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

接口说明

支持商户:【普通商户】

请求方式:【GET】/v3/refund/domestic/refunds/{out_refund_no}

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header HTTP头参数

Authorization  必填 string

请参考签名认证生成认证信息


Accept  必填 string

请设置为application/json


path 路径参数

out_refund_no  必填 string(64)

【商户退款单号】商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|@ ,同一退款单号多次请求只退一笔。

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/1217752501201407033233368018 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json"
5

应答参数

200 OK

refund_id  必填 string(32)

【微信支付退款号】微信侧返回的退款单唯一标识,由数字组成,50或52开头。


out_refund_no  必填 string(64)

【商户退款单号】商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|@ ,同一退款单号多次请求只退一笔。


transaction_id  必填 string(32)

【微信支付订单号】微信支付分扣款单的唯一标识,非0元结单且支付分渠道扣款成功后支付成功回调查询支付分订单返回的收款信息明细collection.details中包含该字段。


out_trade_no  必填 string(32)

【商户订单号】支付分轮询扣款时生成的商户订单号。


channel  必填 string

【退款渠道】本单资金实际的退款渠道
可选取值:

  • ORIGINAL: 原路退款

  • BALANCE: 退回到余额

  • OTHER_BALANCE: 原账户异常退到其他余额账户

  • OTHER_BANKCARD: 原银行卡异常退到其他银行卡


user_received_account  必填 string(64)

【退款入账账户】退款单入账方。
取值有以下几种情况:
退回银行卡:{银行名称}{卡类型}{卡尾号}
退回支付用户零钱:支付用户零钱
退还商户:商户基本账户商户结算银行账户
退回支付用户零钱通:支付用户零钱通
退回支付用户银行电子账户:支付用户银行电子账户
退回支付用户零花钱:支付用户零花钱
退回用户经营账户:用户经营账户
退回支付用户来华零钱包:支付用户来华零钱包
退回企业支付商户:企业支付商户


success_time  选填 string(64)

【退款成功时间】退款成功时间,退款状态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)

【退款创建时间】退款受理时间,遵循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

【退款状态】退款单状态。
可选取值:

  • SUCCESS: 退款成功

  • CLOSED: 退款关闭

  • PROCESSING: 退款处理中

  • ABNORMAL: 退款异常,需商户平台手动处理,参考交易退款方法介绍


funds_account  选填 string

【资金账户】退款所使用资金对应的资金账户类型
可选取值:

  • UNSETTLED: 未结算资金

  • AVAILABLE: 可用余额

  • UNAVAILABLE: 不可用余额

  • OPERATION: 运营户

  • BASIC: 基本账户(含可用余额和不可用余额)

  • ECNY_BASIC: 数字人民币基本账户


amount  必填 object

【金额信息】金额详细信息

属性

promotion_detail  选填 array[object]

【优惠退款信息】代金券信息,当订单支付时,有使用代金券时,该字段将返回所使用的代金券信息。

属性

应答示例

200 OK

1{
2  "refund_id" : "50000000382019052709732678859",
3  "out_refund_no" : "1217752501201407033233368018",
4  "transaction_id" : "1217752501201407033233368018",
5  "out_trade_no" : "1217752501201407033233368018",
6  "channel" : "ORIGINAL",
7  "user_received_account" : "招商银行信用卡0403",
8  "success_time" : "2020-12-01T16:18:12+08:00",
9  "create_time" : "2020-12-01T16:18:12+08:00",
10  "status" : "SUCCESS",
11  "funds_account" : "UNSETTLED",
12  "amount" : {
13    "total" : 100,
14    "refund" : 100,
15    "from" : [
16      {
17        "account" : "AVAILABLE",
18        "amount" : 444
19      }
20    ],
21    "payer_total" : 90,
22    "payer_refund" : 90,
23    "settlement_refund" : 100,
24    "settlement_total" : 100,
25    "discount_refund" : 10,
26    "currency" : "CNY",
27    "refund_fee" : 100
28  },
29  "promotion_detail" : [
30    {
31      "promotion_id" : "109519",
32      "scope" : "GLOBAL",
33      "type" : "COUPON",
34      "amount" : 5,
35      "refund_amount" : 100,
36      "goods_detail" : [
37        {
38          "merchant_goods_id" : "1217752501201407033233368018",
39          "wechatpay_goods_id" : "1001",
40          "goods_name" : "iPhone6s 16G",
41          "unit_price" : 528800,
42          "refund_amount" : 528800,
43          "refund_quantity" : 1
44        }
45      ]
46    }
47  ]
48}

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

401

SIGN_ERROR

签名错误

请检查签名参数和方法是否都符合签名算法要求

404

MCH_NOT_EXISTS

MCHID不存在

请检查MCHID是否正确

404

RESOURCE_NOT_EXISTS

退款单查询失败

请检查退款单号是否有误以及订单状态是否正确,如:未支付、已支付未退款

500

SYSTEM_ERROR

系统超时

请不要更换商户退款单号,请使用相同参数再次调用API。

 

 

反馈
咨询
目录
置顶