# Contents

1. Receiving Coupons in Mini Program

2. Checking Coupons in Mini Program

3. Mini Program Card Activation Component

4.Redirecting to Mini Program from Coupons

# Receiving Coupons in Mini Program

# Scenario

Merchants who run campaigns via Mini Programs can issue coupons to users, who then add the coupons to Cards & Offers in their Weixin. When making payments for orders, users can directly redeem the coupons in Card & Offers to enjoy discounts for the services or products they buy.

In addition, users can add the tickets purchased from some ticketing Mini Programs to Cards & Offers for use upon ticket checking.

# Procedures

  1. You must have an Official Account with coupon permission and a verified Mini Program account.

  2. You need to apply for an Open Platform account, to which the Mini Program account and Official Account are linked. For more information on Open Platform, see Weixin Open Platform.

  3. Create coupons and obtain the card_id by following the instructions in Coupon API Documentation and "Create Coupon" API.

  4. Call the wx.addcard API in the Mini Program and process the callback for successful receipt.

  5. Call the Decoding API using the card_id and code (encrypted code) obtained in the Step 3 to get the real code.

  6. Record user's openid in Mini Program, the code received by the user, and the card_id.

  7. Process the coupon receipt event, record the user's openid in Official Account, and the code received by the user and the card_id.

# API Description

For more information on wx.addcard API, see wx.addcard.

# Notes

  1. The api_ticket in the signature involved in the wx.addcard API should be passed to the ticket obtained by the Official Account which creates the coupon.

  2. After a user receives the coupon, the coupon receipt event will be pushed to developer's server for processing. For more information, see Coupon-Related Event Notifications.

  3. You can determine the source of the user's coupon via outer_str.

  4. This feature only supports base library 1.1.0 or above. For a Mini Program, the compatibility with lower version should be ensured.

# Checking Coupons in Mini Programs

# Scenario

You can call this API to allow users to check and present their coupons in Mini Programs.

# Procedures

  1. When a user enters the Mini Program, you must obtain the coupon's card_id and code (real code) received by the user. 2. Call the wx.opencard API to open a coupon for the user to check and use.

# API Description

For more information on wx.opencard API, see wx.opencard.

# Notes

  1. After receiving a coupon, the user will automatically return to the Mini Program page. If you want the user to stay on the coupon page for additional operations, call the wx.opencard API in the callback of wx.addcard function.

  2. The code returned after the success request for wx.addcard is an encrypted field, and must be decrypted before wx.opencard can be called. For more information, see Decoding API.

# Mini Program Card Activation Component

# Scenario

You can develop your own membership modules within the Mini Program, and embed the card activation process into it. Weixin coupon feature provides the card activation component for member cards in Mini Programs.

When a user enters the card activation component in the Mini Program, the information they entered during the card activation in Weixin will be fetched and entered, so that the user can activate the card in Mini Program quickly.

The card activation component combines "card registration" and “add to Cards & Offers" features, eliminating the need of verification via mobile phone and greatly increasing the merchants' efficiency.

The card activation component can be a redirect-based one, or a non-redirect one.

Notes:

  1. The Official Account must have the Weixin coupon feature before you can call the card activation component in the Mini Program. For more information, see Weixin Coupon Documentation.

  2. You must have the basic knowledge of coupon development before you can call the component. For more information, see Weixin Coupon APIs.

# Procedures

Redirect-based card activation:

  1. Create a member card, select "wx_activate":true,"wx_activate_after_submit" : true" for the card activation method, input information in activate_app_brand_user_name and activate_app_brand_pass to activate Mini Program page, and get card_id. For more information, see "Create Member Card" API.
  2. Set the required and optional fields for activating the card. For more information, see the "Set Card Activation Fields" API.
  3. Obtain the parameters required by card activation component.
  4. Determine whether to call the card activation plug-in based on whether the user is a new one and the Weixin version.
  5. Call the card activation plug-in for the user to activate the card, and process the callback of the card activation plug-in.
  6. Obtain the user information for card activation and activate the user's member card.

The workflow is as follows:

Non-redirect card activation:

  1. Create a member card, select "wx_activate":true,"wx_activate_after_submit" : false" for the card activation method, and obtain the card_id. For more information, see the "Create Member Card" API.
  2. Set the required and optional fields for activating the card. For more information, see the "Set Card Activation Fields" API.
  3. Obtain the parameters required by card activation component.
  4. Determine whether to call the card activation plug-in based on whether the user is a new one and the Weixin version.
  5. Call the card activation plug-in for the user to activate the card, and process the callback of the card activation plug-in.
  6. Obtain the user information for card activation.

# API Description

# API 1: Obtain card activation plug-in parameters

API Description

This API is used to get the parameters required to call the card activation plug-in.

Request Parameters

Parameter Description
access_token Token of the Official Account creating the card
JSON Request data
URL https://api.weixin.qq.com/card/membercard/activate/geturl?access_token=  ACCESS_TOKEN
{ "card_id" : "pbLatji6o5g7hJh8Otuvux4y1ty0", "outer_str" : "123" }
Parameter Required Description
card_id Yes card_id of member card
outer_str No Indicates the channel from which the card is received.
{   "errcode": 0,   "errmsg": "ok",   "url": "https://mp.weixin.qq.com/bizmall/activatemembercard?    action=preshow&&enxxxxxxx=MjM5Mzc0OTEwMA%3D%3D#wechat_redirect" }

Response Parameters

Parameter Description
errcode Error code
errmsg Error message indicating the cause for the error
url Returned URL, which contains the parameters required to call the card activation plug-in.

Notes: 1. The parameters returned for this API must be entered in the card activation plug-in API as they are, and the urldecode operation is required.

# API 2: Open card activation plug-in in Mini Program

API Description

  1. This API is used to open the card activation plug-in in your Mini Program.

  2. As this is a Mini Program API, you must learn about how to call Mini Program APIs before calling it. For more information, see Coupon-Related Event Notifications.

  3. It is supported by base library 1.3.0 or above. Compatibility with lower versions should be ensured.

  4. It is supported by Weixin 6.5.9 or above on iOS devices, and 6.5.10 or above on Android devices. Please use Weixin on an iOS device for debugging first.

Open another Mini Program linked with the same Official Account.

OBJECT Parameters:

Parameter Type Required Description
appId String Yes The appid of the official plug-in to be opened. It is always wxeb490c6f9b154ef9 and cannot be changed.
extraData Object No The data to be passed to the target Mini Program, which can obtain the data from App.onLaunch() and App.onShow().
success Function No The callback function for a successful API call
fail Function No The callback function for a failed API call
complete Function No The callback function used for a completed API call (it is always executed whether the call is successful)

Success Response Parameters:

Parameter | Type | Description | errMsg | String | API request result

Sample code:

wx.navigateToMiniProgram({   appId: 'wxeb490c6f9b154ef9', // It is always the appid and cannot be changed.    extraData: data, // Include encrypt_card_id, outer_str and biz. The parameters come from the link obtained in the Step 3.   success: function() {    },   fail: function() {   },   complete: function() {   } })

Response Description

Analyze the data returned from the card activation Mini Program in App.onShow.

  1. Determine whether data.referrerInfo.appId is the appId wxeb490c6f9b154ef9 of the card activation Mini Program. If not, stop the process.
  2. Determine whether there is data for data.referrerInfo.extraData. If not, it indicates that the user swipes left to return or taps the return button without activating the card, or the user has activated the card.
  3. If activation is successful, get the activate_ticket, card_id and code parameters from data.referrerInfo.extraData for next operations.

Notes: 1. Calling this API on Weixin DevTools does not actually cause the redirect to another Mini Program, but the DevTools verifies whether the redirect is successful. 2. The Weixin DevTools can debug processing of received parameters by the target Mini Program.

# API 3: Obtain user information submitted during card activation (for redirect-based card activation component)

API Description

This API is used to fetch the field values a user entered during the card activation.

Request Parameters

Parameter Description
access_token Token of the Official Account creating the card
JSON Request data
URL https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN
{     "activate_ticket" : "abcdefg"         }
Parameter Required Description
activate_ticket Yes The activation ticket in the callback function called after the card is activated through redirect-based card activation component. It is used to get the user information for activating card.
{
     "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": []
     } 
}

Response Parameters

Type Description
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
info Member information
custom_field_list The list of member information items set by developer, such as Hobbies.
name Member information item name
value Member information item value, such as Level.
value_list Response value for a multi-choice item
value_list Response value for a multi-choice item
common_field_list Weixin-defined information items

common_field_id_list supports the following options:

Parameter Description
USER_FORM_INFO_FLAG_MOBILE Mobile number
USER_FORM_INFO_FLAG_SEX Gender
USER_FORM_INFO_FLAG_NAME Name
USER_FORM_INFO_FLAG_BIRTHDAY Birthday
USER_FORM_INFO_FLAG_IDCARD ID No.
USER_FORM_INFO_FLAG_EMAIL Email
USER_FORM_INFO_FLAG_LOCATION Address
USER_FORM_INFO_FLAG_EDUCATION_BACKGRO Education Background
USER_FORM_INFO_FLAG_INDUSTRY Industry
USER_FORM_INFO_FLAG_INCOME Income
USER_FORM_INFO_FLAG_HABIT Hobbies
  • Note: 1. This API can only be called by the redirect-based card activation component. The callback function of non-redirect card activation component does not contain activate_ticket.

# API 4: Obtain user information submitted during card activation (for non-redirect card activation component)

API Description

This API is used to fetch the field values a user entered during the card activation.

Request Parameters

Parameter Description
access_token Token of the Official Account creating the card
JSON Request data
URL https://api.weixin.qq.com/card/code/get?access_token=TOKEN
{     "card_id" : "abcdefg",     "code" : "abcdefg"         }
Parameter Required Description
card_id No Card Id. It is optional for a member card with a non-custom code.
code Yes Member card code
  • Response data
{
     "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": "Weixin"
             }
         ],
         "custom_field_list": []
     },
     "user_card_status": "NORMAL" 
}

Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
openid User's unique identifier in this Official Account
nickname User alias
bonus Points
balance Points balance
sex User gender
user_info Member information
custom_field_list The list of member information items set by developer, such as Hobbies.
common_field_list Weixin-defined information items, such as points
name Member information item name
value Member information item value, such as Level.
user_card_status Current status of member card. NORMAL: Normal; EXPIRE: Expired; GIFTING: Gifting to another user; GIFT_SUCC: Gifted successfully; GIFT_TIMEOUT: Gifting timed out; DELETE: Deleted; UNAVAILABLE: Unavailable.

common_field_id_list supports the following options:

Parameter Description
USER_FORM_INFO_FLAG_MOBILE Mobile number
USER_FORM_INFO_FLAG_SEX Gender
USER_FORM_INFO_FLAG_NAME Name
USER_FORM_INFO_FLAG_BIRTHDAY Birthday
USER_FORM_INFO_FLAG_IDCARD ID No.
USER_FORM_INFO_FLAG_EMAIL Email
USER_FORM_INFO_FLAG_LOCATION Address
USER_FORM_INFO_FLAG_EDUCATION_BACKGRO Education Background
USER_FORM_INFO_FLAG_INDUSTRY Industry
USER_FORM_INFO_FLAG_INCOME Income
USER_FORM_INFO_FLAG_HABIT Hobbies

# API 5: Activate a member card received by a user (for redirect-based card activation component)

API Description

This API is used to fetch the field values a user entered during the card activation.

Request Parameters

Parameter Description
access_token Token of the Official Account creating the card
JSON Request data
URL https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN
{
     "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" 
}

Parameter Required Type Description
membership_number Yes string(20) The member card number entered by developer and displayed as a serial number in user's Cards & Offers. It can be the same as the code value.
code Yes string(20) The code obtained by the user upon the card receipt.
card_id No string (32) Coupon ID. It is required for a coupon with a custom code.
background_pic_url No string(128) Merchant-customized member card background image. The "Upload Image" API should be called first to upload the background image to the CDN, otherwise an error is returned. The card should be designed by following the "Weixin Member Card Backgroud Design Guidelines".
activate_begin_time No unsigned int The start time of validity of card after its activation (expressed as a Unix timestamp). It defaults to the data_info upon card creation if left empty.
activate_end_time No unsigned int The end time of validity of card after its activation (expressed as a Unix timestamp). It defaults to the data_info upon card creation if left empty.
init_bonus No int Initial points. It defaults to 0 if left empty. Init_bonus_record
init_balance No int Initial balance. It defaults to 0 if left empty.
init_custom_field_value1 No string(12) The initial value of custom_field1 when the card is created. It should not be longer than 12 bytes.
init_custom_field_value2 No string(12) The initial value of custom_field2 when the card is created. It should not be longer than 12 bytes.
init_custom_field_value3 No string(12) The initial value of custom_field3 when the card is created. It should not be longer than 12 bytes.

Response Data

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

Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message

# Notes

  • If a user has received the Weixin member card, you can obtain the user's unionid through the "Obtain User Information" API. After the user authorizes to log in to the Mini Program, the user's existing member account can be linked with the Mini Program.
  • Two processes should be designed for member card activation: for Weixin 6.5.9 or above on iOS devices and Weixin 6.5.10 or above on Android devices, card activation component can be invoked; for lower versions of Weixin, the Mini Program's own registration page must be developed, on which users complete the registration to receive the member cards.

# Redirecting to Mini Program from Coupons

# Scenario

When creating a coupon, a merchant can set the access to the services provided by the card/coupon to the path of a Mini Program.

# Procedures

  1. You need to link the Mini Program to the Official Account by following the steps described in Linking Mini Program to Official Account.

  2. Create a coupon, and set the "cell" in the coupon to the path of the Mini Program.

  3. Process the information obtained upon the redirection to the Mini Program.

# API Description

  • Create a member card.
{ "card": {
     "card_type": "MEMBER_CARD",
     "member_card": {
         "base_info": {
             "custom_url_name": "Use Now",
             "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 Chinese characterstips",
             "promotion_url_name": "More discounts",
           "promotion_url": "http://www.qq.com",
             "promotion_app_brand_user_name": "gh_86a091e50ad4@app",
             "promotion_app_brand_pass":"API/cardPage"
        }
         } 
}

Field Name Description Example
custom_app_brand_user_name User_name of the Mini Program to which the redirection is made through the custom entry button. It takes a format of original id+@app. gh_86a091e50ad4@app
custom_app_brand_pass Address of the Mini Program page to which the redirection is made through the custom entry button. API/cardPage
center_app_brand_user_name User_name of Mini Program gh_86a091e50ad4@app
center_app_brand_pass Address of the Mini Program page to which the redirection is made through the custom entry button centered on the top of coupon. API/cardPage
promotion_app_brand_user_name User_name of Mini Program gh_86a091e50ad4@app
promotion_app_brand_pass Address of the Mini Program page to which the redirection is made through the custom promotional entry button. API/cardPage
activate_app_brand_user_name User_name of Mini Program gh_86a091e50ad4@app
activate_app_brand_pass Address of the activated Mini Program page API/cardPage
custom_field1, custom_field2, custom_field3 The information item fields at the top of the member card, with the following two fields
app_brand_user_name User_name of Mini Program for a custom information item. It takes a format of original id+@app gh_86a091e50ad4@app
app_brand_pass Path of Mini Program for a custom information item API/cardPage
custom_cell1, custom_cell2 Custom entry on member card, with the following two fields
app_brand_user_name User_name of the Mini Program to which the redirection is made through the custom entry button. It takes a format of original id+@app gh_86a091e50ad4@app
app_brand_pass Address of the Mini Program page to which the redirection is made through the custom entry button. API/cardPage
bonus_app_brand_user_name User_name of the Mini Program for the points information item. It takes a format of original id+@app. gh_86a091e50ad4@app
bonus_app_brand_pass Address of the Mini Program page to which the redirection is made through the points button. API/cardPage
balance_app_brand_user_name User_name of the Mini Program for the balance information item. It takes a format of original id+@app. gh_86a091e50ad4@app
balance_app_brand_pass Address of the Mini Program page to which the redirection is made through the balance button. API/cardPage

* Please call the Coupon Update API to update the Mini Program page to the structure of external redirect link, and retain the original H5 fields for redirect.

  • Obtain redirection parameters

After a user is redirected from a coupon to the Mini Program, you can obtain the card_id and encrypt_code that initiate the redirection, as well as the user's openid in Official Account. You must call the Decoding API to decode the encrypt_code into the real code.