# 退款

接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南。

接口英文名：refundOrder

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

# 1. 调用方式

# HTTPS 调用

POST https://api.weixin.qq.com/retail/B2b/refund?access_token=ACCESS_TOKEN

# 云调用

本接口不支持云调用。

# 第三方调用

本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为：158
服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看第三方调用说明文档。

# 2. 请求参数

# 查询参数 `Query String Parameters`

参数名	类型	必填	示例	说明
access_token	string	是	ACCESS_TOKEN	接口调用凭证，可使用 access_token、authorizer_access_token

# 请求体 `Request Payload`

参数名	类型	必填	示例	说明
mchid	string	是	1230000109	微信商户号。长度限制[1,32]。由微信支付生成并下发的商户号。
out_trade_no	string	否	1217752501201407033233368018	商户订单号。长度限制[6,32]。原支付交易对应的商户订单号。商户订单号和B2b支付订单号必填其一
order_id	string	否	o202307291423123564754773	B2b支付订单号。长度限制[1,32]。原支付交易对应的B2b支付订单号。商户订单号和B2b支付订单号必填其一
out_refund_no	string	是	12177525012014070332321235	商户退款单号。长度限制[6, 32] 。商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。
refund_amount	number	是	888	退款金额。单位为分，只能为整数，不能超过原订单支付金额。
refund_from	number	是	1	退款来源，枚举值 1：人工客服退款 2：用户自己退款 3：其他
refund_reason	number	否	3	退款原因。枚举值 0：暂无描述 1：产品问题 2：售后问题 3：意愿问题 4：价格问题 5：其他原因
description	string	否	抱枕	退款商品描述。长度限制[1,127]

# 3. 返回参数

# 返回体 `Response Payload`

参数名	类型	示例	说明
refund_id	string	r202307281444591411763685	B2b支付退款单号。长度限制[1, 32]
out_refund_no	string	12177525012014070332321235	商户退款单号。长度限制[6, 32]。户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。
order_id	string	o202307291423123564754773	B2b支付订单号。长度限制[1,32]。原支付交易对应的B2b支付订单号
out_trade_no	string	o202307291423123564754773	商户订单号。长度限制[1,32]。原支付交易对应的B2b支付订单号
errcode	number	0	错误码
errmsg	string	ok	错误信息

# 4. 注意事项

pay_sig的计算用现网AppKey

a、订单如需多次退款，同笔订单发起退款的间隔须大于一分钟

b、退款接口只是发起退款请求，不表示退款成功，请2分钟后调用退款查询结果轮询退款状态

# 退款通知

通过消息推送功能发送给业务方服务器，业务方按照消息推送的要求回复，否则会认为通知失败。通知失败后会按照一定的策略重新发起通知，以尽可能通知到商户，但并不保证通知最终能成功。（通知重试频率为10s, 30s, 60s, 5min, 15min, 30min, 60m, 3h, 6h, 12h）

通知参数

参数名	变量	类型[长度限制]	必填	描述
小程序原始ID	ToUserName	string	是	小程序原始ID
事件消息openid	FromUserName	string	是	微信官方的openid。示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
消息发送时间	CreateTime	int64	是	消息发送时间戳。示例值：1698643478
消息类型	MsgType	string	是	消息类型，固定为event。示例值：event
事件类型	Event	string	是	事件类型，固定为retail_refund_notify。示例值：retail_refund_notify
小程序ID	appid	string[1,32]	是	商户申请的小程序对应的appid。示例值：wx8888888888888888
微信商户号	mchid	string[1,32]	是	由微信支付生成并下发的商户号。示例值：1230000109
商户退款单号	out_refund_no	string[6, 32]	是	商户系统内部退款单号，商户系统内部唯一，只能是数字、大小写字母_-*，同一退款单号多次请求只退一笔。示例值：12177525012014070332321235
B2b支付退款单号	refund_id	string[1, 32]	否	B2b支付退款单号。示例值：r202307281444591411763685
商户订单号	out_trade_no	string[6,32]	是	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一。示例值：1217752501201407033233368018
B2b支付订单号	order_id	string[1,32]	是	B2b支付生成的订单号。示例值：o202307291423123564754773
退款金额	refund_amount	int64	是	退款金额，单位为分，只能为整数，不能超过原订单支付金额。示例值：888
订单总金额	order_amount	int64	是	订单总支付金额，单位为分。示例值：1300
退款来源	refund_from	string	是	退款来源，枚举值 1：人工客服退款 2：用户自己退款 3：其他。示例值：1
退款原因	refund_reason	string	否	退款原因，枚举值 0：暂无描述 1：产品问题 2：售后问题 3：意愿问题 4：价格问题 5：其他原因。示例值：3
退款创建时间	create_time	string[1, 32]	是	退款受理时间，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss。示例值：2023-07-30 17:04:23
退款成功时间	refund_time	string[1, 32]	否	退款成功时间，当退款状态为退款成功时有返回，标准北京时间，时区为东八区，格式为yyyy-MM-dd HH:mm:ss。示例值：2023-07-30 17:04:28
退款状态	refund_status	string[1, 32]	是	仅退款成功或失败时通知，枚举值：REFUND_SUCC：退款成功；REFUND_FAIL：退款失败；示例值：REFUND_SUCC
微信支付退款单号	wxpay_refund_id	string[1, 32]	否	微信支付退款单号。示例值：1235481444591411763685
订单环境	env	int32	是	订单环境 0：正式环境 1：沙箱环境。示例值：0
交易渠道类型	pay_channel	int32	是	交易渠道类型 0：微信支付 1：银行转账。示例值：0
退款说明	refund_desc	string[1, 256]	否	退款说明。示例值：账户资金不足，请待充足后重新发起

通知示例

{
  "ToUserName": "gh_xxxxx",
  "FromUserName": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
  "CreateTime": "1741168258",
  "MsgType": "event",
  "Event": "retail_refund_notify",
  "appid": "wx8888888888888888",
  "mchid": "1230000109",
  "out_refund_no": "12177525012014070332321235",
  "refund_id": "r202307281444591411763685",
  "out_trade_no": "1217752501201407033233368018",
  "order_id": "o202307291423123564754773",
  "refund_amount": 1,
  "order_amount": 1000,
  "refund_from": "REFUND_FROM_USER",
  "refund_reason": "REFUND_REASON_WILLING",
  "create_time": "2025-03-05 17:50:50",
  "refund_time": "2025-03-05 17:50:53",
  "refund_status": "REFUND_SUCC",
  "wxpay_refund_id": "50302002662025030599670471876",
  "env": 0,
  "pay_channel": 0,
  "refund_desc": "", 
}

应答参数

直接回复success（推荐方式）
直接回复空串（指字节长度为0的空字符串，而不是结构体中content字段的内容为空）

# 5. 代码示例

请求示例

{
  "mchid": "1230000109",
  "out_trade_no": "1217752501201407033233368018",
  "out_refund_no": "12177525012014070332321235",
  "refund_amount": 1,
  "refund_from": 2,
  "refund_reason": 3
}

返回示例

{
  "refund_id": "r202307281444591411763685",
  "out_refund_no": "12177525012014070332321235",
  "order_id": "o202307291423123564754773",
  "out_trade_no": "1217752501201407033233368018",
  "errcode": 0,
  "errmsg": OK
}

# 6. 错误码

以下是本接口的错误码列表，其他错误码可参考通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具辅助定位和分析问题。

错误码	错误描述	解决方案
10604	单笔订单的退款频率过高	在一分钟内只能发起一次退款，请稍后重试
9403200	参数为空或不合法。	按照文档要求传参，根据返回的具体错误描述检查参数
9403201	数据不存在	订单不存在，请检查入参
9403202	退款单已受理	请调用查询退款接口确认退款请求
9403203	建档未完成，还不能发起支付或退款	请完成建档签约流程
9403205	订单无法退款（订单状态不对或超过160天）	请检查订单状态或订单时间
9403206	退款状态未知，请商户2分钟后主动查询退款状态	请2分钟后调用查询退款接口确认退款状态
9403208	该订单正在退款中，请等待退款完成再发起新的退款	请等待退款完成再发起新的退款
9403209	不允许结算前退款	请等待订单结算后再退款

# 7. 适用范围

本接口暂未明确可调用账号类型，或在业务中根据调用传参自行确定是否可调用，请以实际调用情况为准。