退款申请API

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

注意

交易时间超过一年的订单无法提交退款。
微信支付退款支持单笔交易分多次退款, 多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。一笔退款失败后重新提交, 请不要更换退款单号, 请使用原商户退款单号。
请求频率限制: 150qps, 即每秒钟正常的申请退款请求次数不超过 150 次, 错误或无效请求频率限制: 6qps, 即每秒钟异常或错误的退款申请请求不超过 6 次。
每个支付订单的部分退款次数不能超过 50 次。

接口说明

适用对象: 电商平台
请求 URL: https://api.mch.weixin.qq.com/v3/ecommerce/refunds/apply
请求方式: POST
接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3

path 指该参数需在请求 URL 传参
query 指该参数需在请求 JSON 传参

请求参数

变量	类型	必填	参数名/描述/示例值
sub_mchid	string(32)	是	`二级商户号` query 微信支付分配二级商户的商户号。
			1900000109
sp_appid	string(32)	是	`电商平台APPID` `query` 电商平台在微信公众平台申请服务号对应的 APPID, 申请商户功能的时候微信支付会配置绑定关系。
			wx8888888888888888
sub_appid	string(32)	否	`二级商户APPID` `query` 二级商户在微信申请公众号成功后分配的帐号 ID, 需要电商平台侧配置绑定关系才能传参。
			wx8888888888888888
transaction_id	string(32)	否	`微信订单号` `query` 原支付交易对应的微信订单号。
			1217752501201407033233368018
out_trade_no	string(32)	否	`商户订单号` `query` 原支付交易对应的商户订单号。
			1217752501201407033233368018
out_refund_no	string(64)	是	`商户退款单号` `query` 商户系统内部的退款单号, 商户系统内部唯一, 只能是数字、大小写字母`-\|\@`, 同一退款单号多次请求只退一笔。
			1217752501201407033233368018
reason	string(80)	否	`退款原因` `query` 若商户传入, 会在下发给用户的退款消息中体现退款原因。注意: 若订单退款金额 ≤1 元, 且属于部分退款, 则不会在退款消息中体现退款原因
			商品已售完
amount	object	是	`+订单金额` `query` 订单金额信息
notify_url	string(256)	否	`退款结果回调url` `query` 异步接收微信支付退款结果通知的回调地址, 通知 url 必须为外网可访问的 url, 不能携带参数。如果参数中传了 notify_url, 则商户平台上配置的回调地址将不会生效, 优先回调当前传的地址。
			https://weixin.qq.com

订单金额

变量	类型	必填	参数名/描述/示例值
refund	int(64)	是	`退款金额`, 币种的最小单位, 只能为整数, 不能超过原订单支付金额。
			888
total	int(64)	是	`原订单金额` 原支付交易的订单总金额, 币种的最小单位, 只能为整数。
			888
currency	string(18)	否	`退款币种` 符合 ISO 4217 标准的三位字母代码, 目前只支持人民币: CNY。
			CNY

请求示例

{
  "sub_mchid": "1900000109",
  "sp_appid": "wx8888888888888888",
  "sub_appid": "wx8888888888888888",
  "transaction_id": "1217752501201407033233368018",
  "out_trade_no": "1217752501201407033233368018",
  "out_refund_no": "1217752501201407033233368018",
  "reason": "商品已售完",
  "amount": {
    "refund": 888,
    "total": 888,
    "currency": "CNY"
  },
  "notify_url": "https://weixin.qq.com"
}

返回参数

变量	类型	必填	参数名/描述/示例值
refund_id	string(32)	是	`微信退款单号` 微信支付退款订单号。
			1217752501201407033233368018
out_refund_no	string(64)	是	`商户退款单号` 商户系统内部的退款单号, 商户系统内部唯一, 同一退款单号多次请求只退一笔。
			1217752501201407033233368018
create_time	string(64)	是	`退款创建时间` 退款受理时间, 遵循 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 秒。
			2018-06-08T10:34:56+08:00
amount	object	是	`+订单金额` 订单金额信息
promotion_detail	array	否	`+优惠退款详情` 优惠退款功能信息
			见示例

订单金额

变量	类型	必填	参数名/描述/示例值
refund	int(64)	是	`退款金额`, 币种的最小单位, 只能为整数, 不能超过原订单支付金额。
			888
payer_refund	int(64)	是	`用户退款金额` 退款给用户的金额, 不包含所有优惠券金额。
			888
discount_refund	int(64)	否	`优惠退款金额` 优惠券的退款金额, 原支付单的优惠按比例退款。
			888
currency	string(18)	否	`退款币种` 符合 ISO 4217 标准的三位字母代码, 目前只支持人民币: CNY 。
			CNY

优惠退款详情

变量	类型	必填	参数名/描述/示例值
promotion_id	string(32)	是	`券 ID` 券或者立减优惠 id。
			109519
scope	string(32)	是	`优惠范围` 枚举值: GLOBAL: 全场代金券 SINGLE: 单品优惠
			SINGLE
type	string(32)	是	`优惠类型` 枚举值: COUPON: 充值型代金券, 商户需要预先充值营销经费 DISCOUNT: 免充值型优惠券, 商户不需要预先充值营销经费
			DISCOUNT
amount	int64	是	`优惠券面额` 用户享受优惠的金额(优惠券面额=微信出资金额+商家出资金额+其他出资方金额）。
			5
refund_amount	int64	是	`优惠退款金额` 代金券退款金额<=退款金额, 退款金额-代金券或立减优惠退款金额为现金, 说明详见《代金券或立减优惠》。
			100

返回示例

正常示例

{
  "refund_id": "1217752501201407033233368018",
  "out_refund_no": "1217752501201407033233368018",
  "create_time": "2018-06-08T10:34:56+08:00",
  "amount": {
    "refund": 888,
    "payer_refund": 888,
    "discount_refund": 888,
    "currency": "CNY"
  },
  "promotion_detail": [
    {
      "promotion_id": "109518",
      "scope": "SINGLE",
      "type": "DISCOUNT",
      "amount": 5,
      "refund_amount": 100
    },
    {
      "promotion_id": "109519",
      "scope": "SINGLE",
      "type": "DISCOUNT",
      "amount": 5,
      "refund_amount": 100
    }
  ]
}

错误码_{公共错误码}

状态码	错误码	描述	解决方案
500	SYSTEM_ERROR	接口返回错误	请不要更换商户退款单号, 请使用相同参数再次调用 API。
404	RESOURCE_NOT_EXISTS	订单不存在	请检查订单号是否正确且是否已支付, 未支付的订单不能发起退款
400	PARAM_ERROR	参数错误	请求参数错误, 请重新检查再调用退款申请
429	FREQUENCY_LIMITED	频率限制	该笔退款未受理, 请降低频率后重试
403	NOT_ENOUGH	余额不足	此状态代表退款申请失败, 商户可根据具体的错误提示做相应的处理。
403	USER_ACCOUNT_ABNORMAL	退款请求失败	此状态代表退款申请失败, 商户可自行处理退款。
403	NO_AUTH	没有退款权限	此状态代表退款申请失败, 请检查是否有退这笔订单的权限
401	SIGN_ERROR	签名错误	请检查签名参数和方法是否都符合签名算法要求
400	INVALID_REQUEST	请求参数符合参数格式, 但不符合业务规则	此状态代表退款申请失败, 商户可根据具体的错误提示做相应的处理。
400	MCH_NOT_EXISTS	商户号不存在	请检查商户号是否正确
403	REQUEST_BLOCKED	请求受阻	此状态代表退款申请失败, 商户可根据具体的错误提示做相应的处理。

Feedback

Was this page helpful?

很高兴听到！请告诉我们，我们如何才能改善.

很遗憾听到这个消息。请告诉我们，我们如何才能改善.

最后修改 April 12, 2020: 整理文档 (f36b91e)