营销补差回退

更新时间：2026.01.12

商户通过该接口可回退补差款

接口说明

适用对象：直连商户

请求URL：https://api.mch.weixin.qq.com/v3/marketing/busifavor/subsidy/return-receipts

请求方式：POST

前置条件：进行补差的微信支付订单发起了退款，且回退金额不得超过补差金额

是否支持幂等：是

path 指该参数为路径参数

query 指该参数为URL参数

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

请求参数

参数名	变量	类型[长度限制]	必填	描述
商家券批次号	stock_id	string[1, 20]	是	body 由微信支付生成，调用创建商家券API成功时返回的唯一批次ID 仅支持“满减券”和“折扣券”的批次，“换购券”批次不支持示例值：128888000000001
商家券Code	coupon_code	string[1, 128]	是	body 券的唯一标识。在WECHATPAY_MODE的券Code模式下，商家券Code是由微信支付生成的唯一ID；在MERCHANT_UPLOAD、MERCHANT_API的券Code模式下，商家券Code是由商户上传或指定，在批次下保证唯一；示例值：ABCD12345678
微信支付订单号	transaction_id	string[28, 32]	是	body 微信支付下单支付成功返回的订单号示例值：4200000913202101152566792388
微信支付退款单号	refund_id	string[28, 32]	是	body 微信支付退款单号示例值：50100506732021010105138718375
原营销补差扣款商户号	payer_merchant	string[1, 32]	是	body 原营销补差扣款商户号，即回退资金收款商户号示例值：1900000001
原营销补差入账商户号	payee_merchant	string[1, 32]	是	body 原营销补差入账商户号，即回退资金扣款商户号示例值：1900000002
补差回退金额	amount	int	是	body 本次补差回退金额，单位为分。单个券Code回退总金额不能超过补差金额示例值：100
补差回退描述	description	string[1, 1024]	是	body 回退备注描述，查询的时候原样带回示例值：20210115DESCRIPTION
业务请求唯一单号	out_subsidy_return_no	string[1, 128]	是	body 商户侧需保证唯一性。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号示例值：subsidy-abcd-12345678

请求示例

1{
2  "stock_id": "128888000000001",
3  "coupon_code": "ABCD12345678",
4  "transaction_id": "4200000913202101152566792388",
5  "refund_id": "50100506732021010105138718375",
6  "payer_merchant": "1900000001",
7  "payee_merchant": "1900000002",
8  "amount": 100,
9  "description": "20210115DESCRIPTION",
10  "out_subsidy_return_no": "subsidy-abcd-12345678"
11}

返回参数

参数名	变量	类型[长度限制]	必填	描述
补差回退单号	subsidy_return_receipt_id	string[28, 32]	否	补差回退唯一单号，由微信支付生成，仅在补差回退成功后有返回示例值：2120200119165100000000000001
商家券批次号	stock_id	string[1, 20]	是	由微信支付生成，调用创建商家券API成功时返回的唯一批次ID 示例值：128888000000001
商家券Code	coupon_code	string[1, 128]	是	券的唯一标识示例值：ABCD12345678
微信支付订单号	transaction_id	string[28, 32]	是	微信支付下单支付成功返回的订单号示例值：4200000913202101152566792388
微信支付退款单号	refund_id	string[28, 32]	是	微信支付退款单号示例值：50100506732021010105138718375
原营销补差扣款商户号	payer_merchant	string[1, 32]	是	原营销补差扣款商户号，即回退资金收款商户号示例值：1900000001
原营销补差入账商户号	payee_merchant	string[1, 32]	是	原营销补差入账商户号，即回退资金扣款商户号示例值：1900000002
补差回退金额	amount	int	是	本次补差回退金额，单位为分。单个券Code回退总金额不能超过补差金额示例值：100
补差回退描述	description	string[1, 1024]	是	回退备注描述，查询的时候原样带回示例值：20210115DESCRIPTION
补差回退单据状态	status	string[1, 32]	是	补差付款单据状态 SUCCESS：补差回退成功 FAIL：补差回退失败示例值：SUCCESS
补差回退失败原因	fail_reason	string[1, 1024]	否	仅在补差回退失败时，返回告知对应失败的原因 INSUFFICIENT_BALANCE：扣款商户余额不足 RISK_BLOCK：商户风控拦截 OTHER：其他原因示例值：INSUFFICIENT_BALANCE
补差回退完成时间	return_done_time	string[28, 32]	否	仅在补差回退成功时，返回完成时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日， T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2021-01-20T10:29:35+08:00
补差付款单号	subsidy_receipt_id	string[28, 32]	是	此次补差回退操作对应的补差付款单号示例值：1120200119165100000000000001
业务请求唯一单号	out_subsidy_return_no	string[1, 128]	是	商户侧需保证唯一性。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号示例值：subsidy-abcd-12345678
补差回退发起时间	return_create_time	string[28, 32]	否	补差回退单据创建时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日， T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2021-01-20T10:29:35+08:00

返回示例

1{
2  "subsidy_return_receipt_id": "2120200119165100000000000001",
3  "stock_id": "128888000000001",
4  "coupon_code": "ABCD12345678",
5  "transaction_id": "4200000913202101152566792388",
6  "refund_id": "50100506732021010105138718375",
7  "payer_merchant": "1900000001",
8  "payee_merchant": "1900000002",
9  "amount": 100,
10  "description": "20210115DESCRIPTION",
11  "status": "SUCCESS",
12  "return_done_time": "2021-01-20T10:29:35.120+08:00",
13  "subsidy_receipt_id": "1120200119165100000000000001",
14  "out_subsidy_return_no": "subsidy-abcd-12345678",
15  "return_create_time": "2021-01-20T10:29:35.120+08:00"
16}

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	查看具体错误信息，调整参数
500	SYSTEM_ERROR	系统错误	多为网络超时引起，请使用相同参数稍后重新调用
401	SIGN_ERROR	签名验证失败	请检查签名参数和方法是否都符合签名算法要求
429	FREQUENCY_LIMITED	频率限制	调用太频繁，请降低调用接口频率
404	RESOURCE_NOT_EXISTS	券不存在	请检查批次id和券Code是否填写正确

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服