Redeeming Friend's Vouchers

# API Description

This section describes how to redeem Friend's Vouchers for both online and offline purchases.

# Use Cases

# Redemption for Offline Purchase

# Redeem a voucher by scanning a QR code with a code scanner

Scenario

Merchants with development capability and code scanner can redeem a voucher by scanning the QR code using the code scanner. Developers can get the voucher code by scanning the QR code with the code scanner, and then call the code redemption API to quickly redeem the voucher.

API Calling Process

# Redemption via webpage

Scenario

Developers who is not capable of developing a code scanner can develop a webpage to use by the redemption processor. The webpage allows the merchant to redeem Friend's Vouchers when the user present the QR code.

API Calling Process

# Redemption via Voucher Merchant Assistant

Scenario

The Redemption Assistant for mobile is an official voucher redemption tool developed based on the "Voucher Merchant Assistant" Official Account. It also supports redemption of Friend's Vouchers.

Quick Start

Step 1: Follow the "Voucher Merchant Assistant" Official Account.

Step 2: Log in to the merchant backend of the Weixin Official Accounts Platform, select Cards & Offers > Voucher Redemption > Add Redemption Processor, then grant permissions for the redemption processor, and select existing stores.

Step 3: Create a Friend's Voucher and receive it in a mobile phone. Open the QR code and scan it with the mobile phone that is set as the redemption processor, or enter the redemption code to redeem the voucher.

# Redemption via merchant backend

The merchant can log in to the merchant backend of the Weixin Official Accounts Platform on PC, and select Cards & Offers > Voucher Redemption > *Via Webpage to directly redeem vouchers.

# Redemption for Online Purchase

Redemption APIs for online purchase are slightly different from those for offline purchase. Redemption for online purchase requires redirection of the consumer to an HTML5 page. As a result, two users may use a same voucher at the same time. Therefore, when redeeming a voucher without tapping "Present for use" on it, the developer can call the marking API to link a code of a voucher with an openid to ensure that the code is not to be used by another user.

# Quick Redemption via webpage

Scenario

If the developer or the merchant cannot configure the redemption processor, an HTML5 redemption page can be customized. In this case, users can initiate redemption on the voucher page, and redeem the voucher to get another free voucher on the developer-defined HTML5 page.

Note that when creating or updating a voucher that supports self-redemption, developers can set the code_type field to CODE_TYPE_NONE. In this way, the entry to QR code on the voucher can be hidden (as shown below). In addition, developers can pass the redemption URL by using the center_title, center_sub_title, and center_url fields in the creation API. In this case, the custom entry can be centered as required (as shown below).

For more information, see Homepage.

API Calling Process

# API Details

# Querying Code

We strongly recommend that developers call the "Query Code" API before calling the "Redeem Code" API, and deal with unavailable code (for example, code that is being transfered or that is deleted or redeemed) before redemption.

API Request Format

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

Parameters

POST Data

{
    "card_id": "pbLatjorLTVl-tdvZ6zQRIc-Fn6Y",
     "code": "245645675434",
     "check_consume": true
}

The data returned when check_consume is set to true

When the coupon status is normal:

{
    "errcode": 0,
    "errmsg": "ok",
    "card": {
        "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk",
        "begin_time": 1447397802,
        "end_time": 1452893532
    },
    "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
    "can_consume": true,
    "user_card_status": "NORMAL",
    "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
    "use_count": 1
}

When the coupon status is abnormal:

{
    "errcode": 40127,
    "errmsg": "invalid user-card status! Hint: the card was given to user, but may be
    deleted or set unavailable ! hint: [iHBD40040ent3]"
}

The data returned when check_consume is set to false

When the coupon status is normal:

{
    "errcode": 0,
    "errmsg": "ok",
    "card": {
        "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk",
        "begin_time": 1447397802,
        "end_time": 1452893532
    },
    "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
    "can_consume": true,
    "user_card_status": "NORMAL",
    "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
    "use_count": 1
}

When the coupon status is abnormal:

{
    "errcode": 0,
    "errmsg": "ok",
    "card": {
        "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk",
        "begin_time": 1447397802,
        "end_time": 1452893532
    },
    "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
    "can_consume": false,
    "user_card_status": "DELETE",
    "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
    "use_count": 1
}

Notes:

1. A validity period with a fixed time range is converted based on the actual receipt time. For example, if a voucher is received on October 1, 2013 and the fixed time range is 90 days, then the validity period is from October 1, 2013 to December 29, 2013.

2. When the code is not added or it is transfered and received, the error code "invalid serial code" is reported, regardless of whether the check_consume field is set to true or false.

# Fetching Voucher List (chooseCard)

Weixin JS-SDK can only be used in the Weixin built-in browser and does not work for other browsers. Weixin provides the chooseCard API for merchants to call at front-end webpage. The merchant can use it to display the user's voucher content under its filter conditions.

Click to view JS-SDK Documentation.

# Getting Parameters of Custom External Redirect URL

To allow merchants to extend the voucher services, we support adding external redirect URL in the voucher page, with the fields openid, encrypt_code and card_id.

If the specified URL is http://www.qq.com, when a user taps the URL, the redirect URL is: http://www.qq.com?card_id=pWXUrtw4ehIUwDTXxkvCC6THenb8&encrypt_code= LPmXP%2BZFM9bdEQPSqcA8%2F%2F6pefbsKaRxnNUMHh5%2Fq6Q%3D &openid=oWXUrt8i3***ymgmPcHKlo0TdgHw.

Notes:

1. The encrypt_code is an encrypted code, which needs to be decoded to a real code with decoding API.

2. Parameters obtained from the URL must be URL-encoded to be used in POST requests.

# Decoding

Decoding API is applicable to the following cases: 1. After getting choos_card_info, the merchant calls the decoding API using the card_id and encrypt_code to get the real code; 2. The signature used to redirect to an external URL from a voucher will encrypt the code. The real code can only be obtained by calling the decoding API.

API Request Format

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

Parameters

POST Data

{"encrypt_code": "XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"}

Response Data

Example:

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

# Marking Code

Friend's Vouchers are shared between users, and therefore, multiple users may open the custom HTML5 page of a same voucher at the same time. If a user places an order, redeem a voucher, and makes a payment online on this page, other users using the same voucher may not redeem the voucher. To solve this problem, we provide the "Mark Code" API.

In scenarios where consumers tap "Present for use" to redeem vouchers, developers can directly call the redemption API, without considering the mark logic. In this case, Weixin redeems the vouchers.

In scenarios where consumers redeem vouchers on the HTML5 page, before helping consumers with the redemption, developers must link the code with an openid, or in other words, mark the code, and then call the redemption API. Otherwise, an error is reported.

API Request Format

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

Parameters

POST Data

{
    "code": "114567897765",
    "card_id": "pbxxxxxxxxhjahkdjad",
    "openid": "obcdkalgsdklkdooooooo",
    "is_mark": true
}

Response Data

Example:

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

Notes:

1. This API supports only unused normal Friend's Vouchers. Developers must query the code before calling this API.

2. The is_mark field is true by default.

3. If an openid is repeatedly used to mark code, success is returned for all requests.

4. If openid_b is used for marking after openid_a is used for marking, error 40146 is reported.

5. When the is_mark field is false, marking is canceled. The openid passed in must be the same as that used for marking. Otherwise, error 40416 is reported.

6. If the API is not called to cancel marking, the marking is automatically removed after five minutes (the time range is subject to the product policy).

# Redeeming Code Offline

The "Redeem Code" API is the only API for voucher redemption. Only vouchers within validity periods can be redeemed. Otherwise, the error code "invalid time" is returned.

API Request Format

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

Parameters

POST Data

Request for vouchers with non-custom Code{"code": "12312313"}

Response Data

Example:

{
    "errcode": 0,
    "errmsg": "ok",
    "card": {
        "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
    },
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}

# Redeeming Code Online

Different from the common code redemption API, this API requires passing the openid of the user who is currently using the voucher.

API Request Format

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

Parameters

POST Data

{"code": "12312313", "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }

Response Data

Note:

1. In case of redemption for online purchase, only the openid parameter is required to call the redemption API.

2. In case of redemption for offline purchase, only the code parameter is required to call the redemption API.

# Pushing Redemption Event

When a user redeems a voucher, Weixin pushes the event to the URL entered by the developer. For more information, see Pushing Voucher-related Event.

After a user redeemed a voucher, the merchant can give away the same voucher to the user via JS SDK. See the "Give Away Voucher After Redemption" API (JS SDK)

This API is supported as of Weixin 6.3.6, and JS file of version 1.1.0 is required (https://res.wx.qq.com/open/js/jweixin-1.1.0.js).

For more information, see Special Tickets.

# Help

# Error Codes

# FAQs

1. Why is no voucher in the voucher list fetched via JS SDK?

A: The failure of fetching a voucher via JS SDK is generally caused by a signature error or a filter criteria error. The signature error indicates that the signature on the voucher is incorrect. Click http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign to verify the signature. The filter criteria error indicates that the incoming parameter such as shopid, cardid, or cardtype is incorrect. For example, the cardtype that is set to cash is passed in, but there is no such a type of voucher in the user's Cards & Offers.

2. Why do I need to call the marking API?

A: Friend's Vouchers appear at different users' Cards & Offers lists. Therefore, multiple users may simultaneously open the redemption, order placement, or payment page developed by the developer. In this case, a user may fail to redeem a voucher after making payment. To address this problem, the developer must link the code with the current openid by calling the marking API before redemption. Essentially, the code is locked with the user who is currently using the voucher. For example, in the quick payment or order placement scenario, the marking API can be called before payment is made. If marking failed, the payment is disabled. In addition, if a developer-defined self-redemption page is used, the developer can mark the code before redemption to avoid conflicts.