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

1. 接口说明

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

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

请求方式: GET

Path指该参数为路径参数

Query指该参数为URL参数

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

2. 请求参数

参数名	变量	类型[长度限制]	必填	描述
商户号	mchid	string[1,32]	是	Query 微信支付分配的商户号注意：仅适用于直连模式示例值：1900000109
子商户号	sub_mchid	string[1,32]	是	Query 微信支付分配的子商户号注意：仅适用于机构模式示例值：1900000109
机构商户号	sp_mchid	string[1,32]	是	Query 微信支付分配的机构商户号注意：仅适用于机构模式示例值：1900000100
微信支付订单号	transaction_id	string[1,32]	二选一	Query 微信支付订单号示例值：1217752501201407033233368018
商户订单号	out_trade_no	string[1,32]	二选一	Query 商户订单号示例值：1217752501201407033233368018
记录起始位置	offset	int	是	Query 分页功能，起始位置示例值：0
每页笔数	count	int	是	Query 分页功能，每页返回记录数，最大值限制为20 示例值：10

请求示例

微信支付订单号查单商户订单号查单


https://apihk.mch.weixin.qq.com/v3/global/refunds?transaction_id=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109


https://apihk.mch.weixin.qq.com/v3/global/refunds?out_trade_no=1217752501201407033233368018&count=10&offset=0&sp_mchid=1900000100&sub_mchid=1900000109


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


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

3. 返回参数

正常返回

参数名

变量

类型

必填

描述

微信支付交易订单号

id

string[1,32]

是

微信支付交易订单号
示例值：1217752501201407033233368018

商户号

mchid

string[1,32]

是

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

子商户号

sub_mchid

string[1,32]

是

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

机构商户号

sp_mchid

string[1,32]

是

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

商户原交易订单号

out_trade_no

string[1,64]

是

返回的原交易订单号。
示例值： 1217752501201407033233368018

订单金额

amount

object

是

原支付订单金额信息，详细说明见下文

参数名	变量	类型	必填	描述
订单金额	total	int	是	订单总金额，币种的最小单位，只能为整数，详见支付金额示例值：888
货币类型	currency	string[1,16]	否	符合 ISO 4217 标准的三位字母代码示例值：CNY
用户支付金额	payer_total	int	是	用户实际支付金额，币种的最小单位，只能为整数，详见支付金额示例值：888
支付币种	payer_currency	string[1,16]	是	符合ISO 4217标准的三位字母代码示例值：CNY

收起

退款单列表

data

array

是

返回的退款列表，详细说明见下文

参数名

变量

类型

必填

描述

微信退款单号

id

string[1,32]

是

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

商户退款单号

out_refund_no

string[1,64]

是

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

退款渠道

channel

string[1,16]

否

ORIGINAL：原路退款
BALANCE：退回到余额
OTHER_BALANCE：原账户异常退到其他余额账户
OTHER_BANKCARD：原银行卡异常退到其他银行卡
示例值：ORIGINAL

退款入账账户

recv_account

string[1,64]

否

取当前退款单的退款入账方
1）退回银行卡：
{银行名称}{卡类型}{卡尾号}
2）退回支付用户零钱:
支付用户零钱
3）退回支付用户零钱通:
支付用户零钱通
示例值：招商银行信用卡0403

退款资金来源

fund_source

string[1,30]

否

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

退款成功时间

success_time

string[1,64]

否

退款成功时间，当退款状态为退款成功时有返回。
示例值：2018-06-08T10:34:56+08:00

退款创建时间

create_time

string[1,64]

是

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

退款状态

status

string[1,16]

是

退款状态：
SUCCESS：退款成功
REFUNDCLOSE：退款关闭
PROCESSING：退款处理中
ABNORMAL：退款异常，退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往【服务商平台—>交易中心】，手动处理此笔退款
示例值：SUCCESS

退款金额

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

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

收起

订单总退款次数

total_num

int

是

订单总退款次数
示例值：0

本次返回退款单数

current_total_num

int

是

本次返回退款单数
示例值： 10

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

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": "4200000010202207280683365840",
    "sp_mchid": "999952224",
    "sub_mchid": "999968479",
    "out_trade_no": "20220724trade003",
    "amount": {
        "total": 1000,
        "currency": "CNY",
        "payer_total": 500,
        "payer_currency": "CNY"
    },
    "total_num": 2,
    "current_total_num": 2,
    "data": [
        {
            "id": "50202002642022072801898085011",
            "out_refund_no": "20220724trade003",
            "channel": "ORIGINAL",
            "status": "SUCCESS",
            "recv_account": "招商银行借记卡0416",
            "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
            "success_time": "2022-07-28T15:43:11+08:00",
            "create_time": "2022-07-28T15:42:40+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": "50202002642022072801898085012",
            "out_refund_no": "20220724trade003refund001",
            "channel": "ORIGINAL",
            "status": "SUCCESS",
            "recv_account": "招商银行借记卡0416",
            "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
            "success_time": "2022-07-28T15:44:24+08:00",
            "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": "4200000002202207282853224734",
  "sp_mchid": "999952224",
  "sub_mchid": "999968479",
  "out_trade_no": "20220724trade004",
  "amount": {
    "total": 1000,
    "currency": "CNY",
    "payer_total": 500,
    "payer_currency": "CNY"
  },
  "total_num": 1,
  "current_total_num": 1,
  "data": [{
    "id": "50201702652022072801898085013",
    "out_refund_no": "20220724trade004refund001",
    "channel": "ORIGINAL",
    "status": "SUCCESS",
    "recv_account": "招商银行借记卡0416",
    "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
    "success_time": "2022-07-28T15:52:15+08:00",
    "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. 错误码

错误码	描述	解决方案
SYSTEM_ERROR	接口返回错误	请尝试再次掉调用API。
REFUND_NOT_EXIST	退款订单查询失败	请检查订单号是否有误以及订单状态是否正确，如：未支付、已支付未退款，如果订单下没有退款单，则会返回此错误码，其他信息是不返回的
BIZERR_NEED_RETRY	无效transaction_id	请求参数错误，检查原交易号是否存在或发起支付交易接口返回失败
PARAM_ERROR	参数错误	请求参数错误，请检查参数再调用退款申请
APPID_NOT_EXIST	APPID不存在	请检查APPID是否正确
MCHID_NOT_EXIST	MchID不存在	请检查MchID是否正确
REQUIRE_POST_METHOD	请使用post方法	请检查请求参数是否通过post方法提交
SIGN_ERROR	签名错误	请检查签名参数和方法是否都符合签名算法要求

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付产品

资金类产品

其他产品

查询所有退款API

1. 接口说明

2. 请求参数

请求示例

3. 返回参数

正常返回

异常返回

返回示例

4. 错误码