微信支付-融合钱包开发者文档

返回上一层融合钱包 / H5支付 / 申请退款API

申请退款

最新更新时间：2020.1.08 版本说明

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

注意：

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

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

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

● 错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过6次。

接口说明

适用对象:直连模式机构模式

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

请求方式: POST

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3/wei-xin-zhi-fu-api-v3-jie-kou-gui-fan

频率限制:150qps

path 指该参数为路径参数

query 指该参数为URL参数

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

请求参数

参数名

变量

类型

必填

描述

商户号

mchid

string(32)

是

body 微信支付分配的商户号
注意：仅适用于直连模式
示例值：1900000109

APPID

appid

string(32)

是

body 商户在微信开放平台申请移动应用对应的APPID
注意：仅适用于直连模式
示例值：wx8888888888888888

机构商户号

sp_mchid

string(32)

是

body微信支付分配给机构的商户号
注意：仅适用于机构模式
示例值：1900000100

子商户号

sub_mchid

string(32)

是

body 微信支付分配子商户的商户号
注意：仅适用于机构模式
示例值：1900000109

机构APPID

sp_appid

string(32)

是

body商户在微信公众平台申请服务号对应的APPID
注意：仅适用于机构模式
示例值：wx8888888888888888

子商户APPID

sub_appid

string(32)

否

body 子商户在微信开放平台申请移动应用对应的APPID
付款码支付/扫码支付/公众号支付使用商户公众号appid
小程序支付使用商户小程序appid
APP支付使用商户APP应用appid
注意：仅适用于机构模式
示例值：wx8888888888888888

微信订单号

transaction_id

string(32)

二选一

body 原支付交易对应的微信订单号
示例值：1217752501201407033233368018

商户订单号

out_trade_no

string(32)

body 原支付交易对应的订单号
示例值：1217752501201407033233368018

商户退款单号

out_refund_no

string(64)

是

body 商户系统内部的退款单号，商户系统内部唯一，只能是数字、大小写字母_-|*@ ，同一退款单号多次请求只退一笔。
示例值：1217752501201407033233368018

退款原因

reason

string(80)

否

body 若商户传入，会在下发给用户的退款消息中体现退款原因
注意：若订单退款金额≤1元，且属于部分退款，则不会在退款消息中体现退款原因
示例值：商品已售完

+ 订单金额

amount

object

是

body 订单金额信息，详细说明见下文

参数名	变量	类型	必填	描述
退款金额	refund	int	是	退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额，如果有使用券，后台会按比例退。示例值：888
原订单金额	total	int	是	原支付交易的订单总金额，币种的最小单位，只能为整数，详见交易金额示例值：888
退款币种	currency	string(16)	是	符合ISO 4217标准的三位字母代码，退款币种必须和标价币种一致，币种列表详见币种类型示例值：HKD

退款通知地址

notify_url

string(256)

否

body异步接收微信退款状态变更的回调地址，通知url必须为外网可访问的url，不能携带参数。请使用https协议链接
示例值：https://www.weixin.qq.com/wxpay/pay.php

请求示例：

JSON


{
    "sp_appid": "wx2421b1c4370ec43b",
    "sub_appid": "1900000109",
    "sp_mchid": "10000100",
    "sub_mchid": "20000100",
    "transaction_id": "1008450740201411110005820873",
    "out_refund_no": "R20150806125346",
    "amount" : {
        "refund": 50,
        "total":100,
         "currency":"HKD"
    },
    "reason": "商品已售完",
    "source": "REFUND_SOURCE_UNSETTLED_FUNDS"
}

    
｛
JAVA示例代码
｝

返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付退款订单号

string(32)

是

微信支付退款订单号
示例值：1217752501201407033233368018

商户退款单号

out_refund_no

string(64)

是

返回的退款订单号。
示例值：1217752501201407033233368018

退款创建时间

create_time

string(64)

是

退款受理时间，
示例值：2018-06-08T10:34:56+08:00

+ 退款金额

amount

object

是

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

参数名

变量

类型

必填

描述

退款金额

refund

int

是

退款金额，币种的最小单位，只能为整数，不能超过原订单支付金额，如果有使用券，后台会按比例退。
示例值：888

退款币种

currency

string(16)

是

符合ISO 4217标准的三位字母代码
示例值：CNY

用户退款金额

payer_refund

int

是

退款给用户的金额，不包含所有优惠券金额
示例值：888

支付币种

payer_currency

string(16)

是

符合ISO 4217标准的三位字母代码
示例值：CNY

+ 汇率

exchange_rate

object

是

汇率信息

参数名	变量	类型	必填	描述
汇率类型	type	string(16)	否	标价币种和支付币种一致时,type="SETTLEMENT_RATE",即【实时】标价币种和结算币种的汇率；标价币种和支付币种不一致,type="USERPAYMENT_RATE",即【原支付】标价币种和支付币种的汇率示例值：SETTLEMENT_RATE
汇率值	rate	int	否	rate值是兑换比例乘以10的8次方，如果兑换比例是1，则rate=100000000；如果兑换比例为6.5，则rate=650000000 示例值：8000000

+ 优惠退款详情

detail

object

否

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

参数名	变量	类型	必填	描述
券ID	promotion_id	string(32)	是	券或者立减优惠id 示例值：109519
优惠范围	scope	string(32)	否	GLOBAL：全场代金券 SINGLE：单品优惠示例值：SINGLE
优惠类型	type	string(32)	否	COUPON：代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致） DISCOUNT：优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致示例值：DISCOUNT
优惠券面额	amount	int	否	用户享受优惠的金额（优惠券面额=微信出资金额+商家出资金额+其他出资方金额）示例值：5
优惠券退款额	refund_amount	int	否	按比例退款的优惠券金额示例值：5
货币类型	currency	string(16)	是	符合ISO 4217标准的三位字母代码示例值：CNY

异常返回

参数名

变量

类型

必填

描述

返回状态码

code

string(32)

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string(256)

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

+ 详细的错误描述

detail

array

否

当code为PARAM_ERROR时返回，详细说明见下

参数名	变量	类型	必填	描述
指示错误参数的位置	field	string(256)	是	当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer；当错误参数位于请求的url或者querystring时，填写参数的变量名示例值：#/properties/payer
错误参数的值	value	string(256)	是	错误参数的值示例值：1346177081915535577
具体错误原因	issue	string(256)	是	具体错误原因示例值：与ALLOF schema不符
错误参数的位置	location	string(256)	否	body：错误参数位于请求body的JSON中 url：错误参数位于请求url中 query：错误参数位于请求的querystring中示例值：body

返回示例：

{
    {
    "id": "2008450740201411110000174436",
    "out_refund_no": "R20150806125346",
    "create_time": "20141111170042",
    "amount": {
        "refund": 50,
        "currency": "CNY",
        "payer_refund": 49,
        "payer_currency": "HKD",
		"exchange_rate" : {
            "type": "SETTLEMENT_RATE",
            "rate": 8000000
        }
    },
    "detail": [
        {
            "promotion_id":"109519",
            "scope":"GLOBAL",
            "type":"COUPON",
            "amount": 1,
            "refund_amount": 1,
            "currency":"HKD"
        }
    ]
}

{
"code":"INVALID_REQUEST",
"message":"参数格式校验错误",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"与ALLOF schema不符",
    "location":"body"
   }
}

错误码

错误码	描述	解决方案
SYSTEMERROR	接口返回错误	请不要更换商户退款单号，请使用相同参数再次调用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方法提交
SIGNERROR	签名错误	请检查签名参数和方法是否都符合签名算法要求
FREQUENCY_LIMITED	频率限制	该笔退款未受理，请降低频率后重试，该笔退款未受理，请降低频率后原单重试，请勿更换单号
ORDERNOTEXIST	订单号不存在	请检查你的订单号是否正确且是否已支付，未支付的订单不能发起退款
INVALID_REQUEST	请求参数符合参数格式，但不符合业务规则	此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

H5支付

申请退款

注意：

接口说明

请求参数

请求示例：

返回参数

正常返回

异常返回

返回示例：

错误码

版本说明