微信平台会员卡专区（一）

会员卡升级公告

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

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

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

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

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

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

更新日志

1.新版会员卡介绍

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

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

     （a）

2.须知

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

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

3.会员卡玩法介绍

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

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

4.创建会员卡接口详情

4.1 创建会员卡接口

    支持开发者调用该接口创建会员卡，并获取card_id，用于投放。调用该接口前，请开发者详读《创建卡券接口》，快速录入会员卡卡面必要信息。

接口调用请求说明

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

参数说明

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
        }
    }
}

接口字段对应表

参数说明

base_info字段：

返回说明

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

开发者注意事项

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网页接口）、卡券货架、公众号群发以及公众号被动回复消息领取，开发者可以选择一种或者多种。请参考以下各种投放方式详情。

特别注意

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

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

5.1 创建二维码接口

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

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

    微信提供addCard接口供商户前端网页调用,用于将一张或多张卡券添加到用户卡包。详情见批量添加卡券接口

 （微信扫一扫>微信卡券接口>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 接口激活

激活方式说明

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

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

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

接口详情

接口调用请求说明

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

参数说明

{
    "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"
}

返回说明

数据示例：

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

6.2 一键激活 

6.2.1 普通一键激活

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

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

接口说明

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

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

参数说明

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

参数说明

{
    "card_id": "pbLatjnrwUUdZI641gKdTMJzHGfc",
    "service_statement": {
        "name": "会员守则",
        "url": "www.qq.com"
    },
    "bind_old_card": {
        "name": "老会员绑定",
        "url": "www.weixin.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": [
            "喜欢的电影"
        ]
    }
}

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

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

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

推送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>

参数说明

步骤四：同步会员数据

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

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

接口说明

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

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=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": []
    },
    "user_card_status": "NORMAL",
    "has_active": false
}

6.2.2 跳转型一键激活

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

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

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

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

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

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

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

具体方式如下：

       用户点击提交后，微信会在商户的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请求方式: POST
URL:https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=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，开发者可以通过更新会员信息接口更新用户会员数据。

参数说明

7 更新会员信息

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

接口调用请求说明

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

参数说明

{
    "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），不会有积分变动通知。

参数说明：

返回说明

数据示例：

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