## 目录

1.小程序内领取卡券

2.小程序内查看卡券

3.小程序开卡组件

4.卡券内跳转小程序

## 小程序内领取卡券

### 场景介绍

商家在小程序内进行营销活动时，可以将卡券作为奖品、优惠兑换凭证发放给用户，用户领取到卡包后可以快捷地出示使用并进行核销。

同时，某些票务类的小程序也可以将用户购买后的票券供用户添加至卡包，方便用户出示使用。

### 步骤

1. 开发者须有一个有卡券权限的服务号和认证后的小程序账号；
2. 开发者须申请一个开放平台账号，并将小程序和服务号绑定在同一个开放平台账号下，关于开放平台的介绍请参照：[微信开放平台](https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&lang=zh_CN)；
3. 阅读[卡券接口说明](WeChat_Coupon_Interface)和[创建卡券接口](Create_a_Coupon_Voucher_or_Card)，创建卡券并获得card_id；
4. 在小程序内调用[wx.addcard](Create_a_Coupon_Voucher_or_Card)接口并处理领取成功的回调；
5. 在第三步中获取到的card_id、code（加密code）请求解码code接口获取真实的code；
6. 记录用户小程序内的openid、用户领取的code以及card_id；
7. 处理卡券领取事件，记录用户在服务号内的openid、以及用户领取的code以及card_id。

### 接口说明

wx.addcard接口请参考：[wx.addcard](Create_a_Coupon_Voucher_or_Card)

### 注意事项

1. wx.addcard接口中涉及的签名中的api_ticket须传入创建该卡券服务号获取到的ticket；
2. 用户领取卡券后，会有领取卡券事件推送至开发者服务器，开发者须进行处理，详细请见[卡券事件通知](Coupons_Vouchers_and_Cards_Event_Push_Messages)；
3. 开发者可以通过outer_str判断用户的领券来源；
4. 该功能仅支持1.1.0版本以及以上的基础库版本，小程序内须做版本判断并对低版本进行兼容。

# 小程序内查看卡券

### 场景介绍

开发者可以通过调用该接口允许用户在小程序内查看、出示自己的微信卡券。

### 步骤

1.开发者须在用户进入小程序时，获取用户已经领取到的卡券的card_id和code（真实code）； 2.调用wx.openCard打开用户某张卡券供用户查看、使用。

### 接口说明

wx.openCard接口请参考：[wx.openCard](/miniprogram/dev/api/open-api/card/wx.openCard.md)

### 注意事项

1. 目前卡券领取后会自动返回小程序页面，若开发者鼓励用户领卡后继续在卡面上进行下一步操作，须在wx.addcard的函数回调内调用wx.opencard；
2. wx.addcard成功后返回的参数中code为加密字段，须解密后才能调用wx.opencard，详情请见[解码code接口](Redeeming_a_coupon_voucher_or_card#5)；

# 小程序开卡组件

### 场景介绍

开发者可以在小程序里面开发自己的会员模块，并将开卡环节嵌入其中，微信卡券为小程序内会员开卡提供了“开卡组件功能”。

用户在小程序内进入开卡组件时，可以快速拉取到用户之前在微信开卡填写的资料并预填，用户可以做到“一键开卡”。

对商户而言，开卡组件集“开卡注册”和“添加至卡包”于一体，快捷开卡的同时可以省掉手机验证等环节，提高开卡率。

目前开卡组件分为跳转型开卡组件和非跳转型开卡组件。

注意：

1. 小程序调用开卡组件须服务号具有微信卡券功能，详情请见：[微信卡券说明](https://mp.weixin.qq.com/cgi-bin/readtemplate?t=cardticket/faq_tmpl&type=info&token=1952472313&lang=zh_CN)。
2. 开发者须先了解卡券开发的基本知识后调用，详情请见：[微信卡券接口说明](WeChat_Coupon_Interface)。

### 步骤

跳转型一键开卡步骤

1. 创建一张会员卡会员卡，会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : true,并在activate_app_brand_user_name、activate_app_brand_pass传入激活小程序页面的相关信息，并获得card_id，详情见：[创建会员卡接口](Membership_Cards/Create_a_membership_card)；
2. 设置用户开卡时填写的开卡字段，分必填和选填，详情见：设置开卡字段接口
3. 获取开卡组件所需的参数；
4. 判断新老用户、客户端版本决定是否要调用开卡插件接口；
5. 调用开卡插件供用户开卡，并处理开卡插件的回调；
6. 获取用户开卡资料并激活用户的会员卡；

具体流程如图：

![](https://mmbiz.qpic.cn/mmbiz_png/PiajxSqBRaEJsqKkSJGg4TJbGatFpkeRVhJLHaKVXBra8W0icZ7aSDrvbZknHKRTL0iceiaibGKiariaIrhxSG4Z983EQ/0?wx_fmt=png)

非跳转型一键开卡步骤

1. 创建一张会员卡会员卡，会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : false,并获得card_id，详情见：
   [创建会员卡接口](Membership_Cards/Create_a_membership_card)
2. 设置用户开卡时填写的开卡字段，分必填和选填，详情见：设置开卡字段接口
3. 获取开卡组件所需的参数；
4. 判断新老用户、客户端版本决定是否要调用开卡插件接口；
5. 调用开卡插件供用户开卡，并处理开卡插件的回调；
6. 获取用户开卡资料；

![](https://mmbiz.qpic.cn/mmbiz_png/PiajxSqBRaEJsqKkSJGg4TJbGatFpkeRV78aDdxP33LEG19I1kiaTrOsz2iaXTKtgo3ClyBkdTGX0NMjW1SfjWVAQ/0?wx_fmt=png)

### 接口说明

#### 接口1：获取开卡插件参数

接口说明

开发者可以通过该接口获取到调用开卡插件所需的参数。

请求参数说明

| 参数         | 参数说明                                                                             |
| ------------ | ------------------------------------------------------------------------------------ |
| access_token | 创建卡服务号的token                                                                  |
| JSON         | 请求数据                                                                             |
| URL          | https://api.weixin.qq.com/card/membercard/activate/geturl?access_token= ACCESS_TOKEN |

```json
{ "card_id" : "pbLatji6o5g7hJh8Otuvux4y1ty0", "outer_str" : "123" }
```

| 参数      | 是否必填 | 参数说明                           |
| --------- | -------- | ---------------------------------- |
| card_id   | 是       | 会员卡的card_id                    |
| outer_str | 否       | 渠道值，用于统计本次领取的渠道参数 |

```json
{   "errcode": 0,   "errmsg": "ok",   "url": "https://mp.weixin.qq.com/bizmall/activatemembercard?    action=preshow&&enxxxxxxx=MjM5Mzc0OTEwMA%3D%3D#wechat_redirect" }
```

返回参数说明

| 参数    | 参数说明                              |
| ------- | ------------------------------------- |
| errcode | 错误码                                |
| errmsg  | 错误信息，用于定位错误原因            |
| url     | 返回的url，内含调用开卡插件所需的参数 |

注意事项 1.本接口返回的参数须原封不动地填入开卡插件接口，须做urldecode操作；

#### 接口2：小程序内打开开卡插件的接口

接口说明

1.开发者通过该接口可以在自己的小程序内打开开卡插件；

2.该接口为小程序接口，开发者须先了解小程序接口的调用方法：详情见：[卡券事件通知](Coupons_Vouchers_and_Cards_Event_Push_Messages)；

3.基础库 1.3.0 开始支持，低版本需做兼容处理

4.iOS 微信客户端 6.5.9 版本开始支持，Android 客户端即将在 6.5.10 版本开始支持，请先使用 iOS 客户端进行调试

打开同一服务号下关联的另一个小程序。

OBJECT参数说明：

| 参数名    | 类型     | 必填 | 说明                                                                                       |
| --------- | -------- | ---- | ------------------------------------------------------------------------------------------ |
| appId     | String   | 是   | 要打开的官方插件的appid,固定为wxeb490c6f9b154ef9，不可更改                                 |
| extraData | Object   | 否   | 需要传递给目标小程序的数据，目标小程序可在 App.onLaunch()，App.onShow() 中获取到这份数据。 |
| success   | Function | 否   | 接口调用成功的回调函数                                                                     |
| fail      | Function | 否   | 接口调用失败的回调函数                                                                     |
| complete  | Function | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                                           |

success返回参数说明：

参数名 类型 说明 errMsg String 调用结果

示例代码：

```javascript
wx.navigateToMiniProgram({   appId: ‘wxeb490c6f9b154ef9’, // 固定为此appid，不可改动   extraData: data, // 包括encrypt_card_id outer_str biz三个字段，须从step3中获得的链接中获取参数   success: function() {    },   fail: function() {   },   complete: function() {   } })
```

返回说明

在App.onShow里判断从会员开卡小程序返回的数据data

1. 判断data.referrerInfo.appId是否为开卡小程序appId 'wxeb490c6f9b154ef9'，如果不是则中止判断
2. 判断是否有data.referrerInfo.extraData是否有数据，如果没有，表示用户未激活直接左滑/点返回键返回，或者用户已经激活
3. 若用户激活成功，可以从data.referrerInfo.extraData中获取activate_ticket card_id code参数用于下一步操作

Bug & Tip
tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序，但是开发者工具会校验本次调用跳转是否成功
tip: 开发者工具上支持"被跳转的小程序处理接收参数"的调试

#### 接口3：获取用户开卡时提交的信息（跳转型开卡组件）

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

| 参数         | 参数说明                                                                          |
| ------------ | --------------------------------------------------------------------------------- |
| access_token | 创建卡服务号的token                                                               |
| JSON         | 请求数据                                                                          |
| URL          | https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN |

```json
{     "activate_ticket" : "abcdefg"         }
```

| 参数            | 是否必填 | 参数说明                                                       |
| --------------- | -------- | -------------------------------------------------------------- |
| activate_ticket | 是       | 跳转型开卡组件开卡后回调中的激活票据，可以用来获取用户开卡资料 |

```json
{
     "errcode": 0,
     "errmsg": "ok",
     "info": {
         "common_field_list": [
             {
                 "name": "USER_FORM_INFO_FLAG_MOBILE",
                 "value": "15*****518"
             },
             {
                 "name": "USER_FORM_INFO_FLAG_NAME",
                 "value": "HK"
             },
             {
                 "name": "USER_FORM_INFO_FLAG_EDUCATION_BACKGROUND",
                 "value": "研究生"
             }
         ],
         "custom_field_list": []
     }
}

```

返回参数说明

| 类型              | 描述                                     |
| ----------------- | ---------------------------------------- |
| 参数名            | 说明                                     |
| errcode           | 错误码，0为正常                          |
| errmsg            | 错误信息                                 |
| info              | 会员信息                                 |
| custom_field_list | 开发者设置的会员卡会员信息类目，如爱好。 |
| name              | 会员信息类目名称                         |
| value             | 会员卡信息类目值，比如等级值等           |
| value_list        | 填写项目为多选时的返回                   |
| value_list        | 填写项目为多选时的返回                   |
| common_field_list | 官方定义的信息类目                       |

common_field_id_list，支持开发者使用以下选项类型

| 参数                                  | 说明     |
| ------------------------------------- | -------- |
| USER_FORM_INFO_FLAG_MOBILE            | 手机号   |
| USER_FORM_INFO_FLAG_SEX               | 性别     |
| USER_FORM_INFO_FLAG_NAME              | 姓名     |
| USER_FORM_INFO_FLAG_BIRTHDAY          | 生日     |
| USER_FORM_INFO_FLAG_IDCARD            | 身份证   |
| USER_FORM_INFO_FLAG_EMAIL             | 邮箱     |
| USER_FORM_INFO_FLAG_LOCATION          | 详细地址 |
| USER_FORM_INFO_FLAG_EDUCATION_BACKGRO | 教育背景 |
| USER_FORM_INFO_FLAG_INDUSTRY          | 行业     |
| USER_FORM_INFO_FLAG_INCOME            | 收入     |
| USER_FORM_INFO_FLAG_HABIT             | 兴趣爱好 |

- 注意事项 1.本接口仅跳转型开卡组件可以调用，非跳转型的开卡组件回调中不含activate_ticket

#### 接口4：获取用户开卡时提交的信息（非跳转型开卡组件）

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

| 参数         | 参数说明                                                   |
| ------------ | ---------------------------------------------------------- |
| access_token | 创建卡服务号的token                                        |
| JSON         | 请求数据                                                   |
| URL          | https://api.weixin.qq.com/card/code/get?access_token=TOKEN |

```json
{     "card_id" : "abcdefg",     "code" : "abcdefg"         }
```

| 参数    | 是否必填 | 参数说明                               |
| ------- | -------- | -------------------------------------- |
| card_id | 否       | 卡券id，非自定义code类型会员卡不必填写 |
| code    | 是       | 会员卡的code                           |

- 返回数据

```json
{
     "errcode": 0,
     "errmsg": "ok",
     "openid": "obLatjjwDxxxxdoGIdwNqRXw",
     "nickname": "Fourier",
     "membership_number": "316510891298",
     "bonus": 460,
     "sex": "MALE",
     "user_info": {
         "common_field_list": [
             {
                 "name": "USER_FORM_INFO_FLAG_MOBILE",
                 "value": "1552xxxx8888"
             },
             {
                 "name": "USER_FORM_INFO_FLAG_NAME",
                 "value": "微信"
             }
         ],
         "custom_field_list": []
     },
     "user_card_status": "NORMAL"
}

```

| 参数名            | 说明                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| errcode           | 错误码，0为正常                                                                                                                         |
| errmsg            | 错误信息                                                                                                                                |
| openid            | 用户在本服务号内唯一识别码                                                                                                              |
| nickname          | 用户昵称                                                                                                                                |
| bonus             | 积分信息                                                                                                                                |
| balance           | 余额信息                                                                                                                                |
| sex               | 用户性别                                                                                                                                |
| user_info         | 会员信息                                                                                                                                |
| custom_field_list | 开发者设置的会员卡会员信息类目，如爱好。                                                                                                |
| common_field_list | 官方定义的信息类目，如积分。                                                                                                            |
| name              | 会员信息类目名称                                                                                                                        |
| value             | 会员卡信息类目值，比如等级值等                                                                                                          |
| user_card_status  | 当前用户会员卡状态，NORMAL 正常 EXPIRE 已过期 GIFTING 转赠中 GIFT_SUCC 转赠成功 GIFT_TIMEOUT 转赠超时 DELETE 已删除，UNAVAILABLE 已失效 |

common_field_id_list，支持开发者使用以下选项类型

| 参数                                  | 说明     |
| ------------------------------------- | -------- |
| USER_FORM_INFO_FLAG_MOBILE            | 手机号   |
| USER_FORM_INFO_FLAG_SEX               | 性别     |
| USER_FORM_INFO_FLAG_NAME              | 姓名     |
| USER_FORM_INFO_FLAG_BIRTHDAY          | 生日     |
| USER_FORM_INFO_FLAG_IDCARD            | 身份证   |
| USER_FORM_INFO_FLAG_EMAIL             | 邮箱     |
| USER_FORM_INFO_FLAG_LOCATION          | 详细地址 |
| USER_FORM_INFO_FLAG_EDUCATION_BACKGRO | 教育背景 |
| USER_FORM_INFO_FLAG_INDUSTRY          | 行业     |
| USER_FORM_INFO_FLAG_INCOME            | 收入     |
| USER_FORM_INFO_FLAG_HABIT             | 兴趣爱好 |

#### 接口5：激活用户领取的会员卡（跳转型开卡组件）

接口说明

开发者可以通过该接口获取到用户开卡时填写的字段值。

请求参数说明

| 参数         | 参数说明                                                              |
| ------------ | --------------------------------------------------------------------- |
| access_token | 创建卡服务号的token                                                   |
| JSON         | 请求数据                                                              |
| URL          | https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN |

```json
{
     "init_bonus": 100,
     "init_bonus_record":"旧积分同步",
     "init_balance": 200,
     "membership_number": "AAA00000001",
     "code": "12312313",
     "card_id": "xxxx_card_id",
     "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
     "init_custom_field_value1": "xxxxx"
}

```

| 参数                     | 是否必填 | 类型          | 描述                                                                                                                 |
| ------------------------ | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| membership_number        | 是       | string(20)    | 会员卡编号，由开发者填入，作为序列号显示在用户的卡包里。可与Code码保持等值。                                         |
| code                     | 是       | string(20)    | 领取会员卡用户获得的code                                                                                             |
| card_id                  | 否       | string（32）  | 卡券ID,自定义code卡券必填                                                                                            |
| background_pic_url       | 否       | string（128） | 商家自定义会员卡背景图，须 先调用上传图片接口将背景图上传至CDN，否则报错，卡面设计请遵循微信会员卡自定义背景设计规范 |
| activate_begin_time      | 否       | unsigned int  | 激活后的有效起始时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。                                        |
| activate_end_time        | 否       | unsigned int  | 激活后的有效截至时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。                                        |
| init_bonus               | 否       | int           | 初始积分，不填为0。 init_bonus_record                                                                                |
| init_balance             | 否       | int           | 初始余额，不填为0。                                                                                                  |
| init_custom_field_value1 | 否       | string（12）  | 创建时字段custom_field1定义类型的初始值，限制为4个汉字，12字节。                                                     |
| init_custom_field_value2 | 否       | string（12）  | 创建时字段custom_field2定义类型的初始值，限制为4个汉字，12字节。                                                     |
| init_custom_field_value3 | 否       | string（12）  | 创建时字段custom_field3定义类型的初始值，限制为4个汉字，12字节。                                                     |

返回数据

```json
{
     "init_bonus": 100,
     "init_bonus_record":"旧积分同步",
     "init_balance": 200,
     "membership_number": "AAA00000001",
     "code": "12312313",
     "card_id": "xxxx_card_id",
     "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
     "init_custom_field_value1": "xxxxx"
}

```

| 参数名  | 说明            |
| ------- | --------------- |
| errcode | 错误码，0为正常 |
| errmsg  | 错误信息        |

### 注意事项

- 新老会员判断：若用户已领取微信会员卡，开发者可以通过[获取用户信息接口](/doc/subscription/api/usermanage/userinfo/api_userinfo.md)获取到用户的unionid,用户授权登录小程序后可以关联用户之前的会员账户；
- 新老版本判断：开发者对会员开卡须设计两套流程，iOS 6.5.9 &Android 6.5.10及其以上微信版本可以调用开卡组件，低版本须开发小程序自己的注册页面，用户注册完成后领取会员卡即可

# 卡券内跳转小程序

### 场景介绍

商户创建卡券时可以将卡、券内的服务入口设置进入小程序服务。

### 步骤

1. 开发者须将小程序绑定在服务号下，绑定说明请见[绑定服务号与小程序](https://mp.weixin.qq.com/debug/wxadoc/introduction/#服务号关联小程序)
2. 创建卡券，并将卡内的cell设置小程序对应的path；
3. 处理跳转小程序时获取到的信息；

### 接口说明

- 创建会员卡

```json
{ "card": {
     "card_type": "MEMBER_CARD",
     "member_card": {
         "base_info": {
             "custom_url_name": "立即使用",
             "custom_url": "http://www.qq.com",
             "custom_app_brand_user_name": "gh_86a091e50ad4@app",
             "custom_app_brand_pass":"API/cardPage",
             "custom_url_sub_title": "6个汉字tips",
             "promotion_url_name": "更多优惠",
           "promotion_url": "http://www.qq.com",
             "promotion_app_brand_user_name": "gh_86a091e50ad4@app",
             "promotion_app_brand_pass":"API/cardPage"
        }
         }
}

```

| 字段名                                     | 字段描述                                               | 字段示例            |
| ------------------------------------------ | ------------------------------------------------------ | ------------------- |
| custom_app_brand_user_name                 | 自定义使用入口跳转小程序的user_name，格式为原始id+@app | gh_86a091e50ad4@app |
| custom_app_brand_pass                      | 自定义使用入口小程序页面地址                           | API/cardPage        |
| center_app_brand_user_name                 | 小程序的user_name                                      | gh_86a091e50ad4@app |
| center_app_brand_pass                      | 自定义居中使用入口小程序页面地址                       | API/cardPage        |
| promotion_app_brand_user_name              | 小程序的user_name                                      | gh_86a091e50ad4@app |
| promotion_app_brand_pass                   | 自定义营销入口小程序页面地址                           | API/cardPage        |
| activate_app_brand_user_name               | 小程序的user_name,                                     | gh_86a091e50ad4@app |
| activate_app_brand_pass                    | 激活小程序页面地址                                     | API/cardPage        |
| custom_field1、custom_field2 custom_field3 | 会员卡顶部的信息类目字段，包含以下两个字段             |                     |
| app_brand_user_name                        | 自定义信息类目小程序user_name，格式为原始id+@app       | gh_86a091e50ad4@app |
| app_brand_pass                             | 自定义信息类目小程序的页面路径                         | API/cardPage        |
| custom_cell1、custom_cell2                 | 会员卡自定义入口，包含以下两个字段                     |                     |
| app_brand_user_name                        | 自定义入口小程序user_name，格式为原始id+@app           | gh_86a091e50ad4@app |
| app_brand_pass                             | 自定义入口小程序的页面路径                             | API/cardPage        |
| bonus_app_brand_user_name                  | 积分信息类目对应的小程序 user_name，格式为原始id+@app  | gh_86a091e50ad4@app |
| bonus_app_brand_pass                       | 积分入口小程序的页面路径                               | API/cardPage        |
| balance_app_brand_user_name                | 余额信息类目对应的小程序 user_name，格式为原始id+@app  | gh_86a091e50ad4@app |
| balance_app_brand_pass                     | 余额入口小程序的页面路径                               | API/cardPage        |

\*需调用卡券更新接口将相应小程序页面更新至对应跳转外链结构体中，原跳转H5字段保留。

- 获取跳转参数

从卡券跳转小程序后，开发者可以通过apponshow的query中或取到发起跳转的card_id、encrypt_code和用户的服务号openid，开发者须调用 解码code接口 将encrypt_code解码为真实code。