申请退款

更新时间: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. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付退款订单号

id

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

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

退款金额

优惠退款详情

detail

Object

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

优惠退款详情

注意: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

请求参数符合参数格式,但不符合业务规则

此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.