创建代金券批次

更新时间:2024.10.31

商户可以通过调用此接口创建微信支付代金券批次,包括预充值&免充值代金券;创建完成后将获得代金券批次id,将可用于各个营销场景的活动投放。

接口频率:单个商户号调用频率60/min,所有商户号调用频率为1000/min

接口耗时:500ms

接口说明

支持商户:【普通商户】

请求方式:【POST】/v3/marketing/favor/coupon-stocks

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数
折叠全部参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


body  包体参数

 stock_name  必填   string(20)

【批次名称】批次名称
校验规则:
1、批次名称最多9个中文汉字
2、批次名称最多20个字母
3、批次名称中不能包含不当内容和特殊字符 _ , ; |


 comment  选填   string(60)

【批次备注】仅配置商户可见,用于自定义信息


 belong_merchant  必填   string(20)

【归属商户号】批次归属商户号
本字段暂未开放生效,但入参时请设置为当前创建代金券商户号即不会报错,暂时不支持入参其他的商户号


 available_begin_time  必填   string

【可用时间-开始时间】批次开始时间,遵循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秒。
校验规则:
1、开始时间不可早于当前时间
2、不能创建365天后开始的批次
3、批次可用时间范围最长为90天


 available_end_time  必填   string

【可用时间-结束时间】批次结束时间,遵循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秒。


 stock_use_rule  必填   object

【发放规则】批次使用规则

属性

 max_coupons  必填   integer

【发放总上限】最大发券数
校验规则:
1、发放总个数最少5个
2、发放总个数最多1000万个


 max_amount  必填   integer

【总预算】最大发券预算,当营销经费no_cash选择预充值false时,激活批次时会从制券商户的余额中扣除预算,请保证账户金额充足,单位:分
max_amount需要等于coupon_amount(面额) × max_coupons(发放总上限)


 max_amount_by_day  选填   integer

【单天预算发放上限】设置此字段,允许指定单天最大发券预算,单位:分。
校验规则:
1、不能大于总预算
2、max_amount_by_day不可以为0


 max_coupons_per_user  必填   integer

【单个用户可领个数】活动期间每个用户可领个数,当开启了自然人限领时,多个微信号同属于一个身份证时,视为同一用户。
校验规则:
1、不能大于发放总个数
2、最少为1个,最多为60个


 natural_person_limit  必填   boolean

【是否开启自然人限制】当开启了自然人限领时,多个微信号同属于一个身份证时,视为同一用户。
枚举值
true:是
false:否


 prevent_api_abuse  必填   boolean

【是否开启防刷拦截】若开启防刷拦截,当用户命中恶意、小号、机器、羊毛党、黑产等风险行为时,无法成功发放代金券。
枚举值
true:是
false:否


 pattern_info  选填   object

【代金券详情页】代金券详情页

属性

 description  必填   string(1000)

【使用说明】用于说明详细的活动规则,会展示在代金券详情页。
校验规则:最多1000个UTF8字符


 merchant_logo  选填   string(128)

【商户logo】商户logo ,仅支持通过《图片上传API》接口获取的图片URL地址。1、商户logo大小需为120像素*120像素。2、支持JPG/JPEG/PNG格式,且图片小于1M。3、最多128个UTF8字符*


 merchant_name  选填   string(12)

【品牌名称】品牌名称,展示在用户卡包
校验规则:
1、最多12个中文汉字
2、最多36个英文字符


 background_color  选填   string

【背景颜色】券的背景颜色,可设置14种颜色,色值请参考下方说明。颜色取值为颜色图中的颜色名称。可选枚举字段不用则不传,不可以传空值

可选取值:

  • COLOR010: 色值 #63b359

  • COLOR020: 色值 #2c9f67

  • COLOR030: 色值 #509fc9

  • COLOR040: 色值 #5885cf

  • COLOR050: 色值 #9062c0

  • COLOR060: 色值 #d09a45

  • COLOR070: 色值 #e4b138

  • COLOR080: 色值 #ee903c

  • COLOR081: 色值 #f08500

  • COLOR082: 色值 #a9d92d

  • COLOR090: 色值 #dd6549

  • COLOR100: 色值 #cc463d

  • COLOR101: 色值 #cf3e36

  • COLOR102: 色值 #5E6671


 coupon_image  选填   string(128)

【券详情图片】券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,仅支持通过《图片上传API》接口获取的图片URL地址。*


 jump_target  选填   string

【卡包跳转目标】枚举值:PAYMENT_CODE:跳转至微信支付付款码,点击“立即使用”跳转至微信支付付款码 MINI_PROGRAM:跳转至小程序,点击“立即使用”跳转至配置的商家小程序(需要指定小程序appid和path) DEFAULT_PAGE:跳转至默认页, 点击“立即使用”跳转至默认页面 如未传该参数,则默认跳转至默认页。

可选取值

  • PAYMENT_CODE: 点击“立即使用”跳转至微信支付付款码

  • MINI_PROGRAM: 点击“立即使用”跳转至配置的商家小程序(需要指定小程序appid和path)

  • DEFAULT_PAGE: 点击“立即使用”跳转至默认页面


 mini_program_appid  选填   string(128)

【小程序appid】跳转的小程序appid,跳转至小程序时必填。跳转的小程序appid需至少和一个可核销商户有绑定关系。


 mini_program_path  选填   string(128)

【小程序path】跳转的小程序path,跳转至小程序时必填。


 coupon_use_rule  必填   object

【核销规则】

属性

 coupon_available_time  选填   object

【券生效时间】允许指定券的特殊生效时间规则。
该字段暂未开放

属性

 fix_available_time  选填   object

【固定时间段可用】允许指定券在特殊时间段生效。当设置固定时间段可用时不可设置领取后N天有效
该字段暂未开放

属性

 available_week_day  必填   array[integer]

【可用星期数】允许指定每周固定星期数生效,0代表周日生效,1代表周一生效,以此类推。
该字段暂未开放


 begin_time  必填   integer

【当天开始时间】允许指定特殊生效星期数中的具体生效的时间段。
当天开始时间,单位:秒。
该字段暂未开放


 end_time  选填   integer

【当天结束时间】允许指定特殊生效星期数中的具体生效的时间段。
当天结束时间,单位:秒,默认为23点59分59秒。
该字段暂未开放


 second_day_available  选填   boolean

【领取第二天生效】领取后,券的开始时间为领券后第二天,如7月1日领券,那么在7月2日00:00:00开始。
当设置领取后N天有效时,不可设置固定时间段可用。
枚举值:
true:是
false:否
该字段暂未开放


 available_time_after_receive  选填   integer

【领取后有效时间】领取后,券的结束时间为领取N天后,如设置领取后7天有效,那么7月1日领券,在7月7日23:59:59失效(在可用时间内计算失效时间,若券还未到领取后N天,但是已经到了可用结束时间,那么也会过期)
领取后有效时间,单位:天。
该字段暂未开放


 fixed_normal_coupon  选填   object

【固定面额满减券使用规则】stock_type为NORMAL时必填

属性

 coupon_amount  必填   integer

【面额】面额,单位:分。


 transaction_minimum  必填   integer

【门槛】使用券金额门槛,单位:分。


 goods_tag  选填   array[string(128)]

【订单优惠标记】订单优惠标记,按json格式。
商户下单时需要传入相同的标记(goods_tag),用户同时符合其他规则才能享受优惠
校验规则:
1、最多允许录入50个
2、每个订单优惠标记支持字母/数字/下划线,不超过128个UTF8字符。


 trade_type  选填   array[string]

【指定支付模式】允许指定支付方式的交易才可核销/使用代金券,不填则默认“不限”。
枚举值:
MICROAPP:小程序支付
APPPAY:APP支付
PPAY:免密支付
CARD:刷卡支付
FACE:人脸支付
OTHER:其他支付

可选取值:

  • MICROAPP: 小程序支付

  • APPPAY: APP支付

  • PPAY: 免密支付

  • CARD: 刷卡支付

  • FACE: 人脸支付

  • OTHER: 其他支付,公众号、扫码等


 combine_use  选填   boolean

【是否可叠加其他优惠】允许指定本优惠是否可以和本商户号创建的其他券同时使用,不填则默认为:“不允许同时使用”。枚举值:true:是false:否


 available_items  选填   array[string(128)]

【可核销商品编码】包含指定SKU商品编码的交易才可核销/使用代金券:活动商户在交易下单时,需传入用户购买的所有SKU商品编码,当命中代金券中设置的商品编码时可享受优惠。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】


 unavailable_items  选填   array[string(128)]

【不参与优惠商品编码】该字段暂未开放
包含指定SKU商品编码的交易不可核销/使用代金券。
校验规则:
1、单个商品编码的字符长度为【1,128】
2、条目个数限制为【1,50】


 available_merchants  必填   array[string(20)]

【可核销商户号】可用商户的交易才可核销/使用代金券。当营销经费no_cash=false时,可用商户允许填入任何类型的特约商户或普通商户
当营销经费no_cash=true时,分为以下几种情况:
1、创建商户是普通商户或服务商特约商户(子商户):可添加本商户号或同品牌商户。
说明:若可用商户中,有特约商户(子商户),那么特约商户自己发起的交易、以及服务商帮特约商户发起的交易,都可以使用代金券。
2、创建商户是普通服务商:可添加已授权的子商户,详见《申请免充值代金券产品权限》。
说明:特约商户如果有多个服务商,那么服务商为他发起的交易,只要完成了免充值授权,都可以使用代金券;特约商户自己发起的交易不可以使用代金券。
3、创建商户是渠道商、银行服务商或从业机构:可直接添加旗下任意子商户,不需要子商户授权。
校验规则:条目个数限制为【1,50】


 limit_card  选填   object

【指定银行卡BIN】指定银行卡bin付款的交易可核销/使用代金券,当批次限定了指定银行卡时方可生效

属性

 name  必填   string(4)

【银行卡名字】当批次指定付款方式为银行卡且配置了指定银行卡BIN,该字段必填,最多4个中文字符。并将在微信支付收银台中展示给用户。


 bin  必填   array[string(13)]

【银行卡BIN】当批次指定付款方式为银行卡且配置了指定银行卡BIN,该字段必填,按json格式。
特殊规则:单个卡BIN的字符长度为【6,9】,条目个数限制为【1,10】。


 no_cash  必填   boolean

【营销经费】营销经费。
枚举值:
true:免充值
false:预充值
1、免充值:制券方无需提前充值资金,用户核销代金券时,直接从订单原价中扣除优惠减价金额,最终只将用户实际支付的金额结算给核销商户,商户实收少于订单原价。
2、预充值:制券方需将优惠预算提前充值到微信支付商户可用余额中,用户核销代金券时,系统从制券方商户可用余额中扣除优惠减价部分对应的资金,连同用户实际支付的资金,一并结算给核销商户,不影响实收。


 stock_type  必填   string(16)

【批次类型】批次类型,仅支持:
NORMAL:固定面额满减券批次


 out_request_no  必填   string(128)

【商户单据号】商户创建批次凭据号(格式:商户id+日期+流水号),可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,商户侧需保持商户单据号全局唯一。


 ext_info  选填   string(128)

【扩展属性】扩展属性字段,按json格式,如无需要则不填写。
该字段暂未开放

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/favor/coupon-stocks \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "stock_name" : "微信支付代金券批次",
8    "comment" : "零售批次",
9    "belong_merchant" : "98568865",
10    "available_begin_time" : "2015-05-20T13:29:35.120+08:00",
11    "available_end_time" : "2015-05-20T13:29:35.120+08:00",
12    "stock_use_rule" : {
13      "max_coupons" : 100,
14      "max_amount" : 5000,
15      "max_amount_by_day" : 400,
16      "max_coupons_per_user" : 3,
17      "natural_person_limit" : false,
18      "prevent_api_abuse" : false
19    },
20    "pattern_info" : {
21      "description" : "微信支付营销代金券",
22      "merchant_logo" : "CDN地址",
23      "merchant_name" : "微信支付",
24      "background_color" : "COLOR010",
25      "coupon_image" : "https://qpic.cn/xxx",
26      "jump_target" : "PAYMENT_CODE",
27      "mini_program_appid" : "wx23232232323",
28      "mini_program_path" : "/path/index/index"
29    },
30    "coupon_use_rule" : {
31      "coupon_available_time" : {
32        "fix_available_time" : {
33          "available_week_day" : [
34            1
35          ],
36          "begin_time" : 0,
37          "end_time" : 3600
38        },
39        "second_day_available" : false,
40        "available_time_after_receive" : 7
41      },
42      "fixed_normal_coupon" : {
43        "coupon_amount" : 100,
44        "transaction_minimum" : 100
45      },
46      "goods_tag" : [
47        "123321"
48      ],
49      "trade_type" : [
50        "MICROAPP"
51      ],
52      "combine_use" : false,
53      "available_items" : [
54        "123321"
55      ],
56      "unavailable_items" : [
57        "789987"
58      ],
59      "available_merchants" : [
60        "9856000"
61      ],
62      "limit_card" : {
63        "name" : "精粹白金",
64        "bin" : [
65          "62542688"
66        ]
67      }
68    },
69    "no_cash" : false,
70    "stock_type" : "NORMAL",
71    "out_request_no" : "example_out_request_no",
72    "ext_info" : "{'exinfo1':'1234','exinfo2':'3456'}"
73  }'
74

应答参数

200 OK

 stock_id  必填   string

【批次号】微信为每个代金券批次分配的唯一ID。


 create_time  必填   string

【创建时间】创建时间,遵循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秒。

应答示例

200 OK

1{
2  "stock_id" : "98065001",
3  "create_time" : "2015-05-20T13:29:35.120+08:00"
4}
5

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

APPID_MCHID_NOT_MATCH

商户号与AppID不匹配

请绑定调用接口的商户号和AppID后重试

400

INVALID_REQUEST

OpenID与AppID不匹配

请使用AppID下的OpenID

400

INVALID_REQUEST

活动已结束或未激活

请检查批次状态

400

INVALID_REQUEST

非法的商户号

请检查商户号是否正确

400

MCH_NOT_EXISTS

商户号不合法

请输入正确的商户号

400

PARAM_ERROR

回调URL不能为空

请填写回调URL

400

PARAM_ERROR

回调商户不能为空

请填写回调商户

400

PARAM_ERROR

券ID必填

请填写券ID

400

PARAM_ERROR

AppID必填

请输入AppID

400

PARAM_ERROR

OpenID必填

请输入OpenID

400

PARAM_ERROR

页大小超过阈值

请不要超过最大的页大小

400

PARAM_ERROR

输入时间格式错误

请输入正确的时间格式

400

PARAM_ERROR

批次号必填

请输入批次号

400

PARAM_ERROR

商户号必填

请输入商户号

400

PARAM_ERROR

非法的批次状态

请检查批次状态

403

NO_AUTH

你配置的信息需要开通特殊权限

请参考:QA方案

403

NOT_ENOUGH

批次预算不足

请补充预算

403

REQUEST_BLOCKED

调用商户无权限

请开通产品权限后再调用该接口

403

REQUEST_BLOCKED

商户无权发券

调用接口的商户号无权发券,请检查是否是自己的批次或是已授权的批次。

403

REQUEST_BLOCKED

批次不支持跨商户发券

该批次未做跨商户号的授权,请授权后再发放

403

REQUEST_BLOCKED

用户被限领拦截

用户领取已经达到上限,请调高上限或停止发放。

403

REQUEST_BLOCKED

活动未开始或已结束

该活动未开始或已结束

403

USER_ACCOUNT_ABNORMAL

用户非法

该用户账号异常,无法领券。商家可联系微信支付或让用户联系微信支付客服处理。

404

RESOURCE_NOT_EXISTS

批次不存在

请检查批次ID是否正确

429

FREQUENCY_LIMITED

请求过于频繁

稍后重试

 

 

元宝AI
反馈
目录
置顶