微信支付-跨境开发者中心

1. 接口说明

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

请求URL:https://apihk.mch.weixin.qq.com/v3/global/refunds

请求方式: POST

频率限制:150qps

Path指该参数为路径参数

Query指该参数为URL参数

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

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

商户号

mchid

string[1,32]

是

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

APPID

appid

string[1,32]

是

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

机构商户号

sp_mchid

string[1,32]

是

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

子商户号

sub_mchid

string[1,32]

是

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

机构APPID

sp_appid

string[1,32]

是

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

子商户APPID

sub_appid

string[1,32]

否

Body 子商户在微信开放平台申请移动应用对应的APPID
付款码支付/扫码支付/公众号支付使用商户公众号appid
小程序支付使用商户小程序appid
APP支付使用商户APP应用appid
注意：仅适用于机构模式
示例值：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元，且属于部分退款，则不会在退款消息中体现退款原因
示例值：商品已售完

退款资金来源

source

string[1,30]

否

Body REFUND_SOURCE_UNSETTLED_FUNDS：未结算资金退款（默认使用未结算资金退款）
REFUND_SOURCE_RECHARGE_FUNDS：可用余额退款
示例值：REFUND_SOURCE_UNSETTLED_FUNDS

订单金额

amount

object

是

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

参数名

变量

类型

必填

描述

退款金额

refund

int

是

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

原订单金额

total

int

是

原支付交易的订单总金额，币种的最小单位，只能为整数，详见交易金额
示例值：888

退款币种

currency

string[1,16]

是

符合ISO 4217标准的三位字母代码，退款币种必须和标价币种一致，币种列表详见币种类型
示例值：HKD

退款出资来源及金额

from

array

否

跨境分账订单传递此参数指定出资来源及金额；
分账订单如果不传此参数，则默认优先从订单未分可退余额出资退款，不足部分由可垫付退款额度补足，具体出资来源及金额需要根据返回参数中 from 字段确认。
此参数使用场景需要满足以下条件：
1、订单属于跨境分账订单，非跨境订单请不要传递此参数。
参数传递需要满足条件：
1、可垫付退款余额出资金额和订单未分可退余额出资金额之和等于退款金额；
2、出资来源不能重复。
上述任一条件不满足将返回错误。

参数名	变量	类型	必填	描述
出资来源	fund_source	string[1,32]	是	退款出资来源，下面枚举值多选一。枚举值： FUNDS_REFUNDABLE_BALANCE : 可垫付退款余额 ORDER_REFUNDABLE_BALANCE : 订单未分可退余额示例值：FUNDS_REFUNDABLE_BALANCE
出资金额	amount	int	是	对应出资来源金额（币种的最小单位，只能为整数）示例值：888

收起

退款通知地址

notify_url

string[1,256]

否

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

请求示例

场景一: 普通订单退款请求场景二: 分账订单指定出资来源退款请求


{
    "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"
}


{
	"sp_appid": "wx7bc98d929da735fe",
	"sp_mchid": "999952224",
	"sub_mchid": "999968479",
	"out_trade_no": "20220724trade004",
	"out_refund_no": "20220724trade004refund001",
	"amount": {
		"currency": "CNY",
		"refund": 500,
		"total": 1000,
		"from": [{
				"fund_source": "FUNDS_REFUNDABLE_BALANCE",
				"amount": 200
			},
			{
				"fund_source": "ORDER_REFUNDABLE_BALANCE",
				"amount": 300
			}  //#注: 出资来源金额之和必须等于总退款金额， 即 200 + 300 = 500
		]
	},
	"reason": "商品已售完"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付退款订单号

id

string[1,32]

是

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

商户退款单号

out_refund_no

string[1,64]

是

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

退款创建时间

create_time

string[1,64]

是

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

退款金额

amount

object

是

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

参数名

变量

类型

必填

描述

退款金额

refund

int

是

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

退款币种

currency

string[1,16]

是

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

用户退款金额

payer_refund

int

是

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

支付币种

payer_currency

string[1,16]

是

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

结算币种退款金额

settlement_refund

int

是

商户结算币种所对应的退款金额，币种的最小单位，只能为整数
示例值：888

结算币种

settlement_currency

string[1,16]

是

结算币种，符合ISO 4217标准的三位字母代码，币种列表详见币种类型
示例值：HKD

汇率

exchange_rate

object

是

汇率信息

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

收起

退款出资来源及金额

from

array

否

跨境分账订单传递此参数指定出资来源及金额；
分账订单如果不传此参数，则默认优先从订单未分可退余额出资退款，不足部分由可垫付退款额度补足，具体出资来源及金额需要根据返回参数中 from 字段确认。
此参数使用场景需要满足以下条件：
1、订单属于跨境分账订单，非跨境订单请不要传递此参数。
参数传递需要满足条件：
1、可垫付退款余额出资金额和订单未分可退余额出资金额之和等于退款金额；
2、出资来源不能重复。
上述任一条件不满足将返回错误。

参数名	变量	类型	必填	描述
出资来源	fund_source	string[1,32]	是	退款出资来源，下面枚举值多选一。枚举值： FUNDS_REFUNDABLE_BALANCE : 可垫付退款余额 ORDER_REFUNDABLE_BALANCE : 订单未分可退余额示例值：FUNDS_REFUNDABLE_BALANCE
出资金额	amount	int	是	对应出资来源金额（币种的最小单位，只能为整数）示例值：888

收起

优惠退款详情

detail

Object

否

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

参数名	变量	类型	必填	描述
券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	否	按比例退款的优惠券金额示例值：5
货币类型	currency	string[1,16]	是	符合ISO 4217标准的三位字母代码示例值：CNY

收起

注意：goods_remark为备注字段，按照配置原样返回，goods_tag是订单优惠标记，用于区分订单是否可以享受优惠，两个字段内容都在微信后台配置券时进行设置。

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

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

返回信息

message

string[1, 256]

是

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

详细的错误描述

detail

object

否

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

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

收起

返回示例

场景一返回示例场景二: 返回示例异常示例


{
    "id": "50202002642022072801898085012",
    "out_refund_no": "20220724trade003refund001",
    "create_time": "2022-07-28T15:44:07+08:00",
    "amount": {
        "refund": 500,
        "currency": "CNY",
        "payer_refund": 250,
        "payer_currency": "CNY",
        "settlement_refund": 578,
        "settlement_currency": "HKD",
        "exchange_rate": {
            "type": "SETTLEMENT_RATE",
            "rate": 86500000
        }
    },
    "detail": [
        {
            "promotion_id": "11006096615",
            "scope": "GLOBAL",
            "type": "COUPON",
            "amount": 500,
            "refund_amount": 250,
            "currency": "CNY"
        }
    ]
}


{
    "id": "50201702652022072801898085013",
    "out_refund_no": "20220724trade004refund001",
    "create_time": "2022-07-28T15:51:57+08:00",
    "amount": {
        "refund": 500,
        "currency": "CNY",
        "payer_refund": 250,
        "payer_currency": "CNY",
        "settlement_refund": 578,
        "settlement_currency": "HKD",
        "exchange_rate": {
            "type": "SETTLEMENT_RATE",
            "rate": 86490000
        },
        "from": [
            {
                "fund_source": "ORDER_REFUNDABLE_BALANCE",
                "amount": 300
            },
            {
                "fund_source": "FUNDS_REFUNDABLE_BALANCE",
                "amount": 200
            }
        ]
    },
    "detail": [
        {
            "promotion_id": "11006096908",
            "scope": "GLOBAL",
            "type": "COUPON",
            "amount": 500,
            "refund_amount": 250,
            "currency": "CNY"
        }
    ]
}


{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"detail": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

4. 错误码

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

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

申请退款API

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

正常返回

异常返回

返回示例

4. 错误码