> 微信公众号开发手册 > 会员卡专区(一)

会员卡专区

会员卡升级公告

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

-强化客户端一级入口:会员到店即用,快速定位商户会员卡;

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

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

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

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

更新日志

版本号 更新内容 更新时间
V1.0

1.支持创建/更新会员卡直接拉出支付付款码付款,微信支付

  进一步打通会员卡

2.一键激活接口升级,一键激活支持商户设置绑定老会员url、

 设置自定义选项以及设置用户填写一键激活信息后跳转至商户

 页面

2016-6-20
V1.1

1.开发者在变动积分/余额消息时,支持开发者控制发/不发系统模板消息

2.支持商户设置某一张卡支持用户修改信息

2016-8-16

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

1.新版会员卡介绍

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

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

会员卡专区(一)

     (a)

会员卡专区(一)
 (b)

微信公众平台开发概述》、《开始开发》以及《微信卡券接口说明,确保你能了解公众平台和卡券接口的基本术语和调用方法。

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

会员卡专区(一)


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




           会员卡专区(一)                        会员卡专区(一)

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


创建卡券接口,快速录入会员卡卡面必要信息。

接口调用请求说明

HTTP请求方式: POST
URL: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
            },
            "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.xxx.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(24)             会员卡类型。            

background_                

pic_url                

否             string(128)            

商家自定义会员卡背景图,须                

先调用上传图片接口将背景图上传至CDN,否则报错,

卡面设计请遵循微信会员卡自定义背景设计规范  ,像素大小控制在

1000像素*600像素以下

          

base_info             是             JSON结构             基本的卡券数据,见下表,所有卡券类型通用。            
prerogative             是            

string(3072)                 

会员卡特权说明。            
auto_activate             否             bool             设置为true时用户领取会员卡后系统自动将其激活,无需调用激活接口。            
wx_activate             否             bool             设置为true时会员卡支持一键开卡,不允许同时传入activate_url字段,否则设置wx_activate失效。填入该字段后仍需调用接口设置开卡项方可生效。            
supply_bonus             是             bool             显示积分,填写true或false,如填写true,积分相关字段均为必填。            
bonus_url             否             string(128)             设置跳转外链查看积分详情。仅适用于积分无法通过激活接口同步的情况下使用该字段。            
supply_balance             是             bool             是否支持储值,填写true或false。如填写true,储值相关字段均为必填。            
balance_url             否             string(128)             设置跳转外链查看余额详情。仅适用于余额无法通过激活接口同步的情况下使用该字段。            
custom_field1             否             JSON结构             自定义会员信息类目,会员卡激活后显示,包含name_type和url字段            
custom_field2             否             JSON结构             自定义会员信息类目,会员卡激活后显示,包含name_type和url字段            
custom_field3             否             JSON结构             自定义会员信息类目,会员卡激活后显示,包含name_type和url字段            
name_type             否             string(24)            

会员信息类目名称。

FIELD_NAME_TYPE_LEVEL              等级

FIELD_NAME_TYPE_COUPON        优惠券                

FIELD_NAME_TYPE_STAMP            印花

FIELD_NAME_TYPE_DISCOUNT      折扣

FIELD_NAME_TYPE_ACHIEVEMEN  成就

FIELD_NAME_TYPE_MILEAGE          里程                 

url             否             string(128)             点击类目跳转外链url            
bonus_cleared             否             string(128)             积分清零规则。            
bonus_rules             否             string(128)             积分规则。            
balance_rules             否             string(128)             储值说明。            
activate_url             是             string(128)             激活会员卡的url。            
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             每使用5积分。            
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"                

不显示任何码型

brand_name             是             string(36)             商户名字,字数上限为12个汉字。            
title             是             string(27)            

卡券名,字数上限为9个汉字

(建议涵盖卡券属性、服务及金额)。            

color             是             string(16)             券颜色。按色彩规范标注填写Color010-Color100            
notice             是             string(48)             卡券使用提醒,字数上限为16个汉字。            
description             是             string(3072)             卡券使用说明,字数上限为1024个汉字。            
sku             是             JSON结构             商品信息。            
quantity             是             int             卡券库存的数量,不支持填写0,上限为100000000。            
date_info             是             JSON结构             使用日期,有效期的信息。            
type             是             string            

使用时间的类型

支持固定时长有效类型

固定日期有效类型

永久有效类型(DATE_TYPE_PERMANENT)

begin_timestamp                 

否            

unsigned int                

type为DATE_TYPE_FIX_TIME_RANGE时专用,

表示起用时间。从1970年1月1日00:00:00至起用时间的秒数

(东八区时间,单位为秒)            

end_timestamp                 

否             unsigned int            

type为DATE_TYPE_FIX_TERM_RANGE时专用,表示结束时

(东八区时间,单位为秒)             

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码

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。        






































































返回说明

{   
"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日,若要设置更久的有效期,可以选择永久有效类型的有效期。


审核事件推送,会员卡审核通过后可以正式投放会员卡。

 JS-SDK网页接口)、卡券货架、公众号群发以及公众号被动回复消息领取,开发者可以选择一种或者多种。请参考以下各种投放方式详情。

特别注意

1. 开发者调用接口投放的会员卡为无会员信息的“卡套”,会员卡编号、积分、余额等信息需在用户领取会员卡后调用激活/绑定会员卡接口更新上。

2. 调用激活/绑定会员卡接口的凭证为Code码及card_id,开发者需在调用投放会员卡时通过接口或领取卡券事件记录code码与会员OpenID的关系。

创建二维码接口

会员卡专区(一)

批量添加卡券接口

  会员卡专区(一)

 (微信扫一扫>微信卡券接口>addcard接口)

领取事件推送中,推送至开发者服务器。

示例: 在二维码投放方式中设置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 接口激活

激活方式说明

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

   1. 用户必须在填写资料后才能领卡,领卡后开发者调用激活接口为用户激活会员卡;

  2. 是用户可以先领取会员卡,点击激活会员卡跳转至开发者设置的资料填写页面,填写完成后开发者调用激活接口为用户激活会员卡。

接口详情

接口调用请求说明

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

参数说明

参数             是否必须             说明            
access_token             是             调用接口凭证            
POST数据             是             JSON数据            
{
    "init_bonus": 100,
    "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_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             错误信息。            






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请求方式: POST
URL: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": []
    }
}  

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

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

6.3 自动激活

接口说明

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

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

参数说明

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

7 更新会员信息

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

接口调用请求说明

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

参数说明

参数             是否必须             说明            
access_token             是             调用接口凭证            
POST数据             是             JSON数据            
{
    "code": "12312313",
    "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "record_bonus": "消费30元,获得3积分",
    "bonus": 3000,
    //可以传入第三方系统记录的积分全量值"balance": 3000,
    //可以传入第三方系统记录的余额全量值"record_balance": "购买焦糖玛琪朵一杯,扣除金额30元。",
    "custom_field_value1": "xxxxx",
    "notify_optional": {
        "is_notify_bonus": false,
        "is_notify_balance": true,
        "is_notify_custom_field1":true
    }
}

    值得注意的是,如果开发者做不到实时同步积分、余额至微信端,我们强烈建议开发者可以在每天的固定时间点变更积分,一天不超过三次。当传入的积分值与之前无变化时(传入的bonus=原来的bonus),不会有积分变动通知。

参数说明:

参数名             必填             类型             示例值             描述            
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             需要设置的积分全量值,传入的数值会直接显示            
record_bonus             否             string(42)             消费30元,获得3积分             商家自定义积分消耗记录,不超过14个汉字。            
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