摇优惠-核销组件（通过openid发券）开发指引

更新时间：2025.08.18

1、背景介绍

为解决在摇一摇有优惠场景“由于用户在商家小程序未登录正确的领券账号，导致无法找到优惠券”和“用户领取优惠券后在商家小程序未能找到优惠券适用的商品”这两大核心问题，平台侧提供标准化核销组件，用于提升用户领券率与领取核销率。完成核销组件开发后，需对摇优惠活动重新进行测试，详细指引请参考：摇优惠活动测试指引

2、组件介绍

组件页面无需商家开发，商家根据规范在用户用券场景调起核销组件，串接可用单品。

3、如何开通商家券核销组件权限

需联系贵司对接的微信支付行业运营负责人申请。

4、系统版本要求

开发者可通过调用wx.openBusinessView方式在商户小程序中打开商家券核销组件，引导用户核销商家券。

接口兼容：微信 >= 8.0.30&小程序版本库 >= 2.28.1，低版本需提示用户升级到最新的微信版本。

5、接入流程

step1、从摇一摇领券事件回调通知获取用户openid

1、创建商家券接口中设置notify_config.notify_appid，领券事件回调通知接口会按照此appid设置openid。

2、对领券事件回调通知的resource.ciphertext进行解密，得到的资源对象示例（见第 6 行，解密后获取领券用户 openid）。

1{   
2    "event_type":"EVENT_TYPE_BUSICOUPON_SEND",
3    "coupon_code":"1227944959000000911017",
4    "stock_id":"1286950000000039",
5    "send_time":"2019-12-17T10:35:53+08:00",
6    "openid":"odXnH1CJjeQoWTld48db-pnxs-Wg",
7    "unionid":"oOuyajgxj0oVwjocSoQm6mp7PGKw",
8    "send_channel":"BUSICOUPON_SEND_CHANNEL_SHAKE", 
9    "send_merchant":"98568888",
10    "act_id":"1234",
11    "attach_info":""
12}

step2、判断用户登录账号状态

注意

目前从微信卡包页面点击微信卡券的“立即使用”跳转不会携带核销组件的couponCode、stockId、action参数，商户只有接入核销组件且从摇一摇会场“去小程序使用”跳转才会携带核销组件的参数，商户侧需要做兼容处理。

示例

1# 示例：如以下所示路径，是微信跳转商家小程序落地页的完整路径
2# 其中`pages/takefood/index?somequery=$somequery`是商家小程序落地页的路径，由商家侧提供
3# 而`&couponCode=$couponCode&stockId=$stockId&action=wxpayCouponUse&accountType=accountTypeOpenid`由微信侧拼接而成
4
5pages/takefood/index?somequery=$somequery&couponCode=$couponCode&stockId=$stockId&action=wxpayCouponUse&accountType=accountTypeOpenid

核销组件接口调用请参考摇一摇有优惠核销组件API，「摇一摇有优惠」跳转商家小程序的路径query会增加以下属性

属性	类型	说明
couponCode	string	券的唯一标识
stockId	string	批次号
action	string	操作标识，当前为固定值wxpayCouponUse `wxpayCouponUse`：商家券核销操作标识
accountType	string	领券用户类型标识，当前为固定值accountTypeOpenid `accountTypeOpenid`：标识用户领券至openid，身份验证需要按照openid的流程进行处理

商家侧操作说明：

参数校验：从路径 query 参数获取 couponCode（券的唯一标识)
身份验证：
1. 商家使用 couponCode 和 stockId 匹配用户领券openid。
2. 通过商家服务端接口获得当前用户小程序登陆openid。
3. 比对领券 openid 和登录 openid 的一致性，按照协议设置 authState(用户账户登录状态，见本文档5.3 商家调起商家券组件接口说明，extraData 参数 authState 的说明 )

step3、商家调起核销组件接口

开发者可通过调用 wx.openBusinessView 方式在本小程序打开商家券核销组件，引导用户核销商家券。

接口名称：wx.openBusinessView

接口兼容：微信 >= 8.0.30&小程序版本库 >= 2.28.1，低版本需提示用户升级到最新的微信版本。

接口参数

属性	类型	必填	说明
businessType	string	是	固定配置：wxpayCouponUse
extraData	object	是	用于向组件传递商家券信息

extraData参数

属性	类型	必填	说明
couponCode	string	是	券的唯一标识商品详情页跳转商家小程序的路径query会增加该属性，开发者可通过小程序页面query参数获取此值。
stockId	string	是	批次号商品详情页跳转商家小程序的路径query会增加该属性，开发者可通过小程序页面query参数获取此值。
authState	string	是	用户登录账号的状态（通过step2、判断用户登录账号状态）用户正确登录账号：verified 用户登录错误账号：invalidCredentials 用户未登录/注册：unauthenticated

success回调结果参数

属性	类型	必填	说明
extraData	object	是	用于向组件传递商家券信息

extraData参数

属性	类型	必填	参数说明	基于用户动作的商家操作指引
action	string	否	用户动作 selectProduct: 选择商品 auth: 注册/登录 closePage: 关闭页面 switchAccount: 更换登录账号 selectGlobalCoupon: 选择全场券	selectProduct（根据返回的productPath跳转至对应商品详情页） auth（拉起商家小程序微信账号登录流程（由商家自定义页面跳转路径） switchAccount（拉起商家小程序切换账号登录流程（由商家自定义页面跳转路径） selectGlobalCoupon（跳转商家货架选品页面（由商家自定义页面跳转路径）） closePage（无需操作）
productPath	string	否	用户选择的商品路径：当用户选择商品，会在success回调返回商品路径，由开发者自行跳转
errMsg	string	否	错误信息

调用示例

1if (wx.openBusinessView && checkVersion()) {
2//checkVersion版本检查：微信>=8.0.30&小程序版本库 >= 2.28.1
3  wx.openBusinessView({
4    businessType: 'wxpayCouponUse',
5    extraData: {
6      couponCode: '1227944959000000911017', // 从query获取
7      stockId: '1286950000000039',   // 从query获取
8      authState: 'verified' // 见本文档 step2、判断用户登录账号状态
9    },
10    success(e) {
11        console.log(e.extraData.action); // 用户动作
12        console.log(e.extraData.productPath); // 用户选择的商品路径
13      // dosomething
14    },
15    fail() {
16      // dosomething
17    },
18    complete() {
19      // dosomething
20    }
21  });
22} else {
23  // 引导用户升级微信版本
24}

文档是否有帮助

更多支持

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