Gift Card API Documentation

# 1. Gift Card Overview

Weixin provides gift card merchants with a complete process from creation, sale, to the consumption of gift cards. Merchants can create gift cards, create gift card galleries and synchronize balances by calling APIs on the Weixin Official Accounts Platform. Developers can sell the gift cards by configuring the created gift card galleries in the Official Accounts or generating QR codes posted in the stores.

Users can send gift cards to friends to convey good wishes on festivals.

Weixin gift cards offer the following benefits:

1. Users can save the gift cards to Cards & Offers in Weixin, without worrying about losing the cards.

2. Gifting between friends becomes easier and securer.

3. The gift packets given by the gift cards bring pleasant surprises to the recipients of gift cards.

4. With the dynamic code feature provided by Weixin, merchants can ensure a secure QR code-based payment and consumption processes, without the need to develop the security feature by themselves.

5. Merchants can sell the gift cards by configuring the gift card galleries in multiple channels such as Official Account menus, articles, QR codes and ads.

# 2.Gift Card Workflow

The following figures are only for reference.

# 2.1 Purchasing and Gifting a Gift Card

# 2.2 Receiving a Gift Card

# 3.1 Supported Categories

The gift card feature mainly supports the following merchant categories, and does not support virtual categories.

# 3.2 Merchant Qualification Requirements

Weixin gift cards include prepaid balance and specific-item gift cards. A prepaid balance gift card means a card issued upon the receipt of a set amount beforehand, such as 1000-CNY card. An specific-item gift card is used to exchange for specified item, such as a hamburger card. The qualification requirements for merchants vary between the two kinds of cards.

# 3.2.1 Prepaid Balance Gift Cards

A merchant needs to have a single-purpose prepaid card license to conduct gift card business (including prepaid balance gift cards and gift coupons). If the license holder is different from the Official Account owner, one of the following conditions should be met: the cards are issued by the Group; the cards are issued by brand owner; the cards are guaranteed by multi-purpose card license holder.

Additional Required Documents

The documents are submitted by emails currently:

(1) Card issuance by Group: If the single-purpose prepaid card license holder is the Group (parent company), and the Official Account owner applying for prepaid card permission is a subsidiary of the Group which holds more than 50% of the Group's shares, the applicant should additionally provide "Group Authorization Letter for Card Issuance" (affixed with the license holder's official seal) to activate the permission.

(2) Card issuance by brand owner: If the single-purpose prepaid card license holder is the brand owner, and the Official Account owner applying for prepaid card permission is a franchisee authorized by the brand owner, the applicant should additionally provide "Franchise Authorization Letter" (affixed with the license holder's official seal) to activate the permission.

In either of the above two cases, the authorization letter should be prepared by the authorizer and should provide the following information: authorizer information, prepaid card license information, the authorized entity, reason for authorization (issuing cards in the name of the Group/brand owner, and the authorizer's responsibility for redeeming the cards issued by the authorized entity).

(3) Multi-purpose prepaid card license: If an applicant obtains the cooperative authorization of the card issuer or agent holding the "Payment Business License", the applicant can directly email the documents for "Multi-purpose Prepaid Card Business License" along with the "Cooperation Agreement" signed with the license holder (affixed with the license holder's official seal) to activate the permission.

Notes:

(a) The license holder should be the prepaid card issuer, instead of the card agent; (b) After the authorization, the brand owner should entrust the license holder with the card making and issuance, and its Official Account has no permission for prepaid cards. A license holder can sell the prepaid cards only after the evaluation by a legal authority shows no "second settlement" risk. As required by the applicable regulations, card issuers shall issue and sell prepaid cards through physical POSs (point-of-sales). Therefore, it is recommended to prefer merchants providing physical card services.

(c) According to the "Administrative Measures for Prepaid Card Business of Payment Institutions", payment institutions shall conduct prepaid card business in strict accordance with the terms and conditions of the Payment Business License, and shall not conduct prepaid card business in the provinces (autonomous regions/municipalities directly under the central government/municipalities with independent planning status) where no provincial branches are set up. Therefore, local license holders shall not conduct the business nationwide.

In the case of authorization of multi-purpose prepaid-card license holder, in addition to the above information, the following information should be provided in the authorization letter:

(a) Authorizer information, authorizer's license information, the authorized entity, reason for authorization, and the authorizer's responsibility for redeeming the cards issued by the authorized entity.

(b) Basic information of contracted merchant.

(c) Charging items and standards.

(d) Requirements for guaranteeing the rights of cardholders.

(e) Requirements for managing card information, transaction data, terminals and transaction documents.

(f) Merchant's payment receiving account name, bank name, account number and the fund settlement period.

(g) Requirements for account reconciliation, error handling and dispute settlement.

(h) Mechanisms for related business risk and liability for breach of contract.

(i) Termination of agreement, and creditor's rights and settlement of debts after termination.

The supplementary documents should be emailed to weixincard@tencent.com. Submission to Weixin Official Accounts Platform will be supported in the future.

# 3.2.2 Specific-Item Gift Card

For specific-item gift cards, prepaid card qualification is not required. The merchants who provide services falling under the supported categories can develop exchange cards directly without submitting application.

# 4 Preparations

# 4.1 Owning a Verified Official Account and Activating the Cards & Offers Feature

# 4.1.1 Registration Procedures for New Merchants

• A merchant who does not have an Official Account with activated Cards & Offers feature can log in to Weixin Official Accounts Platform to register an Official Account and complete identity verification. For more information, please see Registering with Weixin Official Accounts Platform.
• After the registration, log in to the Weixin Official Accounts Platform, go to Add Plug-in > Cards & Offers to submit required documents and activate the Cards & Offers feature. For more information, please see Weixin Cards & Offers Feature Usage Rules.

# 4.1.2 Registration Procedures for Existing Merchants

• The merchants who have owned an Official Account with activated Cards & Offers feature can choose whether to reuse the application documents for Official Account.

Note: It takes 3-5 business days to approve the application.

# 4.2 Applying for a Verified Mini Program (for gift card only)

Merchants who want to use gift cards need to apply for an independent Mini Program to upload gift card codes and information.

# 4.2.1 Registration Procedures for New Merchants

• A merchant who does not have a Mini Program account can log in to Weixin Official Accounts Platform to register a Mini Program and complete identity verification. For more information, please see Registering Mini Program Account.

# 4.2.2 Reusing Official Account Verification Documents for Quick Registration

• A merchant who have owned a verified Official Account can log in to Weixin Official Accounts Platform, go to Manage Mini Program > Add > Quick Registration and Verification for Mini Program to register the Mini Program and complete identity verification quickly.

# 4.3 Using the Merchant ID Obtained with Official Account

• A merchant needs to use the merchant ID obtained with Official Account to configure the gift cards. For more information, please see Weixin Official Accounts Platform.

Notes:

1. Self-configuration only supports the merchant ID obtained with Official Account, instead of the one obtained with Mini Program.

2. It is recommended to use the merchant ID exclusively for gift cards for an easier account reconciliation.

3. Only merchant IDs of service providers and direct merchants are supported. Those under banks and payment institutions are not supported.

# 5 Development

# 5.1 Instructions

Gift card is a type of Weixin coupons/cards. Before developing the gift card feature, refer to Official Accounts Platform API Documentation, Weixin Cards & Offers API Documentation, and Weixin Cards & Offers Feature Usage Guidelines to get familiar with the basic concepts involved in gift card development and guidelines on gift card operation.

# 5.2 Key Terms

The development process will involve the following terms.

# 5.3 Development Procedures

Gift card development involves such steps as card creation and issuance, as well as card information synchronization, as shown below.

Notes:

This document only describes the main steps for gift card creation. For additional steps, please see the coupon/card API documentation.

1. For differences between custom and non-custom codes and the steps for importing codes, please see:

Weixin Cards & Offers API Instructions

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN&anchor=2.2

Importing Custom Codes:

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025062&token=&lang=zh_CN&anchor=4.1

Weixin Official Accounts Platform Event Handling

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CN

# 5.4 Document References

In the process of gift card development, you may need to refer to the following documents.

Weixin Official Accounts Platform API Documentation (Token acquisition and caching, and event push):

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1445241432&token=&lang=zh_CN

Weixin Cards & Offers API Documentation (gift card creation, custom codes, code import):

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141229&token=&lang=zh_CN

# 6. Creating Gift Cards

# 6.1 Uploading Gift Card Images

You need to upload the Weixin user's gift card logo and background images to the Weixin CDN, and obtain the URLs to be used in logo_url and background_pic_url fields of the Gift Card Creation API.

For more information, see

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN&anchor=2.3

Notes:

• The card background should be designed by strictly following the Weixin VIP Card Background Design Guidelines.
• The images uploaded by merchants will be protected against hotlinking and be restricted from being displayed on the webpages that have a domain name other than the merchant's.

# 6.2 Uploading Gift Card Stores

For a gift card related to geographical locations, we recommend entering the stores when you create the gift card so that it can be automatically placed on top of the card sorting list when a user is near the store.

For more information, see

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025056&token=&lang=zh_CN

# 6.3 Creating Gift Cards

API Description

Gift Card Creation API is a basic API for Weixin Cards & Offers feature, and is used to create a new group of same gift cards and obtain the card_id. After the gift cards are created and approved, the merchant can issue the cards to users using other APIs described in the document. The card inventory balance is decreased with each successful purchase.

API Request Format

Request parameters

POST data example:

{
	"card": {
	    "card_type": "GENERAL_CARD",
	    "general_card": {
	        "sub_card_type": "GIFT_CARD",
	        "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/",
	        "base_info": {
	            "max_give_friend_times": 1,
	            "giftcard_info": {
	                "price": 1
	            },
	            "logo_url": "https://mmbiz.qlogo.cn/mmbiz/p98FjXy8LaeMq67mEpDmkj05EtiaVcGOibVaVux3Agib1ibcHFkCoic7HuQWFawx9XGCNWIO085drjdxTib2nBHlYGAA/0?wx_fmt=gif",
	            "brand_name": "Weixin Cafe",
	            "code_type": "CODE_TYPE_QRCODE",
	            "title": "Gift Card",
	            "color": "Color020",
	            "notice": "Present 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_FIX_TIME_RANGE",
	                "begin_timestamp": 1397577600,
	                "end_timestamp": 1472724261
	            },
	            "sku": {
	                "quantity": 50000000
	            },
	            "get_limit": 0,
	            "use_custom_code": false,
	            "can_give_friend": true,
	            "location_id_list": [
	                213059884
	            ],
	            "center_title": "Centered button at the top",
	            "center_sub_title": "Words under the button",
	            "center_url": "www.qq.com",
	            "center_app_brand_user_name": "gh_86a091e50ad4@app",
	            "center_app_brand_pass": "pages/index/index",
	            "custom_url_name": "What's New",
	            "custom_url": "https://www.starbucks.com.cn/",
	            "custom_app_brand_user_name": "gh_86a091e50ad4@app",
	            "custom_app_brand_pass": "pages/index/index",
	            "need_push_on_view": true
	        },
	        "advanced_info": {
	            "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 for the taste of everyone at all ages."
	                }
	            ]
	        },
	        "supply_balance": true,
	        "prerogative": "Use your gift card to save more money",
	        "auto_activate": true,
	        "init_balance": 10000,
	        "custom_field1": {
	            "name": "General Coupon",
	            "url": "",
	            "app_brand_user_name": "",
	            "app_brand_pass": ""
	        },
	        "custom_field2": {
	            "name": "Exchange Coupon",
	            "url": "",
	            "app_brand_user_name": "",
	            "app_brand_pass": ""
	        }
	    }
	}
}

`Request Data

Gift Card

Note: You can enter values in at most 3 fields among supply_balance, custom_field1, custom_field2, and custom_field3, otherwise an error occurs.

base_info field

advanced_info field

Example of Response Data:

{

"errcode":0,

"errmsg":"ok",

"card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"

}

Response Data

Notes:

1. For the gift cards supporting dynamic codes, please see https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1478005752&version=1&lang=zh_CN&platform=2

2. Gift Card Gallery

7.1 Gallery Styles

The following styles are only for reference:

7.2. Creating Gift Card Gallery

API Description

This API is used to create a gift card gallery which is used to sell gift cards in Official Accounts or stores.

API Request Format

Request parameters

POST data example:

{
    "page": {
        "page_title": "Gift Card",
        "support_multi": true,
        "banner_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
        "theme_list": [
            {
                "theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                "title": "title",
                "title_color": "#FB966E",
                "show_sku_title_first": true,
                "item_list": [
                    {
                        "card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg",
                        "title": "Caramel Coffee Latte"
                    },
                    {
                        "card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs",
                        "title": "Caramel Coffee Latte"
                    }
                ],
                "pic_item_list": [
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings1"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings2"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings3"
                    }
                ],
                "category_index": 0
            },
            {
                "theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                "title": "title_lalala",
                "title_color": "#FB966E",
                "item_list": [
                    {
                        "card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg",
                        "title": "Caramel Coffee Latte"
                    },
                    {
                        "card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs",
                        "title": "Cake"
                    }
                ],
                "pic_item_list": [
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings1",
                        "outer_img_id": "outer_img_id_1"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings2",
                        "outer_img_id": "outer_img_id_2"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings3",
                        "outer_img_id": "outer_img_id_3"
                    }
                ],
                "category_index": 1
            },
            {
                "theme_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                "title": "title_lalala",
                "title_color": "#FB966E",
                "item_list": [
                    {
                        "card_id": "pbLatjiSj_yVRH5XTb2Zsln7DNQg"
                    },
                    {
                        "card_id": "pbLatjlq75CPBR_tYCRdPlxSGlOs"
                    }
                ],
                "pic_item_list": [
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings1",
                        "outer_img_id": "outer_img_id_1"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings2",
                        "outer_img_id": "outer_img_id_2"
                    },
                    {
                        "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/p98FjXy8LafBWIJsGFe7tlPvtBFxXXTPdx5cEuFMcWWsiaR1DyrN5ML3jiaVYZibovA8OrwOylUia6ywvVU6Aqboibw/0",
                        "default_gifting_msg": "Greetings3",
                        "outer_img_id": "outer_img_id_3"
                    }
                ],
                "is_banner": true
            }
        ],
        "category_list": [
            {
                "title": "Theme Category 1"
            },
            {
                "title": "Theme Category 2"
            }
        ],
        "address": "No. 222, Haizhu District, Guangzhou",
        "service_phone": "020-12345678",
        "biz_description": "Refund Guide",
        "cell_1": {
            "title": "Request Invoice",
            "url": "https://open.weixin.qq.com"
        },
        "cell_2": {
            "title": "Request Refund",
            "url": "https://mp.weixin.qq.com"
        }
    }
}

Request Data:

"theme_list" is in a JSON format with the following fields:

"item_list" and "pic_item_list" are in a JSON format with the following fields:

"cell1" and "cell2" are in a JSON format with the following fields:

"category_list" is in a JSON format with the following fields:

# Response Parameters

Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk"
}

Response Data

Notes

1.Gallery URL Construction Rule

You can access the homepage of the gallery by replacing the original page_id in the following URL with the URL encoded page_id**.

https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=123456#wechat_redirect

For example, if page_id is: abcedfghifk=+Uasdaseq14fadkf8123h4jk

URL encoded page_id is: abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk

The final URL:

https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id= abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk #wechat_redirect

2. Channel Values

The outer_str field is provided to indicate channels and can be obtained in "Query Orders" API or relevant callbacks.

For example, if outer_str=abc:

The above URL is changed to:

https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=123456&outer_str=abc#wechat_redirect

page_id is: abcedfghifk=+Uasdaseq14fadkf8123h4jk

URL encoded page_id is: abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk

The final URL:

https://mp.weixin.qq.com/bizmall/giftcard?action=homepage&page_id=abcedfghifk%3d%2bUasdaseq14fadkf8123h4jk#wechat_redirect

3. Gallery's external redirect URL

The URL in "cell" will contain order_id and openid in the GET parameter when the redirection occurs.

For example, if the original data is:

https://mp.weixin.qq.com, it is changed to:

https://mp.weixin.qq.com/?order_id=Z2y2rY4UxUZYitvVGA&openid=oAAAAAKe1ri5AAaAiB50-Ak6Vs1w

4. Setting Whitelist for Approval

• The created gallery can be viewed and purchased only after the merchant applies for its launch and gets the approval.

• As the developer, you can whitelist your own Weixin ID for testing. For more information about API, please see mp.weixin.qq.com > Cards & Offers > Issuing Coupons/Cards > Setting Whitelist.

# 7.3 Querying Gift Card Gallery Info

API Description

This API is used to query the information of a gift card gallery.

API Request Format

Request parameters

POST data example:

{

"page_id" : "abcedfghifk=+Uasdaseq14fadkf8123h4jk"

}

Request Data:

Example of Response Data:

Request Data: | Parameter | Description | Required | | page_id | Gallery ID obtained in the last step | Required | Response parameters: Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "page": {
        "banner_pic_url": "http://img.com/banner_pic",
        "theme_list": [
            {
                "theme_pic_url": "http://img.com/theme_pic",
                "title": "title_lalala",
                "title_color": "#FFFFFF",
                "item_list": [
                    {
                        "card_id": "card_id_lalala"
                    }
                ],
                "pic_item_list": [
                    {
                        "background_pic_url": "http://img.com/bg_pic1",
                        "default_gifting_msg": "Greetings1"
                    },
                    {
                        "background_pic_url": "http://img.com/bg_pic2",
                        "default_gifting_msg": "Greetings2"
                    },
                    {
                        "background_pic_url": "http://img.com/bg_pic3",
                        "default_gifting_msg": "Greetings3"
                    }
                ]
            }
        ]
    }
}

Response Data

"theme_list" is in a JSON format with the following fields:

"item_list" and "pic_item_list" are in a JSON format with the following fields:

"cell1" and "cell2" are in a JSON format with the following fields:

"category_list" is in a JSON format with the following fields:

# 7.4 Modifying Gift Card Gallery Info

API Description

This API is used to update the gift card gallery information.

API Request Format

Request parameters

POST data example:

{
    "page": {
        "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
        "banner_pic_url": "http://img.com/banner_pic",
        "theme_list": [
            {
                "theme_pic_url": "http://img.com/theme_pic",
                "title": "title_lalala",
                "title_color": "#FFFFFF",
                "item_list": [
                    {
                        "card_id": "card_id_lalala"
                    }
                ],
                "pic_item_list": [
                    {
                        "background_pic_url": "http://img.com/bg_pic1",
                        "default_gifting_msg": "Greetings1"
                    },
                    {
                        "background_pic_url": "http://img.com/bg_pic2",
                        "default_gifting_msg": "Greetings2"
                    },
                    {
                        "background_pic_url": "http://img.com/bg_pic3",
                        "default_gifting_msg": "Greetings3"
                    }
                ]
            }
        ]
    }
}

Request Data:

"theme_list" is in a JSON format with the following fields:

"item_list" and "pic_item_list" are in a JSON format with the following fields:

"cell1" and "cell2" are in a JSON format with the following fields:

"category_list" is in a JSON format with the following fields:

# Response Parameters

Example of Response Data:

{

"errcode" : 0,

"errmsg" : "ok"

}

Response Data

# 7.5 Querying Gift Card Gallery List

API Description

This API is used to query all the gift card gallery IDs under the current merchant.

API Request Format

Request parameters

POST data example:

{}

# Response Parameters

Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "page_id_list": [
        "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
        "abcedfghifk=+Uasdaseq14fadkf8123h4jl",
        "abcedfghifk=+Uasdaseq14fadkf8123h4jm",
        "abcedfghifk=+Uasdaseq14fadkf8123h4jn"
    ]
}

Response Data

# 7.6 Removing Gift Card Galleries

API Description

This API is used to remove the gift card galleries under the current merchant.

API Request Format

Request parameters

Request Parameters

POST data example:

Remove a gallery

{
    "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
    "maintain": true
}

or all the galleries under this merchant

{
    "all": true,
    "maintain": true
}

Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "control_info": {
        "biz_control_type": "E_PAGE_CONTROL_BIZ",
        "system_biz_control_type": "E_PAGE_CONTROL_NORMAL",
        "list": [
            {
                "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
                "page_control_type": "E_PAGE_CONTROL_BIZ",
                "system_page_control_type": "E_PAGE_CONTROL_SYSTEM"
            }
        ]
    }
}

Response Data

"control_info" is a structured field with the following components:

"list" is a structured field with the following components:

8. Gift Card Mini Program ============

# 8.1 Activating WeChat Pay Gift Card Permission

# 8.1.1 Applying for WeChat Pay Gift Card Permission

URL:

https://api.weixin.qq.com/card/giftcard/pay/whitelist/add?access_token=TOKEN

Request example

{
    "sub_mch_id": "1900015421"//WeChat Pay sub-merchant ID
}

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "url": "https://pay.weixin.qq.com/index.php/public/product/detail?pid=61&productType=0"
}

Notes

1. The entered merchant ID must be the ID of a service provider or direct merchant. A gift card merchant ID is recommended.

2. The merchant ID must be the one requested via the Official Account, otherwise an error occurs.

3. The token used for calling an API must be the token for the Official Account, otherwise an error occurs.

4. The Official Account calling the API and the merchant ID must have the same owner. Otherwise, please contact the BD (business development) personnel. If the gift card Official Account/Mini Program has a different owner than that of the merchant ID, perform the following steps: _ 1. Contact the WeChat Pay BD personnel to sign the "Application for Linking Official Account/Mini Program with Merchant ID". _ 2. Send the following information to weixincard@tencent.com_ Email Subject: Application for Linking Official Account/Mini Program with Merchant ID for xxx Gift Card Content: Official Account Name 　 Appid of Verified Official Account Official Account Owner Info Appid of Verified Mini Program Mini Program Owner Info Gift Card Merchant ID Company Name of Merchant ID

_3. After verifying the information, we'll handle your application within 5 business days.

# 8.1.2 Confirming Activation of Gift Card Feature

After performing the Step 4.1, click the URL returned in this step to log in to the WeChat Pay Merchant Platform, and click Confirm to activate the gift card feature.

1. Click the URL obtained in Step 4.1 to log in to the WeChat Pay Merchant Platform.

2. Enter the Product Center, and click Activate in Weixin Gift Card.

3. Activate the gift card feature.

# 8.2 Linking Merchant ID to Gift Card Mini Program

URL

https://api.weixin.qq.com/card/giftcard/pay/submch/bind?access_token=TOKEN

Request example

{
    "sub_mch_id": "1900015421",
    "wxa_appid": "wx8638fbedaf138a87"
}

Response Example

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

Notes

1. The entered merchant ID must be the ID of a service provider or direct merchant. A gift card merchant ID is recommended.

2. The merchant ID must be the one requested via the Official Account, otherwise an error occurs.

3. The token used for calling an API must be the one for the Official Account.

4. The Official Account must be linked to the gift card Mini Program. For more information, please see https://mp.weixin.qq.com/debug/wxadoc/introduction/#Linking Official Account to Mini Program

# 8.3 Uploading Mini Program Code

# 8.3.1 Uploading Mini Program Code

URL

https://api.weixin.qq.com/card/giftcard/wxa/set?access_token=TOKEN

Request example

{
    "wxa_appid": "wx123456789",
    "page_id": "asdasdjkafkjaslfjasl+fjas="
}

Response Example

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

Notes

1. The Official Account must be linked to the Mini Program.

2. After uploading the Mini Program code, log in to the Mini Programs Platform to submit the Mini Program for approval.

# 8.3.2 Submitting Mini Program for Release

Enter the basic information of the gift card Mini Program.

After completing the Step 5.1, log in to the Mini Programs Platform (mp.weixin.qq.com), and enter the information of the Mini Program to submit it for approval.

Release trial version for test

Click Submit for Approval

Click Submit for Release

# 9. Gift Card Orders

# 9.1 Querying a Single Gift Card Order

API Description

This API is used to query the order details for an order No.

API Request Format

Request parameters

POST data example:

{
    "order_id" : "Z2y2rY74ksZX1ceuGA"
}

Request Parameters

# Response Parameters

Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "order": {
        "order_id": "Z2y2rY74ksZX1ceuGA",
        "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
        "trans_id": "4001562001201608292531663351",
        "create_time": 123,
        "pay_finish_time": 123,
        "total_price": 123,
        "open_id": "123",
        "accepter_openid": "123",
        "card_list": [
            {
                "card_id": "card_id_1",
                "price": 123,
                "code": "code_123456",
                "default_gifting_msg": "",
                "background_pic_url": "",
                "accepter_openid": "123"
            }
        ],
        "outer_str": "web",
        "IsChatRoom": true
    }
}

Response Data

# 9.2 Querying Gift Card Orders in Batch

API Description

This API is used to query the details of the merchant's orders created during a certain time period.

API Request Format

Request parameters

POST data example:

{
    "begin_time": 1472400000,
    "end_time": 1472716604,
    "sort_type": "ASC",
    "offset": 0,
    "count": 2
}

Request Parameters

# Response Parameters

Example of Response Data:

{
    "errcode": 0,
    "errmsg": "ok",
    "total_count": 47,
    "order_list": [
        {
            "order_id": "Z2y2rY74ksZX1ceuGA",
            "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
            "trans_id": "4001562001201608292531663351",
            "create_time": 123,
            "pay_finish_time": 123,
            "total_price": 123,
            "open_id": "123",
            "accepter_openid": "123",
            "card_list": [
                {
                    "card_id": "card_id_1",
                    "price": 123,
                    "code": "code_123456",
                    "default_gifting_msg": "",
                    "background_pic_url": "",
                    "accepter_openid": "123"
                }
            ],
            "outer_str": "web","IsChatRoom": true
        },
        {
            "order_id": "Z2y2rY74ksZX1ceuGA",
            "page_id": "abcedfghifk=+Uasdaseq14fadkf8123h4jk",
            "trans_id": "4001562001201608292531663351",
            "create_time": 123,
            "pay_finish_time": 123,
            "total_price": 123,
            "open_id": "123",
            "accepter_openid": "123",
            "card_list": [
                {
                    "card_id": "card_id_1",
                    "price": 123,
                    "code": "code_123456",
                    "default_gifting_msg": "",
                    "background_pic_url": ""
                }
            ],
            "outer_str": "web"
        }
    ]
}

Response Data

Notes:

(1) "total_count" in the response is specific to the current query condition. It is similar to the paging implementation "offset/count". When $offset+count=total_count$ in a request, the data fetch ends.

(2) The difference between begin_time and end_time cannot be greater than 31 days.

(3) "count" cannot be greater than 100.

(4) Enter "ASC" or "DESC" for sort_type to indicate the *orders are sorted by creation time in an ascending or descending order.

# 10. Gift Card-Related Events

Notes

Account reconciliation may be needed for the merchants who conduct gift card transactions. Therefore, a higher reliability is required for the callbacks sent to the merchant servers.

If a callback is not received by a merchant, a maximum of 30 retries are allowed within 24 hours.

Upon the receipt of the callback, the merchant, in addition to returning "200" in the Header in response, needs to return the following content:

<xml\>ok</xml\>

to notify Weixin platform that the callback has been received and processed successfully.

Otherwise, the Weixin platform will continue to retry.

# 10.1. Event of Successful Payment for Purchase of Gift Card

Protocol

<xml>

<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>

<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>

<CreateTime>1472631550</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[giftcard_pay_done]]></Event>

<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>

<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>

</xml>

Request Parameters

# 10.2 Event of Gifting Gift Card

Protocol

<xml>

<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>

<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>

<CreateTime>1472631550</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[giftcard_send_to_friend]]></Event>

<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>

<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>

<IsChatRoom>true</IsChatRoom>

<IsReturnBack><![CDATA[true]]></IsReturnBack>

</xml>

Request Parameters

# 10.3. Event of Successful Receipt of Gift Card

Protocol

<xml>

<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>

<FromUserName><![CDATA[obLatjgoYejavUtHsWwrX-2GtFJE]]></FromUserName>

<CreateTime>1472631800</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[giftcard_user_accept]]></Event>

<PageId><![CDATA[OQK0R3MaFnCm74Phw5hwFJlz5sn+jy1zzM2amDidDbU=]]></PageId>

<OrderId><![CDATA[Z2y2rY74ksZX1ceuGA]]></OrderId>

<IsChatRoom>true</IsChatRoom>

</xml>

Request Parameters

# 10.4 Event of Returning Unaccepted Card

If a gift card fails to be accepted within 24 hours, it will be automatically returned to the sender's Cards & Offers. When the card is sent again and received by the recipient, the event changes to a "Card Gifting-Receiving" event.

Receiving a Card

Protocol

<xml>

<ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>

<FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>

<CreateTime>1472551036</CreateTime>

<MsgType> <![CDATA[event]]> </MsgType>

<Event> <![CDATA[user_get_card]]> </Event>

<CardId> <![CDATA[pZI8Fjwsy5fVPRBeD78J4RmqVvBc]]> </CardId>

<IsGiveByFriend>0</IsGiveByFriend>

<UserCardCode> <![CDATA[226009850808]]> </UserCardCode>

<FriendUserName> <![CDATA[]]> </FriendUserName>

<OldUserCardCode> <![CDATA[]]> </OldUserCardCode>

</xml>

Request Parameters

Gifting a Card

Protocol

<xml>

<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>

<FromUserName><![CDATA[obLatjjwDolFjRRd3doGIdwNqRXw]]></FromUserName>

<CreateTime>1474181868</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[user_gifting_card]]></Event>

<CardId><![CDATA[pbLatjhU-3pik3d4PsbVzvBxZvJc]]></CardId>

<UserCardCode><![CDATA[297466945104]]></UserCardCode>

<IsReturnBack>0</IsReturnBack>

<FriendUserName><![CDATA[obLatjlNerkb62HtSdQUx66C4NTU]]></FriendUserName>

<IsChatRoom>0</IsChatRoom>

</xml>

Request Parameters

# 11. Consuming Gift Cards

# 11.1 How to Consume

Offline: In a store, the card holder shows the QR code or barcode for the gift card to the merchant. After recognizing the code, the merchant' POS device requests Weixin to verify the user identity and then deducts the amount from the card balance.

Online: The card holder goes to the merchant's online store via the card to select and purchase products, and select "Gift Card" as the payment method when making payment. When receiving the payment request, the merchant requests Weixin to update the card balance.

# 11.2 Updating Gift Card Info

API Description

This API is used to update the gift card balance when the card is consumed by a user.

API Request Format

Request parameters

POST data example:

{
    "code": "12312313",
    "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,
    "custom_field_value1": "xxxxx",
    "can_give_friend": true
}

Request Parameters

# Response Parameters

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

# 11.3 Terminating Gift Card

API Description

When a gift card is run out or its balance is transfered or linked to another card, this API can be used to terminate the card so that it is no longer used.

API Request Format

Request parameters

POST data example:

{
    "code": "12312313",
    "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

Request Parameters

# Response Parameters

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

# 11.4 Querying Gift Card Info

API Description

This API is used to query the card information (balance, expiration date, order No, etc.) by the card code. If an order is missing after the transaction, the redemption and balance can be processed based on the card information obtained via this API.

API Request Format

Request parameters

POST data example:

{
    "code": "12312313",
    "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

Request Parameters

# Response Parameters

{
    "errcode": 0,
    "errmsg": "ok",
    "card": {
        "card_id": "pbLatjoAAyLz6Pt36wGQNfxNrucU",
        "begin_time": 1397577600,
        "end_time": 1662724261,
        "balance": 1,
        "code": "027691806183",
        "card_number": "027691806183"
    },
    "openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
    "can_consume": true,
    "user_card_status": "NORMAL",
    "order_id": "AQAAPdZIMrAvjeoKBmy2rY6RnF1D",
    "background_pic_url": "http://mmbiz.qpic.cn/mmbiz_jpg/ibV1WeaY2IEuMzDp7RjSPib7GOIvMKPucibziaBPS0ialicialKWiaflOHMb5s1jGvCdZ9Z88kBUnfsUjq5Eo9NOGkH1Jg/0"
}

# 12. After-Sales Processes

# 12.1 Reconciliation

By receiving the order completion event notification and regularly querying the number of completed orders, a merchant can ensure the transactions are reconciled properly. A merchant can also log in to WeChat Pay Merchant Platform to query specific transactions and transaction details for reconciliation.

# 12.2 Refund and Invoicing

According to the applicable laws and regulations, gift card merchants must have a refund-related process in place to protect the rights and interests of users.

A merchant can develop the refund process by calling the Refund API.

Gift card gallery merchants can input the links of invoicing and refund processes when creating the gallery, and developers can develop the pages to process user requests.

# 12.2.1 Refund

API Description

This API is used to refund an order. Note: This API requires higher privacy, so please increase the permission level needed to perform the operation.

API Request Format

Request parameters

POST data example:

{ "order_id": "xxx" }

Request Data:

# Response Parameters

Example of Response Data:

{

    "errcode" : 0,
    "errmsg" : "ok"

}

Response Data

Note: After the refund, the gift card will be removed from the user's Cards & Offers.

# 12.2.2 Post-Payment Invoicing

When creating a gift card, the merchant can set the "need_reciept" field to enable post-payment invoicing. After a user enters and submits the invoice title and other information in the invoicing page which is displayed when the user clicks the "payment successful" message, Weixin server will push an event to the merchant's server.

# 12.2.2.1 Procedures

Enable post-payment invoicing by following the steps below:

Step 1: Use the relevant API to set such information as the merchant ID, appid, and s_appid for post-payment invoicing and the information required to be provided by users on the invoicing page.

Step 2: Set the fields that a user needs to populate in the invoice title page.

Step 3: After the user makes a payment, tap Me > WeChat Pay > Wallet > Transactions in Weixin to go to the Transaction Details of the order. Locate the Invoicing button, and enter the required item information. After you tap Confirm Invoicing, the request result will be sent to you. When the request for invoicing is accepted and processed successfully, a notification indicating the invoice has been issued is sent to the user (If the user has followed the merchant's Official Account, the notification is sent via the Official Account. Otherwise, it is sent via a service message).
Step 4: The merchant receives the message indicating user has authorized invoicing, and sends the invoicing request to the invoicing platform, which then issues the invoice to the merchant.

# 12.2.2.2 Set Post-Payment Invoicing

"Set Post-Payment Invoicing Info" API

API Description

This API is used to specify that when a payment is received by a merchant ID, the invoicing authorization button is displayed on the payment message.

Request

URL:

https://api.weixin.qq.com/card/invoice/setbizattr?action=set_pay_mch&access_token={access_token}

Request method: POST

Request parameters

Data format: JSON

"paymch_info" is composed of the following fields:

Response parameters

Data format: JSON

Examples

{
    "paymch_info": {
        "mchid": "1234",
        "s_pappid": "wxabcd"
    }
}

Response:

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

"Query Post-Payment Invoicing Info" API

Request

URL:

https://api.weixin.qq.com/card/invoice/setbizattr?action=get_pay_mch&access_token={access_token}

Request method: POST

Request parameters

Data format: JSON

If data is null, pass {}

Response parameters

Data format: JSON

If the error code is 0, the following information is returned:

"paymch_info" is composed of the following fields:

Examples

Request:

{}

Response:

{
    "errcode": 0,
    "errmsg": "ok",
    "paymch_info": {
        "mchid": "1234",
        "s_pappid": "wxabcd"
    }
}

# 12.2.2.3 Set Invoicing Page Info

"Set Authorization Page Field Info" API

API Description

This API is used to specify the information that users must provide to authorize invoicing.

Request Description

URL:

https://api.weixin.qq.com/card/invoice/setbizattr?action=set_auth_field&access_token={access_token}

Request method: POST

Request parameters

Data format: JSON

"auth_field" is composed of the following fields:

"user_field" is composed of the following fields:

"biz_field" is composed of the following fields:

"custom_field" is a list, with each component containing the following fields:

Response parameters

Data format: JSON

Examples

{
    "auth_field": {
        "user_field": {
            "show_title": 1,
            "show_phone": 1,
            "show_email": 1,
            "custom_field": [
                {
                    "key": "field1"
                }
            ]
        },
        "biz_field": {
            "show_title": 1,
            "show_tax_no": 1,
            "show_addr": 1,
            "show_phone": 1,
            "show_bank_type": 1,
            "show_bank_no": 1,
            "custom_field": [
                {
                    "key": "field2"
                }
            ]
        }
    }
}

Response:

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

Note

Titles of the individual and company voices are displayed by default.

"Query Authorization Page Field Info" API

API Description

This API is used to check the entries of the invoice title on authorization page.

Request Description

URL:

https://api.weixin.qq.com/card/invoice/setbizattr?action=get_auth_field&access_token={access_token}

Request method: POST

Request parameters

Data format: JSON

If data is null, pass {}

Response parameters

Data format: JSON

If the error code is 0, the following information is returned:

"auth_field" is composed of the following fields:

"user_field" is composed of the following fields:

"biz_field" is composed of the following fields:

"custom_field" is a list, with each component containing the following fields:

Request example

# 12.2.2.4 Receiving Invoicing Event

API Description

After the user authorization, the merchant receives an authorization completion event and requests the invoicing platform for invoicing.

For more information on event push, please see:

http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CN

Request parameters

Data format: xml

Examples

<xml> 
  <ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>  
  <FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>  
  <CreateTime>1475134700</CreateTime>  
  <MsgType> <![CDATA[event]]> </MsgType>  
  <Event> <![CDATA[user_authorize_invoice]]> </Event>  
  <SuccOrderId> <![CDATA[1202933957956]]> </SuccOrderId>  
  <FailOrderId> <![CDATA[]]> </FailOrderId>
  <AppId> <![CDATA[]]> </AppId>
  <Source> <![CDATA[]]> </Source>
</xml>

# 12.2.2.5 Querying Invoicing Information

API Description

This API is used to query the invoicing information for an order when a user completes the authorization.

Request format

URL: https://api.weixin.qq.com/card/invoice/getauthdata?access_token={access_token}

Request method: POST

Protocol: HTTPS

Request parameters

Data format: JSON

Response parameters

Data format: JSON

If the error code is 0, the following information is returned:

"user_auth_info" is in a JSON format with the following fields:

"user_auth_info" is in a JSON format with the following fields:

Request example

{
    "s_pappid": "{s_pappid}",
    "order_id": "{order_id}"
}

Response Data:

Individual invoice title:{
    "errcode": 0,
    "errmsg": "ok",
    "invoice_status": "auth success",
    "auth_time": 1480342498,
    "user_auth_info": {
        "user_field": {
            "title": "Dhxhhx ",
            "phone": "5554545",
            "email": "dhxhxhhx@qq.cind",
            "custom_field": [
                {
                    "key": "field1",
                    "value": "ABCD"
                }
            ]
        }
    }
}

Company invoice title:  {
    "errcode": 0,
    "errmsg": "ok",
    "invoice_status": "auth success",
    "auth_time": 1480342897,
    "user_auth_info": {
        "biz_field": {
            "title": "xxxxx",
            "tax_no": "6464646766",
            "addr": "No. 6, xx Road, xx District, xx City",
            "phone": "1557548768",
            "bank_type": "State-owned",
            "bank_no": "545454646",
            "custom_field": [
                {
                    "key": "field2",
                    "value": "EFGH"
                }
            ]
        }
    }
}

# 12.2.2.6 Invoicing

After receiving the above information, the merchant must forward the information to the invoicing platform for invoicing. An e-invoice can be issued if it is supported. Otherwise, a paper-base invoice can be issued by mail.

# 13.3 Online Customer Service

A merchant can define a custom "cell" on the after-sales help page of a gallery as the entry to the customer service page. When a user is redirected to the service page, the user's order and identity information is passed as well. The merchant can arrange an online chat between customer service agent and the user to offer after-sale service to the user.

# 14. Must-Knows

# 14.1 Gift Card External Redirect Link Protocol

When a user is redirected to the merchant's custom center_url, custom_url and promotion_url from a gift card, openid, encrypt_code and card_id will be contained in the GET parameter.

The encrypt_code is an encrypted code, which needs to be decoded to a real code with Decode API. For example, if the specified URL is: http://www.qq.com,

the redirect URL is:

http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID&openid=xxxx&outer_str=xxxxx

For more information on the Decode API, see Decode API.

When a user is redirected from the gift card to the Mini Program to which the merchant's custom center_url, custom_url, and promotion_url point, you can obtain the parameters needed in the Page.onshow parameter of the Mini Program when the redirection occurs.

# 14.2 Gift Card Gallery External Redirect Link Protocol

When a user is redirected to the after-sales service webpage via the merchant's custom "cell" on the order details page, the order_id and openid are contained in the GET parameter when the redirection occurs.

For example, if the original data is:

https://mp.weixin.qq.com

It will changes to:

https://mp.weixin.qq.com/?order_id=Z2y2rY4UxUZYitvVGA&openid=oAAAAAKe1ri5AAaAiB50-Ak6Vs1w

The openid is the unique identifier of the user under the merchant, and the order_id is the unique identifier of the order.

# 15. Configuring Coupons Under Gift Cards

Merchants can configure WeChat Pay cash coupons that are only used for gift cards. When creating a campaign, set "goods_tag" to "mmbizgiftcard" and ensure that the goods_tag is not passed for other orders under the current merchant ID.

# 16 Contact Us

For any problems during your debugging process,

contact us by emailing to wx_card@tencent.com

Please follow the format below:

Subject: "Feedback About Gift Card Gallery" xxxxx

Problem description: xxxx

page_id: xxxxx

User's Weixin ID: xxx

Time when the problem occurred: xxxxx

Contact: mobile number/Weixin ID