商家券营销补差回退

更新时间：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 商户侧需保证唯一性，需要与商家券回退的out_request_no保持对应一致。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号示例值：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]	是	补差付款单据状态 RETURN_RECEIPT_ACCEPTED：补差回退已受理 RETURN_RECEIPT_SUCCESS：补差回退成功 RETURN_RECEIPT_FAIL：补差回退失败示例值：RETURN_RECEIPT_SUCCESS
补差回退失败原因	fail_reason	string[1, 64]	否	仅在补差回退失败时，返回告知对应失败的原因 RETURN_RECEIPT_INSUFFICIENT_BALANCE：扣款商户余额不足 RETURN_RECEIPT_OTHER：其他原因示例值：RETURN_RECEIPT_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-06-15T19:35:11+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-06-15T19:35:11+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": "RETURN_RECEIPT_SUCCESS",
12  "return_done_time": "2021-06-15T19:35:11+08:00",
13  "subsidy_receipt_id": "1120200119165100000000000001",
14  "out_subsidy_return_no": "subsidy-abcd-12345678",
15  "return_create_time": "2021-06-15T19:35:11+08:00"
16}

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	查看具体错误信息，调整参数
500	SYSTEM_ERROR	系统错误	多为网络超时引起，请使用相同参数稍后重新调用
401	SIGN_ERROR	签名验证失败	请检查签名参数和方法是否都符合签名算法要求
429	FREQUENCY_LIMITED	频率限制	调用太频繁，请降低调用接口频率
404	RESOURCE_NOT_EXISTS	券不存在	请检查批次id和券Code是否填写正确
404	REFUND_NOT_EXISTS	退款单不存在或状态未完成	请检查微信支付退款单号是否填写正确，微信支付退款单号与支付订单是否对应，退款状态是否已完成
403	RULELIMIT	补差回退金额超出上限	补差回退金额不得超过补差金额
		资金付款或收款商户号非原商家券补差付款收款商户号，不支持回退补差	请更换出、入款方为原补差发起的出入款方后重试
		券已被其他微信支付退款单补差回退	该笔退款单已完成补差回退，不可以再发起补差回退
		补差回退时券状态需为可用态	券当前未被回退，请核实
		券类型不合法	当前仅支持满减券类型进行补差
		券回退明细查询为空	券回退明细查询为空，需先进行券回退操作才能发起补差回退
		付款商户号可用余额不足付款，请充值后重试	补差回退的出款商户号（原入账方商户号）余额不足，请充值后重试

文档是否有帮助

更多支持

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