商户进件
特约商户进件
基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
支付即服务
点金计划
行业方案
电商收付通(商户进件)
电商收付通(普通支付)
电商收付通(合单支付)
电商收付通(分账)
电商收付通(补差)
电商收付通(退款)
电商收付通(余额查询)
电商收付通(商户提现)
电商收付通(下载账单)
智慧商圈
微信支付分停车服务
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
分账
连锁品牌分账
风险合规
商户开户意愿确认
消费者投诉2.0
其他能力
图片上传
视频上传

申请退款API

最新更新时间:2021.02.22 版本说明


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


注意:

1. 交易时间超过一年的订单无法提交退款。

2. 微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号。

3. 请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次,单笔订单请求频率限制:1qpm,即单笔订单每分钟申请退款请求次数不超过1次。

4. 每个支付订单的部分退款次数不能超过50次。

5. 申请退款接口的返回仅代表业务的受理情况,具体退款是否成功,需要通过退款查询接口获取结果。

6. 当二级商户退款账户余额不足时,可发起垫付退款,从电商平台指定账户垫付退款资金。当二级商户退款账户余额充足时,可把退款垫付的资金回补到电商平台账户。垫付退款需要向微信支付申请开通权限,开通权限时需要指定一个垫付出款账户。

接口说明

适用对象:电商平台

请求URL:https://api.mch.weixin.qq.com/v3/ecommerce/refunds/apply

请求方式:POST


path指该参数为路径参数

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

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


请求参数

参数名 变量 类型[长度限制] 必填 描述
二级商户号 sub_mchid string[1,32] body 微信支付分配二级商户的商户号。
示例值: 1900000109
电商平台APPID sp_appid string[1,32] body 电商平台在微信公众平台申请服务号对应的APPID,申请商户功能的时候微信支付会配置绑定关系。
示例值:wx8888888888888888
二级商户APPID sub_appid string[1,32] body 二级商户在微信申请公众号成功后分配的账户ID,需要电商平台侧配置绑定关系才能传参(即二级商户已绑定微信公众号时传入)。
示例值: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元,且属于部分退款,则不会在退款消息中体现退款原因
示例值:商品已售完
+订单金额 amount object body 订单金额信息
参数名 变量 类型[长度限制] 必填 描述
退款金额 refund int 退款金额,币种的最小单位,只能为整数,不能超过原订单支付金额。
示例值:888
原订单金额 total int 原支付交易的订单总金额,币种的最小单位,只能为整数。
示例值:888
退款币种 currency string[1,18] 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。
示例值:CNY
退款结果回调url notify_url string[1,256] body 异步接收微信支付退款结果通知的回调地址,通知url必须为外网可访问的url,不能携带参数。 如果参数中传了notify_url,则商户平台上配置的回调地址将不会生效,优先回调当前传的地址。
示例值:https://weixin.qq.com
退款出资商户 refund_account string[1, 32] body电商平台垫资退款专用参数。需先确认已开通此功能后,才能使用。若需要开通,请联系微信支付客服。
枚举值:
REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付,需要向微信支付申请开通
REFUND_SOURCE_SUB_MERCHANT : 二级商户,默认值
注意:
1、电商平台垫资退款专用参数,需先确认已开通此功能后,才能使用。 若需要开通,请联系微信支付客服。
2、若传入REFUND_SOURCE_PARTNER_ADVANCE,代表使用垫付退款功能。实际出款账户为开通该功能时商户指定的出款账户,实际以退款申请受理结果或查单结果为准。

示例值:REFUND_SOURCE_SUB_MERCHANT
资金账户 funds_account string[1, 32] body若订单处于待分账状态,可以传入此参数,指定退款资金来源账户。当该字段不存在时,默认使用订单交易资金所在账户出款,即待分账时使用不可用余额的资金进行退款,已分账或无分账时使用可用余额的资金进行退款。 AVAILABLE:可用余额
示例值:AVAILABLE

请求示例


{
 "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_account": "REFUND_SOURCE_SUB_MERCHANT"
}
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
微信退款单号 refund_id string[1,32] 微信支付退款订单号。
示例值:1217752501201407033233368018
商户退款单号 out_refund_no string[1,64] 商户系统内部的退款单号,商户系统内部唯一,同一退款单号多次请求只退一笔。
示例值:1217752501201407033233368018
退款创建时间 create_time string[1,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 订单金额信息
参数名 变量 类型[长度限制] 必填 描述
退款金额 refund int 退款金额,币种的最小单位,只能为整数,不能超过原订单支付金额。
示例值:888
用户退款金额 payer_refund int 退款给用户的金额,不包含所有优惠券金额。
示例值:888
优惠退款金额 discount_refund int 优惠券的退款金额,原支付单的优惠按比例退款。
示例值:888
退款币种 currency string[1,18] 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY 。
示例值:CNY
+优惠退款详情 promotion_detail array 优惠退款功能信息,discount_refund>0时,返回该字段
示例值:见示例
参数名 变量 类型[长度限制] 必填 描述
券ID promotion_id string[1,32] 券或者立减优惠id。
示例值:109519
优惠范围 scope string[1,32] 枚举值:
GLOBAL:全场代金券
SINGLE:单品优惠
示例值:SINGLE
优惠类型 type string[1,32] 枚举值:
COUPON:充值型代金券,商户需要预先充值营销经费
DISCOUNT:免充值型优惠券,商户不需要预先充值营销经费
示例值:DISCOUNT
优惠券面额 amount int 用户享受优惠的金额(优惠券面额=微信出资金额+商家出资金额+其他出资方金额 )。
示例值:5
优惠退款金额 refund_amount int 代金券退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见《代金券或立减优惠》 。
示例值:100
退款资金来源 refund_account string[1, 32] 枚举值:
REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付
REFUND_SOURCE_SUB_MERCHANT : 二级商户,默认值
示例值:REFUND_SOURCE_SUB_MERCHANT

返回示例


{
 "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
   }
 ],
 "refund_account": "REFUND_SOURCE_SUB_MERCHANT"
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

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


版本说明

关闭
V1.1
2020.08.06
1. 字段:out_refund_no(商户退款单号)修改为必填
V1.0
2019.09.18
1. 退款申请接口上线

技术咨询

文档反馈