微信公众平台开发者文档
/ 卡券事件推送
卡券事件推送
卡券事件推送
1.更新日志
| 版本号 | 更新内容 | 更新时间 |
|---|---|---|
| V1.0 | 核销事件新增核销门店，如果为手机助手核销则可以推送核销员openid。 | 2015-8-31 |
| V1.1 | 核销事件新增买单相关字段，商户订单号和微信支付交易订单号。 | 2015-9-8 |
| V1.2 | 新增库存报警事件，当用户领取到最好一张卡券的时候推送库存报警事件 | 2015-9-8 |
| V1.3 | 新增库会员卡内容更新事件，通过事件告知开发者积分和余额变动情况 | 2015-10-28 |
| V1.4 | 新增转赠会员卡接口 | 2016-9-19 |
2.卡券事件推送
卡券通过审核、卡券被用户领取、卡券被用户删除、卡券被商户核销、从卡券进入公众号等情况均会触发事件推送，该事件将发送至开发者填写的URL（登录公众平台进入【开发者中心设置】）。 开发者可通过事件推送完成数据统计、用户身份识别等操作。
微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。关于重试的消息排重，推荐使用FromUserName + CreateTime 排重。假如服务器无法保证在五秒内处理并回复，可以直接回复空串，微信服务器不会对此作任何处理，并且不会发起重试。
2.1 审核事件推送
生成的卡券通过审核时，微信会把这个事件推送到开发者填写的URL。
<xml> <ToUserName><![CDATA[toUser]]></ToUserName> <FromUserName><![CDATA[FromUser]]></FromUserName> <CreateTime>123456789</CreateTime> <MsgType><![CDATA[event]]></MsgType> <Event><![CDATA[card_pass_check]]></Event> //不通过为card_not_pass_check <CardId><![CDATA[cardid]]></CardId> <RefuseReason><![CDATA[非法代制]]></RefuseReason> </xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号 |
| FromUserName | 发送方帐号（一个OpenID） |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息类型，event |
| Event | 事件类型，card_pass_check(卡券通过审核)、card_not_pass_check（卡券未通过审核） |
| CardId | 卡券ID |
RefuseReason | 审核不通过原因 |
使用网页调试工具调试该接口
2.2 领取事件推送
用户在领取卡券时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：
<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> </xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 领券方帐号（一个OpenID）。 |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event |
| Event | 事件类型，user_get_card(用户领取卡券)。 |
| CardId | 卡券ID。 |
| IsGiveByFriend | 是否为转赠领取，1代表是，0代表否。 |
| FriendUserName | 当IsGiveByFriend为1时填入的字段，表示发起转赠用户的openid |
| UserCardCode | code序列号。 |
| OldUserCardCode | 为保证安全，微信会在转赠发生后变更该卡券的code号，该字段表示转赠前的code。 |
| OuterStr | 领取场景值，用于领取渠道数据统计。可在生成二维码接口及添加Addcard接口中自定义该字段的字符串值。 |
| IsRestoreMemberCard | 用户删除会员卡后可重新找回，当用户本次操作为找回时，该值为1，否则为0 |
使用网页调试工具调试该接口
2.3转赠事件推送
用户在转赠卡券时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 领券方帐号（一个OpenID）。 |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event |
| Event | 事件类型，user_gifting_card(用户转赠卡券)。 |
| CardId | 卡券ID。 |
| FriendUserName | 接收卡券用户的openid |
| UserCardCode | code序列号。 |
IsReturnBack | 是否转赠退回，0代表不是，1代表是。 |
IsChatRoom | 是否是群转赠 |
使用网页调试工具调试该接口
2.4 删除事件推送
用户在删除卡券时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID） |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event |
| Event | 事件类型，user_del_card(用户删除卡券) |
| CardId | 卡券ID。 |
| UserCardCode | code序列号。自定义code及非自定义code的卡券被领取后都支持事件推送。 |
使用网页调试工具调试该接口
2.5 核销事件推送
卡券被核销时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：
<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>
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID）。 |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event。 |
| Event | 事件类型，user_consume_card(核销事件) |
| CardId | 卡券ID。 |
| UserCardCode | 卡券Code码。 |
| ConsumeSource | 核销来源。支持开发者统计API核销（FROM_API）、公众平台核销（FROM_MP）、卡券商户助手核销（FROM_MOBILE_HELPER）（核销员微信号） |
| LocationName | 门店名称，当前卡券核销的门店名称（只有通过自助核销和买单核销时才会出现该字段） |
| StaffOpenId | 核销该卡券核销员的openid（只有通过卡券商户助手核销时才会出现） |
VerifyCode | 自助核销时，用户输入的验证码 |
| RemarkAmount | 自助核销时，用户输入的备注金额 |
| OuterStr | 开发者发起核销时传入的自定义参数，用于进行核销渠道统计 |
使用网页调试工具调试该接口
2.6 买单事件推送
微信买单完成时，微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例：
<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>
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID）。 |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event。 |
| Event | 事件类型，User_pay_from_pay_cell(微信买单事件) |
| CardId | 卡券ID。 |
| UserCardCode | 卡券Code码。 |
| TransId | 微信支付交易订单号（只有使用买单功能核销的卡券才会出现） |
| LocationId | 门店ID，当前卡券核销的门店ID（只有通过卡券商户助手和买单核销时才会出现） |
| Fee | 实付金额，单位为分 |
| OriginalFee | 应付金额，单位为分 |
使用网页调试工具调试该接口
2.7 进入会员卡事件推送
用户在进入会员卡时，微信会把这个事件推送到开发者填写的URL。
需要开发者在创建会员卡时填入need_push_on_view 字段并设置为true。开发者须综合考虑领卡人数和服务器压力，决定是否接收该事件。
推送XML数据包示例：
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID）。 |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event。 |
| Event | 事件类型，user_view_card(用户点击会员卡) |
| CardId | 卡券ID。 |
| UserCardCode | 商户自定义code值。非自定code推送为空串。 |
| OuterStr | 商户自定义二维码渠道参数，用于标识本次扫码打开会员卡来源来自于某个渠道值的二维码 |
使用网页调试工具调试该接口
2.8 从卡券进入公众号会话事件推送
用户在卡券里点击查看公众号进入会话时（需要用户已经关注公众号），微信会把这个事件推送到开发者填写的URL。开发者可识别从卡券进入公众号的用户身份。 推送XML数据包示例：
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID） |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event |
| Event | 事件类型，user_enter_session_from_card(用户从卡券进入公众号会话) |
| CardId | 卡券ID。 |
| UserCardCode | Code码。 |
使用网页调试工具调试该接口
2.9 会员卡内容更新事件
当用户的会员卡积分余额发生变动时，微信会推送事件告知开发者。 推送XML数据包示例：
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号。 |
| FromUserName | 发送方帐号（一个OpenID） |
| CreateTime | 消息创建时间 （整型）。 |
| MsgType | 消息类型，event |
| Event | 事件类型，update_member_card(会员卡内容更新） |
| CardId | 卡券ID。 |
| UserCardCode | Code码。 |
| ModifyBonus | 变动的积分值。 |
| ModifyBalance | 变动的余额值。 |
使用网页调试工具调试该接口
2.10 库存报警事件
当某个card_id的初始库存数大于200且当前库存小于等于100时，用户尝试领券会触发发送事件给商户，事件每隔12h发送一次。
<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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号 |
| FromUserName | 发送方，微信 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息类型，event |
| Event | 事件类型，card_sku_remind库存报警 |
| CardId | 卡券ID |
| Detail | 报警详细信息 |
使用网页调试工具调试该接口
2.11 券点流水详情事件
当商户朋友的券券点发生变动时，微信服务器会推送消息给商户服务器。
<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[开通账户奖励]]></Memo> <ReceiptInfo><![CDATA[]]></ReceiptInfo> </xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号 |
| FromUserName | 发送方，微信 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息类型，event |
| Event | 事件类型，card_pay_order券点流水详情事件 |
| OrderId | 本次推送对应的订单号 |
| Status | 本次订单号的状态,ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票 |
| CreateOrderTime | 购买券点时，支付二维码的生成时间 |
| PayFinishTime | 购买券点时，实际支付成功的时间 |
| Desc | 支付方式，一般为微信支付充值 |
| FreeCoinCount | 剩余免费券点数量 |
| PayCoinCount | 剩余付费券点数量 |
| RefundFreeCoinCount | 本次变动的免费券点数量 |
| RefundPayCoinCount | 本次变动的付费券点数量 |
| OrderType | 所要拉取的订单类型 ORDER_TYPE_SYS_ADD 平台赠送券点 ORDER_TYPE_WXPAY 充值券点 ORDER_TYPE_REFUND 库存未使用回退券点 ORDER_TYPE_REDUCE 券点兑换库存 ORDER_TYPE_SYS_REDUCE 平台扣减 |
| Memo | 系统备注，说明此次变动的缘由，如开通账户奖励、门店奖励、核销奖励以及充值、扣减。 |
| ReceiptInfo | 所开发票的详情 |
使用网页调试工具调试该接口
2.12 会员卡激活事件推送
当用户通过一键激活的方式提交信息并点击激活时，商户会收到用户激活的事件推送
<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>
参数说明
| 参数 | 说明 |
|---|---|
| ToUserName | 开发者微信号 |
| FromUserName | 发送方帐号（一个OpenID） |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息类型，event |
| CardId | 卡券ID |
| UserCardCode | 卡券Code码 |
使用网页调试工具调试该接口