# Issuing Friend's Vouchers
# This section describes how to issue and work with Friend's Vouchers as well as related APIs.
# 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:
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.
Call the "Create QR Code" API to generate a voucher receipt QR code.
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:
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.
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:
- 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.