微信支付-开发者文档

返回上一层文档首页 / 请求补差API

请求补差API

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

服务商下单的时候带上补差标识，微信订单支付成功并结算完成后，发起分账前，调用该口进行补差。

注意：

• 电商平台下单时传入补差金额，详见【合单下单API】文档中补差字段说明。

• 在发起分账前，调用该接口进行补差。

• 补差金额需要和下单的时候传入的补差金额保持一致(发生用户退款时可以小于下单时的补差金额，须有对应的微信退款单号，任意一笔该订单的微信退款单)。

• 该接口支持重入，请求参数相同只会扣款一次，重入有效期180天。

• 系统异常（如返回SYSTEM_ERROR），请使用相同参数稍后重新调用，请务必用原参数来重入此接口，如更换金额重试，可能会导致重复扣款，系统会在1天后回退到原账户。

接口频率：

• 单个发起方（请求补差）80QPS。

• 单个分账方（请求补差）100QPS。

接口说明

适用对象：电商平台

请求URL：https://api.mch.weixin.qq.com/v3/ecommerce/subsidies/create

请求方式：POST

path指该参数为路径参数

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

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

请求参数

参数名	变量	类型[长度限制]	必填	描述
二级商户号	sub_mchid	string[1,32]	是	body 补差的电商平台二级商户，填写微信支付分配的商户号。示例值：1900000109
微信订单号	transaction_id	string[1,64]	是	body 微信支付订单号。示例值： 4208450740201411110007820472
补差金额	amount	int	是	body 补差金额，单位为分，只能为整数，不能超过下单时候的最大补差金额。注意：单笔订单最高补差金额为5000元示例值：10
补差描述	description	string[1,80]	是	body 补差备注描述，查询的时候原样带回。示例值：测试备注
微信退款单号	refund_id	string[1,64]	否	body 微信退款单号，微信支付系统退款返回的唯一标识，当补差金额小于下单时候的金额，该字段必填示例值：3008450740201411110007820472

请求示例

JSON


{
  "sub_mchid": "1900000109",
  "transaction_id": "4208450740201411110007820472",
  "amount": 10,
  "description": "测试备注",
  "refund_id": "3008450740201411110007820472"
}

    
｛
JAVA示例代码
｝

返回参数

参数名	变量	类型[长度限制]	必填	描述
二级商户号	sub_mchid	string[1,32]	是	补差的电商平台二级商户，填写微信支付分配的商户号。示例值：1900000109
微信订单号	transaction_id	string[1,64]	是	微信支付订单号。示例值： 4208450740201411110007820472
微信补差单号	subsidy_id	string[1,64]	是	微信补差单号，微信支付系统返回的唯一标识。示例值： 3008450740201411110007820472
补差描述	description	string[1,80]	是	补差描述示例值：满减补差活动
补差金额	amount	int	是	补差金额示例值：10
补差单结果	result	string[1,16]	是	补差单状态，枚举值： SUCCESS：补差成功 FAIL：补差失败 REFUND：已全额回退示例值：SUCCESS
补差完成时间	success_time	string[1,32]	是	补贴完成时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss:sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss:sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。示例值： 2015-05-20T13:29:35.120+08:00

返回示例

正常示例


{
  "sub_mchid": "1900000109",
  "transaction_id": "4208450740201411110007820472",
  "subsidy_id": "3008450740201411110007820472",
  "description": "满减补差活动",
  "amount": 10,
  "result": "PROCESSING",
  "success_time": "2015-05-20T13:29:35.120+08:00"
}


    http://2323weixin.qq.com

错误码公共错误码

状态码	错误码	描述	解决方案
500	SYSTEM_ERROR	系统错误	系统异常，请使用相同参数稍后重新调用
400	PARAM_ERROR	参数错误	请使用正确的参数重新调用
400	INVALID_REQUEST	参数错误	请使用正确的参数重新调用
429	FREQUENCY_LIMITED	频率限制	请降低频率后重试

微信支付商户平台