Write off cards and coupons

Cancellation of Cards and Vouchers

##Update Log

Version number	Update content	Update time
V1.0	1. Standardize the write-off guidance process. It is recommended that developers call the query code interface to check the code status before calling the write-off interface 2. Optimize the query code interface to make it easier for developers to use and compatible with the old interface	2015-8-31

Version number

Update content

Update time

V1.0

1. Standardize the write-off guidance process. It is recommended that developers call the query code interface to check the code status before calling the write-off interface

2. Optimize the query code interface to make it easier for developers to use and compatible with the old interface

2015-8-31

This section mainly introduces how developers The process of making the coupon disappear from the user's WeChat client after the user uses the coupon is called write-off.

Writoff is currently divided into two types: online write-off and offline write-off.

Online cancellation refers to the process of users actively selling coupons after entering an HTML5 web page from the coupon page, such as WeChat mall coupons, self-service verification, etc.;

Offline verification means that after the user arrives at the store, he or she will present the QR code or string code, and the cashier will complete the write-off action, such as scanning code for write-off, machine write-off , etc.

1 Offline write-off

##1.1 Query Code interface

We strongly recommend that developers call the query code interface before calling the write-off code interface, and check the code in an illegal status (such as being transferred, deleted, and verified) before writing it off. Sales, etc.) are processed.

##Interface call request description

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/code/get?access_token=TOKEN

Parameter Description

Parameter	Is it required	Description
POST data	is	Json data
access_token	is the	calling interface credential

##POST data

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

Parameter description

Return data when check_consume is true

Card 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"
}

Card Abnormal coupon status:

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

#Return data when check_consume is false

The card 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"
}

The card 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"
}

Parameter name	Required	Type	Example value	Description
##code	is	string(20)	110201201245	The only one for a single card standard.
card_id	No	string(32)	pFS7Fjg8kV1I ##dDz01r4SQwMkuCKc	Coupon ID represents a type of coupon . Custom code coupons are required.
check_consume	No	bool	true	Whether to verify the code write-off status, the code exception status return data is different when true and false are filled in.

Parameter name

Required

Type

Example value

Description

##code

string(20)

110201201245

The only one for a single card standard.

card_id

string(32)

pFS7Fjg8kV1I

##dDz01r4SQwMkuCKc

Coupon ID represents a type of coupon . Custom code coupons are required.

check_consume

bool

true

Whether to verify the code write-off status, the code exception status return data is different when true and false are filled in.

##errmsgError messageopeniduseropenidcard_idCoupon IDbegin_timeStart use timeend_timeEnd time##can_consume

Precautions:

1. The fixed duration validity period will be converted according to the actual time of collection by the user. For example, if the user collects the subscription on October 1, 2013, the fixed duration validity period is 90 days, that is, the validity period is from October 1, 2013 to December 29, 2013.

#2. No matter whether check_consume is filled in with true or false, when the code is not added or the code is transferred and received, a uniform error will be reported: invalid serial code

1.2 Write-off Code interface

The consumption code interface is the only interface for writing off cards and coupons, developed The user can call the current interface to cancel the user's coupon, and this process is irreversible.

Interface call request description

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

参数说明

Parameter name	Description
##errcode	Error code





user_card_status	The status of the card corresponding to the current code NORMAL Normal CONSUMED Has been written off ##EXPIRE Expired GIFTING Re-gifting GIFT_TIMEOUT Transfer timeout DELETE Deleted UNAVAILABLE Expired # If the ##code has not been added or has been transferred and received, an error will be reported: invalid serial code
Whether it can be written off, true means it can be written off, false means it cannot be written off

Parameter	Is it required	Description
POST data	is	Json data
access_token	is the	calling interface credential

##POST data

非自定义Code卡券的请求
{
  "code": "12312313"
}
或自定义Code卡券的请求
{
  "code": "12312313",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

Parameter name	Required	Type	Example value	Description
##card_id	No	string(32)	##pFS7Fjg8kV1Id ##Dz01r4SQwMkuCKc	Coupon ID. Required when use_custom_code is filled in true when creating a coupon. Non-custom Code does not need to be filled in.
code	is	string(20)	1231231	The code to be written off.

Parameter name

Required

Type

Example value

Description

##card_id

string(32)

##pFS7Fjg8kV1Id

##Dz01r4SQwMkuCKc

Coupon ID. Required when use_custom_code is filled in true when creating a coupon. Non-custom Code does not need to be filled in.

code

string(20)

1231231

The code to be written off.

Return data

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

#Note:

1. Only valid for write-off Cards and coupons in abnormal status cannot be written off. (Exception status includes: card and coupon deleted, not valid, expired, transfer in progress, transfer returned, expired)

2.Customization For coupons with code (use_custom_code is true), this interface must be called when the code is canceled. Used to change the code status of the user client. When calling the interface for cards and coupons with custom codes, the post data must contain card_id, otherwise an invalid serial code will be reported. Non-custom codes do not need to be reported.

2 Online verification

#2.1 Pull card and coupon list interface (JS-SDK)

WeChat JS-SDK can only be used in WeChat’s built-in browser, and calls from other browsers are invalid. WeChat provides the chooseCard interface for merchants to call the front-end web page, which is used to pull up the card and coupon content of the merchant's filter conditions under the user's name. Click to view Call up the list of cards and coupons applicable to the store and obtain the user selection list JS-SDK

2.2 Code decoding interface

The code decoding interface supports two scenarios:

1. After the merchant obtains chooses_card_info, it passes the card_id and encrypt_code fields through the decoding interface to obtain the real code.

#2. The code will be encrypted in the signature of the external link within the card, and the real code will be obtained by calling the decoding interface.

Interface call request description

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN

Parameter description

Parameter name	Description
##errcode	error code.
errmsg	Error message.
openid	The user’s unique identity within the public account.
card_id	Card ID.

Parameter	Is it required	Description
POST data	is	Json data
access_token	is the	calling interface credential

##POST data

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

参数说明

##string(128)##XXIzTtMqCxwOaawoE91 VJdsFmv7b

Parameter name	Required	Type	Example value	Description
##encrypt_code	is		##8g0VZIZkqf4GWA60Fzpc8ksZ/ 5ZZ0DVkXdE	Encrypted Code.

#Return data

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

Parameter Description

Parameter name	Description
errcode	Error code
errmsg	Error message
code	The real Code obtained after decryption

# Notes

#1. Only the encrypted code obtained by this official account can be decoded.

2. If the developer obtains the encryption code from the URL, please pay attention to urldecode first, otherwise an error will be reported.

3.encrypt_code is the encrypted code code obtained by encrypting the card code, which corresponds to the code one-to-one.

4. Developers can only decrypt the encrypted code of this public account, otherwise an error will be reported.

2.3 Query Code interface

We strongly recommend that developers call the query code interface before calling the write-off code interface, and Codes in illegal status (such as being transferred, deleted, written off, etc.) should be processed before write-off.

2.4 Verification Code interface

The online verification interface for ordinary coupons is the same as the offline verification interface The interface for selling ordinary coupons is the same.

Write off cards and coupons

Cancellation of Cards and Vouchers

##Update Log

1 Offline write-off

##1.1 Query Code interface

1.2 Write-off Code interface

2 Online verification

#2.1 Pull card and coupon list interface (JS-SDK)

2.2 Code decoding interface

2.3 Query Code interface

2.4 Verification Code interface

php.cn