会员营销DEMO介绍

      会员营销DEMO是一套基于会员营销产品开发的会员营销场景体验系统，目前主要包括商户会员卡、营销活动等主要产品。具体场景包括商户会员卡开卡流程，商户会员卡开卡并领券流程和用户消费送券流程。

      服务端框架采用SpringBoot+myBatis+sqlLite 搭建，前端框架采用BootStrap+jQuery+H5搭建。具体运行和使用方法请参见《会员营销DEMO使用说明文档》，此文档详细描述了开发环境的搭建，参数的配置，服务的部署，以及场景介绍。

      开发者可以点击此处下载DEMO源码。此源码本着学习交流的目的，供开发者参考调试使用。

      我们也将这套会员营销DEMO部署在云服务器上对外提供服务，欢迎广大开发者通过支付宝钱包扫码体验。

      会员营销场景DEMO主页入口二维码和会员营销测试门店体验二维码如下：

                                

场景方案一：商户会员卡开卡

业务介绍

      会员卡开卡是商户会员卡产品最基本的功能，也是会员营销的基础。商户会员卡产品介绍可参考在线文档（点击访问）

流程介绍

      用户通过领卡入口*，进入用户授权页面。授权完毕，进入会员信息确认页面。用户填入必填信息，点击“开通会员卡”按钮，跳转至会员卡详情页面，展示开卡结果。用户可以体验会员卡各功能，包括会员卡基本信息，二级菜单，外链URL等。用户也可以在卡券包里查找已开会员卡。

     *商户会员卡领卡入口目前支持如下几种：a）线下扫描二维码进行领卡 b）口碑店铺页领卡入口 c）支付成功页广告位引导领卡 d）生活号推送领卡消息引导领卡。

线下扫描二维码领卡流程如下图所示：

                    

口碑店铺页领卡流程如下图所示：

                     

 其他领卡入口类似，不在这里描述。会员营销DEMO也提供了前两种最常用的方式为大家演示。

快速接入

      关于商户会员卡接入的基本流程和接口调用请参考商户会员卡快速接入文档（点击访问）。此文档站在产品接入的角度详细介绍了从创建应用到接口调用的具体步骤。我们在这里从场景开发的角度为大家描述具体接入的细节及注意事项。

接入准备

      创建应用，配置秘钥，搭建开发环境请参见会员卡快速接入文档（点击访问）。除此以外，需要为应用开通如下功能权限：商户会员卡、第三方应用授权、口碑开店（图片上传接口）、获取会员信息。同时，必须为开发者创建的应用配置正确的授权回调地址，该地址域名必须指向开发者的会员卡服务域名，否则调用时会报错。

步骤一：创建会员卡模板

      创建会员卡模板是商户为用户发卡的前提。开发者需要实现会员卡模板创建接口（alipay.marketing.card.template. create）接口来创建卡模板。卡模板布局介绍、业务流程图以及接口具体实现方法请参见快速接入文档。除此以外，还有几点需要特殊注意：

      1）request_id为接口调用唯一性标识，开发者需要确保每次调用不可重复，否则将以幂等性规则处理。

      2）卡模板所需所有图片资料都需要使用图片和视频资料上传接口（alipay.offline.material.image.upload）事先上传，并获取图片ID作为模板创建接口参数传入。各图片规格要求请参见快速接入文档模板创建部分。

      3）若要使用口碑店铺页作为领卡入口，开发者需提前申请开通口碑门店。具体操作流程请参见口碑开店快速接入。

      4）在创建会员卡模板时，需要传入shop_ids参数，指定需要露出领卡入口的店铺ID，才会在相应的口碑店铺页露出领卡入口，否则不会显示。

      5）shop_ids, open_card_conf, pub_channels 三个参数需要同时传入方可调用成功。shop_ids为数组类型，元素数量最大为1024；open_card_conf的子参数open_card_url需要指向开发者的领卡页面，否则入口无效。

      6）column_info_list的子参数more_info.params作为more_info.url的可传入扩展参数，是在调用开卡接口时需要url回带的值。若回带参数格式为xxx_yyy_zzz, 则more_info.params的值需要设为{key:$XxxYyyZyy$}方可被识别。

      7）调用此接口时还可能遇到如下错误：{"code":"40004","msg":"Business Failed","sub_code":"INVALID_PARAMETER", "sub_msg" : "参数有误。请求参数存在敏感词问题"} －原因是支付宝有敏感词库，请求信息不能包含敏感词库中的词，外加“充值”字样。

       由于卡模板创建接口参数比较多，数据类型比较复杂，开发者可参考Demo源码进行调用和调试。

步骤二：会员卡开卡

      调用会员卡开卡（alipay.marketing.card.open）接口之前，为防止向用户滥发会员卡，需要获取用户授权，即开卡接口公共参数auth_token为必填参数。获取auth_token的方法可以参见用户信息授权文档。获取用户授权的权限值scope需要取值“auth_user,auth_ecard”。redirect_uri为商户领卡链接地址。此链接需要开发者在代码中自行拼装，链接示例如下：
https://openauth.alipay.com/oauth2/publicAppAuthorize.htm?app_id=2015072700188950&auth_skip=false&scope=auth_user,auth_ecard&redirect_uri=http%3A%2F%2Fkely.ngrok.sapronlee.com%2Fshop%2Fhello

      开卡成功后，需要调用会员卡查询接口(alipay.marketing.card.query)，获取会员卡信息和schema_url。会员卡信息中包含支付宝为用户分配的业务卡号，作为商户会员卡在支付宝端的唯一标识。schema_url是跳转至会员卡详情页的链接地址，为系统自动生成。开发者可以通过此链接实现开卡成功直接跳转至卡详情页的业务逻辑。

      开卡接口详细介绍、业务流程图以及接口具体实现方法请参见快速接入文档。除此以外，还有几点需要特殊注意：      

      1）app_id为开发会员卡的应用ID，并且配置的授权回调地址域名必须与redirect_uri域名保持一致，否则授权回调时会报无法打开页面的错误。

      2）如果是商户授权ISV进行开发，在ISV完成第三方授权流程后会获取到app_auth_token。该参数需要和模版创建接口的app_auth_token保持一致。

      3）对于已绑卡，即使使用不同流水号和相同卡号再次调用开卡接口，系统也不会将此卡与其他支付宝业务卡号绑定。也就是说不会产生一张外部卡对应多张支付宝业务卡的情况。

      4）开卡接口调用时间必须在卡片有效期内，否则会开卡失败。

步骤三：实现开发者页面流程和数据存储

      从用户信息授权页面到会员卡详情页之间的所有业务流程页面均为开发者自行开发。主要包括会员信息确认页面，或者业务需要的其他自定义页面。一般来说主要实现商户会员身份的校验同时根据不同身份实现不同流程的逻辑。

      开发者需要在本地数据库存储一些必要信息，例如卡模版ID（templateId），用户ID（alipay_user_id），商户外部卡号（external_card_no），支付宝业务卡号（alipay_card_no），卡详情页地址（schema_url）等，具体存储参数可根据业务需要增加，具体存储方式可根据开发者数据库类型自行实现。

 

      到此为止，商户会员卡开卡场景就基本实现了。在整个开发过程中还可能会用到其他接口，

功能	相关API	描述	查看
商户会员卡	卡模板修改接口（alipay.marketing.card.template.modify）	修改商户会员卡模版	查看API
商户会员卡	卡模板查询接口（alipay.marketing.card.template.query）	查询商户会员卡模版	查看API
商户会员卡	会员卡更新接口（alipay.marketing.card.update）	更新商户会员卡信息	查看API
商户会员卡	会员卡删除接口（alipay.marketing.card.delete）	删除商户会员卡	查看API
商户会员卡	消费记录同步接口（alipay.marketing.card.consume.sync）	下架营销活动	查看API

在这里需要介绍一下会员卡删卡的逻辑，其他不做一一介绍，可以参见快速接入文档和API接口文档。

会员卡删卡

关于会员卡删卡接口的使用需要注意以下几点：

      1）用户端卡删除是逻辑删除，不是物理删除，所以后期可以提供再次绑定的功能。

      2）删卡接口参数reason_code有三个可选值，USER_UNBUND：用户解绑（可以重新绑定） CANCEL：销户（完成销户后，就不能再重新绑定） PRESENT：转赠（可以重新绑定）。此点需要特殊注意。

      3）开卡成功后删除，再绑卡时如果使用同样的流水号和卡号，返回结果依然是成功，但此时卡未再次绑定。为了保证每次请求成功，需要开发者保证流水号的唯一性。即必须使用不同的流水号和相同的卡号重新绑卡方可成功。

      4）卡片删除后，通过卡查询接口依然可以查询到此卡，但URL地址为空，此点为判断卡是否已被删除的依据。

 

场景方案二：商户会员卡开卡领券

业务介绍

      会员卡开卡领券是商户会员卡产品结合营销活动最典型的场景，也是会员营销的基本业务流程。商户会员卡产品介绍可参考在线文档（点击访问），营销活动产品介绍可以参考在线文档（点击访问）。

流程介绍

      用户通过开卡领券入口*，进入用户授权页面。授权完毕，进入会员信息确认页面。用户填入必填信息，点击“开通会员卡并领券”按钮，跳转至口碑领券页面。用户点击领券，领券成功后跳转至卡券包，展示已领券和卡。用户可以点击券进入券详情页，并且可以点击去买单进行支付核销。同时，用户也可以在卡券包点击会员卡进入到会员卡详情页，可以体验会员卡各功能，包括会员卡基本信息，二级菜单，外链URL等。

     *商户会员卡领卡入口目前支持如下几种：a）线下扫描二维码进行领卡 b）口碑店铺页领卡入口 c）支付成功页广告位引导领卡 d）生活号推送领卡消息引导领卡。赠券为领卡权益，可以作为商户引流会员的一种营销手段使用。

线下扫描二维码开卡领券流程如下图所示：

               

      口碑店铺页也可以配置成开卡领券的入口。其他开卡领券入口类似，不在这里描述。会员营销DEMO提供了线下二维码扫码开卡领券的方式为大家演示。 

快速接入

      关于商户会员卡接入的基本流程和接口调用请参考商户会员卡快速接入文档（点击访问），营销活动接入的基本流程和接口调用请参考营销活动快速接入文档（点击访问）。此文档站在产品接入的角度详细介绍了从创建应用到接口调用的具体步骤。我们在这里从场景开发的角度为大家描述具体接入的细节及注意事项。

接入准备

      创建应用，配置秘钥，搭建开发环境请参见会员卡快速接入文档（点击访问）和营销活动快速接入文档（点击访问）。除此以外，需要为应用开通如下功能权限：商户会员卡、第三方应用授权、口碑开店（图片上传接口）、获取会员信息、会员集点（发券授权接口）、营销活动。同时，必须为开发者创建的应用配置正确的授权回调地址，该地址域名必须指向开发者的会员卡服务域名，否则调用时会报错。

步骤一：创建会员卡模板

     参见场景一 

步骤二：创建营销活动

      通过活动创建接口（koubei.marketing.campaign.activity.create）根据业务需要设置好要发的券，发券可参考示例。需要注意发券渠道publish_channels中，发券渠道type必须为URL_WITH_TOKEN，还需要设置公共参数notify_url用于接收用户领券通知，如何设置券，请预先参考营销接入文档设置券字段（点击访问）。创建成功后返回camp_id，即为创建活动的ID。

步骤三：会员卡开卡

     参见场景一     

步骤四：领券

      通过活动查询接口（koubei.marketing.campaign.activity.query），根据camp_id查询活动详情，并在返回字段publish_channels的ext_info中，获得领券链接（由URL_WITH_TOKEN字段标识），实例如下：publish_channels: [{config={}, ext_info={"URL_WITH_TOKEN":"https://render.alipay.com/p/z/pointset/index.html?itemId=2016102020076000000009664943"}, name=带token的链接投放, type=URL_WITH_TOKEN}]。接下来需要为领券链接添加用户授权token。

      通过授权发券接口（koubei.marketing.tool.prizesend.auth）获取发券的授权令牌，其中prize_id即为上一步中链接中的itemId字段，需要注意支付宝用户id（user_id）需要通过获取用户信息的流程，通过用户授权得到。user_id为支付宝用户的唯一标识，在支付宝体系内全局唯一。调用成功获取用户领券的授权token，用于拼接最后的用户领券链接。

      将领券URL展示在商户H5页面，用户点击该链接跳转至支付宝页面进行领券操作。用户领券token有效期为1小时，用户领券成功后，会向第一步中填写的notify_url同步用户领券成功的信息。（点击访问领券通知字段）

      拼接的授权授权领券链接以及链接字段解释入下：

      https://render.alipay.com/p/z/pointset/index.html?type=membercard&itemId=2016091820076000000005569798&token=5b78189e931a415f8c9b9df248a597a9&outBizNo=prize1476966783310

      type: 领券页类型(必填) pointcard-兑换，membercard-领取

      itemId：优惠券ID(必填)

      token：用户领券令牌(必填)

      outBizNo：外部交易流水号(必填)

      buyerId：用户UserId(选填)

      shopId：该优惠券适用的附近距离最近的商家口碑店铺ID(选填) 

步骤五：实现开发者页面流程和数据存储

      从用户信息授权页面到支付宝领券页之前的所有业务流程页面均为开发者自行开发。主要包括会员信息确认页面，或者业务需要的其他自定义页面。一般来说主要实现商户会员身份的校验同时根据不同身份实现不同流程的逻辑。

      开发者需要在本地数据库存储一些必要信息，例如卡模版ID（templateId），用户ID（alipay_user_id），商户外部卡号（external_card_no），支付宝业务卡号（alipay_card_no），卡详情页地址（schema_url），活动ID（camp_id），外部批次号（out_biz_no），商户ID（merchant_uid），券ID（prize_id），具体存储参数可根据业务需要增加，具体存储方式可根据开发者数据库类型自行实现。

     

      到此为止，商户会员卡开卡领券场景就基本实现了。在整个开发过程中还可能会用到其他接口，会员卡相关接口可以参见API接口文档，营销活动相关接口可以参见API接口文档。

 

功能	相关API	描述	查看
商户会员卡	卡模板修改接口（alipay.marketing.card.template.modify）	修改商户会员卡模版	查看API
商户会员卡	卡模板查询接口（alipay.marketing.card.template.query）	查询商户会员卡模版	查看API
商户会员卡	会员卡更新接口（alipay.marketing.card.update）	更新商户会员卡信息	查看API
商户会员卡	会员卡删除接口（alipay.marketing.card.delete）	删除商户会员卡	查看API
商户会员卡	消费记录同步接口（alipay.marketing.card.consume.sync）	同步用户消费记录	查看API
营销活动	活动修改接口（koubei.marketing.campaign.activity.modify）	修改营销活动信息	查看API
营销活动	活动下架接口（koubei.marketing.campaign.activity.offline）	下架营销活动	查看API

相关文档

      1、第三方应用授权（点击访问，当系统商帮商户开发系统对接支付宝，并且系统由系统商维护时，商户可通过第三方应用授权，将商户的支付宝账号权限授权给系统商进行会员卡管理而无需向系统商提供商户账号密码）

      2、获取用户信息（点击访问，当在支付宝钱包内获取用户信息时需要用到，主要用于门店固定二维码支付和同步支付宝用户信息）

      3、营销活动业务文档，用于产生券（点击访问），配合授权发券接口（点击访问）生成领券链接供用户在H5页面领取。

      4、创建营销活动券时会用到门店信息，可以通过口碑店铺管理相关接口，查询商户的所有门店或者查询商户所有门店摘要

      5、商户可以通过商家详情页广告进行会员卡广告宣传（点击访问）

 

场景方案三：用户消费送券

业务介绍

      用户消费送券是基于支付能力的最常用的营销活动之一，也是商户增加二次消费的主要方式。当面付产品介绍可以参见在线文档（点击访问），营销活动产品介绍可以参考在线文档（点击访问）。

流程介绍

      用户通过口碑店铺页或扫码消费后，系统将自动为用户发券。用户会收到送券通知，并且可以在卡券包点击券进入券详情页，进而点击去买单进行支付核销。

口碑店铺页消费送券流程如下图所示：

               

                

  其他消费入口类似，不在这里描述。会员营销DEMO提供了口碑店铺页消费和DEMO主页链接消费为大家演示。

快速接入

      关于当面付产品的接入请参见当面付快速接入文档（点击访问），营销活动接入的基本流程和接口调用请参见营销活动快速接入文档（点击访问）。此文档站在产品接入的角度详细介绍了从创建应用到接口调用的具体步骤。我们在这里从场景开发的角度为大家描述具体接入的细节及注意事项。

接入准备

      创建应用，配置秘钥，搭建开发环境请参见当面付快速接入文档（点击访问）和营销活动快速接入文档（点击访问）。除此以外，需要为应用开通如下功能权限：当面付、第三方应用授权、营销活动。同时，必须为开发者创建的应用配置正确的授权回调地址，该地址域名必须指向开发者的券服务域名，否则调用时会报错。

步骤一：实现当面付接口

      当面付作为支付宝基础支付能力，已经实现标准化接入，具体步骤请参见当面付快速接入文档。

       若需要在口碑店铺页露出“优惠买单”按钮，需要调用统一收单交易创建接口（alipay.trade.create）指定交易金额和所涉及店铺ID。

步骤二：创建营销活动

      通过活动创建接口（koubei.marketing.campaign.activity.create）根据业务需要设置好要发的券，发券可参考示例。需要注意发券渠道publish_channels中，发券渠道type必须为URL_WITH_TOKEN，还需要设置公共参数notify_url用于接收用户领券通知，如何设置券，请预先参考营销接入文档设置券字段（点击访问）。创建成功后返回camp_id，即为创建活动的ID。

      为实现指定门店消费后自动送券，有如下几点需要注意：

      1）需要将接口中type参数设置成CONSUME_SEND。活动创建接口还支持其他多种形式，包括DIRECT_SEND：直发奖活动，REAL_TIME_SEND：实时立减类活动，GUESS_SEND：口令送，RECHARGE_SEND：充值送，以及POINT_SEND：集点卡活动。开发者可根据自身业务需要选择合适的营销活动类型，此场景仅以消费送为例作为展示。

      2）接口参数promo_tools>send_rule>min_cost需要设定消费送最低消费金额，凡是消费金额超过或等于此金额才会触发送券动作。

      3) 接口参数constraint_info>suit_shops为消费送活动适用的门店列表，需要传入消费送活动覆盖门店ID，不能为空。只有在品牌商发起的招商活动时可为空，最多支持10万家门店。

      4）在相应门店配好活动以后，用户进行消费达到送券要求的，会在消费后推送送券通知给用户，提示用户已获取一张券，可在卡券包查看。

      5）若用户已有某门店代金券，在下次消费时，交易创建时会自动核销。

 

      到此为止，用户消费送券场景就基本实现了。在整个开发过程中还可能会用到其他接口，营销活动相关接口可以参见API接口文档。

接口英文名	接口中文名	详情
koubei.marketing.campaign.activity.modify	活动修改接口	查看文档
koubei.marketing.campaign.activity.offline	活动下架接口	查看文档
koubei.marketing.campaign.activity.query	活动详情查询	查看文档
koubei.marketing.campaign.activity.batchquery	口碑营销活动列表查询	查看文档
koubei.marketing.campaign.recruit.shop.query	招商门店分页查询接口	查看文档

特殊场景技术集成方案

（方案一）商户支付系统与会员系统由两家ISV提供时的交易通知

      当商户的支付系统由系统商A提供，而会员系统由系统商B提供，并且AB两个系统商并没有打通支付数据时，可以由支付宝技术支持申请当面付条码支付异步通知，将商户条码支付的异步通知地址设置为会员卡系统商B的网关地址。这样当用户付款成功后，会员卡系统商B会接收到用户支付成功的通知。该方案中支付成功异步通知格式同当面付扫码支付异步通知格式（点击查看）。

      使用条件：该方案有使用前提，必须商户只使用了当面付条码支付(接口名:alipay.trade.pay)以及没有配置条码支付异步通知地址，该方案才有效。

（方案二）商户支付系统与会员系统由两家ISV提供时的交易通知

      当商户的支付系统由系统商A提供，而会员系统由系统商B提供，并且AB两个系统商并没有打通支付数据时，可以通过支付宝交易第三方通知接口（alipay.trade.fastpay.third.notify）通知会员系统。当用户使用A系统商的支付系统支付成功后，提供会员系统的系统商B能够接收到支付宝以表单方式发出的用户支付成功的通知，会员系统商从而可以通过支付成功的结果，对该会员进行积分更新等操作。

      申请交易第三方通知的权限，需要向支付宝技术支持提交会员系统商在支付宝开放平台创建的应用id（app_id），以及接收通知的网关地址，如https://www.isv-xxx.com/notify_url/pay_success，支付宝添加完权限后，会员系统商需要将服务发布至开放平台服务市场（点此访问发布服务流程），服务发布成功后，需要让商户订购服务商发布的服务，（点此访问订购服务流程），商户使用支付的账号登录并订购完服务后，即表示商户授权会员系统商接收商户支付成功的通知。

通知字段如下：

卡券url scheme

卡列表（此appId为内部参数，不能更改）alipays://platformapi/startapp?appId=20000021&b=m&hasData=true&has_member_data=true

商户卡列表（pid参数指定商户的支付宝partner_id）alipays://platformapi/startapp?appId=20000021&b=t&a=sh&pid=xxx

卡详情（p参数指定会员卡的支付宝编号）alipays://platformapi/startapp?appId=20000021&b=m&p=11111&tagfrom=push

会员卡项目上线评估手册

序号	链路环节	主要事项	验收人	评估结果 （是否合格）	容易出现问题的关键点
1	用户注册开卡 路程	一键授权	技术/产品
		用户信息自动获取
		相关领卡界面的视觉&交互评估			是否符合要求，需要再优化？
		用户注册会员卡的需要勾选的资料信息（手机号，性别，地址等）或者自动获取用户信息			用户姓名和手机号是否会完全暴暴露？是否能获取？
		用户手机号注册			用户注册了微信会员或线下实体卡，同一手机号是否可以再注册支付宝会员？
		领取会员卡成功后，显示附近门店			是否显示，显示的门店是否正确？
2	商家提供的权益	会员引新阶段--商家提供权益	BD／运营		具体是什么权益？
		权益实现方式			用户是否实时收到？
		会员长期运营阶段--商家提供权益			具体是什么权益？
		会员长期运营阶段--会员专区及线下物料宣传			具体的会员专区是什么形式（地堆专区/整组货架专区/端架专区等）
3	用户领卡途径	支付成功页跳转领取	技术/产品		1、链路是否打通? 2、店铺页广告位插件功能是否已经申请？ 3、支付成功页广告位https协议是否采购和嵌入？ 4、会员卡广告位的设计图是否OK了？
		商家店铺页跳转领取
		线下扫码跳转领取
4	运营方案及配置 --口碑	新用户开卡后用户如何感知权益（券配置，券／积分等）	BD／运营		权益是否能实时触达到用户？
		新用户开卡后的券配置			券配置方是谁？能否实现券包？
		长期运营方案
5	后台数据沉淀	商家、服务商及口碑三方数据同步	BD/产品		老会员的数据是否可以同步？

 

 

 

 

 

 

FAQ

关于此文档暂时还没有FAQ