申请退款API

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


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

注意:

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

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

3、错误或无效请求频率限制:6qps,即每秒钟异常或错误的退款申请请求不超过6次

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

5、如果同一个用户有多笔退款,建议分不同批次进行退款,避免并发退款导致退款失败

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

7、一个月之前的订单申请退款频率限制为:5000/min

状态机

退款状态转变如下:

接口说明

适用对象:服务商

请求URL:https://api.mch.weixin.qq.com/v3/refund/domestic/refunds

请求方式:POST

接口频率:150qps


path 指该参数为路径参数

query 指该参数为URL参数

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


请求参数

参数名 变量 类型[长度限制] 必填 描述
子商户号 sub_mchid string[1, 32] body子商户的商户号,由微信支付生成并下发。
示例值:1900000109
微信支付订单号 transaction_id string[1, 32] 二选一 body原支付交易对应的微信订单号
示例值:1217752501201407033233368018
商户订单号 out_trade_no string[6, 32] body原支付交易对应的商户订单号
示例值:1217752501201407033233368018
商户退款单号 out_refund_no string[1, 64] body商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
示例值:1217752501201407033233368018
退款原因 reason string[1, 80] body若商户传入,会在下发给用户的退款消息中体现退款原因
示例值:商品已售完
退款结果回调url notify_url string[8, 256] body异步接收微信支付退款结果通知的回调地址,通知url必须为外网可访问的url,不能携带参数。 如果参数中传了notify_url,则商户平台上配置的回调地址将不会生效,优先回调当前传的这个地址。
示例值:https://weixin.qq.com
退款资金来源 funds_account string[1,32] body若传递此参数则使用对应的资金账户退款,否则默认使用未结算资金退款(仅对老资金流商户适用)
枚举值:
AVAILABLE:可用余额账户
示例值:AVAILABLE
+金额信息 amount object body订单金额信息
参数名 变量 类型[长度限制] 必填 描述
退款金额 refund int 退款金额,币种的最小单位,只能为整数,不能超过原订单支付金额。
示例值:888
+退款出资账户及金额 from array 退款需要从指定账户出资时,传递此参数指定出资金额(币种的最小单位,只能为整数)。
同时指定多个账户出资退款的使用场景需要满足以下条件:
  1、未开通退款支出分离产品功能;
  2、订单属于分账订单,且分账处于待分账或分账中状态。
参数传递需要满足条件:
  1、基本账户可用余额出资金额与基本账户不可用余额出资金额之和等于退款金额;
  2、账户类型不能重复。
上述任一条件不满足将返回错误
参数名 变量 类型[长度限制] 必填 描述
出资账户类型 account string[1, 32] 下面枚举值多选一。
枚举值:
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
示例值:AVAILABLE
出资金额 amount int 对应账户出资金额
示例值:444
原订单金额 total int 原支付交易的订单总金额,币种的最小单位,只能为整数。
示例值:888
退款币种 currency string[1, 16] 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。
示例值:CNY
+退款商品 goods_detail array body指定商品退款需要传此参数,其他场景无需传递
参数名 变量 类型[长度限制] 必填 描述
商户侧商品编码 merchant_goods_id string[1, 32] 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
示例值:1217752501201407033233368018
微信侧商品编码 wechatpay_goods_id string[1, 32] 微信支付定义的统一商品编号(没有可不传)
示例值:1001
商品名称 goods_name string[1, 256] 商品的实际名称
示例值:iPhone6s 16G
商品单价 unit_price int 商品单价金额,单位为分
示例值:528800
商品退款金额 refund_amount int 商品退款金额,单位为分
示例值:528800
商品退货数量 refund_quantity int 单品的退款数量
示例值:1

请求示例


{
  "sub_mchid": "1900000109",
  "transaction_id": "1217752501201407033233368018",
  "out_refund_no": "1217752501201407033233368018",
  "reason": "商品已售完",
  "notify_url": "https://weixin.qq.com",
  "funds_account": "AVAILABLE",
  "amount": {
    "refund": 888,
    "from": [
      {
        "account": "AVAILABLE",
        "amount": 444
      }
    ],
    "total": 888,
    "currency": "CNY"
  },
  "goods_detail": [
    {
      "merchant_goods_id": "1217752501201407033233368018",
      "wechatpay_goods_id": "1001",
      "goods_name": "iPhone6s 16G",
      "unit_price": 528800,
      "refund_amount": 528800,
      "refund_quantity": 1
    }
  ]
}

{
JAVA示例代码
}

返回参数

参数名 变量 类型[长度限制] 必填 描述
微信支付退款单号 refund_id string[1, 32] 微信支付退款单号
示例值:50000000382019052709732678859
商户退款单号 out_refund_no string[1, 64] 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。
示例值:1217752501201407033233368018
微信支付订单号 transaction_id string[1, 32] 微信支付交易订单号
示例值:1217752501201407033233368018
商户订单号 out_trade_no string[1, 32] 原支付交易对应的商户订单号
示例值:1217752501201407033233368018
退款渠道 channel string[1, 16] 枚举值:
ORIGINAL:原路退款
BALANCE:退回到余额
OTHER_BALANCE:原账户异常退到其他余额账户
OTHER_BANKCARD:原银行卡异常退到其他银行卡
示例值:ORIGINAL
退款入账账户 user_received_account string[1, 64] 取当前退款单的退款入账方,有以下几种情况:
1)退回银行卡:{银行名称}{卡类型}{卡尾号}
2)退回支付用户零钱:支付用户零钱
3)退还商户:商户基本账户商户结算银行账户
4)退回支付用户零钱通:支付用户零钱通
示例值:招商银行信用卡0403
退款成功时间 success_time string[1, 64] 退款成功时间,当退款状态为退款成功时有返回。
示例值:2020-12-01T16:18:12+08:00
退款创建时间 create_time string[1, 64] 退款受理时间
示例值:2020-12-01T16:18:12+08:00
退款状态 status string[1, 32] 退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往服务商平台-交易中心,手动处理此笔退款。
枚举值:
SUCCESS:退款成功
CLOSED:退款关闭
PROCESSING:退款处理中
ABNORMAL:退款异常
示例值:SUCCESS
资金账户 funds_account string[1, 32] 退款所使用资金对应的资金账户类型
枚举值:
UNSETTLED : 未结算资金
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
OPERATION : 运营户
BASIC : 基本账户(含可用余额和不可用余额)
示例值:UNSETTLED
+金额信息 amount object 金额详细信息
参数名 变量 类型[长度限制] 必填 描述
订单金额 total int 订单总金额,单位为分
示例值:100
退款金额 refund int 退款标价金额,单位为分,可以做部分退款
示例值:100
+退款出资账户及金额 from array 退款出资的账户类型及金额信息
参数名 变量 类型[长度限制] 必填 描述
出资账户类型 account string[1, 32] 下面枚举值多选一。
枚举值:
AVAILABLE : 可用余额
UNAVAILABLE : 不可用余额
示例值:AVAILABLE
出资金额 amount int 对应账户出资金额
示例值:444
用户支付金额 payer_total int 现金支付金额,单位为分,只能为整数
示例值:90
用户退款金额 payer_refund int 退款给用户的金额,不包含所有优惠券金额
示例值:90
应结退款金额 settlement_refund int 去掉非充值代金券退款金额后的退款金额,单位为分,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额
示例值:100
应结订单金额 settlement_total int 应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额,单位为分
示例值:100
优惠退款金额 discount_refund int 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠,单位为分
示例值:10
退款币种 currency string[1, 16] 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。
示例值:CNY
+优惠退款信息 promotion_detail array 优惠退款信息
参数名 变量 类型[长度限制] 必填 描述
券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
+商品列表 goods_detail array 优惠商品发生退款时返回商品信息
参数名 变量 类型[长度限制] 必填 描述
商户侧商品编码 merchant_goods_id string[1, 32] 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成
示例值:1217752501201407033233368018
微信侧商品编码 wechatpay_goods_id string[1, 32] 微信支付定义的统一商品编号(没有可不传)
示例值:1001
商品名称 goods_name string[1, 256] 商品的实际名称
示例值:iPhone6s 16G
商品单价 unit_price int 商品单价金额,单位为分
示例值:528800
商品退款金额 refund_amount int 商品退款金额,单位为分
示例值:528800
商品退货数量 refund_quantity int 单品的退款数量
示例值:1

返回示例


{
  "refund_id": "50000000382019052709732678859",
  "out_refund_no": "1217752501201407033233368018",
  "transaction_id": "1217752501201407033233368018",
  "out_trade_no": "1217752501201407033233368018",
  "channel": "ORIGINAL",
  "user_received_account": "招商银行信用卡0403",
  "success_time": "2020-12-01T16:18:12+08:00",
  "create_time": "2020-12-01T16:18:12+08:00",
  "status": "SUCCESS",
  "funds_account": "UNSETTLED",
  "amount": {
    "total": 100,
    "refund": 100,
    "from": [
      {
        "account": "AVAILABLE",
        "amount": 444
      }
    ],
    "payer_total": 90,
    "payer_refund": 90,
    "settlement_refund": 100,
    "settlement_total": 100,
    "discount_refund": 10,
    "currency": "CNY"
  },
  "promotion_detail": [
    {
      "promotion_id": "109519",
      "scope": "SINGLE",
      "type": "DISCOUNT",
      "amount": 5,
      "refund_amount": 100,
      "goods_detail": {
        "merchant_goods_id": "1217752501201407033233368018",
        "wechatpay_goods_id": "1001",
        "goods_name": "iPhone6s 16G",
        "unit_price": 528800,
        "refund_amount": 528800,
        "refund_quantity": 1
      }
    }
  ]
}
                    

http://2323weixin.qq.com
                    

错误码公共错误码

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




技术咨询

文档反馈