微信支付

2023-09-09 14:13| 来源: 网络整理| 查看: 265

返回上一层文档首页 / 创建商家券API 创建商家券API

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

商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户，商户可调用发券接口【小程序发券】、【H5发券】发放该批次商家券。

接口说明

适用对象：直连商户

请求URL：https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks

请求方式：POST

频率限制：IP级限制15/s，接口级限制1000/min

path 指该参数为路径参数

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

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

请求参数参数名变量类型[长度限制] 必填描述商家券批次名称 stock_name string[1,21] 是 body 批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。示例值：8月1日活动券批次归属商户号 belong_merchant string[8,15] 是 body 批次归属于哪个商户。注：普通直连模式，该参数为直连商户号示例值：10000022 批次备注 comment string[1,20] 否 body 仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。示例值：活动使用适用商品范围 goods_name string[1,15] 是 body 用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。示例值：xxx商品使用批次类型 stock_type string[1,32] 是 body 批次类型 NORMAL：固定面额满减券批次 DISCOUNT：折扣券批次 EXCHANGE：换购券批次示例值：NORMAL +核销规则 coupon_use_rule object 是 body 券核销相关规则参数名变量类型[长度限制] 必填描述 +券可核销时间 coupon_available_time object 是日期区间内可以使用优惠。参数名变量类型[长度限制] 必填描述开始时间 available_begin_time string[1,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秒。注意：商家券有效期最长为1年。示例值：2015-05-20T13:29:35+08:00 结束时间 available_end_time string[1,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秒。注意：商家券有效期最长为1年。示例值：2015-05-20T13:29:35+08:00 生效后N天内有效 available_day_after_receive int 否日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推。注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。示例值：3 + 固定周期有效时间段 available_week object 否可以设置多个星期下的多个可用时间段，比如每周二10点到18点，用户自定义字段。参数名变量类型[长度限制] 必填描述可用星期数 week_day array[int] 条件选填 0代表周日，1代表周一，以此类推当填写available_day_time时，week_day必填示例值：1, 2 + 当天可用时间段 available_day_time array 否可以填写多个时间段，最多不超过2个。参数名变量类型[长度限制] 必填描述当天可用开始时间 begin_time int 否当天可用开始时间，单位：秒，1代表当天0点0分1秒。示例值：3600 当天可用结束时间 end_time int 否当天可用结束时间，单位：秒，86399代表当天23点59分59秒。示例值：86399 + 无规律的有效时间段 irregulary_avaliable_time array 否无规律的有效时间，多个无规律时间段，用户自定义字段。参数名变量类型[长度限制] 必填描述开始时间 begin_time string[1,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秒。示例值：2015-05-20T13:29:35+08:00 结束时间 end_time string[1,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秒。示例值：2015-05-20T13:29:35+08:00 领取后N天开始生效 wait_days_after_receive int 否日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推。用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。注：最大不能超过30天示例值：7 +固定面额满减券使用规则 fixed_normal_coupon object 三选一 stock_type为NORMAL时必填。参数名变量类型[长度限制] 必填描述优惠金额 discount_amount int 是优惠金额，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：5 消费门槛 transaction_minimum int 是消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100 +折扣券使用规则 discount_coupon object stock_type为DISCOUNT时必填。参数名变量类型[长度限制] 必填描述折扣比例 discount_percent int 是折扣百分比，例如：86为八六折。示例值：86 消费门槛 transaction_minimum int 是消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100 +换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。参数名变量类型[长度限制] 必填描述单品换购价 exchange_price int 是单品换购价，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100 消费门槛 transaction_minimum int 是消费门槛，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100 核销方式 use_method string[1,128] 是枚举值： OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。 MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。 PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。 SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。示例值：OFF_LINE 小程序appid mini_programs_appid string[1,32] 条件选填核销方式为线上小程序核销才有效。示例值：wx23232232323 小程序path mini_programs_path string[1,128] 条件选填核销方式为线上小程序核销才有效。示例值：/path/index/index +发放规则 stock_send_rule object 是 body 券发放相关规则参数名变量类型[长度限制] 必填描述批次最大发放个数 max_coupons int 是批次最大可发放个数限制特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100 用户最大可领个数 max_coupons_per_user int 是用户可领个数，每个用户最多100张券。示例值：5 单天发放上限个数 max_coupons_by_day int 否单天发放上限个数（stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限）。特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100 是否开启自然人限制 natural_person_limit bool 否不填默认否，枚举值： true：是 false：否注：自然人防刷即同证件号下的所有账户合并计算的限领次数（限领次数指的是参数字段“用户最大领取个数”填写的值）示例值：false 可疑账号拦截 prevent_api_abuse bool 否不填默认否，枚举值： true：是 false：否如：黑灰产账号示例值：false 是否允许转赠 transferable bool 否不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false 是否允许分享链接 shareable bool 否不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false 商户请求单号 out_request_no string[1,128] 是 body 商户创建批次凭据号（格式：商户id+日期+流水号），商户侧需保持唯一性。示例值：100002322019090134234sfdf +自定义入口 custom_entrance object 否 body 卡详情页面，可选择多种入口引导用户。参数名变量类型[长度限制] 必填描述 +小程序入口 mini_programs_info object 否需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。 appid要与归属商户号有M-A or M-m-suba关系。注：请查看绑定关系说明文档参数名变量类型[长度限制] 必填描述商家小程序appid mini_programs_appid string[1,32] 是商家小程序appid要与归属商户号有M-A or M-m-suba关系。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID 或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx234545656765876 商家小程序path mini_programs_path string[1,128] 是商家小程序path 示例值：/path/index/index 入口文案 entrance_words string[1,5] 是入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购引导文案 guiding_words string[1,6] 否小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠商户公众号appid appid string[1,32] 否可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID 或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx324345hgfhfghfg 营销馆id hall_id string[1,64] 否填写微信支付营销馆的馆id，用户自定义字段。营销馆需在商户平台创建。示例值：233455656 可用门店id store_id string[1,64] 否填写代金券可用门店id，用户自定义字段。示例值：233554655 code展示模式 code_display_mode string[1,8] 否枚举值： NOT_SHOW：不展示code BARCODE：一维码 QRCODE：二维码示例值：BARCODE +样式信息 display_pattern_info object 否 body 创建批次时的样式信息。参数名变量类型[长度限制] 必填描述使用须知 description string[1,1000] 否用于说明详细的活动规则，会展示在代金券详情页。示例值：xxx门店可用商户logo merchant_logo_url string[1,128] 否若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。商户logo的URL地址，仅支持通过《图片上传API》接口获取的图片URL地址。 1、商户logo大小需为120像素*120像素。 2、支持JPG/JPEG/PNG格式，且图片小于1M。示例值：https://qpic.cn/xxx 商户名称 merchant_name string[1,16] 否不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。示例值：微信支付背景颜色 background_color string[1,16] 否券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。示例值：Color020 券详情图片 coupon_image_url string[1,128] 否券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://qpic.cn/xxx + 视频号相关信息 finder_info object 否视频号相关信息参数名变量类型[长度限制] 必填描述视频号ID finder_id string[1,32] 是关联视频号将展示在优惠券详情的顶部右侧，作为跳转去视频号的入口，请求参数请配置视频号ID，请前往视频号助手管理查看视频号ID 示例值：sph6Rngt2T4RlUf 视频号视频ID finder_video_id string[1,256] 是券详情视频内容，支持配置关联视频号下的具体视频内容，请求参数请配置视频ID，请前往视频号助手管理后台复制具体视频ID 示例值：export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94 视频号封面图 finder_video_cover_image_url string[1,256] 是截取的视频号图片将在券到期提醒消息、券详情中展示。 1.图片尺寸：1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。 2.仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://wxpaylogo.qpic.cn/xxx 券code模式 coupon_code_mode string[1,128] 是 body 枚举值： WECHATPAY_MODE：系统分配券code。（固定22位纯数字） MERCHANT_API：商户发放时接口指定券code。 MERCHANT_UPLOAD：商户上传自定义code，发券时系统随机选取上传的券code。特殊规则： 1、券code模式为WECHATPAY_MODE时，是微信自动分配券code，商户不需要预存code；适用于多种场景 2、券code模式为MERCHANT_API时，无需调用上传预存code接口，调用发券接口时需指定券code；更多用在商家自有流量场景（例如：商家自有小程序、H5网页等） 3、券code模式为MERCHANT_UPLOAD，需要调用上传预存code接口上传code，调用发券接口时无需指定code；更多适用在微信支付平台流量场景（例如：支付有礼、支付有优惠等）示例值：WECHATPAY_MODE +事件通知配置 notify_config object 否 body 事件回调通知商户的配置。参数名变量类型[长度限制] 必填描述事件通知appid notify_appid string[1,64] 否用于回调通知时，计算返回操作用户的openid（诸如领券用户），支持小程序or公众号的APPID；如该字段不填写，则回调通知中涉及到用户身份信息的openid与unionid都将为空。示例值：wx23232232323 是否允许营销补贴 subsidy bool 否 body 该批次发放的券是否允许进行补差，默认为false 示例值：false

卡券背景颜色图

商家券样式图

券详情信息展示

请求示例 JSON { "stock_name":"8月1日活动券", "belong_merchant":"10000098", "comment": "活动使用", "goods_name": "XXX商品使用", "stock_type": "NORMAL", "coupon_use_rule": { "coupon_available_time": { "available_begin_time": "2015-05-20T13:29:35+08:00", "available_end_time": "2015-05-20T13:29:35+08:00", "available_day_after_receive": 3, "wait_days_after_receive":7, "available_week": { "week_day": [ 1, 2 ], "available_day_time": [ { "begin_time": 3600, "end_time": 86399 } ] }, "irregulary_avaliable_time": [ { "begin_time": "2015-05-20T13:29:35+08:00", "end_time": "2015-05-20T13:29:35+08:00" } ] }, "fixed_normal_coupon": { "discount_amount": 5, "transaction_minimum": 100 }, "use_method": "OFF_LINE", "mini_programs_appid":"wx23232232323", "mini_programs_path":"/path/index/index" }, "stock_send_rule": { "max_coupons": 100, "max_coupons_per_user": 5, "max_coupons_by_day": 100, "natural_person_limit": false, "prevent_api_abuse": false, "transferable": false, "shareable": false }, "out_request_no": "100002322019090134234sfdf", "custom_entrance": { "mini_programs_info": { "mini_programs_appid": "wx234545656765876", "mini_programs_path": "/path/index/index", "entrance_words": "欢迎选购", "guiding_words": "获取更多优惠" }, "appid": "wx324345hgfhfghfg", "hall_id": "233455656", "store_id": "233554655" }, "display_pattern_info": { "description": "xxx门店可用", "merchant_logo_url": "https://xxx", "merchant_name": "微信支付", "background_color": "Color020", "coupon_image_url": "https://qpic.cn/xxx", "finder_info": { "finder_id": "sph6Rngt2T4RlUf", "finder_video_cover_image_url": "https://wxpaylogo.qpic.cn/xxx", "finder_video_id": "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94" } }, "coupon_code_mode": "WECHATPAY_MODE" } ｛ JAVA示例代码｝返回参数参数名变量类型[长度限制] 必填描述批次号 stock_id string[1,20] 是微信为每个商家券批次分配的唯一ID。示例值：98065001 创建时间 create_time string[1,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秒。示例值：2015-05-20T13:29:35+08:00 返回示例正常示例 { "stock_id": "98065001", "create_time": "2015-05-20T13:29:35+08:00" } http://2323weixin.qq.com 跳转小程序带参数说明

如果商家券配置了跳转小程序的入口（包括立即使用以及自定义入口），跳转链接会带有批次号、openid以及加密的code，解密方式可参考解密说明。

/path/index/index.html?stock_id=128695000000007&openid=o7tgX0RiTlJo9IXVVfemjFSlFMo4&nonce=B9Jr9gtzMSs7&associate=COUPON_CODE&ciphertext=nmARA5zbjlL%2FaCiKN7S3h1z%2FGhmCfNW9IGQHX6XqTR3zYzQ43sQ%3D 解密说明

通过以下步骤，可对加密的数据进行解密：

1、用商户平台上设置的APIv3密钥【微信商户平台—>账户设置—>API安全—>设置APIv3密钥】，记为key。 2、从跳转路径中取得参数nonce、associate和密文ciphertext； 3、使用urldecode对ciphertext进行解码，得到strUrlDecodeText； 4、使用base64对strUrlDecodeText进行解码，得到strBase64DecodeText； 5、使用key、nonce和associate，对数据密文strBase64DecodeText进行解密，得到的字符串即为coupon_code。

注： AEAD_AES_256_GCM算法的接口细节，请参考rfc5116。微信支付使用的密钥key长度为32个字节，随机串nonce长度12个字节，associated当前为固定值"COUPON_CODE"。

错误码公共错误码状态码错误码描述解决方案 400 PARAM_ERROR 参数错误查看具体错误信息，调整参数 400 SYSTEM_ERROR 系统错误请使用相同参数稍后重新调用 400 RESOURCE_ALREADY_EXISTS 批次已存在查看out_request_no字段是否重复使用券已被其他订单核销请通过查询券API确认券是否已被其他订单核销 404 RESOURCE_NOT_EXISTS 查询的资源不存在请检查查询资源的对应id是否填写正确 403 NOAUTH 无权限查看具体错误信息，确认是否有权限 400 APPID_MCHID_NOT_MATCH appid与请求方商户无关联关系 appid与请求方商户不匹配，请确认appid与请求方商户是否有关联关系 400 MCH_NOT_EXISTS 商户号不存在请确认传入的商户号是否正确 404 USER_NOT_EXISTS openid不正确请确认传入的openid是否正确 500 SYSTEM_ERROR 系统失败多为网络超时引起，重试 429 FREQUENCY_LIMITED 频率限制调用太频繁，请降低调用接口频率 403 RULELIMIT 券不在有效期请确认券是否能在当前时间核销 400 INVALID_REQUEST 发券模式不合法请更换支持预上传code的批次后重试上传的自定义code已达上限请更换一个新的批次后重试

【本文地址】

公司简介

联系我们