会员卡升级公告

2016年5月15日起，微信卡券团队对会员卡能力进行全面升级。在原有能力基础上进行以下能力升级，旨在帮助商家更好地进行会员管理。

-强化客户端一级入口：会员到店即用，快速定位商户会员卡；

-自定义卡面能力：开发者可以根据会员身份设置不同的卡面背景；

-门店扫码方案：新用户到店扫码领卡，老用户到店扫码快速打开会员卡，实现会员点餐、买单等多种功能

-支付即会员：支持开发者设置微信支付后为用户下发领卡消息，顾客支付即会员，快速拉新；

-运营策略调整：会员卡新增开放类目限制，自4月20日起，仅限会员卡类目内的商户新建会员卡，原有会员卡不受影响，详情请见：《会员卡公告》

# 1.新版会员卡介绍

在原有能力的基础上，微信卡券团队将对会员卡新增自定义卡面、门店扫码方案、支付后模板消息、按会员标签分组群发消息等能力，卡券消息能力也进行了升级，旨在帮助商家更好地进行会员管理。

-(a)增加自定义背景，开发者可以设置;

-(b)卡券消息升级，积分/余额变动通过模板消息自动发送，可携带营销信息。

（a）

(b)

# 2.须知

阅读该部分之前请先阅读首页、《开始开发》以及《微信卡券接口说明》确保你能了解公众平台和卡券接口的基本术语和调用方法。

一般地，会员卡的接口调用顺序可参考以下流程：

# 3.会员卡玩法介绍

门店扫码方案会员卡快速买单会员卡与CRM打通

会员卡与支付系统打通老会员绑定会员卡打通储值

开卡组件

卡券-小程序打通

# 4.创建会员卡接口详情

# 4.1 创建会员卡接口

支持开发者调用该接口创建会员卡，并获取card_id，用于投放。调用该接口前，请开发者详读创建卡券接口部分上传图片接口、首页部分，快速录入会员卡卡面必要信息。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON结构

POST数据示例：

{
    "card": {
        "card_type": "MEMBER_CARD",
        "member_card": {
            "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/",
            "base_info": {
                "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZ/0",
                "brand_name": "海底捞",
                "code_type": "CODE_TYPE_TEXT",
                "title": "海底捞会员卡",
                "color": "Color010",
                "notice": "使用时向服务员出示此券",
                "service_phone": "020-88888888",
                "description": "不可与其他优惠同享",
                "date_info": {
                    "type": "DATE_TYPE_PERMANENT"
                },
                "sku": {
                    "quantity": 50000000
                },
                "get_limit": 3,
                "use_custom_code": false,
                "can_give_friend": true,
                "location_id_list": [
                    123,
                    12321
                ],
                "custom_url_name": "立即使用",
                "custom_url": "http://weixin.qq.com",
                "custom_url_sub_title": "6个汉字tips",
                "promotion_url_name": "营销入口1",
                "promotion_url": "http://www.qq.com",
                "need_push_on_view": true
            },
             "advanced_info": {
               "use_condition": {
                   "accept_category": "鞋类",
                   "reject_category": "阿迪达斯",
                   "can_use_with_other_discount": true
               },
             "abstract": {
                   "abstract": "微信餐厅推出多种新季菜品，期待您的光临",
                   "icon_url_list": [
                       "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj
  piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                   ]
               },
               "text_image_list": [
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品精选食材，以独特的烹饪方法，最大程度地刺激食 客的味蕾"
                   },
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "此菜品迎合大众口味，老少皆宜，营养均衡"
                   }
               ],
               "time_limit": [
                   {
                       "type": "MONDAY",
                       "begin_hour":0,
                       "end_hour":10,
                       "begin_minute":10,
                       "end_minute":59
                   },
                   {
                       "type": "HOLIDAY"
                   }
               ],
               "business_service": [
                   "BIZ_SERVICE_FREE_WIFI",
                   "BIZ_SERVICE_WITH_PET",
                   "BIZ_SERVICE_FREE_PARK",
                   "BIZ_SERVICE_DELIVER"
               ]
           },
            "supply_bonus": true,
            "supply_balance": false,
            "prerogative": "test_prerogative",
            "auto_activate": true,
            "custom_field1": {
                "name_type": "FIELD_NAME_TYPE_LEVEL",
                "url": "http://www.qq.com"
            },
            "activate_url": "http://www.qq.com",
            "custom_cell1": {
                "name": "使用入口2",
                "tips": "激活后显示",
                "url": "http://www.qq.com"
            },
            "bonus_rule": {
                "cost_money_unit": 100,
                "increase_bonus": 1,
                "max_increase_bonus": 200,
                "init_increase_bonus": 10,
                "cost_bonus_unit": 5,
                "reduce_money": 100,
                "least_money_to_use_bonus": 1000,
                "max_reduce_bonus": 50
            },
            "discount": 10
        }
    }
}

接口字段对应表

参数说明

参数名	必填	类型	描述
card_type	是	string	会员卡类型。
background_ pic_ur l	否	string(128)	商家自定义会员卡背景图，须先调用上传图片接口将背景图上传至CDN，否则报错，卡面设计请遵循微信会员卡自定义背景设计规范 ,像素大小控制在 1000像素*600像素以下
base_info	是	JSON	基本的卡券数据，见下表，所有卡券类型通用。
prerogative	是	strin g(3072)	会员卡特权说明,限制1024汉字。
auto_activate	否	bool	设置为true时用户领取会员卡后系统自动将其激活，无需调用激活接口，详情见自动激活。
wx_activate	否	bool	设置为true时会员卡支持一键开卡，不允许同时传入activate_url字段，否则设置wx_activate失效。填入该字段后仍需调用接口设置开卡项方可生效，详情见一键开卡。
supply_bonus	是	bool	显示积分，填写true或false，如填写true，积分相关字段均为必填若设置为true则后续不可以被关闭。
bonus_url	否	string(128)	设置跳转外链查看积分详情。仅适用于积分无法通过激活接口同步的情况下使用该字段。
supply_balance	是	bool	是否支持储值，填写true或false。如填写true，储值相关字段均为必填若设置为true则后续不可以被关闭。该字段须开通储值功能后方可使用，详情见：获取特殊权限
balance_url	否	string(128)	设置跳转外链查看余额详情。仅适用于余额无法通过激活接口同步的情况下使用该字段。
custom_field1	否	JSON结构	自定义会员信息类目，会员卡激活后显示,包含name_type (name) 和url字段
custom_field2	否	JSON结构	自定义会员信息类目，会员卡激活后显示，包含name_type(name)和url字段
custom_field3	否	JSON结构	自定义会员信息类目，会员卡激活后显示，包含name_type (name) 和url字段
name_type	否	string(24)	会员信息类目半自定义名称，当开发者变更这类类目信息的value值时可以选择触发系统模板消息通知用户。 FIELD_NAME_TYPE_LEVEL 等级 FIELD_NAME_TYPE_COUPON 优惠券 FIELD_NAME_TYPE_STAMP 印花 FIELD_NAME_TYPE_DISCOUNT 折扣 FIELD_NAME_TYPE_ACHIEVEMEN 成就 FIELD_NAME_TYPE_MILEAGE 里程 FIELD_NAME_TYPE_SET_POINTS 集点 FIELD_NAME_TYPE_TIMS 次数
name	否	string(24)	会员信息类目自定义名称，当开发者变更这类类目信息的value值时不会触发系统模板消息通知用户
url	否	string（128）	点击类目跳转外链url
bonus_cleared	否	string（128）	积分清零规则。
bonus_rules	否	string（128）	积分规则。
balance_rules	否	string（128）	储值说明。
activate_url	否	string（128）	激活会员卡的url。
activate_app_brand_user_name	否	string（128）	激活会员卡url对应的小程序user_name，仅可跳转该公众号绑定的小程序
activate_app_brand_pass	否	string（128）	激活会员卡url对应的小程序path
custom_cell1	否	JSON结构	自定义会员信息类目，会员卡激活后显示。
name	是	string(15)	入口名称。
tips	是	string(18)	入口右侧提示语，6个汉字内。
url	是	string(128)	入口跳转链接。
bonus_rule	否	JSON结构	积分规则。
cost_money_unit	否	int	消费金额。以分为单位。
increase_bonus	否	int	对应增加的积分。
max_increase _bonus	否	int	用户单次可获取的积分上限。
init_increase _bonus	否	int	初始设置积分。
cost_bonus_unit	否	int	每使用X积分。
reduce_money	否	int	抵扣xx元，（这里以分为单位）
least_money_to_ use_bonus	否	int	抵扣条件，满xx元（这里以分为单位）可用。
max_reduce _bonus	否	int	抵扣条件，单笔最多使用xx积分。
discount	否	int	折扣，该会员卡享受的折扣优惠,填10就是九折。

base_info字段：

参数名	必填	类型	描述
logo_url	是	string(128)	卡券的商户logo，建议像素为300*300。
code_type	是	string(16)	Code展示类型， "CODE_TYPE_TEXT" 文本 "CODE_TYPE_BARCODE" 一维码 "CODE_TYPE_QRCODE" 二维码 "CODE_TYPE_ONLY_QRCODE" 仅显示二维码 "CODE_TYPE_ONLY_BARCODE" 仅显示一维码 "CODE_TYPE_NONE" 不显示任何码型
pay_info	否	JSON	支付功能结构体，swipe_card结构
swipe_card	否	JSON	刷卡功能结构体，包含is_swipe_card字段
is_swipe_card	否	bool	是否设置该会员卡支持拉出微信支付刷卡界面
is_pay_and_qrcode	否	bool	是否设置该会员卡中部的按钮同时支持微信支付刷卡和会员卡二维码
brand_name	是	string	商户名字,字数上限为12个汉字。
title	是	string	卡券名，字数上限为9个汉字 (建议涵盖卡券属性、服务及金额)。
color	是	string	券颜色。按色彩规范标注填写Color010-Color100
notice	是	string	卡券使用提醒，字数上限为16个汉字。
description	是	string	卡券使用说明，字数上限为1024个汉字。
sku	是	JSON	商品信息。
quantity	是	int	卡券库存的数量，不支持填写0，上限为100000000。
date_info	是	JSON	使用日期，有效期的信息。
type	是	string	使用时间的类型支持固定时长有效类型固定日期有效类型永久有效类型( DATE_TYPE_PERMANENT)
begin _timestamp	否	int	type为DATE_TYPE_FIX_TIME_RANGE时专用，表示起用时间。从1970年1月1日00:00:00至起用时间的秒数（东八区时间,UTC+8，单位为秒）
end _timestamp	否	int	type为DATE_TYPE_FIX_TERM_RANGE时专用，表示结束时间（东八区时间,UTC+8，单位为秒）
fixed_term	否	int	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天内有效，领取后当天有效填写0（单位为天）
fixed_begin _term	否	int	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天开始生效。（单位为天）
use_custom _code	否	bool	是否自定义Code码。填写true或false，默认为false 通常自有优惠码系统的开发者选择自定义Code码，详情见是否自定义code
bind_openid	否	bool	是否指定用户领取，填写true或false。默认为false
service_phone	否	string（24）	客服电话
location_id_list	否	array	门店位置ID。调用 POI门店管理接口获取门店位置ID。
use_all_locations	否	bool	会员卡是否支持全部门店，填写后商户门店更新时会自动同步至卡券
center_title	否	string（18）	卡券中部居中的按钮，仅在卡券激活后且可用状态时显示
center_sub _title	否	string（24）	显示在入口下方的提示语，仅在卡券激活后且可用状态时显示
center_url	否	string（128）	顶部居中的url ，仅在卡券激活后且可用状态时显示
custom_url _name	否	string（15）	自定义跳转外链的入口名字。
custom_url	否	string（128）	自定义跳转的URL。
custom_url _sub_title	否	string（18）	显示在入口右侧的提示语。
promotion _url_name	否	string（15）	营销场景的自定义入口名称。
promotion _url	否	string（128）	入口跳转外链的地址链接。
promotion_ url_sub_title	否	string（18）	显示在营销入口右侧的提示语。
get_limit	否	int	每人可领券的数量限制，建议会员卡每人限领一张
can_share	否	bool	卡券领取页面是否可分享，默认为true
can_give _friend	否	bool	卡券是否可转赠,默认为true
need_push_on _view	否	bool	填写true为用户点击进入会员卡时推送事件，默认为false。详情见进入会员卡事件推送

Advanced_info（卡券高级信息）字段

字段	是否必填	类型	说明
advanced_info	否	JSON结构	创建优惠券特有的高级字段
use_condition	否	JSON结构	使用门槛（条件）字段，若不填写使用条件则在券面拼写：无最低消费限制，全场通用，不限品类；并在使用说明显示：可与其他优惠共享
accept_category	否	string（512）	指定可用的商品类目，仅用于代金券类型，填入后将在券面拼写适用于xxx
reject_category	否	string（512）	指定不可用的商品类目，仅用于代金券类型，填入后将在券面拼写不适用于xxxx
least_cost	否	int	满减门槛字段，可用于兑换券和代金券，填入后将在全面拼写消费满xx元可用。
object_use_for	否	string（512）	购买xx可用类型门槛，仅用于兑换，填入后自动拼写购买xxx可用。
can_use_with_other_discount	否	bool	不可以与其他类型共享门槛，填写false时系统将在使用须知里拼写“不可与其他优惠共享”，填写true时系统将在使用须知里拼写“可与其他优惠共享”，默认为true
abstract	否	JSON结构	封面摘要结构体名称
abstract	否	string（24 ）	封面摘要简介。
icon_url_list	否	string（128 ）	封面图片列表，仅支持填入一个封面图片链接，上传图片接口上传获取图片获得链接，填写非CDN链接会报错，并在此填入。建议图片尺寸像素850*350
text_image_list	否	JSON结构	图文列表，显示在详情内页，优惠券券开发者须至少传入一组图文列表
image_url	否	string（128 ）	图片链接，必须调用上传图片接口上传图片获得链接，并在此填入，否则报错
text	否	string（512 ）	图文描述
business_service	否	arry	商家服务类型： BIZ_SERVICE_DELIVER 外卖服务； BIZ_SERVICE_FREE_PARK 停车位； BIZ_SERVICE_WITH_PET 可带宠物； BIZ_SERVICE_FREE_WIFI 免费wifi，可多选
time_limit	否	JSON结构	使用时段限制，包含以下字段
type	否	string（24）	限制类型枚举值：支持填入 MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日此处只控制显示，不控制实际使用逻辑，不填默认不显示
begin_hour	否	int	当前type类型下的起始时间（小时），如当前结构体内填写了MONDAY，此处填写了10，则此处表示周一 10:00可用
begin_minute	否	int	当前type类型下的起始时间（分钟），如当前结构体内填写了MONDAY， begin_hour填写10，此处填写了59，则此处表示周一 10:59可用
end_hour	否	int	当前type类型下的结束时间（小时），如当前结构体内填写了MONDAY，此处填写了20，则此处表示周一 10:00-20:00可用
end_minute	否	int	当前type类型下的结束时间（分钟），如当前结构体内填写了MONDAY， begin_hour填写10，此处填写了59，则此处表示周一 10:59-00:59可用

返回说明

{
   "errcode":0,
   "errmsg":"ok",
   "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。
card_id	卡券ID。

开发者注意事项

*1. 仅部分类目可创建会员卡，非开放类目将返回错误码，类目明细见会员卡公告

2.创建会员卡时，需设置会员卡激活后呈现的信息类目，目前支持积分、余额、等级、优惠券、里程、印花、成就、折扣等类型，微信6.2以上版本显示会员信息类目的上限为3个，即创建时类目字段supply_bonus 、supply_balance、 custom_field1、custom_field2 、custom_field3最多选择三项填写。

3.创建卡券时，开发者填入的时间戳须注意时间戳溢出时间，设置的时间戳须早于2038年1月19日，若要设置更久的有效期，可以选择永久有效类型的有效期。

# 4.2 获取会员卡审核结果

调用接口成功创建会员卡后，会由系统自动提交审核，审核结果将在三个工作日内以事件形式告知开发者，同时支持调用接口主动查询卡券状态。

审核事件推送

生成的卡券通过审核时，微信会把这个事件推送到开发者填写的URL，详情见：卡券事件推送会员卡审核通过后可以正式投放会员卡。

# 4.3 设置测试白名单接口

若会员卡暂时未审核通，开发者可以将测试人员的微信号设置成白名单，领取未审核通过的卡券。白名单状态领取的卡信息不随卡券实时更新，请开发者注意。详情见:投放卡券

# 5 投放会员卡接口详情

目前微信会员卡支持通过扫描二维码、在网页直接点击（参考 JS-SDK说明文档）、卡券货架、公众号群发以及公众号被动回复消息领取，开发者可以选择一种或者多种。请参考以下各种投放方式详情。

特别注意

开发者调用接口投放的会员卡为无会员信息的“卡套”，会员卡编号、积分、余额等信息需在用户领取会员卡后调用激活/绑定会员卡接口更新上。
调用激活/绑定会员卡接口的凭证为Code码及card_id，开发者需在调用投放会员卡时通过接口或领取卡券事件记录code码与会员OpenID的关系。

# 5.1 创建二维码接口

创建会员卡二维码，打印后置于店内，顾客扫码领取会员卡，扫描下方二维码体验领取，若已领取可扫码快速打开会员卡。接口详情见：投放卡券

# 5.2 网页内单张/批量添加卡券接口

微信提供addCard接口供商户前端网页调用,用于将一张或多张卡券添加到用户卡包。详情见 JS-SDK说明文档

（微信扫一扫>微信卡券接口>addcard接口）

# 5.3 通过卡券货架投放会员卡

卡券货架简介

卡券货架支持开发者通过调用接口生成一个卡券领取H5页面，并获取页面链接，进行卡券投放动作。接口详情见投放卡券

# 5.4 公众号消息投放会员卡

开发者也可以通过公众号群发消息或者客服消息为用户发送一张会员卡，详情见：投放卡券

# 5.5 记录用户领卡行为

用户领取会员卡后，微信会给开发者服务器推送领取会员卡事件通知，以便开发者记录用户OpenID与会员卡code的关联关系，并可以通过事件内的参数区分领取渠道（见1.5）。

详情见：卡券事件推送

# 5.6 统计投放渠道数据

为方便开发者统计各渠道的卡券投放数据，新增字段outer_id。将不同设值的outer_id填入card_ext的JSON结构中，当用户领取卡券时会将相应设值的outer_id带入卡券事件推送推送中，推送至开发者服务器。

示例：在二维码投放方式中设置outer_id为1

{
    "action_name": "QR_CARD",
    "action_info": {
        "card": {
            "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
            "code": "198374613512",
            "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
            "expire_seconds": 1800,
            "is_unique_code": false,
            "outer_id": 1
        }
    }
}

领取事件XML文件

<xml>
   <ToUserName>< ![CDATA[toUser] ]></ToUserName>
    <FromUserName>< ![CDATA[FromUser] ]></FromUserName>
    <FriendUserName>< ![CDATA[FriendUser] ]></FriendUserName>
    <CreateTime>123456789</CreateTime>
    <MsgType>< ![CDATA[event] ]></MsgType>
    <Event>< ![CDATA[user_get_card] ]></Event>
    <CardId>< ![CDATA[cardid] ]></CardId>
    <IsGiveByFriend>1</IsGiveByFriend>
    <UserCardCode>< ![CDATA[12312312] ]></UserCardCode>
    <OuterId>1</OuterId>
</xml>

# 6 激活会员卡

当用户领取会员卡“卡套”后，支持调用该接口对会员卡进行激活，并设置会员信息的初始值，如积分、余额、等级、会员卡编号等会员信息。目前，微信会员卡支持三种激活方式，分别是接口激活、一键激活和自动激活。

开发者注意事项

1.开发者可以根据业务场景需要选择合适的激活流程。三种激活流方法只能选择一种；

2.激活会员卡需传入用户领取时获取的Code码，将该Code码对应设置会员卡编号membership_number。

# 6.1 接口激活

激活方式说明

接口激活通常需要开发者开发用户填写资料的网页。通常有两种激活流程：

用户必须在填写资料后才能领卡，领卡后开发者调用激活接口为用户激活会员卡；
是用户可以先领取会员卡，点击激活会员卡跳转至开发者设置的资料填写页面，填写完成后开发者调用激活接口为用户激活会员卡。

接口详情

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	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	否	string(32)	积分同步说明。
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字节。

返回说明

数据示例：

{
   "errcode":0,
   "errmsg":"ok"
}

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。

# 6.2 一键激活

6.2.1 普通一键激活

一键激活是微信提供的快速便捷的激活方案，用户领取后点击“激活会员卡”会跳转至官方的资料填写页面，微信会自动拉取该用户之前填写过的开卡信息，用户无需重复填写，同时避免了手机号验证的过程，从而实现一键激活的目的，提高了开卡率。具体流程如下图：

步骤一：在创建接口填入wx_activate字段

接口说明

设置微信一键开卡功能，现支持在创建会员卡时填入指定字段指定要一键激活，member_card中增加"wx_activate": true。详情请见创建会员卡接口

若商户使用了自定义卡号，开发者可以设置用户填写信息后跳转至商户的网页，并由开发者进行激活。

参数说明

参数	是否必须	说明
member_card
wx_activate	否	填写true or false

POST数据示例：

{
    "card": {
        "member_card": {
            "wx_activate": true
        }
    }
}

开发者注意事项

1.填入了自动激活auto_activate字段，激活链接activate_url和一键开卡接口设置都会失效；

2.若同时传入了activate_url，则一键开卡接口设置会失效；

3.建议开发者activate_url、auto_activate和wx_activate只填写一项。

步骤二：设置开卡字段接口

开发者在创建时填入wx_activate字段后，需要调用该接口设置用户激活时需要填写的选项，否则一键开卡设置不生效。

接口调用请求说明

HTTP请求方式: POST URL:https://api.weixin.qq.com/card/membercard/activateuserform/set?access_token=TOKEN

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON结构

{
    "card_id": "pbLatjnrwUUdZI641gKdTMJzHGfc",
    "service_statement": {
        "name": "会员守则",
        "url": "https://www.qq.com"
    },
    "bind_old_card": {
        "name": "老会员绑定",
        "url": "https://www.qq.com"
    },
    "required_form": {
        "can_modify"：false,
        "rich_field_list": [
            {
                "type": "FORM_FIELD_RADIO",
                "name": "兴趣",
                "values": [
                    "钢琴",
                    "舞蹈",
                    "足球"
                ]
            },
            {
                "type": "FORM_FIELD_SELECT",
                "name": "喜好",
                "values": [
                    "郭敬明",
                    "韩寒",
                    "南派三叔"
                ]
            },
            {
                "type": "FORM_FIELD_CHECK_BOX",
                "name": "职业",
                "values": [
                    "赛车手",
                    "旅行家"
                ]
            }
        ],
        "common_field_id_list": [
            "USER_FORM_INFO_FLAG_MOBILE"
        ]
    },
    "optional_form": {
        "can_modify"：false,
        "common_field_id_list": [
            "USER_FORM_INFO_FLAG_LOCATION",
            "USER_FORM_INFO_FLAG_BIRTHDAY"
        ],
        "custom_field_list": [
            "喜欢的电影"
        ]
    }}

参数名	必填	类型	描述
card_id	是	string(32)	卡券ID。
required_form	否	JSON结构	会员卡激活时的必填选项。
optional_form	否	JSON结构	会员卡激活时的选填项。
can_modify	否	bool	当前结构（required_form或者optional_form ）内的字段是否允许用户激活后再次修改，商户设置为true 时，需要接收相应事件通知处理修改事件
common_field_id_list	否	arry	微信格式化的选项类型。见以下列表。
custom_field_list	否	arry	自定义选项名称，开发者可以分别在必填和选填中至多定义五个自定义选项
rich_field_list	否	arry	自定义富文本类型，包含以下三个字段，开发者可以分别在必填和选填中至多定义五个自定义选项
type	否	string( 21 )	富文本类型 FORM_FIELD_RADIO 自定义单选 FORM_FIELD_SELECT 自定义选择项 FORM_FIELD_CHECK_BOX 自定义多选
name	否	string(21)	字段名
values	否	arry	选择项
service_statement	否	JSON结构	服务声明，用于放置商户会员卡守则
name	否	string( 21 )	会员声明字段名称
url	否	string(128)	自定义url 请填写http:// 或者https://开头的链接
bind_old_card	否	JSON结构	绑定老会员链接
name	否	string(32)	链接名称
url	否	string(128)	自定义url，请填写http:// 或者https://开头的链接

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	兴趣爱好

步骤三：接收会员信息事件通知

用户填写、提交资料后，会有事件推送给商家，开发者可以在接收到事件通知后调用激活接口，传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息，进行会员管理。

推送XML数据包示例

<xml>
   <ToUserName> < ![CDATA[gh_3fcea188bf78] ]></ToUserName>
    <FromUserName>< ![CDATA[obLatjlaNQKb8FqOvt1M1x1lIBFE] ]></FromUserName>
    <CreateTime>1432668700</CreateTime>
    <MsgType>< ![CDATA[event] ]></MsgType>
    <Event>< ![CDATA[submit_membercard_user_info] ]></Event>
    <CardId>< ![CDATA[pbLatjtZ7v1BG_ZnTjbW85GYc_E8] ]></CardId>
    <UserCardCode>< ![CDATA[018255396048] ]></UserCardCode> 
</xml>

参数说明

参数	说明
ToUserName	开发者微信号
FromUserName	发送方账号（一个OpenID）
CreateTime	消息创建时间（整型）
MsgType	消息类型，event
CardId	卡券ID
UserCardCode	卡券Code码

步骤四：同步会员数据

开发者可以在接收到事件通知后调用激活接口，传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息，详情请见：激活会员卡接口

步骤五：拉取会员信息接口

接口说明

支持开发者根据CardID和Code查询会员信息。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN

参数说明

参数	是否必须	说明
POST数据	是	JSON结构
access_token	是	调用接口凭证

POST数据

{
   "card_id": "pbLatjtZ7v1BG_ZnTjbW85GYc_E8",
   "code": "916679873278"
}

返回数据

{
    "errcode": 0,
    "errmsg": "ok",
    "openid": "obLatjjwDolFj******wNqRXw",
    "nickname": "*******",
    "membership_number": "658*****445",
    "bonus": 995,
    "sex": "MALE",
    "user_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": [
      {
        "name": "兴趣",
        "value": "钢琴",
        "value_list": []
      },
      {
        "name": "喜好",
        "value": "郭敬明",
        "value_list": []
      },
      {
        "name": "职业",
        "value": "",
        "value_list": [
          "赛车手",
          "旅行家"
        ]
      }
    ]
    },
    "user_card_status": "NORMAL",
    "has_active": false
}

参数名	说明
errcode	错误码，0为正常
errmsg	错误信息
openid	用户在本公众号内唯一识别码
nickname	用户昵称
bonus	积分信息
balance	余额信息
sex	用户性别
user_info	会员信息
custom_field_list	开发者设置的会员卡会员信息类目，如等级。
name	会员信息类目名称
value	会员卡信息类目值，比如等级值等
value_list	填写项目为多选时的返回
user_card_status	当前用户的会员卡状态，NORMAL 正常 EXPIRE 已过期 GIFTING 转赠中 GIFT_SUCC 转赠成功 GIFT_TIMEOUT 转赠超时 DELETE 已删除，UNAVAILABLE 已失效
has_active	该卡是否已经被激活，true表示已经被激活，false表示未被激活

6.2.2 跳转型一键激活

跳转型一键激活支持用户在提交会员开卡资料后跳转至商户自定义的网页。不同于普通一键激活，跳转型一键激活的激活会员卡动作由商户完成，商户可以在跳转到的网页内做激活、激活奖励、开卡条件判断等逻辑，同时也保证了开卡的实时性，适合使用自定义卡号的商户使用。

步骤一：在创建/更新接口填入跳转型一键激活相关字段

若商户设置用户激活后跳转自己的网页，需要在创建或更新接口传入以下参数。

{
    "card": {
         "member_card": {
     ························
      ························
    "wx_activate": true, "wx_activate_after_submit" : true,
   //是否设置跳转型一键激活 "wx_activate_after_submit_url" : "https://qq.com"
      //用户提交信息后跳转的网页 }
    }
}

参数名	必填	类型	描述
member_card	是	JSON结构	会员卡结构体
wx_activate	否	bool	是否支持一键激活，填true或false
wx_activate_after_submit	否	bool	是否支持跳转型一键激活，填true或false
wx_activate_after_submit_url	否	bool	跳转型一键激活跳转的地址链接，请填写http:// 或者https://开头的链接

步骤二：设置开卡字段接口

见6.2.1

步骤三：获取用户提交资料

用户填写并提交开卡资料后，会跳转到商户的网页，商户可以在网页内获取用户已填写的信息并进行开卡资质判断，信息确认等动作。

具体方式如下：

用户点击提交后，微信会在商户的url后面拼接获取用户填写信息的参数：activate_ticket、openid、card_id和加密code-encrypt_code,如商户填写的wx_activate_after_submit_url为www.qq.com,则拼接后的url为 www.qq.com&card_id=pbLatjvFdsLDUMoN8JqcsGeiMHKk&encrypt_code=Bupk8bb9xxxxxx3rdXV6fClBVtkHQplYohdzGvgDl4%3D&outer_str=&openid=obLatjjwDxxxxxxxoGIdwNqRXw&activate_ticket=fDZv9eMQAFfrNr3XBoqhb%2F%2BMSDM0yjDF6CdiUhC%2BOlEaxb0clsUxxxxxxxxxxxd6yQsjRMRu4kAcKTibYLN5tmHBdll1b6zQRsLF53MpKjGU%3D。

开发者可以根据activate_ticket获取到用户填写的信息，用于开发者页面的逻辑判断。

接口说明

支持开发者根据activate_ticket获取到用户填写的信息。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN

参数说明

参数	是否必须	说明
POST数据	是	JSON结构
access_token	是	调用接口凭证

POST数据

{
    "activate_ticket" : "abcdefg"
}

返回数据

  {
    "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": []
    }
}

注意事项：

1.开发者须使用制卡appid调用该接口，否则报错；

2.开发者在URL上截取ticket后须先进行urldecode。

步骤四：调用接口激活会员卡

开发者可以在接收到事件通知后调用激活接口，传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息，详情请见：激活会员卡接口

# 6.3 自动激活

接口说明

设置会员卡自动激活功能，需在创建会员卡时填入指定字段，base_info中增加"auto_activate": true，获取card_id。详情请见创建会员卡接口

值得注意的是，传入自动激活字段auto_activate之后，一键开卡设置和接口激活设置的激活url均不再显示，用户领取卡片之后，系统自动帮用户激活，积分、储值等自定义显示信息均为0，开发者可以通过更新会员信息接口更新用户会员数据。

参数说明

参数	是否必须	说明
member_card
auto_activate	否	填写true or false

# 7 更新会员信息

当会员持卡消费后，支持开发者调用该接口更新会员信息。会员卡交易后的每次信息变更需通过该接口通知微信，便于后续消息通知及其他扩展功能。

接口调用请求说明

HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/updateuser?access_token=TOKEN

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON结构

{
    "code": "179011264953",
     "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "record_bonus": "消费30元，获得3积分",
    "bonus": 3000,
     "add_bonus": 30,
    "balance": 3000,
    "add_balance": -30,
    "record_balance": "购买焦糖玛琪朵一杯，扣除金额30元。",
     "custom_field_value1": "xxxxx"，
      "custom_field_value2": "xxxxx"，
    "notify_optional": {
        "is_notify_bonus": true,
        "is_notify_balance": true,
        "is_notify_custom_field1":true
    }
}

参数说明：

参数名	必填	类型	示例值	描述
code	是	string(20)	1231123	卡券Code码。
card_id	是	string（32）	p1Pj9jr90_SQ RaVqYI239Ka1erkI	卡券ID。
background_pic_url	否	string（128）	https://mmbiz.qlogo.cn/	支持商家激活时针对单个会员卡分配自定义的会员卡背景。
bonus	否	int	100	需要设置的积分全量值，传入的数值会直接显示
add_bonus	否	int	100	本次积分变动值，传负数代表减少
record_bonus	否	string(42)	消费30元，获得3积分	商家自定义积分消耗记录，不超过14个汉字
balance	否	int	100	需要设置的余额全量值，传入的数值会直接显示在卡面
add_balance	否	int	100	本次余额变动值，传负数代表减少
record_balance	否	string(42)	购买焦糖玛琪朵一杯，扣除金额30元。	商家自定义金额消耗记录，不超过14个汉字。
custom_field_value1	否	string（12）	白金	创建时字段custom_field1定义类型的最新数值，限制为4个汉字，12字节。
custom_field_value2	否	string（12）	8折	创建时字段custom_field2定义类型的最新数值，限制为4个汉字，12字节。
custom_field_value3	否	string（12）	500	创建时字段custom_field3定义类型的最新数值，限制为4个汉字，12字节。
notify_optional	否	JSON	--	控制原生消息结构体，包含各字段的消息控制字段
is_notify_bonus	否	bool	true	积分变动时是否触发系统模板消息，默认为true
is_notify_balance	否	bool	true	余额变动时是否触发系统模板消息，默认为true
is_notify_custom_field1	否	bool	false	自定义group1变动时是否触发系统模板消息，默认为false。（2、3同理）

返回说明

数据示例：

{
    "errcode": 0,
    "errmsg": "ok",
    "result_bonus": 100,
    "result_balance": 200,
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}

参数名	描述
errcode	错误码，0为正常
errmsg	错误信息
result_bonus	当前用户积分总额
result_balance	当前用户预存总金额
openid	用户openid

注意事项

1.开发者可以同时传入add_bonus和bonus解决由于同步失败带来的幂等性问题。同时传入add_bonus和bonus时

add_bonus作为积分变动消息中的变量值，而bonus作为卡面上的总积分额度显示。余额变动同理。

2.开发者可以传入is_notify_bonus控制特殊的积分对账变动不发送消息，余额变动同理。