---
url: "https://pay.weixin.qq.com/doc/brand/4016105616.md"
title: "小程序核销组件开发指引"
doc_id: 4016105616
---

>更新时间：2026.04.02

### 1、背景介绍

为解决在摇一摇有优惠场景“由于用户在商家小程序未登录正确的领券账号，导致无法找到优惠券”和“用户领取优惠券后在商家小程序未能找到优惠券适用的商品”这两大核心问题，平台侧提供标准化核销组件，用于提升用户领券率与领取核销率。完成核销组件开发后，需对摇优惠活动重新进行测试，详细指引请参考：[品牌经营平台管理活动](https://pay.weixin.qq.com/doc/brand/4016080826.md#5%E3%80%81%E6%B4%BB%E5%8A%A8%E6%B5%8B%E8%AF%95)。

### 2、组件介绍

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

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/b0af17b1207b3d9b86b4ee0961353048.png)

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

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

### 4、系统版本要求

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

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

### 5、 接入流程

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

1、[创建商品券](https://pay.weixin.qq.com/doc/brand/4015736297.md)接口中设置notify\_config.notify\_appid，[领券事件回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)接口会按照此appid设置openid。

2、对[领券事件回调通知](https://pay.weixin.qq.com/doc/brand/4015755761.md)的resource.ciphertext进行解密，得到的资源对象示例（见第 6 行，解密后获取领券用户 openid）。

```
{
	"coupon_code": "1227944959000000911017",
	"product_coupon_id": "1000932014",
	"stock_id": "1000932014001",
	"appid": "wx233544546545989",
	"openid": "oh-394z-6CGkNoJrsDLTTUKiAnp4",
    "unionid": "oOuyajgxj0oVwjocSoQm6mp7PGKw",
	"receive_time": "2025-05-20T13:29:35.120+08:00",
	"send_request_no": "SEND120395730984",
	"send_channel": "API",
    "phone_number": "13212345678",
	"country_code": "86",
	"attach": "brand_custom_attach"
}
```

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

注意

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

示例

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

pages/takefood/index?somequery=$somequery&couponCode=$couponCode&stockId=$stockId&action=wxpayCouponUse&accountType=accountTypeOpenid
```

核销组件接口调用请参考[摇一摇有优惠核销组件API](https://pay.weixin.qq.com/doc/brand/4016104850.md)，「摇一摇有优惠」跳转商家小程序的路径query会增加以下属性

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

商家侧操作说明：

1. 参数校验：从路径 query 参数获取 couponCode（券的唯一标识)

2. 身份验证：

   1. 商家使用 couponCode 和 stockId 匹配用户领券openid。

   2. 通过商家服务端接口获得当前用户[小程序登陆](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html)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 | 是 | 券的唯一标识<br>商品详情页跳转商家小程序的路径query会增加该属性，开发者可通过小程序页面query参数获取此值。 |
| stockId | string | 是 | 批次号<br>商品详情页跳转商家小程序的路径query会增加该属性，开发者可通过小程序页面query参数获取此值。 |
| authState | string | 是 | 用户登录账号的状态（通过step2、判断用户登录账号状态）<br>用户正确登录账号：verified<br>用户登录错误账号：invalidCredentials<br>用户未登录/注册：unauthenticated |

success回调结果参数

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

extraData参数

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

调用示例

```
if (wx.openBusinessView && checkVersion()) {
//checkVersion版本检查：微信>=8.0.30&小程序版本库 >= 2.28.1
  wx.openBusinessView({
    businessType: 'wxpayCouponUse',
    extraData: {
      couponCode: '1227944959000000911017', // 从query获取
      stockId: '1286950000000039',   // 从query获取
      authState: 'verified' // 见本文档 step2、判断用户登录账号状态
    },
    success(e) {
        console.log(e.extraData.action); // 用户动作
        console.log(e.extraData.productPath); // 用户选择的商品路径
      // dosomething
    },
    fail() {
      // dosomething
    },
    complete() {
      // dosomething
    }
  });
} else {
  // 引导用户升级微信版本
}
```