Configuring the Inventory and Topping Up Token Account
This section describes how to configure the inventory for the card_id, top up the token account, and manage tokens.
# 1 API Description
After creating a Friend's Voucher, the developer can configure the inventory for the card_id via tha API. Different from other vouchers, the inventory of Friend's Vouchers are redeemed by using tokens (What is Token?) Tokens are classified into free tokens and paid tokens. Free tokens are given by Weixin. Paid tokens are generated from top-ups made by developers.
# 2 API Calling Process
# 3 API Details
This section describes the method for calling the inventory and token APIs and the passed parameters.
# 3.1 Activating Token Account
This API allows developers to activate a token account for the current AppID and obtain free tokens as a reward.
API Request Format
HTTP request method: GET https://api.weixin.qq.com/card/pay/activate?access_token=ACCESS_TOKEN
Example of response data
{"errcode": 0, "errmsg": "ok", "reward": 200}
Example of response data
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| reward | The quantity of rewarded tokens. The calculated amount is in CNY. Weixin Cards & Offers reward 200 tokens to each merchant who activates a token account. For the token rule, see What is Token. |
# 3.2 Calculating Voucher Quantity
This API is used to query the quantity of tokens required for the new inventory.
API Request Format
HTTP request method: POST https://api.weixin.qq.com/card/pay/getpayprice?access_token=ACCESS_TOKEN
Parameters
| Parameter | Required | Description |
|---|---|---|
| POST data | Yes | JSON data |
| access_token | Yes | The credential for API call |
POST Data
{"card_id": "pbLatjpQxxxxxxxxCEV_cLTwoB7yU", "quantity": "1"}
Request parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| card_id | Yes | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | The card_id for which the inventory needs to be configured |
| quantity | Yes | int | 100 | The number of tokens used to redeem the inventory |
Example of response data
{
"errcode": 0,
"errmsg": "ok",
"order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIf7Ag5Ww-YdxP-KeT6LeJBttb1xpY0Uf7g8DNHrbUyHopolqfUqPBBLDEmB7Z-91I8",
"price": "0.2",
"free_coin": "0.2",
"pay_coin": "0"
}
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| order_id | Order ID of this calculation. It is used in the following top-up inventory confirmation API. It takes effect only for the current order and can be used only once. It can be used to redeem inventory within 60 seconds. |
| price | The total amount of tokens be paid for this redemption |
| free_coin | The total amount of free tokens be paid for this redemption |
| pay_coin | The total amount of paid tokens be paid for this redemption |
Notes:
For more information about the token mechanism, see What is Token?
# 3.3 Querying Token Balance
This API is used to query the total quantity and amount of free tokens and paid tokens in the current token account.
API Request Format
HTTP request method: GET https://api.weixin.qq.com/card/pay/getcoinsinfo?access_token=ACCESS_TOKEN
Example of response data
{"errcode": 0,
"errmsg": "ok",
"free_coin": 200
"pay_coin": 1
"total_coin": 201
}
Response Parameters
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| free_coin | Number of free tokens |
| pay_coin | Number of paid tokens |
| total_coin | Number of all tokens |
# 3.4 Confirming Inventory Redemption
This API is used to confirm the inventory redemption. After confirmation, tokens are redeemed for the inventory. This operation cannot be undone.
API Request Format
HTTP request method: POST https://api.weixin.qq.com/card/pay/confirm?access_token=ACCESS_TOKEN
Parameters
| Parameter | Required | Description |
|---|---|---|
| POST data | Yes | JSON data |
| access_token | Yes | The credential for API call |
POST Data
{
"card_id": "pbLatjpxxxxlCEV_cLTwoB7yU",
"order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIfkbR7Ag5WwYdxP-KeT6LeJBttb1xpYxxxxxxxxxxxxHrbUyHopolqfUqPBBLDEmB7Z-91I8",
"quantity": "1"
}
Request parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| card_id | Yes | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | The card ID for which the inventory needs to be redeemed |
| quantity | Yes | int | 100 | The number of tokens used to redeem the inventory |
| order_id | Yes | string | P9zzllX2VJ5NgiF9kFVarX7bc8r | To ensure that the pricing is effective, only the order ID obtained above can be used in this field. |
Example of response data
{"errcode":0, "errmsg":"ok"}
Parameters
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
Note
The order_id obtained in the previous step must be used within 60 seconds. Otherwise, the "Confirm Inventory Redemption" API will be invalidated.
# 3.5 Topping Up Token Account
This API is used to top up the token account with tokens. One CNY is equal to 1 token. After calling this API, developers can get a link to the payment QR code of WeChat Pay, and then convert the link into a QR code and make payment by scanning the code.
API Request Format
HTTP request method: POST https://api.weixin.qq.com/card/pay/recharge?access_token=ACCESS_TOKEN
Parameters
| Parameter | Required | Description |
|---|---|---|
| POST data | Yes | JSON data |
| access_token | Yes | The credential for API call |
POST Data
{"coin_count": 100}
Request parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| coin_count | Yes | int | 10000 | The number of tokens that are used for top-up. 1 token = 1 CNY. |
Example of response data
{
"errcode": 0,
"errmsg": "ok",
"order_id": "100005790120***221401000171",
"qrcode_url": "weixin://wxpay/bizpayurl?pr=xxxxxxxxx",
"qrcode_buffer": "pwxs*************xxxxxxxxxx"
}
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| order_id | Order ID for this payment, used to query the order status. |
| qrcode_url | The link to the payment QR code. Developers can call the common library generated from a QR code to convert it into a QR code, and display the QR code on a webpage, so that users can make payment by scanning the QR code via Weixin. |
| qrcode_buffer | Data stream for a QR code. Developers can display the QR code by writing a file. |
Notes:
Developers can buffer the display of a QR code by referring to the following methods.
<?php $file = fopen("test.jpg","w"); echo fwrite($file, $qrcode_buffer); fclose($file); ?>
# 3.6 Querying Order Details
This AIP is used to query the status of top-up orders.
API Request Format
HTTP request method: POST https://api.weixin.qq.com/card/pay/getorder?access_token=ACCESS_TOKEN
Parameters
| Parameter | Required | Description |
|---|---|---|
| POST data | Yes | JSON data |
| access_token | Yes | The credential for API call |
POST Data
{"order_id": "100005790********401000171"}
Request parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| order_id | Yes | int | 10000 | The order ID obtained in the previous step. It is the unique credential for a transaction. |
Example of response data
{
"errcode": 0,
"errmsg": "ok",
"order_info": {
"order_id": "100005790120151221401000171",
"status": "ORDER_STATUS_FINANCE_SUCC",
"create_time": 1450712798,
"pay_finish_time": 1450712905,
"desc": "Top-up via WeChat Pay",
"free_coin_count": "0",
"pay_coin_count": "1",
"refund_free_coin_count": "0",
"refund_pay_coin_count": "0",
"openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
"order_type": "ORDER_TYPE_WXPAY"
}
}
Response Data
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| order_info | Structure of order information |
| order_id | Order ID |
| status | Order status. ORDER_STATUS_WAITING: To be paid. ORDER_STATUS_SUCC: Payment successful. ORDER_STATUS_FINANCE_SUCC: Token account topped up. ORDER_STATUS_QUANTITY_SUCC: Voucher inventory balance increased. ORDER_STATUS_HAS_REFUND: Tokens refunded. ORDER_STATUS_REFUND_WAITING: Awaiting refund. ORDER_STATUS_ROLLBACK: Rolled back. System failed. ORDER_STATUS_HAS_RECEIPT: Invoiced. |
| create_time | The time when the order is created |
| pay_finish_time | The time when the payment is made |
| desc | Payment description. It is generally top-up via WeChat Pay. |
| free_coin_count | The number of paid tokens in this top-up. The calculated amount is in CNY. |
| pay_coin_count | A data stream for the QR code. Developers can display the QR code by writing a file. |
| refund_free_coin_count | Refunded free tokens |
| refund_pay_coin_count | Refunded paid tokens |
| openid | Payer's OpenID |
| order_tpye | Order type. ORDER_TYPE_WXPAY: Top-up. |
# 3.7 Querying Token Count Change
This API is used to query token count changes.
API Request Format
HTTP request method: POSThttps://api.weixin.qq.com/card/pay/getorderlist?access_token=ACCESS_TOKEN
Parameters
| Parameter | Required | Description |
|---|---|---|
| POST data | Yes | JSON data |
| access_token | Yes | The credential for API call |
POST Data
{
"offset": 0,
"count": 5,
"order_type": "ORDER_TYPE_WXPAY",
"nor_filter": {
"status": "ORDER_STATUS_SUCC"
},
"sort_info": {
"sort_key": "SORT_BY_TIME",
"sort_type": "SORT_DESC"
},
"begin_time": "1440420538",
"end_time": "1450713203"
}
Request parameters
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
| offset | No | int | 0 | Start point of batch queries. It is 0 by default. |
| count | No | int | 50 | Number of batch queries |
| begin_time | No | int | 14552146398 | Start event for a batch query order. It is a timestamp and is one week ago by default. |
| end_time | No | int | 14552146398 | End event for a batch query order. It is a timestamp and is the current time by default. |
| order_type | No | string | ORDER_TYPE_WXPAY | The type of order to fetch. ORDER_TYPE_SYS_ADD: Tokens given by platform. ORDER_TYPE_WXPAY: Token account topped up. ORDER_TYPE_REFUND: Tokens returned from expired inventory. ORDER_TYPE_REDUCE: Tokens used to increase voucher inventory balance. ORDER_TYPE_SYS_REDUCE: Tokens deducted by platform. |
| nor_filter | No | JSON structure | ORDER_STATUS_QUANTITY_SUCC | Unselects orders that are not fetched |
| status | No | string | ORDER_STATUS_REFUND_WAITING | The status of order that is not fetched. ORDER_STATUS_WAITING: To be paid. ORDER_STATUS_SUCC: Payment successful. ORDER_STATUS_FINANCE_SUCC: Token account topped up. ORDER_STATUS_QUANTITY_SUCC: Voucher inventory balance increased. ORDER_STATUS_HAS_REFUND: Tokens refunded. ORDER_STATUS_REFUND_WAITING: Awaiting refund. ORDER_STATUS_ROLLBACK: Rolled back. System failed. ORDER_STATUS_HAS_RECEIPT: Invoiced. |
| sort_info | No | JSON structure | Sorts the results | |
| sort_key | No | string | SORT_BY_TIME | Sorting basis. SORT_BY_TIME: Sort by order time. |
| sort_type | No | string | SORT_DESC | Sorting rule. SORT_ASC: Ascending order. SORT_DESC: Descending order. |
Example of response data
{
"errcode": 0,
"errmsg": "ok",
"total_num": 1,
"order_list": [
{
"order_id": "100005790120151221401000171",
"status": "ORDER_STATUS_FINANCE_SUCC",
"create_time": 1450712798,
"pay_finish_time": 1450712905,
"desc": "Top-up via WeChat Pay",
"free_coin_count": "0",
"pay_coin_count": "1",
"refund_free_coin_count": "0",
"refund_pay_coin_count": "0",
"openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
"order_type": "ORDER_TYPE_WXPAY"
}
]
}
Response Data
| Parameter | Description |
|---|---|
| errcode | Error code |
| errmsg | Error message |
| total_num | The total number of orders that meet conditions |
| order_list | The list of order details displayed by offset and count |
| order_id | Order ID |
| status | Order status. ORDER_STATUS_WAITING: To be paid. ORDER_STATUS_SUCC: Payment successful. ORDER_STATUS_FINANCE_SUCC: Token account topped up. ORDER_STATUS_QUANTITY_SUCC: Voucher inventory balance increased. ORDER_STATUS_HAS_REFUND: Tokens refunded. ORDER_STATUS_REFUND_WAITING: Awaiting refund. ORDER_STATUS_ROLLBACK: Rolled back. System failed. ORDER_STATUS_HAS_RECEIPT: Invoiced. |
| create_time | The time when the order is created |
| pay_finish_time | The time when the payment is made |
| desc | Payment description. It is generally top-up via WeChat Pay. |
| free_coin_count | The number of paid tokens in this top-up. The calculated amount is in CNY. |
| pay_coin_count | Data stream for a QR code. Developers can display the QR code by writing a file. |
| refund_free_coin_count | Refunded free tokens |
| refund_pay_coin_count | Refunded paid tokens |
| openid | Payer's OpenID |
| order_tpye | Order type. ORDER_TYPE_WXPAY: Top-up. |
# 3.8 Pushing Token Count Change Event
When the token count changes, the Weixin server pushes the information such as the type of this change, the amount of the tokens, and the change time to the developer server.
For more information, see Voucher-related Event Pushing.