---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012587973.md"
title: "查询退款"
doc_id: 4012587973
---

>更新时间：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 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/merchant/4012075113.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考[签名认证](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D)生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| out_refund_no | string(64) | true | 【商户退款单号】商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母\_-&#124;@ ，同一退款单号多次请求只退一笔。 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| refund_id | string(32) | true | 【微信支付退款号】微信侧返回的退款单唯一标识，由数字组成，50或52开头。 |
| out_refund_no | string(64) | true | 【商户退款单号】商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母\_-&#124;@ ，同一退款单号多次请求只退一笔。 |
| transaction_id | string(32) | true | 【微信支付订单号】微信支付分扣款单的唯一标识，非0元结单且支付分渠道扣款成功后[支付成功回调](https://pay.weixin.qq.com/doc/v3/merchant/4012587960.md)和[查询支付分订单](https://pay.weixin.qq.com/doc/v3/merchant/4012587902.md)返回的收款信息明细collection.details中包含该字段。 |
| out_trade_no | string(32) | true | 【商户订单号】支付分轮询扣款时生成的商户订单号。 |
| channel | string | true | 【退款渠道】本单资金实际的退款渠道<br>可选取值：<br><ul><li>ORIGINAL: 原路退款</li><li>BALANCE: 退回到余额</li><li>OTHER\_BALANCE: 原账户异常退到其他余额账户</li><li>OTHER\_BANKCARD: 原银行卡异常退到其他银行卡</li></ul> |
| user_received_account | string(64) | true | 【退款入账账户】退款单入账方。<br>取值有以下几种情况:<br>退回银行卡：{银行名称}{卡类型}<br>退回支付用户零钱：支付用户零钱<br>退还商户：商户基本账户商户结算银行账户<br>退回支付用户零钱通：支付用户零钱通<br>退回支付用户银行电子账户：支付用户银行电子账户<br>退回支付用户零花钱：支付用户零花钱<br>退回用户经营账户：用户经营账户<br>退回支付用户来华零钱包：支付用户来华零钱包<br>退回企业支付商户：企业支付商户<br>退回支付用户小金罐：支付用户小金罐<br>退回支付用户分付：支付用户分付<br>退回微银通：{银行名称}微银通 |
| success_time | string(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_time | string(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秒。 |
| status | string | true | 【退款状态】退款单状态。<br>可选取值：<br><ul><li>SUCCESS: 退款成功</li><li>CLOSED: 退款关闭</li><li>PROCESSING: 退款处理中</li><li>ABNORMAL: 退款异常，需商户平台手动处理，参考[交易退款方法介绍](https://kf.qq.com/faq/140225MveaUz150107mAVz6F.html)</li></ul> |
| funds_account | string | false | 【资金账户】退款所使用资金对应的资金账户类型<br>可选取值：<br><ul><li>UNSETTLED: 未结算资金</li><li>AVAILABLE: 可用余额</li><li>UNAVAILABLE: 不可用余额</li><li>OPERATION: 运营户</li><li>BASIC: 基本账户（含可用余额和不可用余额）</li><li>ECNY\_BASIC: 数字人民币基本账户</li></ul> |
| amount | object | true | 【金额信息】金额详细信息 |
| amount.total | integer | true | 【订单金额】原支付交易的订单总金额，单位为分，只能为整数。 |
| amount.refund | integer | true | 【退款金额】申请退款时传的退款金额，整型，单位为分。 |
| amount.from | array[object] | false | 【退款出资账户及金额】申请退款时传的出资账户类型及出资金额。 |
| amount.account | string | true | 【出资账户类型】出资账户类型<br>可选取值：<br><ul><li>AVAILABLE: 可用余额</li><li>UNAVAILABLE: 不可用余额</li></ul> |
| amount.amount | integer | true | 【出资金额】对应账户出资金额，单位为分 |
| amount.payer_total | integer | true | 【用户支付金额】用户现金支付金额，整型，单位为分，例如10元订单用户使用了2元代金券，则该金额为用户实际支付的8元。 |
| amount.payer_refund | integer | true | 【用户退款金额】指用户实际收到的现金退款金额，数据类型为整型，单位为分。例如在一个10元的订单中，用户使用了2元的代金券，若商户申请退款5元，则用户将收到4元的现金退款(即该字段所示金额)和1元的代金券退款。<br>注：部分退款用户无法继续使用代金券，只有在订单全额退款且代金券未过期的情况下，用户才能继续使用代金券。<br>详情参考 [含优惠退款说明](https://docs.qq.com/doc/DT2NWT3h1ZUpKbXph) |
| amount.settlement_refund | integer | true | 【应结退款金额】去掉免充值代金券退款金额后的退款金额，整型，单位为分，例如10元订单用户使用了2元代金券(一张免充值1元 + 一张预充值1元)，商户申请退款5元，则该金额为 退款金额5元 - 0.5元免充值代金券退款金额 = 4.5元。 |
| amount.settlement_total | integer | true | 【应结订单金额】去除免充值代金券金额后的订单金额，整型，单位为分，例如10元订单用户使用了2元代金券(一张免充值1元 + 一张预充值1元)，则该金额为 订单金额10元 - 免充值代金券金额1元 = 9元。 |
| amount.discount_refund | integer | true | 【优惠退款金额】申请退款后用户收到的代金券退款金额，整型，单位为分，例如10元订单用户使用了2元代金券，商户申请退款5元，用户收到的是4元现金 + 1元代金券退款金额(该字段) |
| amount.currency | string(16) | true | 【退款币种】固定值CNY，代表人民币。 |
| amount.refund_fee | integer | false | 【手续费退款金额】订单退款时退还的手续费金额，整型，单位为分，例如一笔100元的订单收了0.6元手续费，商户申请退款50元，该金额为等比退还的0.3元手续费 |
| promotion_detail | array[object] | false | 【优惠退款信息】代金券信息，当订单支付时，有使用代金券时，该字段将返回所使用的代金券信息。 |
| promotion_detail.promotion_id | string(32) | true | 【券ID】券或者立减优惠id |
| promotion_detail.scope | string | true | 【优惠范围】优惠活动中代金券的适用范围，分为两种类型：<br><ul><li>GLOBAL: 全场代金券-以订单整体可优惠的金额为优惠门槛的代金券；</li><li>SINGLE: 单品优惠-以订单中具体某个单品的总金额为优惠门槛的代金券；</li></ul> |
| promotion_detail.type | string | true | 【优惠类型】代金券资金类型，优惠活动中代金券的结算资金类型，分为两种类型：<br><ul><li>CASH: 预充值-带有结算资金的代金券，会随订单结算给订单收款商户；</li><li>NOCASH: 免充值-不带有结算资金的代金券，无资金结算给订单收款商户；</li></ul> |
| promotion_detail.amount | integer | true | 【优惠券面额】代金券优惠的金额 |
| promotion_detail.refund_amount | integer | true | 【优惠退款金额】优惠退款金额<=退款金额，退款金额-代金券或立减优惠退款金额为用户支付的现金，说明详见代金券或立减优惠，单位为分 |
| promotion_detail.goods_detail | array[object] | false | 【商品列表】优惠商品发生退款时返回商品信息 |
| promotion_detail.wechatpay_goods_id | string(32) | false | 【微信侧商品编码】微信支付定义的统一商品编号（没有可不传） |
| promotion_detail.goods_name | string(256) | false | 【商品名称】商品的实际名称 |
| promotion_detail.unit_price | integer | true | 【商品单价】商品单价金额，单位为分 |
| promotion_detail.refund_amount | integer | true | 【商品退款金额】商品退款金额，单位为分 |
| promotion_detail.refund_quantity | integer | true | 【商品退货数量】对应商品的退货数量 |
## 错误码

### 公共错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/merchant/4012072670.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 401 | SIGN\_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求 |
| 404 | MCH\_NOT\_EXISTS | MCHID不存在 | 请检查MCHID是否正确 |
| 404 | RESOURCE\_NOT\_EXISTS | 退款单查询失败 | 请检查退款单号是否有误以及订单状态是否正确，如：未支付、已支付未退款 |
| 500 | SYSTEM\_ERROR | 系统超时 | 请不要更换商户退款单号，请使用相同参数再次调用API。 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012587973-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012587973-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012587973-go.md)


应答示例

200 OK

```
{
  "refund_id" : "50000000382019052709732678859",
  "out_refund_no" : "1217752501201407033233368018",
  "transaction_id" : "1217752501201407033233368018",
  "out_trade_no" : "1217752501201407033233368018",
  "channel" : "ORIGINAL",
  "user_received_account" : "招商银行信用卡",
  "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",
    "refund_fee" : 100
  },
  "promotion_detail" : [
    {
      "promotion_id" : "109519",
      "scope" : "GLOBAL",
      "type" : "COUPON",
      "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
        }
      ]
    }
  ]
}
```
