申请退款

更新时间：2025.03.03

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，微信支付将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。

注意：

交易时间超过一年的订单无法提交退款。
微信支付退款支持单笔交易分多次退款（不超50次），多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号。
错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次。
每个支付订单的部分退款次数不能超过50次。
如果同一个用户有多笔退款，建议分不同批次进行退款，避免并发退款导致退款失败。
申请退款接口的返回仅代表业务的受理情况，具体退款是否成功，需要通过退款查询接口获取结果。
一个月之前的订单申请退款频率限制为：5000/min。
同一笔订单多次退款的请求需相隔1分钟。

1. 接口说明

适用对象:直连模式机构模式

请求URL: https://apihk.mch.weixin.qq.com/v3/global/refunds

请求方式: POST

频率限制: 150qps

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

商户号

mchid

string[1,32]

是

Body 微信支付分配的商户号
注意：仅适用于直连模式
示例值：1900000109

APPID

appid

string[1,32]

是

Body 商户在微信开放平台申请移动应用对应的APPID
注意：仅适用于直连模式
示例值：wx8888888888888888

机构商户号

sp_mchid

string[1,32]

是

Body 微信支付分配给机构的商户号
注意：仅适用于机构模式
示例值：1900000100

子商户号

sub_mchid

string[1,32]

是

Body 微信支付分配子商户的商户号
注意：仅适用于机构模式
示例值：1900000109

机构APPID

sp_appid

string[1,32]

是

Body 商户在微信公众平台申请服务号对应的APPID
注意：仅适用于机构模式
示例值：wx8888888888888888

子商户APPID

sub_appid

string[1,32]

否

Body 子商户在微信开放平台申请移动应用对应的APPID
付款码支付/扫码支付/公众号支付使用商户公众号appid
小程序支付使用商户小程序appid
APP支付使用商户APP应用appid
注意：仅适用于机构模式
示例值：wx8888888888888888

微信订单号

transaction_id

string[1,32]

二选一

Body 原支付交易对应的微信订单号
示例值：1217752501201407033233368018

商户订单号

out_trade_no

string[1,32]

Body 原支付交易对应的订单号
示例值：1217752501201407033233368018

商户退款单号

out_refund_no

string[1,64]

是

Body 商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。
示例值：1217752501201407033233368018

退款原因

reason

string[1,80]

否

Body 若商户传入，会在下发给用户的退款消息中体现退款原因
注意：若订单退款金额≤1元，且属于部分退款，则不会在退款消息中体现退款原因
示例值：商品已售完

退款资金来源

source

string[1,30]

否

Body REFUND_SOURCE_UNSETTLED_FUNDS：未结算资金退款（默认使用未结算资金退款）
REFUND_SOURCE_RECHARGE_FUNDS：可用余额退款
示例值：REFUND_SOURCE_UNSETTLED_FUNDS
备注：该字段不适用于分账业务。

订单金额

amount

object

是

Body 订单金额信息，详细说明见下文

订单金额

退款通知地址

notify_url

string[1,256]

否

Body 异步接收微信退款状态变更的回调地址，通知url必须为外网可访问的url，不能携带参数。请使用https协议链接
示例值：https://www.weixin.qq.com/wxpay/pay.php

请求示例

场景一: 普通订单退款请求

1{
2    "sp_appid": "wx2421b1c4370ec43b",
3    "sub_appid": "1900000109",
4    "sp_mchid": "10000100",
5    "sub_mchid": "20000100",
6    "transaction_id": "1008450740201411110005820873",
7    "out_refund_no": "R20150806125346",
8    "amount" : {
9        "refund": 50,
10        "total":100,
11         "currency":"HKD"
12    },
13    "reason": "商品已售完",
14    "source": "REFUND_SOURCE_UNSETTLED_FUNDS"
15}
16

场景二: 分账订单指定出资来源退款请求

1{
2	"sp_appid": "wx7bc98d929da735fe",
3	"sp_mchid": "999952224",
4	"sub_mchid": "999968479",
5	"out_trade_no": "20220724trade004",
6	"out_refund_no": "20220724trade004refund001",
7	"amount": {
8		"currency": "CNY",
9		"refund": 500,
10		"total": 1000,
11		"from": [{
12				"fund_source": "FUNDS_REFUNDABLE_BALANCE",
13				"amount": 200
14			},
15			{
16				"fund_source": "ORDER_REFUNDABLE_BALANCE",
17				"amount": 300
18			}  //#注: 出资来源金额之和必须等于总退款金额， 即 200 + 300 = 500
19		]
20	},
21	"reason": "商品已售完"
22}

3. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付退款订单号

string[1,32]

是

微信支付退款订单号
示例值：1217752501201407033233368018

商户退款单号

out_refund_no

string[1,64]

是

返回的退款订单号。
示例值：1217752501201407033233368018

退款创建时间

create_time

string[1,64]

是

退款受理时间，
示例值：2018-06-08T10:34:56+08:00

退款金额

amount

object

是

退款金额信息，详细说明见下文

退款金额

参数名

变量

类型

必填

描述

退款金额

refund

int

是

退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额，如果有使用券，后台会按比例退。
示例值：888

退款币种

currency

string[1,16]

是

符合ISO 4217标准的三位字母代码
示例值：CNY

用户退款金额

payer_refund

int

是

退款给用户的金额，不包含所有优惠券金额
示例值：888

支付币种

payer_currency

string[1,16]

是

符合ISO 4217标准的三位字母代码
示例值：CNY

结算币种退款金额

settlement_refund

int

是

商户结算币种所对应的退款金额，币种的最小单位，只能为整数
示例值：888

结算币种

settlement_currency

string[1,16]

是

结算币种，符合ISO 4217标准的三位字母代码，币种列表详见币种类型
示例值：HKD

汇率

exchange_rate

object

是

汇率信息

汇率

退款出资来源及金额

from

array

否

跨境分账订单传递此参数指定出资来源及金额；
分账订单如果不传此参数，则默认优先从订单未分可退余额出资退款，不足部分由可垫付退款额度补足，具体出资来源及金额需要根据返回参数中 from 字段确认。
此参数使用场景需要满足以下条件：
1、订单属于跨境分账订单，非跨境订单请不要传递此参数。
参数传递需要满足条件：
1、可垫付退款余额出资金额和订单未分可退余额出资金额之和等于退款金额；
2、出资来源不能重复。
上述任一条件不满足将返回错误。

退款出资来源及金额

优惠退款详情

detail

array

否

优惠退款详情信息，详细说明见下文

优惠退款详情

注意：goods_remark为备注字段，按照配置原样返回，goods_tag是订单优惠标记，用于区分订单是否可以享受优惠，两个字段内容都在微信后台配置券时进行设置。

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string[1, 256]

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

详细的错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下

详细的错误描述

返回示例

场景一返回示例

1{
2    "id": "50202002642022072801898085012",
3    "out_refund_no": "20220724trade003refund001",
4    "create_time": "2022-07-28T15:44:07+08:00",
5    "amount": {
6        "refund": 500,
7        "currency": "CNY",
8        "payer_refund": 250,
9        "payer_currency": "CNY",
10        "settlement_refund": 578,
11        "settlement_currency": "HKD",
12        "exchange_rate": {
13            "type": "SETTLEMENT_RATE",
14            "rate": 86500000
15        }
16    },
17    "detail": [
18        {
19            "promotion_id": "11006096615",
20            "scope": "GLOBAL",
21            "type": "COUPON",
22            "amount": 500,
23            "refund_amount": 250,
24            "currency": "CNY"
25        }
26    ]
27}

场景二: 返回示例

1{
2    "id": "50201702652022072801898085013",
3    "out_refund_no": "20220724trade004refund001",
4    "create_time": "2022-07-28T15:51:57+08:00",
5    "amount": {
6        "refund": 500,
7        "currency": "CNY",
8        "payer_refund": 250,
9        "payer_currency": "CNY",
10        "settlement_refund": 578,
11        "settlement_currency": "HKD",
12        "exchange_rate": {
13            "type": "SETTLEMENT_RATE",
14            "rate": 86490000
15        },
16        "from": [
17            {
18                "fund_source": "ORDER_REFUNDABLE_BALANCE",
19                "amount": 300
20            },
21            {
22                "fund_source": "FUNDS_REFUNDABLE_BALANCE",
23                "amount": 200
24            }
25        ]
26    },
27    "detail": [
28        {
29            "promotion_id": "11006096908",
30            "scope": "GLOBAL",
31            "type": "COUPON",
32            "amount": 500,
33            "refund_amount": 250,
34            "currency": "CNY"
35        }
36    ]
37}

异常示例

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

4. 错误码

错误码	描述	解决方案
RESOURCE_NOT_EXISTS	查询的资源不存在	请检查查询资源的对应id是否填写正确
SYSTEM_ERROR	接口返回错误	请不要更换商户退款单号，请使用相同参数再次调用API。否则可能造成资金损失
BIZERR_NEED_RETRY	退款业务流程错误，需要商户触发重试来解决	请不要更换商户退款单号，请使用相同参数再次调用API。否则可能造成资金损失
TRADE_OVERDUE	订单已经超过退款期限	请选择其他方式自行退款
ERROR	业务错误	该错误都会返回具体的错误原因，请根据实际返回做相应处理。
USER_ACCOUNT_ABNORMAL	退款请求失败	此状态代表退款申请失败，商户可自行处理退款。
INVALID_REQ_TOO_MUCH	无效请求过多	请检查业务是否正常，确认业务正常后请在1分钟后再来重试
NOT_ENOUGH	余额不足	此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。
INVALID_TRANSACTIONID	无效transaction_id	请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败
PARAM_ERROR	参数错误	请求参数错误，请重新检查再调用退款申请
APPID_NOT_EXIST	APPID不存在	请检查APPID是否正确
MCHID_NOT_EXIST	MchID不存在	请检查MchID是否正确
REQUIRE_POST_METHOD	请使用post方法	请检查请求参数是否通过post方法提交
SIGN_ERROR	签名错误	请检查签名参数和方法是否都符合签名算法要求
FREQUENCY_LIMITED	频率限制	触发退款操作频次限制，当前退款请求受理状态不明。建议先通过查询退款接口确认退款状态，或稍后通过原退款单号重试
INVALID_REQUEST	请求参数符合参数格式，但不符合业务规则	此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。