Gift Card API Documentation

Updated On Description
2016/11/15 Supported adding, deleting, modifying and querying galleries
2016/12/7 Updated "Create Gallery" API to add theme structure
2016/12/14 Added the event of gifting gift card
2016/12/21 Changed request method from GET to POST for "Fetch in Batch" API
2016/12/27 Added exchange card type
2017/1/5 Supported setting the maximum number of times a gift card is allowed to be gifted
2017/1/19 Added page_title field to allow customizing page title
2017/2/8 Added "Remove Gallery Page" API
2017/2/20 Added application process
2017/4/25 Supported "Post-Payment Invoicing" feature
2017/6/2 Added "Send a Gift Card to a Group" feature
2017/12/25 1. Supported purchasing gift cards for users themselves; 2. Supported querying a single order/multiple orders; 3. Supported adding product thumbnails and descriptions; 4. Added merchant self-configuration of Mini Program; 5. Supported marketing features; 6. Supported custom channel vales for Mini Programs

# 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

image

# 2.2 Receiving a Gift Card

image ## 2.2 Gift Cards in Cards & Offers image # 3. Prerequisites

# 3.1 Supported Categories

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

Category Sub-Categories
Shopping Department stores, shopping malls/shopping streets, supermarkets, convenience stores, general food, healthcare food, alcohol, non-staple food stores, clothing, footwear/bags, jewelries & accessories, cosmetics, daily necessities, watches/clocks/glasses, flowers and gifts, maternal and child supplies, sports outdoor, musical instruments, books/newspapers/magazines, pharmacies/pharmacies, digital appliances, home textiles, building materials/hardware/mechanical instruments, integrated e-commerces
Life Services Car sales, gas stations, housekeeping services, healthcare, wedding services, car repair
Hotel Star hotels, resorts, express hotels
Dinner Cantonese cuisine, tea restaurant, Sichuan cuisine, Hunan cuisine, Northeast cuisine, Northwest cuisine, hot pot, buffet, snacks, fast food, Japanese cuisine, Korean cuisine, Southeast Asian cuisine, Western food, bread & dessert, cafe, JiangZhe cuisine, Other foods, bar/club, food delivery
Entertainment Beauty salon, manicure, Spa bath, gym, foot massage

# 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

# 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

# 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.
  1. It is recommended to use the merchant ID exclusively for gift cards for an easier account reconciliation.
  1. 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.

Parameter Description
card_id Coupon/Card ID that identifies a group of same coupons/cards. It contains a specified number of codes.
code Coupon/Card code that uniquely identifies a coupon/card. It is used in coupon redemption, and can be customized by merchants.
openid User's unique ID under the Official Account
access_token Credential for calling an API. It is valid for 7200 seconds, and is refreshed for each API request. It can be obtained using the "Get access_token" API. You need to save it properly by enabling credential caching.
jsapi_ticket The signature ticket to be used when the JS-SDK APIs for invoking the Weixin native features are called in webpages within Weixin. For more information, see JS-SDK Documentation.
api_ticket The temporary ticket signed when Weixin Cards & Offers APIs are called. It is valid for 7200 seconds, within which it remains unchanged for repeated requests. This ticket can be obtained using the "Get api_ticket" API.
card_ext Additional information of expandable coupons/cards, used to pass basic coupon/card information during coupon/card issuance.
outer_str Scene value of coupon/card receipt channel. The merchant can enter a custom scene value to card_ext for coupon/card issuance. When a user receives a coupon/card, the scene value is pushed to the merchant with the coupon/card receipt event.
Event push The coupon/card approval, receipt, deletion and redemption events are pushed to the server URL entered by the developer in the Official Accounts Platform Developer Center.
Custom Entries When creating coupons/cards using an API, a merchant can customize the entries through which a redirection is made from the coupon/card details page to the external URLs.
Gift Card Consumption When the balance of a gift card decreases, the gift card is considered to be consumed. The scenarios include but are not limited to offline deduction through POS, and online consumption.

# 5.3 Development Procedures

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

image

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

Parameter Description
Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

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

Structure Structure Field Description Required
card Coupon/card information Yes
card_type GENERAL_CARD Coupon/card type Yes
general_card background_pic_url Gift card background image No
base_info Basic coupon/card data. See the table below. This field is applicable to all coupons/cards. Yes
advanced_info Coupon/card details (text and images) No
sub_card_type Card type. Supported types: Yes
GIFT_CARD: gift card; VOUCHER: exchange card
auto_activate Indicates whether to activate card automatically. If no activation is required, enter "true". No
supply_bonus Indicates whether to support loyalty points. Enter "true" or "false" (default). Yes
supply_balance Indicates whether to support balance. Enter "true" or "false" (default). Yes
init_balance Initial balance displayed on the card when a user purchases it No
custom_field1 A custom member information item. It is displayed after the member card is activated. It includes name and URL fields. No
custom_field2 A custom member information item. It is displayed after the member card is activated. It includes name and URL fields. No
custom_field3 A custom member information item. It is displayed after the member card is activated. It includes name and URL fields. No
name Custom information item name No
url Custom information item redirect URL No
need_push_on_view Indicates whether to push event notification when a user taps the gift card. Default is "true". No

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

Structure Field Field Description Required
base_info Basic coupon/card data Yes
giftcard_info price Price of gift card (accurate to cent) Yes
logo_url Merchant logo of the coupon/card. The image dimension is 300*300 pixels. You must upload the logo to CDN first, otherwise an error occurs. Yes
max_give_friend_times Maximum number of times that the gift card can be gifted Yes
code_type Code display type Yes
CODE_TYPE_TEXT: Text; CODE_TYPE_BARCODE: Barcode; CODE_TYPE_QRCODE: QR code; CODE_TYPE_ONLY_QRCODE: QR code without numeric code; CODE_TYPE_ONLY_BARCODE: Barcode without numeric code. Yes
brand_name Merchant name, with a maximum length of 12 characters (enter the name of the merchant who directly provides the service) Yes
title Coupon/card title, with a maximum length of 9 Chinese characters (18 English characters). A combination of coupon/card attributes, service items and amount is recommended. Yes
color Coupon/card color. Enter a value between Color010 and Color100. Yes
notice Usage tips displayed on the main page, with a maximum length of 12 characters, such as: Please present your QR code to redeem the coupon. Yes
description Usage instructions, with a maximum length of 1000 characters (line breaks are allowed). Yes
date_info Information of validity period Yes
type DATE_TYPE_FIX_TIME_RANGE: A fixed time range; DATE_TYPE_ FIX_TERM: A fixed number of days; DATE_TYPE_PERMANENT: Valid permanently. Yes
begin_timestamp Indicates the start time of validity period, and only takes effect when type = DATE_TYPE_FIX_TIME_RANGE. It is expressed as a Unix timestamp, i.e. the number of seconds that have elapsed since 00:00:00 1/1/1970. Yes
end_timestamp Indicates the end time of validity period (in sec), and only takes effect when type = DATE_TYPE_FIX_TIME_RANGE. It is expressed as a Unix timestamp, i.e. the number of seconds that have elapsed since 00:00:00 1/1/1970. Yes
fixed_term Indicates the number of days during which the received coupon/card is valid, and only takes effect when type = DATE_TYPE_FIX_TERM. If the coupon/card is only valid on the day of it receipt, enter 0. Yes
fixed_begin_term Indicates the number of days after which the received coupon/card becomes valid, and only takes effect when type = DATE_TYPE_FIX_TERM. Yes
sku Product information Yes
quantity Coupon/card inventory (quantity). A big value is recommended. Yes
location_id_list Store location ID. Merchants need to enter the store information on the Weixin Official Accounts Platform, or obtain the store location IDs by calling the "Import Store Info in Batch" API No
use_all_locations Indicates whether to support all stores. Enter "true" or "false" (default). Yes
use_custom_code Indicates whether to use custom code. Enter "true" or "false" (default). No
bind_openid Indicates whether to specify the users who receive the coupon/gift. It is recommended to enter "false" for a gift card. No
can_share Indicates whether the coupon/card's native page is sharable. Enter "true" or "false". It is recommended to enter "false" for a gift card. No
can_give_friend Indicates whether the coupon/card can be gifted. Enter "true" (default) or "false". No
get_limit Maximum number of coupon/cards each user can receive. Enter 0. No
service_phone Customer service number No
center_title The button centered on the gift card. It is only displayed when the card status is normal (available for redemption). It is used for encouraging the card use or topping up. No
center_sub_title Words below the centered entry button No
center_url URL of the centered entry button No
custom_url_name Merchant's custom entry button title, which is used with the custom_url field. The length is limited to 5 characters. No
center_app_brand_user_name Username of the Mini Program to which the redirection is made through the custom "cell". It takes a format of "Original ID of Official Account @app" No
center_app_brand_pass Path of the Mini Program to which the redirection is made through the custom "cell". No
custom_url External URL to which a redirection is made through the merchant's custom entry. The content of the target page should match the custom "cell" title. No
custom_url_sub_title Tips shown to the right of the entry button, with a maximum length of 6 characters. No
custom_app_brand_user_name Username of the Mini Program to which the redirection is made through the custom "cell". It takes a format of "Original ID of Official Account @app" No
custom_app_brand_pass Path of the Mini Program to which the redirection is made through the custom "cell". No
promotion_url_name Custom entry button to the promotional page No
promotion_url URL of external redirect link No
promotion_app_brand_user_name Username of the Mini Program to which the redirection is made through the custom "cell". It takes a format of "Original ID of Official Account @app" No
promotion_app_brand_pass Path of the Mini Program to which the redirection is made through the custom "cell". No

advanced_info field

Structure Field Description Required
advanced_info For an exchange card, you can set the details (text and images) of the card. No
text_image_list List of text and images No
image_url Product images, which should be uploaded to CDN first No
text Textual description of products No

Example of Response Data:

{

"errcode":0,

"errmsg":"ok",

"card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"

}

Response Data

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

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:

image

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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/page/add?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

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:

Structure Parameter Description Required
page Structured field for gallery information, which is composed of the following fields.
page_title Gift card gallery title Yes
support_multi Indicates whether to support buying multiple cards at a time and sending to a group. true: Yes; false: No. Default is "false". No
support_buy_for_self Indicates whether to support buying for users themselves. true: Yes; false: No. Default is "false". No
banner_pic_url Banner image at the top of the gift card gallery theme page. The image must be uploaded to CDN first. Recommended image dimension is 750*630 pixels Yes
theme_list JSON structured field for theme Yes
category_list Theme category list No
address Merchant address Yes
service_phone Merchant service number Yes
biz_description Description of refund, invoice or other processes Yes
need_receipt Indicates whether the order for the gallery can be invoiced. Enter "true" or "false" (default). If "true" is entered, the workflow in 2.2 needs to be debugged. No
cell_1 Merchant's custom link that points to refund, invoice or other processes Yes
cell_2 Merchant's custom link that points to refund, invoice or other processes Yes

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

Parameter Parameter Description Required
theme_list Structured field for theme, which is composed of the following fields. Yes
theme_pic_url Theme cover image, which must be uploaded to CDN first. The image dimension cannot be greater than 1000*600 pixels Yes
title Theme title, such as "Christmas", "Gratitude for Family" Yes
title_color Theme title color. Enter the color value. Yes
item_list List of gift cards. It specifies the card values available under the theme. Yes
pic_item_list Cover list Yes
category_index Theme index corresponding to the "title" in category_list. If values are entered in the category_list, this index is required for each theme. Yes
show_sku_title_first Indicates whether the product name is highlighted in the theme page. No
is_banner Indicates whether to set the current theme to the banner theme (main recommendation) No

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

Parameter Parameter Description Required
item_list Structured field for product, which is composed of the following fields. Yes
card_id ID of the card to be sold on gallery Yes
title Product name. It defaults to the card title if left empty Yes
pic_url Product thumbnail. The image dimension cannot be greater than 1000*600 pixels. Yes
desc Product description Yes
pic_item_list Structured field for card image, which is composed of the following fields. Yes
background_pic_url Card image, which must be uploaded to CDN first. The image dimension cannot be greater than 1000*600 pixels. Yes
outer_img_id Custom card image ID No
default_gifting_msg Default greetings on the card, if no content is specified by user. Yes

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

Structure Parameter Description Required
cell Structured field for merchant's custom service entry, which is composed of the following fields Yes
title Title of custom entry Yes
url URL of custom entry Yes

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

Structure Parameter Description Required
category_list Structured field for theme categories, which is composed of the following fields. No
title Theme category title No

# Response Parameters

Example of Response Data:

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

Response Data

Field Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
page_id Gallery ID, used to query gallery details and get gallery URL

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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/page/get?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

{

"page_id" : "abcedfghifk=+Uasdaseq14fadkf8123h4jk"

}

Request Data:

Parameter Description Required
page_id Gallery ID obtained in previous step Yes

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

Parameter Parameter Description
errcode Error code
errmsg Error message
page Structured field for gallery information, which is composed of the following fields.
banner_pic_url Banner image at the top of the gift card gallery theme page. The image must be uploaded to CDN first.
support_multi Indicates whether to support buying multiple cards at a time and sending to a group
support_buy_for_self Indicates whether to support buying for users themselves.
theme_list JSON structured field for theme
category_list Theme category list
address Merchant address
service_phone Merchant service number
biz_description Description of refund, invoice, or other processes
cell_1 Merchant's custom link that points to refund, invoice or other processes
cell_2 Merchant's custom link that points to refund, invoice or other processes

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

Parameter Parameter Description
theme_list Structured field for theme, which is composed of the following fields.
theme_pic_url Theme cover image, which must be uploaded to CDN first.
title Theme title, such as "Christmas", "Gratitude for Family"
title_color Theme title color. Enter the color value.
item_list List of gift cards. It specifies the card values available under the theme.
pic_item_list Cover list
category_index Theme index corresponding to the "title" in category_list. If values are entered in the category_list, this index is required for each theme.
is_banner Indicates whether to set the current theme as the banner theme (main recommendation)

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

Parameter Parameter Description
item_list Structured field for product, which is composed of the following fields.
card_id ID of the card to be sold on gallery
pic_item_list Structured field for card image, which is composed of the following fields.
background_pic_url Card image, which must be uploaded to CDN first.
outer_img_id ID of the custom card image
default_gifting_msg Default greetings on the card, if no content is edited by user.

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

Parameter Parameter Description
cell Structured field for merchant's custom service entry, which is composed of the following fields.
title Title of custom entry
url URL of custom entry

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

Parameter Description
category_list Structured field for theme categories, which is composed of the following fields.
title Theme category title

API Description

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

API Request Format

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/page/update?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

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:

Parameter Parameter Description Required
page Structured field for gallery information, which is composed of the following fields.
page_id Gallery ID to be modified Yes
banner_pic_url Banner image at the top of the gift card gallery theme page. The image must be uploaded to CDN first. Yes
theme_list JSON structured field for theme Yes
category_list Theme category list No
address Merchant address Yes
service_phone Merchant service number Yes
biz_description Description of refund, invoice or other processes Yes
cell_1 Merchant's custom link that points to refund, invoice or other processes Yes
cell_2 Merchant's custom link that points to refund, invoice or other processes Yes

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

Parameter Parameter Description Required
theme_list Structured field for theme, which is composed of the following fields.
theme_pic_url Theme cover image, which must be uploaded to CDN first. Yes
title Theme title, such as "Christmas", "Gratitude for Family" Yes
title_color Theme title color. Enter the color value. Yes
item_list List of gift cards. It specifies the card values available under the theme. Yes
pic_item_list Cover list Yes
category_index Theme index corresponding to the "title" in category_list. If values are entered in the category_list, this index is required for each theme. Yes
is_banner Indicates whether to set the current theme to the banner theme (main recommendation) No

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

Parameter Parameter Description Required
item_list Structured field for product, which is composed of the following fields.
card_id ID of the card to be sold on gallery Yes
pic_item_list Structured field for card image, which is composed of the following fields.
background_pic_url Card image, which must be uploaded to CDN first. Yes
outer_img_id ID of custom card image No
default_gifting_msg Default greetings on the card, if no content is specified by user. Yes

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

Parameter Parameter Description Required
cell Structured field for merchant's custom service entry, which is composed of the following fields.
title Title of custom entry Yes
url URL of custom entry Yes

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

Parameter Parameter Description Required
category_list Structured field for theme categories, which is composed of the following fields.
title Theme category title No

# Response Parameters

Example of Response Data:

{

"errcode" : 0,

"errmsg" : "ok"

}

Response Data

Parameter Description
errcode Error code
errmsg Error message

API Description

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

API Request Format

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/page/batchget?access_token=ACCESS_TOKEN

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

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

Parameter Description
errcode Error code
errmsg Error message
page_id_list List of gift card gallery IDs

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/maintain/set?access_token=ACCESS_TOKEN

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

Request Parameters

Parameter Description
page_id Page_id to be removed
all
maintain

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

Parameter Description
errcode Error code
errmsg Error message
control_info Structured field controlling the results

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

Parameter Description
biz_control_type Statuses of all galleries under the appid controlled by the merchant
system_biz_control_type Statuses of all galleries under the merchant appid controlled by the system
list List of all galleries under the merchant

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

Parameter Description
page_id Unique ID of a gallery
page_control_type Merchant-controlled gallery status
system_page_control_type System-controlled gallery status
  1. 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.
image
  1. Enter the Product Center, and click Activate in Weixin Gift Card.
image
  1. Activate the gift card feature.
image

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

image

Release trial version for test

image

Click Submit for Approval

image

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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/order/get?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

{
    "order_id" : "Z2y2rY74ksZX1ceuGA"
}

Request Parameters

Parameter Description
order_id Gift card order No, which can be obtained via the "Successful Purchase" event or the "Query Orders in Batch" API.

# 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

Parameter Parameter Description
errcode Error code
errmsg Error message
order Structured field for order, which is composed of the following fields.
order_id Order ID
page_id Gallery ID
trans_id WeChat Pay transaction order No.
create_time Creation time of order, expressed as a 10-digit timestamp (UTC+8)
pay_finish_time Completion time of order payment, expressed as a 10-digit timestamp (UTC+8)
total_price Total amount (accurate to cents)
open_id Purchaser's openid
accepter_openid Recipient's openid
outer_str Channel from which the gallery is provided
IsChatRoom Indicates whether the gift card for the order is sent to a group
card_list Structured field for card list, which is composed of the following fields.
card_id
price
code
default_gifting_msg
background_pic_url
outer_img_id
accepter_openid

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/order/batchget?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

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

Request Parameters

Parameter Description
begin_time Start time of the time range, expressed as a 10-digit timestamp (UTC+8)
end_time Start time of the time range, expressed as a 10-digit timestamp (UTC+8)
sort_type Enter "ASC" or "DESC" to indicate the orders are sorted by creation time in an ascending or descending order.
offset Order data offset that indicates the point in the order records where the query should start. A value of 100 means the fetch of order data starts from the 100th order.
count Number of orders to be queried. If Offset is 100, and Count is 10, the query covers the orders from the 100th order to the 110th one.

# 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

Parameter Description
errcode Error code
errmsg Error message
total_count Total number of orders
order_list Order list structure
order Structured field for order, which is composed of the following fields.
order_id Order ID
page_id Gallery ID
trans_id WeChat Pay transaction order No.
create_time Creation time of order, expressed as a 10-digit timestamp (UTC+8)
pay_finish_time Completion time of order payment, expressed as a 10-digit timestamp (UTC+8)
total_price Total amount (accurate to cents)
open_id Purchaser's openid
accepter_openid Recipient's openid
outer_str Channel from which the gallery is provided
IsChatRoom Indicates whether the gift card for the order is sent to a group
card_list Structured field for card list, which is composed of the following fields.
card_id List of the card_ids of the purchased cards
price Price of the card
code Code obtained by the user
default_gifting_msg Default greetings. This field is left empty if user has specified greetings.
background_pic_url Card background image
accepter_openid Recipient's openid when the card is sent to a group

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

Parameter Description
ToUserName Original ID of the Official Account receiving the event
FromUserName Openid of the gift card purchaser (event initiator)
CreateTime Creation time of the event
MsgType Message type
Event Event type. Enter "giftcard_pay_done" to indicate the order has been paid.
PageId Gallery ID
OrderId Order ID

# 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

Parameter Description
ToUserName Original ID of the Official Account receiving the event
FromUserName Openid of the gift card purchaser (event initiator)
CreateTime Creation time of the event
MsgType Message type
Event Event type that indicates the gift card has been gifted.
PageId Gallery ID
OrderId Order ID
IsChatRoom Indicates whether the gift card is sent to a group. true: Yes; false: No.
IsReturnBack Indicates whether the gift card is returned to Cards & Offers if it fails to be accepted within 24 hours. true: Yes; false: No.

# 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

Parameter Description
ToUserName Original ID of the Official Account receiving the event
FromUserName Openid of the gift card recipient (event initiator)
CreateTime Creation time of the event
MsgType Message type
Event Event type. Enter "giftcard_user_accept" to indicate the gift card has been received.
PageId Gallery ID
OrderId Order ID
IsChatRoom Indicates whether the gift card is sent to a group. true: Yes; false: No.

# 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

Parameter Description
ToUserName Original ID of the Official Account receiving the event
FromUserName Openid of the gift card recipient (event initiator)
CreateTime Creation time of the event
MsgType Message type
Event Event type. Enter "user_get_card" to indicate the card has been received.
CardId Cardid
IsGiveByFriend Whether the card is sent from a friend
UserCardCode The code obtained by the user
FriendUserName Card sender's openid
OldUserCardCode Old code. If it is a non-custom code, the code obtained by the recipient will be changed.

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

Parameter Description
ToUserName Original ID of the Official Account receiving the event
FromUserName Openid of the gift card recipient (event initiator)
CreateTime Creation time of the event
MsgType Message type
Event Event type. Enter "user_get_card" to indicate the card has been received.
CardId Cardid
IsReturnBack Indicates whether the coupon/card is returned after being gifted. 1: Yes; 0: Gift the coupon/card again
UserCardCode The code obtained by the user
FriendUserName Card sender's openid
IsChatRoom Indicates whether the card is sent to a group

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/generalcard/updateuser?access_token=TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

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

Parameter Description Required
code Coupon/card code Yes
card_id Coupon/card ID Yes
background_pic_url A merchant can configure custom card background image for a gift card. No
balance The total balance to be specified. It is displayed directly. No
record_balance The merchant's custom card consumption record, with a maximum length of 14 characters. No
custom_field_value1 New value of custom_field1 when the card is created. It should not be longer than 12 bytes. No
custom_field_value2 New value of custom_field2 when the card is created. It should not be longer than 12 bytes. No
custom_field_value3 New value of custom_field3 when the card is created. It should not be longer than 12 bytes. No
can_give_friend Indicates whether to display the Gifting entry after the point value changes No

# Response Parameters

{
    "errcode": 0,
    "errmsg": "ok",
    "result_bonus": 100,
    "result_balance": 200,
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
result_bonus Current user's total points
result_balance Current user's total card balance
openid User's openid
errcode Error code. 0 indicates a successful request.
errmsg Error message

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/code/consume?access_token=TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

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

Request Parameters

Parameter Description Required
code Coupon/card code Yes
card_id Coupon/card ID. It is required for a coupon/card with a custom code. Yes

# Response Parameters

{
    "errcode": 0,
    "errmsg": "ok",
}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/code/get?access_token=TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

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

Request Parameters

Parameter Description Required
code Coupon/card code Yes
card_id Coupon/card ID. It is required for a coupon/card with a custom code. Yes

# 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"
}
Parameter Description
errcode Error code. 0 indicates a successful request.
errmsg Error message
card_id card_id of gift card
begin_time Start time of the card validity period
end_time End time of the card validity period
bonus Current points (ignore it if no point exists)
balance Current balance
code Code of gift card
card_number Card No. displayed on the card. It is same as the code if no value is set.
openid User's openid
order_id Order No. for the gift card

# 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

Protocol HTTPS
HTTP request method POST
Request URL https://api.weixin.qq.com/card/giftcard/order/refund?access_token=ACCESS_TOKEN
POST data format JSON

Request parameters

Parameter Description Required
access_token Credential for calling API Yes
JSON JSON data Yes

POST data example:

{ "order_id": "xxx" }

Request Data:

Parameter Description Required
order_id ID of the order to be refunded Yes

# Response Parameters

Example of Response Data:

{

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

}

Response Data

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

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.

image

# 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

Parameter Type Required Description
paymch_info Object Yes Authorization page field

"paymch_info" is composed of the following fields:

Parameter Type Required Description
mchid String Yes WeChat Pay Merchant ID
s_pappid String Yes Invoicing platform ID, which is provided by the platform

Response parameters

Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

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

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

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

Parameter Type Required Description
paymch_info Object No Authorization page field

"paymch_info" is composed of the following fields:

Parameter Type Required Description
mchid String Yes WeChat Pay Merchant ID
s_pappid String Yes Invoicing platform ID, which is provided by the platform

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

Parameter Type Required Description
auth_field Object Yes Authorization page field

"auth_field" is composed of the following fields:

Parameter Type Required Description
user_field Object Yes Individual invoice fields on authorization page
biz_field Object Yes Company invoice fields on authorization page

"user_field" is composed of the following fields:

Parameter Type Required Description
show_title Int No Indicates whether to enter the invoice title. 0: No; 1: Yes
show_phone Int No Indicates whether to enter the phone number. 0: No; 1: Yes
show_email Int No Indicates whether to enter the email address. 0: No; 1: Yes
custom_field Object No Custom field

"biz_field" is composed of the following fields:

Parameter Type Required Description
show_title Int No Indicates whether to enter the invoice title. 0: No; 1: Yes
show_tax_no Int No Indicates whether to enter the tax code. 0: No; 1: Yes
show_addr Int No Indicates whether to enter the company address. 0: No; 1: Yes
show_phone Int No Indicates whether to enter the phone number. 0: No; 1: Yes
show_bank_type Int No Indicates whether to enter the bank name. 0: No; 1: Yes
show_bank_no Int No Indicates whether to enter the bank account number. 0: No; 1: Yes
custom_field Object No Custom field

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

Parameter Type Required Description
key String Yes Custom field name with a maximum length of 5 characters

Response parameters

Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

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

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

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

Parameter Type Required Description
auth_field Object Yes Authorization page field

"auth_field" is composed of the following fields:

Parameter Type Required Description
user_field Object No Individual invoice fields on authorization page
biz_field Object No Company invoice fields on authorization page

"user_field" is composed of the following fields:

Parameter Type Required Description
show_title Int No Indicates whether to enter the invoice title. 0: No; 1: Yes
show_phone Int No Indicates whether to enter the phone number. 0: No; 1: Yes
show_email Int No Indicates whether to enter the email address. 0: No; 1: Yes
custom_field Object No Custom field

"biz_field" is composed of the following fields:

Parameter Type Required Description
show_title Int No Indicates whether to enter the invoice title. 0: No; 1: Yes
show_tax_no Int No Indicates whether to enter the tax code. 0: No; 1: Yes
show_addr Int No Indicates whether to enter the company address. 0: No; 1: Yes
show_phone Int No Indicates whether to enter the phone number. 0: No; 1: Yes
show_bank_type Int No Indicates whether to enter the bank name. 0: No; 1: Yes
show_bank_no Int No Indicates whether to enter the bank account number. 0: No; 1: Yes
custom_field Object No Custom field

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

Parameter Type Required Description
key String Yes Custom field name with a maximum length of 5 characters

Request example

Request: {} Response: { "errcode": 0, "errmsg": "ok", "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"}] } } }

# 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

Parameter Type Description
ToUserName String Official account ID
FromUserName String User's openid
CreateTime Int Event creation time
MsgType String Message type, which is always "event".
Event String This is always user_authorize_invoice.
SuccOrderId String Order No. for which invoicing is authorized successfully
FailOrderId String Order No. for which invoicing authorization fails
AppId String AppId of the Official Account receiving the event
Source String Authorization source. web: H5 page in Weixin; app: App.

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

Parameter Type Required Description
order_id string Yes Order ID
s_appid String Yes Invoicing platform's appid

Response parameters

Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

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

Parameter Type Description
invoice_status String Order's authorization status. See "Notes".
auth_time Int Authorization time expressed as a 10-digit timestamp (UTC+8)
user_auth_info JSON Structured field for user authorization information, which is displayed only when type=1

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

Parameter Type Description
user_field JSON Structured field for authorization information for an individual invoice
biz_field JSON Structured field for authorization information for a company invoice
title String Individual/company invoice title
phone String Individual/company's phone number
email String Individual's email address
title String Company title
tax_no String Company's tax code
addr String Company's registered address
bank_type String Company's bank
bank_no String Company's bank account number
custom_field JSON Structured field for merchant's custom information

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

Parameter Type Description
key String Merchant's custom information item name
value String Information entered by user in merchant's custom information item

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

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.

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