查询单笔退款(通过商户退款单号)

更新时间:2024.09.18

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

【微信支付退款号】微信支付退款号


out_refund_no  必填 string(64)

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


transaction_id  必填 string(32)

【微信支付订单号】微信支付交易订单号


out_trade_no  必填 string(32)

【商户订单号】原支付交易对应的商户订单号


channel  必填 string

【退款渠道】退款渠道

可选取值:

  • ORIGINAL: 原路退款

  • BALANCE: 退回到余额

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

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


user_received_account  必填 string(64)

【退款入账账户】取当前退款单的退款入账方,有以下几种情况:
1)退回银行卡:{银行名称}{卡类型}{卡尾号}
2)退回支付用户零钱:支付用户零钱
3)退还商户:商户基本账户商户结算银行账户
4)退回支付用户零钱通:支付用户零钱通
5)退回支付用户银行电子账户:支付用户银行电子账户
6)退回支付用户零花钱:支付用户零花钱
7)退回用户经营账户:用户经营账户
8)退回支付用户来华零钱包:支付用户来华零钱包
9)退回企业支付商户:企业支付商户


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

【退款状态】退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。

可选取值:

  • 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}
49

 

错误码

公共错误码

状态码

错误码

描述

解决方案

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。

 

 

反馈
咨询
目录
置顶