Member Card Upgrade Notice

From May 15, 2016, the Weixin Coupons Team started to upgrade the member card capabilities to help merchants better manage their members.

-The primary entries to member cards were optimized on Weixin, so that members can locate the cards quickly in stores.

-Different card backgrounds can be customized based on membership levels.

-By scanning code in stores, new users can receive cards and existing users can open cards quickly to enjoy such features as ordering meals and making purchases.

-Issue membership invitation messages to users immediately after they make payments using Weixin to enroll new members quickly.

-New member card categories are added. As of April 20, 2016, only the merchants who provide products and services falling under the supported member card categories can create member cards. The existing member cards are not affected. For more information, please see"Update of Supported Weixin Member Card Categories"

Contents

1. What's New in the Member Card

2. Instructions

3. How to Use Member Cards

4. Details of the "Create Member Card" API

4.1 Creating Member Cards

4.2 Obtaining Member Card Review Results

4.3 Setting Test Whitelist

5. Issuing Member Cards

5.1 Creating QR Codes

5.2 Adding One or More Coupons a Web Page

5.3 Issuing Member Cards via Gallery

5.4 Issuing Member Cards via an Official Account Message

5.5 Recording Users' Card Receipt Behaviors

5.6 Collecting Issuance Channel Data

6. Activating Member Cards

6.1 API-based Activation

6.2 Quick Activation

6.3 Automatic Activation

7. Updating Member Information

# 1. What's New in the Member Card

Based on the native capabilities, Weixin Cards & Offers Team adds capabilities such as card background customization, an in-store QR code scanning solution, post-payment message templates, and member tag-based group messages, and upgrades the Cards & Offers messaging capability to help merchants manage members in a better way.

-(a) Supported custom backgrounds specified by developers.

-(b) Upgraded cards & offers messages. Loyalty point/Balance changes are automatically sent via message templates that may carry promotion information.

(a)

# 2. Instructions

Before reading this part, read Homepage, Getting Started, and Weixin Coupon APIs to ensure that you understand basic terms and call methods of the Weixin Official Accounts Platform and coupon APIs.

Generally, for the calling order of member card APIs, see the following procedure:

# 3. How to Use Member Cards

In-Store QR Code Scanning Quick Pay with Member Cards Connecting Member Cards to CRM

Connecting Member Cards to the Payment System Linking Old Members Top-Up with Member Cards

<a href="https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1479824356&version=1&lang=zh_CN&platform=2 "Card Activation Component"" target="_blank">Card Activation Component

Connecting Cards & Offers to Mini Programs

# 4. Details of the "Create Member Card" API

# 4.1 Creating Member Cards

Developers can call this API to create a member card, and obtain card_id to issue the member card. Before calling this API, read the "Upload Image" API and Homepage in the description of "Create Coupon" API, and quickly record required information displayed on the member card.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

Parameters

POST data example:

{
    "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": "Hai Di Lao",
                "code_type": "CODE_TYPE_TEXT",
                "title": "Hai Di Lao Member Card",
                "color": "Color010",
                "notice": "Present this coupon to the waiter at the time of use",
                "service_phone": "020-88888888",
                "description": "Using with other coupons is not allowed",
                "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": "Use Now",
                "custom_url": "http://weixin.qq.com",
                "custom_url_sub_title": "6 Chinese characterstips",
                "promotion_url_name": "Promotion Entrance 1",
                "promotion_url": "http://www.qq.com",
                "need_push_on_view": true
            },
             "advanced_info": {
               "use_condition": {
                   "accept_category": "Shoes",
                   "reject_category": "Adidas",
                   "can_use_with_other_discount": true
               },
             "abstract": {
                   "abstract": "Weixin Restaurant introduces a variety of new dishes. We look forward to your visit!",
                   "icon_url_list": [
                       "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj
  piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
                   ]
               },
               "text_image_list": [
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "This dish is cooked in a unique way with selective ingredients to tickle the taste buds of diners to the greatest extent. "
                   },
                   {
                       "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
                       "text": "This dish offers balanced nutrition to cater to the public's taste. It is suitable for all ages."
                   }
               ],
               "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": "Entrance 2",
                "tips": "It is displayed after activation.",
                "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
        }
    }
}

Table of the API's fields

Parameters

base_info:

advanced_info

Response Description

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

Notes

*1. Member cards can be created only for some categories. If a member card is to be created for an unsupported category, an error code is returned. For the supported items, see Update of Supported Weixin Member Card Categories.

2. When creating a member card, you need to specify the information item to be displayed after the member card is activated. Currently, the loyalty points, balance, level, coupons, mileage, stamp, achievements, and discounts can be displayed. A maximum of three member information items can be displayed on Weixin 6.2 and later. To be specific, a maximum of three fields among supply_bonus, supply_balance, custom_field1, custom_field2, and custom_field3 can be selected during creation of a member card.

3. When creating coupons, you must specify a time stamp earlier than January 19, 2038. To specify a longer validity period, you can select Permanently Effective.

# 4.2 Obtaining Member Card Review Results

After a member card is created by calling the API, the system automatically submits the member card for review. The review results are sent as events within three business days to the developer. In addition, the status of the member card can be queried by calling an API.

Coupon Approval Event

When the generated coupons are approved, Weixin pushes the event to the URL entered by the developer. For details, see Coupon-related Event Push. After approval, The member card can be officially put into use .

# 4.3 Setting Test Whitelist

If a member card is not approved, the developer can whitelist the tester's Weixin ID for them to claim the card. Note that the information of the card claimed in the whitelisted state is not updated with coupons in real time. For details, see Issuing Coupons.

# 5 Details of the "Issue Member Card" API

Weixin Member Cards can be claimed by scanning a QR code, by tapping a link on a web page (For details, see JS-SDK Description Documentation), or from Gallery, a broadcast message of an Official Account, or a message passively replied by an Official Account. Developers can choose one or more issuance methods as described below.

Notes

1. A member card issued by calling the API is a "card set" without information such as the number, loyalty points, and balance. Such information needs to be updated by calling the member card activation or linking API after the user claims the member card.

2. The credential for calling the member card activation or linking API is code and card_id. Before calling the "Issue Member Card" API, the developer needs to record the relationship between the code and the member's OpenID via the API or card claiming event.

# 5.1 Creating QR Codes

Create a QR code for the member card and print and place it in the store, so that customers can scan it to claim member cards. You can scan the following QR code to try to claim it. If you have claimed it before, you can scan it to quickly open the member card. For details about this API, see Issuing Coupons.

# 5.2 Adding One or More Coupons in a Web Page

Weixin provides the addCard API for merchants to call at front-end webpage. This API can be used to add one or more coupons to the user's Cards & Offers. See JS-SDK Documentation for details.

(Weixin Scan > Cards & Offers > addcard API)

# 5.3 Issuing Member Cards via Gallery

Introduction to Gallery

The gallery allows developers to call an API to generate an HTML5 page for coupon receipt and obtain the page link required to issue coupons. For details about the API, see Issuing Coupons.

# 5.4 Issuing Member Cards via an Official Account Message

The developer can send a member card to a user by using a broadcast message of an Official Account or a customer service message. For details, see Issuing Coupons.

# 5.5 Recording Users' Card Receipt Behaviors

After a user receives a member card, Weixin pushes a member card receipt event to the developer server. In this way, the developer can record a relationship between the user's OpenID and the code of the member card, and distinguish between receipt channels (see section 1.5) based on parameters in the event.

For details, see Coupon-related Event Push.

# 5.6 Collecting Issuance Channel Data

The outer_id field is added to help developers collect statistics about card issuance data of each channel. After different values of outer_id are entered in the JSON structure of card_ext, when users receive cards, the corresponding values of outer_id are passed into Coupon-related Event Push messages, which are pushed to the developer server.

Example: Set outer_id to 1 in the QR code issuance mode.

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

Get the event XML file

<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 Activating Member Cards

After a user receives a member card, you can call this API to activate the member card, and specify initial values for member information, such as the loyalty points, balance, level, and number of the member card. Currently, Weixin member cards can be activated in three ways: API-based activation, quick activation, and automatic activation.

Notes

1. Developers can select an appropriate activation procedure based on service scenarios. Only one of the three activation methods can be selected.

2. To activate a member card, developers need to pass in the code that is obtained when a user receives the member card, and specify the member card number membership_number according to the code.

# 6.1 API-based Activation

Description

In the API-based activation method, developers need to develop a web page for users to enter information. Usually, two activation procedures are available:

1. A user must enter information before claiming a member card. After the member card is claimed, the developer calls the activation API to activate the member card for the user.

2. A user claims a member card and then taps the member card activation button to go to an information page set by the developer. After the user enters required information, the developer calls the activation API to activate the member card for the user.

API details

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN

Parameters

{
    "init_bonus": 100,
    "init_bonus_record":" Initial points synchronization",
    "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"
}

Response Description

Example:

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

# 6.2 Quick Activation

6.2.1 Common Quick Activation

Quick activation is a convenient activation solution provided by Weixin. After claiming a member card, a user can tap "Activate the Member Card" to go to the official information page. Weixin automatically pulls activation information previously entered by the user, so the user does not need to re-enter the activation information, and the mobile number does not need to be re-verified. In this way, the member card is quickly activated, and the activation rate of member cards is increased. For the specific procedure, see the following figure.

Step 1: Enter the wx_activate field in the creation API

API Description

To allow quick activation in Weixin, set wx_activate to "true" in member_card when creating a member card. For details, see the "Create Member Card" API.

If a merchant uses custom member card numbers, the developer can navigate users to the merchant's page after they enters relevant information and activate member cards for the users.

Parameters

POST data example:

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

Notes

1. If auto_activate is specified, both activate_url and the quick activation API do not take effect.

2. If activate_url field is specified, the quick activation API do not take effect.

3. Specify only one of activate_url, auto_activate, and wx_activate.

Step 2. Set the card activation API

After specifying wx_activate during member card creation, developers need to call this API to set options required for users to activate the member cards. Otherwise, the settings for quick activation do not take effect.

API Request Format

HTTP request method: POST
URL:https://api.weixin.qq.com/card/membercard/activateuserform/set?access_token=TOKEN

Parameters

{
    "card_id": "pbLatjnrwUUdZI641gKdTMJzHGfc",
    "service_statement": {
        "name": "Membership rules",
        "url": "https://www.qq.com"
    },
    "bind_old_card": {
        "name": "Links old members",
        "url": "https://www.qq.com"
    },
    "required_form": {
        "can_modify": false,
        "rich_field_list": [
            {
                "type": "FORM_FIELD_RADIO",
                "name": "Hobbies",
                "values": [
                    "Piano",
                    "Dance",
                    "Football"
                ]
            },
            {
                "type": "FORM_FIELD_SELECT",
                "name": "Interests",
                "values": [
                    "Guo Jingming",
                    "Han Han",
                    "Nanpai Sanshu"
                ]
            },
            {
                "type": "FORM_FIELD_CHECK_BOX",
                "name": "Occupation",
                "values": [
                    "Racing driver",
                    "Traveler"
                ]
            }
        ],
        "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": [
            "Favorite movie"
        ]
    }}

common_field_id_list supports the following options:

Step 3: Receive a member information event notification

After a user enters and submits member information, an event is pushed to the merchant. After receiving the event notification, the developer can call the activation API to pass in information such as the member card number and initial loyalty points or call the member information pulling API to obtain the member information to manage the member card.

Example of pushing an XML data packet

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

Parameters

Step 4: Synchronize member data

After receiving the event notification, the developer can call the activation API to pass in information such as the member card number and initial loyalty points or call the member information pulling API to obtain the member information. For details, see the "Activation Member Card" API.

Step 5: Call the member information pulling API

API Description

This API allows developers to query member information by CardID and code.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN

Parameters

POST Data

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

Response Data

{
    "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": "postgraduate"
            }
        ],
        "custom_field_list": [
      {
        "name": "Hobbies",
        "value": "Piano",
        "value_list": []
      },
      {
        "name": "Interests",
        "value": "Guo Jingming",
        "value_list": []
      },
      {
        "name": "Occupation",
        "value": "",
        "value_list": [
          "Racing driver",
          "Traveler"
        ]
      }
    ]
    },
    "user_card_status": "NORMAL",
    "has_active": false
}

6.2.2 Redirect-based Quick Activation

Redirect-based quick activation allows merchants to redirect users to a merchant-defined web page after the users submit member information for activation. In redirect-based quick activation, member cards are activated by merchants. Merchants can provide logics for activation, activation bonuses, and activation condition determining on the destination web pages. This also ensures that member cards are activated in a timely manner. It is applicable to merchants who use custom member card numbers.

Step 1: Enter fields related to redirect-based quick activation in the creation or update API.

To redirect users to a merchant-defined web page after activation, merchants need to specify the following parameters for the creation or update API.

{
    "card": {
         "member_card": {
     ························
      ························
    "wx_activate": true, "wx_activate_after_submit" : true,
   //Specifies whether to enable redirect-based quick activation. "wx_activate_after_submit_url": "https://qq.com"
      // The URL to which users are redirected after they submit information }
    }
}

Step 2. Set the card activation API

For details, see 6.2.1.

Step 3: Obtain the information submitted by users

After entering and submitting information for activation, users are redirected to a merchant-defined web page. The Merchant can obtain the user-entered information from the web page, check the activation qualification of the users, and confirm the information.

The specific operations are as follows:

After users submit information, Weixin appends the merchant's URL with user-entered information obtaining parameters such as activate_ticket, openid, and card_id and encrypts code-encrypt_code. For example, if the wx_activate_after_submit_url field specified by the merchant is www.qq.com, the obtained URL is www.qq.com&card_id=pbLatjvFdsLDUMoN8JqcsGeiMHKk&encrypt_code=Bupk8bb9xxxxxx3rdXV6fClBVtkHQplYohdzGvgDl4%3D&outer_str=&openid=obLatjjwDxxxxxxxoGIdwNqRXw&activate_ticket=fDZv9eMQAFfrNr3XBoqhb%2F%2BMSDM0yjDF6CdiUhC%2BOlEaxb0clsUxxxxxxxxxxxd6yQsjRMRu4kAcKTibYLN5tmHBdll1b6zQRsLF53MpKjGU%3D.

Developers can obtain the user-entered information from activate_ticket for logic determination on the developer's page.

API Description

This API allows developers to obtain user-entered information from activate_ticket.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN

Parameters

POST Data

{
    "activate_ticket" : "abcdefg"
}

Response Data

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

Notes:

1. When calling this API, developers need to use the AppID of the member card. Otherwise, an error occurs.

2. After obtaining the ticket from the URL, developers need to call urldecode.

Step 4: Activate the member card by calling the activation API

After receiving the event notification, the developer can call the activation API to pass in information such as the member card number and initial loyalty points or call the member information pulling API to obtain the member information. For details, see the "Activation Member Card" API.

# 6.3 Automatic Activation

API Description

To allow automatic activation of member cards, set auto_activate to "true" in base_info when creating a member card to obtain card_id. For details, see the "Create Member Card" API.

It should be noted that after auto_activate is specified, both quick activation settings and the activation URL specified in the API-based activation are not displayed. After users claim the member cards, the system automatically activates the member cards for the users, and information such as loyalty points and balance is displayed as "0". Developers can update member information by calling the "Update Member Information" API.

Parameters

# 7 Updating Member Information

After a member paid with the member card, the developer can call this API to update the member's information. To facilitate subsequent notification and other extended features, the developer needs to notify Weixin of each information change after payment.

API Request Format

HTTP request method: POSTURL:https://api.weixin.qq.com/card/membercard/updateuser?access_token=TOKEN

Parameters

{
    "code": "179011264953",
     "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "record_bonus": "Get 3 points for spending 30 CNY",
    "bonus": 3000,
     "add_bonus": 30,
    "balance": 3000,
    "add_balance": -30,
    "record_balance": "Purchased a cup of caramel macchiato. Deducted 30 CNY.",
     "custom_field_value1": "xxxxx",
      "custom_field_value2": "xxxxx",
    "notify_optional": {
        "is_notify_bonus": true,
        "is_notify_balance": true,
        "is_notify_custom_field1":true
    }
}

Parameters:

Response Description

Example:

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

Notes

1. Developers can pass in both add_bonus and bonus to solve the idempotence issue caused by synchronization failure. When both add_bonus and bonus are passed in, add_bonus is a variable in loyalty points change messages, and bonus is the total loyalty points displayed on the card. The same rule applies to a balance change.

2. Developers can pass in is_notify_bonus to avoid sending a message for a special loyalty points change. The same rule applies to a special balance change.