微信公众平台开发者文档 / 卡券事件推送

卡券事件推送

卡券事件推送

39f4e18a-0faa-389f-9755-1c5b108402ea.png

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
UserCardCodecode序列号。
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
UserCardCodecode序列号。

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。
UserCardCodecode序列号。自定义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。
UserCardCodeCode码。

使用网页调试工具调试该接口


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。
UserCardCodeCode码。
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码            

使用网页调试工具调试该接口