Contents
2.7 Event of Opening Member Card
2.8 Event of Entering Official Account Chat from Coupons
2.10 Coupon Inventory Balance Alarm Event
2.11 Coupon Token Count Change Event
2.12 Member Card Activation Event
# 2.Coupon-Related Events
A coupon-related event (e.g. a coupon is approved by Weixin or received, deleted, or redeemed by a user, or a user enters the Official Account from a coupon) will be pushed to the URL provided by the developer ( Log in to Official Accounts Platform, go to "Developer Center"). Developers can perform such operations as generating statistics or authenticating user identities through the pushed events.
If the Weixin server does not receive the response within five seconds, the connection is broken and the request is initiated again. A maximum of three retries are made. It is recommended to use FromUserName + CreateTime for de-duplication of requests. If merchant's server cannot ensure the request is processed within five seconds, it can return an empty string. When receiving the string, the Weixin server will not take any action or make a retry.
# 2.1 Coupon Approval Event
When the generated coupons are approved, Weixin pushes the event to the URL entered by the developer.
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[card_pass_check]]></Event> //If the coupons are rejected, card_not_pass_check is pushed.
<CardId><![CDATA[cardid]]></CardId>
<RefuseReason><![CDATA[Illegal entrusted coupon creation]]></RefuseReason>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integer) |
| MsgType | Message type (event) |
| Event | Event type. card_pass_check: Approved; card_not_pass_check: Rejected. |
| CardId | Coupon ID |
| RefuseReason | Rejection reason |
Debug this API using webpage debugging tool
# 2.2 Coupon Receipt Event
When a user receives a coupon, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:
<xml>
<ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>
<FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>
<CreateTime>1472551036</CreateTime>
<MsgType> <![CDATA[event]]> </MsgType>
<Event> <![CDATA[user_get_card]]> </Event>
<CardId> <![CDATA[pZI8Fjwsy5fVPRBeD78J4RmqVvBc]]> </CardId>
<IsGiveByFriend>0</IsGiveByFriend>
<UserCardCode> <![CDATA[226009850808]]> </UserCardCode>
<FriendUserName> <![CDATA[]]> </FriendUserName>
<OuterId>0</OuterId>
<OldUserCardCode> <![CDATA[]]> </OldUserCardCode>
<OuterStr> <![CDATA[12b]]> </OuterStr>
<IsRestoreMemberCard>0</IsRestoreMemberCard>
<IsRecommendByFriend>0</IsRecommendByFriend>
<UnionId>o6_bmasdasdsad6_2sgVt7hMZOPfL</UnionId>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Coupon recipient ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_get_card: A user receives a coupon. |
| CardId | Coupon ID |
| IsGiveByFriend | Indicates whether the coupon is gifted by another user. 1: Yes; 0: No. |
| FriendUserName | When the value of IsGiveByFriend is 1, this field indicates the openid of the user who gifts the coupon. |
| UserCardCode | Coupon code |
| OldUserCardCode | To ensure security, Weixin changes the coupon code after the coupon is gifted. This field indicates the old coupon code before the gifting. |
| OuterStr | Indicates the channel from which the coupon is received. The field value can be customized in the APIs "Generate QR Code" and "Add Addcard". |
| IsRestoreMemberCard | Indicates whether a member card is recoverable after being deleted by user. 1: Yes; 0: No. |
| UnionId | UnionId of the coupon recipient. |
Debug this API using webpage debugging tool
# 2.3 Coupon Gifting Event
When a user gifts a coupon, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:
<xml>
<ToUserName><![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjjwDolFjRRd3doGIdwNqRXw]]></FromUserName>
<CreateTime>1474181868</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_gifting_card]]></Event>
<CardId><![CDATA[pbLatjhU-3pik3d4PsbVzvBxZvJc]]></CardId>
<UserCardCode><![CDATA[297466945104]]></UserCardCode>
<IsReturnBack>0</IsReturnBack>
<FriendUserName><![CDATA[obLatjlNerkb62HtSdQUx66C4NTU]]></FriendUserName>
<IsChatRoom>0</IsChatRoom>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Coupon recipient ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_gifting_card: A user gifts a coupon. |
| CardId | Coupon ID |
| FriendUserName | The openid of the coupon recipient |
| UserCardCode | Coupon code |
| IsReturnBack | Indicates whether the gifted coupon is returned back to the original user. 0: No; 1: Yes. |
| IsChatRoom | Indicates whether the coupon is gifted in a group. |
Debug this API using webpage debugging tool
# 2.4 Coupon Deletion Event
When a user deletes a coupon, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_del_card]]></Event>
<CardId><![CDATA[cardid]]></CardId>
<UserCardCode><![CDATA[12312312]]></UserCardCode>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_del_card: A user deletes a coupon. |
| CardId | Coupon ID |
| UserCardCode | Coupon code. Event push is supported for both coupons with custom codes and the ones with non-custom codes. |
Debug this API using webpage debugging tool
# 2.5 Coupon Redemption Event
When a user redeems a coupon, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:
<xml>
<ToUserName> <![CDATA[gh_fc0a06a20993]]> </ToUserName>
<FromUserName> <![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]> </FromUserName>
<CreateTime>1472549042</CreateTime>
<MsgType> <![CDATA[event]]> </MsgType>
<Event> <![CDATA[user_consume_card]]> </Event>
<CardId> <![CDATA[pZI8Fj8y-E8hpvho2d1ZvpGwQBvA]]> </CardId>
<UserCardCode> <![CDATA[452998530302]]> </UserCardCode>
<ConsumeSource> <![CDATA[FROM_API]]> </ConsumeSource>
<LocationName> <![CDATA[]]> </LocationName>
<StaffOpenId> <![CDATA[oZ********nJ3bPJu_Rtjkw4c]]> </StaffOpenId>
<VerifyCode> <![CDATA[]]> </VerifyCode>
<RemarkAmount> <![CDATA[]]> </RemarkAmount>
<OuterStr> <![CDATA[xxxxx]]> </OuterStr>
</xml>
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_consume_card: A user redeems a coupon. |
| CardId | Coupon ID |
| UserCardCode | Coupon code |
| ConsumeSource | Redemption source. Redemption can be made via API (FROM_API), Official Accounts Platform, and Mobile Merchant Assistant (FROM_MOBILE_HELPER) (redemption processor's Weixin ID). |
| LocationName | Name of the store where the coupon is redeemed (this field is only applicable to self-redemption and redemption via Weixin Checkout. |
| StaffOpenId | Openid of the coupon redemption processor (only applicable to the redemption via Mobile Merchant Assistant) |
| VerifyCode | Verification code entered by user for self-redemption |
| RemarkAmount | Amount in remarks that is entered by user for self-redemption |
| OuterStr | A custom parameter passed by the developer when the redemption is initiated. It is used for redemption channel statistics. |
Debug this API using webpage debugging tool
# 2.6 Payment Event
After a user makes a payment, Weixin pushes the event to the URL entered by the developer. The following is an example of XML packet for push:
<xml>
<ToUserName><![CDATA[gh_e2243xxxxxxx]]></ToUserName>
<FromUserName><![CDATA[oo2VNuOUuZGMxxxxxxxx]]></FromUserName>
<CreateTime>1442390947</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_pay_from_pay_cell]]></Event>
<CardId><![CDATA[po2VNuCuRo-8sxxxxxxxxxxx]]></CardId>
<UserCardCode><![CDATA[38050000000]]></UserCardCode>
<TransId><![CDATA[10022403432015000000000]]></TransId>
<LocationId>291710000</LocationId>
<Fee><![CDATA[10000]]></Fee>
<OriginalFee><![CDATA[10000]]> </OriginalFee>
</xml>
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. User_pay_from_pay_cell: A user makes a payment with WeChat Pay. |
| CardId | Coupon ID |
| UserCardCode | Coupon code |
| TransId | Transaction order number generated in WeChat Pay (only applicable to the coupons redeemed with Weixin Checkout) |
| LocationId | ID of the store where the coupon is redeemed (only applicable to the coupons redeemed via Mobile Merchant Assistant and Weixin Checkout. |
| Fee | Amount actually paid (in cents). |
| OriginalFee | The original amount before discount |
Debug this API using webpage debugging tool
# 2.7 Event of Opening Member Card
When a user opens a member card, Weixin pushes the event to the URL entered by the developer.
Developers need to set need_push_on_view to "true" on homepage. Whether to receive this event depends on the number of users receiving the cards and server load.
Example of pushing an XML data packet:
<xml>
<ToUserName> <![CDATA[gh_fcxxxx6a20993]]> </ToUserName>
<FromUserName> <![CDATA[oZI8Fj040-xxxxx6gkoPOQTQ]]> </FromUserName>
<CreateTime>1467811138</CreateTime>
<MsgType> <![CDATA[event]]> </MsgType>
<Event> <![CDATA[user_view_card]]> </Event>
<CardId> <![CDATA[pZI8Fj2ezBbxxxxxT2UbiiWLb7Bg]]> </CardId>
<UserCardCode> <![CDATA[4xxxxxxxx8558]]> </UserCardCode>
<OuterStr> <![CDATA[12b]]> </OuterStr>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_view_card: A user taps the member card. |
| CardId | Coupon ID |
| UserCardCode | Merchant's custom code. For non-custom code, an empty string is pushed. |
| OuterStr | Merchant's custom QR code channel. It is used to indicate the source from which the QR code is scanned to open the member card. |
Debug this API using webpage debugging tool
# 2.8 Event of Entering Official Account Chat from Coupons
When a user enters an Official Account chat by tapping a coupon (following the Official Account is required), Weixin pushes the event to the URL entered by the developer. The developer can authenticate the identity of the user who enters the Official Account from the coupon. The following is an example of XML packet for push:
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_enter_session_from_card]]></Event>
<CardId><![CDATA[cardid]]></CardId>
<UserCardCode><![CDATA[12312312]]></UserCardCode>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. user_enter_session_from_card: A user enters an Official Account chat from a coupon. |
| CardId | Coupon ID |
| UserCardCode | Coupon code |
Debug this API using webpage debugging tool
# 2.9 Member Card Update Event
When a user's loyalty points balance on member card changes, Weixin pushes the event to the developer. The following is an example of XML packet for push:
<xml>
<ToUserName><![CDATA[gh_9e1765b5568e]]></ToUserName>
<FromUserName><![CDATA[ojZ8YtyVyr30HheH3CM73y7h4jJE]]></FromUserName>
<CreateTime>1445507140</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[update_member_card]]></Event>
<CardId><![CDATA[pjZ8Ytx-nwvpCRyQneH3Ncmh6N94]]></CardId>
<UserCardCode><![CDATA[485027611252]]></UserCardCode>
<ModifyBonus>3</ModifyBonus>
<ModifyBalance>0</ModifyBalance>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integral) |
| MsgType | Message type (event) |
| Event | Event type. update_member_card: Member card is updated. |
| CardId | Coupon ID |
| UserCardCode | Coupon code |
| ModifyBonus | Added or deducted points |
| ModifyBalance | Changed balance |
Debug this API using webpage debugging tool
# 2.10 Coupon Inventory Balance Alarm Event
When the initial inventory balance of a card_id is greater than 200 and the current inventory balance is less than or equal to 100, a user's attempt to claim coupon will trigger the event. The event is pushed to the merchant every 12 hours.
<xml>
<ToUserName><![CDATA[gh_2d62d*****0]]></ToUserName>
<FromUserName><![CDATA[oa3LFuBvWb7*********]]></FromUserName>
<CreateTime>1443838506</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[card_sku_remind]]></Event>
<CardId><![CDATA[pa3LFuAh2P65**********]]></CardId>
<Detail><![CDATA[the card's quantity is equal to 0]]></Detail>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender's Weixin ID |
| CreateTime | Creation time of message (integer) |
| MsgType | Message type (event) |
| Event | Event type. card_sku_remind: Coupon inventory balance alarm |
| CardId | Coupon ID |
| Detail | Alarm details |
Debug this API using webpage debugging tool
# 2.11 Coupon Token Count Change Event
When a merchant's coupon token count for friend's coupons changes, Weixin server pushes a message to the merchant server.
<xml>
<ToUserName><![CDATA[gh_7223c83d4be5]]></ToUserName>
<FromUserName><![CDATA[ob5E7s-HoN9tslQY3-0I4qmgluHk]]></FromUserName>
<CreateTime>1453295737</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[card_pay_order]]></Event>
<OrderId><![CDATA[404091456]]></OrderId>
<Status><![CDATA[ORDER_STATUS_FINANCE_SUCC]]></Status>
<CreateOrderTime>1453295737</CreateOrderTime>
<PayFinishTime>0</PayFinishTime>
<Desc><![CDATA[]]></Desc>
<FreeCoinCount><![CDATA[200]]></FreeCoinCount>
<PayCoinCount><![CDATA[0]]></PayCoinCount>
<RefundFreeCoinCount><![CDATA[0]]></RefundFreeCoinCount>
<RefundPayCoinCount><![CDATA[0]]></RefundPayCoinCount>
<OrderType><![CDATA[ORDER_TYPE_SYS_ADD]]></OrderType>
<Memo><![CDATA[Bonus for account opening]]></Memo>
<ReceiptInfo><![CDATA[]]></ReceiptInfo>
</xml>
Parameters:
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender's Weixin ID |
| CreateTime | Creation time of message (integer) |
| MsgType | Message type (event) |
| Event | Event type. card_pay_order: Coupon token count changes. |
| OrderId | The order number for the event push. |
| 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: Coupon 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. |
| CreateOrderTime | Creation time of payment QR code when coupon tokens are purchased. |
| PayFinishTime | Completion time of payment when coupon tokens are purchased. |
| Desc | Payment method, which is usually top-up via WeChat Pay. |
| FreeCoinCount | Number of remaining free tokens. |
| PayCoinCount | Number of remaining paid tokens. |
| RefundFreeCoinCount | Number of free tokens added or deducted. |
| RefundPayCoinCount | Number of paid tokens added or deducted. |
| OrderType | The order type to fetch. ORDER_TYPE_SYS_ADD: Coupon tokens are added by platform. ORDER_TYPE_WXPAY: Coupon token account is topped up. ORDER_TYPE_REFUND: Unused coupon tokens are returned from expired inventory. ORDER_TYPE_REDUCE: Tokens are used to increase coupon inventory balance. ORDER_TYPE_SYS_REDUCE: Tokens are deducted by platform. |
| Memo | Reason for the change, such as bonus for account-opening, store incentive, reward for coupon redemption, top-up, deduction, etc. |
| ReceiptInfo | Invoice details |
Debug this API using webpage debugging tool
# 2.12 Member Card Activation Event
After a user submits the member card information and taps "Activate" or modifies the member card information, an event is pushed to the merchant.
<xml>
<ToUserName> <![CDATA[gh_3fcea188bf78]]></ToUserName>
<FromUserName><![CDATA[obLatjlaNQKb8FqOvt1M1x1lIBFE]]></FromUserName>
<CreateTime>1432668700</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[submit_membercard_user_info]]></Event>
<CardId><![CDATA[pbLatjtZ7v1BG_ZnTjbW85GYc_E8]]></CardId>
<UserCardCode><![CDATA[018255396048]]></UserCardCode>
</xml>
Parameters
| Parameter | Description |
|---|---|
| ToUserName | Developer's Weixin ID |
| FromUserName | Sender ID (OpenID) |
| CreateTime | Creation time of message (integer) |
| MsgType | Message type (event) |
| CardId | Coupon ID |
| UserCardCode | Coupon code |