Contents

1. Offline Redemption

1.1 Querying the Code

1.2 Redeeming the Code

2. Online Redemption

2.1 Pulling the Card/Coupon List

2.2 Decrypting the Code

2.3 Querying the Code

2.4 Redeeming the Code

This section describes how the developer makes the card/coupon disappear from the user's Weixin app after being used. This process is called "redemption".

There are two types of redemption: online redemption and offline redemption.

Online redemption refers to the automatic redemption process after the user enters into an HTML5 page from the coupon, such as Weixin Mall coupon and self-redemption.

Offline redemption refers to the redemption process conducted by the clerk after the user presents a QR code or a coupon code in the store, such as scanning redemption and machine redemption.

# 1. Offline Redemption

# 1.1 Querying the 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: POSTURL:https://api.weixin.qq.com/card/code/get?access_token=TOKEN

Parameters

POST Data

{
   "card_id" : "card_id_123+",
   "code" : "123456789",
   "check_consume" : true
}

Parameters

The data returned when check_consume is set to true

When the coupon status is normal:

{
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "user_card_status": "NORMAL"
}

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": "pbLatjk4T4Hx-QFQGL4zGQy27_Qg",
    "begin_time": 1457452800,
    "end_time": 1463155199
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": true,
  "user_card_status": "NORMAL"
}

When the coupon status is abnormal:

 {
  "errcode": 0,
  "errmsg": "ok",
  "card": {
    "card_id": "pbLatjnK8NLbWgwMgfMtnj3gaglw",
    "begin_time": 1457625600,
    "end_time": 1460217599
  },
  "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
  "can_consume": false,
  "user_card_status": "GIFTING"
}

Notes:

1. A validity period with a fixed time range is converted based on the actual receipt time. For example, if a coupon 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 gifted and received, the error code "invalid serial code" is reported, regardless of whether the check_consume field is set to true or false.

# 1.2 Redeeming the Code

The "Redeem Code" API is the only API for coupon redemption. The developer can call this API to redeem the user's coupons. The process cannot be recovered.

API Request Format

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

Parameters

POST Data

Non-custom Code coupon request {  "code": "12312313"} or custom Codecoupon request {  "code": "12312313",  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"}

Response Data

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

Notes:

1. Only a valid coupon can be redeemed. An exceptional coupon cannot be redeemed. (Exception states include: coupon deleted, not coming into effect, expired, gifted, returned back to the original user, and invalid.)

2. The API has to be called when redeeming a custom code (use_custom_code = true) for the coupon in order to change the code status in the user's app. When the API is called for a coupon with custom code, card_id must be included in POST data, otherwise "invalid serial code" will be reported. Non-custom code does not need to report.

# 2. Online Redemption

# 2.1 Pulling the Card/Coupon List (JS-SDK)

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 card/coupon content under its filter conditions. Click to view See JS-SDK Documentation for details.

# 2.2 Decrypting the Code

The "Decrypt Code" API is applicable to the following two cases:

1. After the merchant obtains choos_card_info, it can obtain the real code by leading the fields card_id and encrypt_code through the decryption API.

2. The signature used to redirect to an external URL from a card/coupon will encrypt the code. The real code can only be obtained by calling the decryption API.

API Request Format

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

Parameters

POST Data

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

Parameters

Response Data

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

Parameters

Notes

1. Only the code obtained from the card/coupons of the same Official Account can be decrypted.

2. The developer should execute urldecode first when obtaining the encrypted code from a URL. Otherwise, an error is reported.

3. encrypt_code is obtained by encrypting the card/coupon code. One encrypt_code corresponds to one card/coupon code.

4. The developer can only decrypt the code obtained from the same Official Account. Otherwise, an error is reported.

# 2.3 Querying the 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.

For details, see Offline Redemption: "Query Code" API.

# 2.4 Redeeming the Code

For common coupons, the online redemption API is the same as the offline redemption API. For details, see Offline Redemption: "Redeem Code" API.