# Issuing Friend's Vouchers

# 1 API Description

This section describes the channels and methods of issuing Weixin vouchers. We recommend that developers read this document carefully to prevent the failure in sharing issued vouchers.

# 2 Note

Issuance of shared vouchers is slightly different from that of other vouchers. Shared vouchers can be issued only by using an offline QR code (excluding tapping and holding to recognize the QR code), an HTML5 page opened by Weixin Shake with iBeacon, and an HTML5 page in a Wi-Fi environment. You can also scan a QR code to go to an HTML5 page to receive a shared voucher. Other issuance channels are not available now.

# 3 Use Cases

# 3.1 Issuance via QR Code

# 3.1.1 Scenario

QR codes are usually used to issue merchants' vouchers via stores, posters, and leaflets. After generating a QR code by calling the specified API, the merchant can post the QR code on the cashier desk or promotional materials such as posters and leaflets. A user can scan the QR code to receive the voucher and share it to the list of shared vouchers, so that the user and the user's friends can use the voucher.

# 3.1.2 How to use

To complete the preceding steps, developers need to perform the following operations:

  1. Create a Friend's Voucher and submit it for review. Upon approval, log in to the merchant backend on the Weixin Official Accounts Platform, and add the Friend's Voucher to the inventory.

  2. Call the "Create QR Code" API to generate a voucher receipt QR code.

  3. Listen on the voucher receipt event, record the number of issued vouchers, and make statistics of data.

# 3.1.3 API List

Step API Purpose API Property
1 Create QR Code Creates a QR code to get the URL for displaying the QR code Issuance
2 Push Voucher Receipt Event Gets user information such as the openid, code, and card_id after the user receives a voucher Event push

# 3.2 Issuance via HTML5 Page

# 3.2.1 Scenario

Developers can develop a voucher receipt HTML5 page, and convert the URL of the HTML5 page into a QR code or issue the voucher via the HTML5 page configured through Weixin Shake or Weixin Wi-Fi. This channel is applicable to merchants who want to customize the style of a voucher receipt page to highlight the brand value or define a receipt procedure (for example, including a game).

Note:

  1. Friend's Vouchers can be issued only in offline mode. For example, the Friend's Vouchers can be received by scanning a voucher QR code, from an HTML5 page that is opened via Weixin Scan, or from an HTML5 page that is opened via Weixin Wi-Fi or iBeacon. Other channels are not supported.

  2. For more information, click Wi-Fi and Shake Nearby (iBeacon).

# 3.2.2 API Calling Process

# 3.2.3 API List

Step API Purpose API Property
1 Get JSAPI_TICKET Obtains JSAPI_TICKET and pass it to the JS SDK configuration file Basic
2 Get Voucher's API_TICKET Obtains the voucher's API_TICKET and pass it to cardext for signature Issuance
3 Add Vouchers in Batch Adds shared vouchers to the user's voucher list in batch Issuance
4 Push Voucher Receipt Event Gets user information such as the openid, code, and card_id after the user receives a voucher Event push

# 4 API Details

# 4.1 Setting Test Whitelist

If a Friend's Voucher is rejected, the developer can set a whitelist for receiving and sharing it. Unapproved shared vouchers are visible only to users in the whitelist. For details, see the "Set Test Whitelist" API.

# 4.2 Creating QR Code

API Request Format


HTTP request method: POST https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

Parameters

Parameter Required Description
POST data Yes JSON data
access_token Yes The credential for API call

POST Data

Developers can generate a QR code to allow users to receive a single voucher. In this case, the POST data is as follows:


{

    "action_name": "QR_CARD",

    "expire_seconds": 1800,

    "action_info": {

        "card": {

            "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",

            "code": "198374613512",

            "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",

            "is_unique_code": false,

            "outer_id": 1

        }

    }}


Parameter Required Type Sample Value Description
code Yes string(20) 110201201245 Voucher code. It is required only when the use_custom_code field is true.
card_id No string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc Voucher ID
openid No string(32) oXch-jkrxp42VQu8ldweCwDt97qo Receiver's OpenID. The voucher can only be received by this user. It is required only when the bind_openid field is true.
expire_seconds No unsigned int 60 The validity period of the QR code. It ranges between 60 seconds and 1800 seconds. If it is not specified, the QR code is permanently effective.
is_unique_code No bool false Specifies a QR code for voucher issuance. A code is randomly assigned to the created QR code. The code cannot be used after the voucher is received. Available values: True or False (default).
outer_id No int 12 Scene value of receipt, which is required for collecting statistics on data of the receipt channel. It is set to 0 by default. It is an integer containing a maximum of 60 bits. This custom scene value is carried in the event triggered when the user receives a voucher.

Note:

  1. If the developer sets is_unique_code to true, ensure that the voucher is approved and is available in the inventory. Otherwise, an error is reported.

Response Data

Data example:


{

    "errcode": 0,

    "errmsg": "ok",

    "ticket": "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",

    "expire_seconds": 1800,

    "url": "http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o",

    "show_qrcode_url": " https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH98DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0czVzRlSWpsamlyM2plWTNKVktvAAIE6SfgVQMEgDPhAQ%3D%3D"

}


Parameter Description
errcode Error code
errmsg Error message
ticket The ticket of the QR code. This ticket is used to call the "Exchange Ticket for QR Code" API to exchange for the QR code within the validity period.
url The URL obtained by resolving the QR code image. Developers can generate the required QR code image based on this URL.
show_qrcode_url The URL to display the QR code. After tapping this URL, the user is redirected to the QR code page.

# 4.3 Getting JSAPI_TICKET

API Request Format


HTTP request method: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi

Response Data


{
    "errcode": 0,
    "errmsg": "ok",
    "ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
    "expires_in": 7200
}

Parameter Description
errcode Error code
errmsg Error message
ticket JSAPI_TICKET obtained
expires_in Validity period. A ticket is effective for two hours within which it remains unchanged.

# 4.4 Getting Voucher's API_TICKET

API Request Format


HTTP request method: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card

Response Data


{
    "errcode": 0,
    "errmsg": "ok",
    "ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",
    "expires_in": 7200
}

Parameter Description
errcode Error code
errmsg Error message
ticket Voucher's API_TICKET received
expires_in Validity period. A ticket is effective for two hours within which it remains unchanged.

# 4.5 Adding Vouchers in Batch (addcard)

To receive Friend's Vouchers, you need to upgrade Weixin to the latest version. This API is supported as of Weixin 6.3.6 for iOS and Weixin 6.3.7 for Android. Developers can determine the user's Weixin version before calling the addcard API. For details, see "Determine User's Weixin Version" and "Add Vouchers in Batch" APIs.

# 4.6 Voucher Receipt Event

After a user receives a Friend's Voucher, an event is pushed to the developer server. See voucher-related event pushing mechanism.

# 5 Help

# 5.1 Error Codes

Error Code Description How to Debug
40053 Incorrect JSON structure The card_id or the parameter name is incorrect. Refer to the example for troubleshooting.
43008 WeChat Pay or the "Issue Voucher after Payment" API is not activated for the current account. Therefore, the feature of transferring Friend's Vouchers after payment cannot be set. Activate WeChat Pay
45021 The list of voucher-giving rules contains more than 10 rules Delete some voucher-giving rules in the list
47001 Incorrect JSON structure Refer to the example for troubleshooting based on the location indicated in the error message

# 5.2 FAQs

1. How can I distinguish between the receipt channels?

Developers can specify the outer_id field (the custom channel value) when creating a QR code or HTML5 page to add a voucher. This value is carried in the receipt event and pushed to the developer server, to help developers identify the issuance channel for each voucher's code.

2. Why can't I receive a voucher by tapping and holding a QR code?

Friend's Vouchers can be issued only via offline channels. Online channels (such as broadcast messages from Official Accounts or QR codes that are extracted by tapping and holding image) are restricted.