---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012791883.md"
title: "退款申请"
doc_id: 4012791883
---

>更新时间：2025.01.09

在交易完成后的一年内（以支付成功时间为起点+365天计算），若因用户或商户方面导致需进行订单退款，商户可通过此接口将支付金额的全部或部分原路退还至用户。详细介绍参考：[订单退款-产品介绍](https://pay.weixin.qq.com/doc/v3/merchant/4013071001.md)。

注意：

1、一笔订单最多支持50次部分退款（若需多次部分退款，请更换商户退款单号并间隔1分钟后再次调用）。

2、在申请退款失败后进行重试时，请务必使用原商户退款单号，以避免因重复退款而导致的资金损失。

3、同一商户号下，此接口调用成功的频率限制为150QPS，而调用失败报错时的频率限制为6QPS。

4、申请退款接口返回成功仅表示退款单已受理成功，具体的退款结果需依据[退款结果通知](https://pay.weixin.qq.com/doc/v3/merchant/4013071196.md)及[查询退款](https://pay.weixin.qq.com/doc/v3/merchant/4013071041.md)的返回信息为准。

5、若一个月前的订单申请退款时返回报错“频率限制，1个月之前的订单请降低申请频率再重试”，请调整退款时间，再使用原参数进行重试。




## 接口说明

支持商户：【普通商户】

请求方式：【POST】 `/v3/refund/domestic/refunds`

请求域名：【主域名】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#1.1-%E8%AF%B7%E6%B1%82%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E6%8E%A5%E5%8F%A3) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `application/json` |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| transaction_id | string(32) | false | 【微信支付订单号】微信支付侧订单的唯一标识，订单支付成功后，[查询订单](https://pay.weixin.qq.com/doc/v3/merchant/4013070356.md)和[支付成功回调通知](https://pay.weixin.qq.com/doc/v3/merchant/4013070368.md)会返回该参数。<br>transaction\_id和out\_trade\_no必须二选一进行传参。 |
| out_trade_no | string(32) | false | 【商户订单号】商户下单时传入的商户系统内部订单号。<br>transaction\_id和out\_trade\_no必须二选一进行传参。 |
| out_refund_no | string(64) | true | 【商户退款单号】 商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母\_-&#124;\*@ ，同一商户退款单号多次请求只退一笔。不可超过64个字节数。 |
| reason | string(80) | false | 【退款原因】 若商户传了退款原因，该原因将在下发给用户的退款消息中显示，具体展示可参见 [退款通知UI示意图](https://pay.weixin.qq.com/doc/v3/merchant/4013071001.md)。<br>请注意：1、该退款原因参数的长度不得超过80个字节；2、当订单退款金额小于等于1元且为部分退款时，退款原因将不会在消息中体现。 |
| notify_url | string(256) | false | 【退款结果回调url】 异步接收微信支付退款结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数。 如果传了该参数，则商户平台上配置的回调地址（ [商户平台](https://pay.weixin.qq.com/)-交易中心-退款管理-退款配置）将不会生效，优先回调当前传的这个地址。 |
| funds_account | string | false | 【退款资金来源】 若传递此参数则使用对应的资金账户退款。<br>可选取值：<br><ul><li>`AVAILABLE`: 仅对旧资金流商户适用(请参考 [旧资金流介绍](https://kf.qq.com/faq/161223N7fi2E161223EvY3Ir.html) 区分)，传此枚举指定从可用余额账户出资，否则默认使用未结算资金退款。</li><li>`UNSETTLED`: 仅对出行预付押金退款适用，指定从未结算资金出资。</li></ul> |
| amount | object | true | 【金额信息】订单退款金额信息 |
| amount.refund | integer | true | 【退款金额】 退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额。 |
| amount.from | array[object] | false | 【退款出资账户及金额】退款需从指定账户出资时，可传递该参数以指定出资金额（币种最小单位，仅限整数）。<br>多账户出资退款需满足：1、未开通退款支出分离功能；2、订单为待分账或分账中的分账订单。<br>传递参数需确保：1、基本账户可用与不可用余额之和等于退款金额；2、账户类型不重复。不符条件将返回错误。 |
| amount.from.account | string | true | 【出资账户类型】 退款出资的账户类型。<br>可选取值：<br>AVAILABLE : 可用余额<br>UNAVAILABLE : 不可用余额 |
| amount.from.amount | integer | true | 【出资金额】对应账户出资金额 |
| amount.total | integer | true | 【原订单金额】 原支付交易的订单总金额，币种的最小单位，只能为整数 |
| amount.currency | string(16) | true | 【退款币种】  符合ISO 4217标准的三位字母代码，固定传：CNY，代表人民币。 |
| goods_detail | array[GoodsDetail] | false | 【退款商品】 请填写需要指定退款的商品信息，所指定的商品信息需要与下单时传入的单品列表 `goods_detail` 中的对应商品信息一致，如无需按照指定商品退款，本字段不填。 |
| goods_detail.merchant_goods_id | string(32) | true | 【商户侧商品编码】 订单下单时传入的商户侧商品编码。 |
| goods_detail.wechatpay_goods_id | string(32) | false | 【微信侧商品编码】 订单下单时传入的微信侧商品编码（没有可不传） |
| goods_detail.goods_name | string(256) | false | 【商品名称】 订单下单时传入的商品名称。 |
| goods_detail.unit_price | integer | true | 【商品单价】 订单下单时传入的商品单价。 |
| goods_detail.refund_amount | integer | true | 【商品退款金额】 商品退款金额，单位为分 |
| goods_detail.refund_quantity | integer | true | 【商品退货数量】 对应商品的退货数量 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| refund_id | string(32) | true | 【微信支付退款单号】申请退款受理成功时，该笔退款单在微信支付侧生成的唯一标识。 |
| out_refund_no | string(64) | true | 【商户退款单号】 商户申请退款时传的商户系统内部退款单号。 |
| transaction_id | string(32) | true | 【微信支付订单号】微信支付侧订单的唯一标识。 |
| 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>1）退回银行卡：{银行名称}{卡类型}<br>2）退回支付用户零钱:支付用户零钱<br>3）退还商户:商户基本账户商户结算银行账户<br>4）退回支付用户零钱通:支付用户零钱通<br>5）退回支付用户银行电子账户:支付用户银行电子账户<br>6）退回支付用户零花钱:支付用户零花钱<br>7）退回用户经营账户:用户经营账户<br>8）退回支付用户来华零钱包:支付用户来华零钱包<br>9）退回企业支付商户:企业支付商户<br>10）退回支付用户小金罐:支付用户小金罐<br>11）退回支付用户分付:支付用户分付<br>12）退回微银通:{银行名称}微银通 |
| success_time | string(64) | false | 【退款成功时间】<br>1、定义：退款成功的时间，该字段在退款状态status为SUCCESS（退款成功）时返回。<br>2、格式：遵循[rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)标准格式： `yyyy-MM-DDTHH:mm:ss+TIMEZONE`。 `yyyy-MM-DD` 表示年月日； `T` 字符用于分隔日期和时间部分； `HH:mm:ss` 表示具体的时分秒； `TIMEZONE` 表示时区（例如， `+08:00` 对应东八区时间，即北京时间）。<br>示例： `2015-05-20T13:29:35+08:00` 表示北京时间2015年5月20日13点29分35秒。 |
| create_time | string(64) | true | 【退款创建时间】<br>1、定义：提交退款申请成功，微信受理退款申请单的时间。<br>2、格式：遵循[rfc3339](https://datatracker.ietf.org/doc/html/rfc3339)标准格式： `yyyy-MM-DDTHH:mm:ss+TIMEZONE`。 `yyyy-MM-DD` 表示年月日； `T` 字符用于分隔日期和时间部分； `HH:mm:ss` 表示具体的时分秒； `TIMEZONE` 表示时区（例如， `+08:00` 对应东八区时间，即北京时间）。<br>示例： `2015-05-20T13:29:35+08:00` 表示北京时间2015年5月20日13点29分35秒。 |
| status | string | true | 【退款状态】退款单的退款处理状态。<br><ul><li>`SUCCESS`: 退款成功</li><li>`CLOSED`: 退款关闭</li><li>`PROCESSING`: 退款处理中</li><li>`ABNORMAL`: 退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往[商户平台](https://pay.weixin.qq.com/)-交易中心，手动处理此笔退款，可参考： [退款异常的处理](https://kf.qq.com/faq/140225MveaUz150107mAVz6F.html)，或者通过 [发起异常退款](https://pay.weixin.qq.com/doc/v3/merchant/4013071193.md) 接口进行处理。<br>注：状态流转说明请参考 [状态流转图](https://pay.weixin.qq.com/doc/v3/merchant/4013071031.md#3%E3%80%81%E9%80%80%E6%AC%BE%E5%8D%95%E7%8A%B6%E6%80%81%E6%B5%81%E8%BD%AC%E5%9B%BE)</li></ul> |
| funds_account | string | true | 【资金账户】 退款所使用资金对应的资金账户类型<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.from.account | string | true | 【出资账户类型】下面枚举值多选一。<br>枚举值：<br>AVAILABLE : 可用余额<br>UNAVAILABLE : 不可用余额 |
| amount.from.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>GLOBAL：全场代金券-以订单整体可优惠的金额为优惠门槛的代金券；<br>SINGLE：单品优惠-以订单中具体某个单品的总金额为优惠门槛的代金券 |
| promotion_detail.type | string | true | 【优惠类型】代金券资金类型，优惠活动中代金券的结算资金类型，分为两种类型：<br>CASH：预充值-带有结算资金的代金券，会随订单结算给订单收款商户；<br>NOCASH：免充值-不带有结算资金的代金券，无资金结算给订单收款商户。 |
| promotion_detail.amount | integer | true | 【代金券面额】 代金券优惠的金额 |
| promotion_detail.refund_amount | integer | true | 【优惠退款金额】 代金券退款的金额 |
| promotion_detail.goods_detail | array[object] | false | 【退款商品】 指定商品退款时传的退款商品信息。 |
| promotion_detail.goods_detail.merchant_goods_id | string(32) | true | 【商户侧商品编码】 申请退款的商户侧商品编码。 |
| promotion_detail.goods_detail.wechatpay_goods_id | string(32) | false | 【微信侧商品编码】 申请退款的微信侧商品编码。（申请退款时没传则不返回） |
| promotion_detail.goods_detail.goods_name | string(256) | false | 【商品名称】 申请退款的商品名称。（申请退款时没传则不返回） |
| promotion_detail.goods_detail.unit_price | integer | true | 【商品单价】申请退款的商品单价。 |
| promotion_detail.goods_detail.refund_amount | integer | true | 【商品退款金额】申请退款的商品退款金额。 |
| promotion_detail.goods_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/4012365347.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | INVALID\_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| 401 | SIGN\_ERROR | 签名错误 | 请检查签名参数和方法是否都符合签名算法要求，参考：[如何生成签名](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#2.-%E4%BB%80%E4%B9%88%E6%97%B6%E5%80%99%E9%9C%80%E8%A6%81%E9%AA%8C%E7%AD%BE%EF%BC%9F%E5%A6%82%E4%BD%95%E9%AA%8C%E7%AD%BE%EF%BC%9F) |
| 403 | NOT\_ENOUGH | 余额不足 | 此状态代表退款申请失败，商户账户余额不足。 |
| 403 | USER\_ACCOUNT\_ABNORMAL | 退款请求失败 | 此状态代表退款申请失败，商户可自行处理退款。 |
| 404 | MCH\_NOT\_EXISTS | MCHID不存在 | 请检查商户号是否正确，商户号获取方式请参考[普通商户模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/merchant/4013070756.md) |
| 404 | RESOURCE\_NOT\_EXISTS | 订单号不存在 | 请检查你的订单号是否正确且是否已支付，未支付的订单不能发起退款 |
| 429 | FREQUENCY\_LIMITED | 频率限制 | 该笔退款为受理中，请调用查单接口确认或降低频率原单重试，重试请勿更换单号 |
| 500 | SYSTEM\_ERROR | 系统超时 | 请不要更换商户退款单号，请使用相同参数再次调用API。 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012791883-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012791883-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/merchant/4012791883-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
        }
      ]
    }
  ]
}
```
