一脸通行接入(刷脸支付&刷脸核身)

支付宝校园一脸通行平台用于解决中小学刷脸支付和刷脸核身场景需求，在上线了一脸通行服务的学校，用户在一脸通行小程序（支付宝->中小学->一脸通行）开通刷脸服务后，根据学校实际落地的场景，可以在校园内通过刷脸进行支付（校园食堂消费、校园超市消费等），或者通过刷脸进出门禁

阅读对象

合作伙伴业务人员、合作伙伴开发人员、支付宝业务同学、集成技术支持小二、

技术准备

1.硬件技术能力：设备对接的时候，需要了解硬件设备知识、技术。2.2.需要有Android方面技术的储备，ISV开发app应用，封闭场景SDK开发。3.需要小程序开发技术能力。4.服务端接口开发通用能力。

2.IOT知识储备：能够懂IOT相关知识及技术。

3.客户端技术能力：需要有Android方面技术的储备，ISV开发app应用，封闭场景人脸SDK开发。

4.小程序技术能力：需要支付宝小程序开发技术能力。

5.服务端技术能力：具备服务端开发语言java、.net、php等编码能力，开发服务端接口。

集成方案链接

在正式接入前，请先参考相关的解决方案文档:

K12团餐一脸通行方案	https://alipay.open.taobao.com/docs/doc.htm?treeId=693&articleId=118577&docType=1
支付场景人脸app接入	https://alipay.open.taobao.com/docs/doc.htm?articleId=118578&docType=1
核身场景人脸app接入	https://alipay.open.taobao.com/docs/doc.htm?articleId=118579&docType=1

关键接入步骤和流程

对ISV技术对接的关键接入步骤和流程进行整体说明，其中涉及到的传参部分需要重点关注，这些传参会影响到返佣链路

第一步：硬件接入开发

硬件合作模式有三种：合作方自有硬件接入、合作方基于海马S1（商米FT1 MINI）接入、合作方基于第三方硬件接入。根据合作模式不同，接入的要求、内容和步骤会有差别。

1).合作方基于自有硬件或第三方硬件接入

具体接入步骤，请见邻客蚁上对应合作方的项目空间上的产品文档：《刷脸团餐设备开发指南 V 1.0》

支付宝内部文档链接：https://linkant.alipay.com/100/document#nm8i9w

2).合作方基于海马S1接入

具体接入步骤，请见邻客蚁上对应合作方的项目空间上的产品文档：《刷脸设备海马S1（FT1 MINI）开发指南 V 1.1》

支付宝内部文档链接：https://docs.open.alipay.com/11623/bmegh0/

第二步：对接一脸通行平台

一脸通行平台需要跟校园系统进行对接，对用户进行校园身份认证，同时按照学校维度建立人脸特库

（1）ISV为学校提供的校园系统，建议具备以下几个维度的数据：

• 学校维度的数据：学校名称、支付宝账户、学校统一社会信用代码、学校唯一标识、人脸特征库下载地址、第三方应用授权、门店ID信息等
• 人员维度的数据：姓名、身份证、身份（学生、教职工、访客等）、照片、支付宝UID、代扣协议信息、学生监护人手机号等
• 机具维度的数据：厂商、型号、SN等

（2）创建ISV自有小程序，并将小程序和学校信息提交给到对应BD

ISV信息：只需要提交一次

ISV中文名称		示例：鑫考教育
ISV英文名称		示例：xinkaojiaoyu
ISV小程序APPID		示例：2019xxxxxx

学校信息：测试学校用ISV的信息创建，每次上线学校都需要提交。

学校名称		事业单位法人证书，或者民办非企业单位登记证书中的学校名称
地区		省、市、区
学校支付宝账户		刷脸支付学校，需要提供学校支付宝账户，或者学校食堂承包商的支付宝账户；刷脸核身学校，不需要提供支付宝账户
统一社会信用代码		事业单位法人证书，或者民办非企业单位登记证书中的信息
学校类型		跟证件中的业务范围保持一致
客服电话		学校或者ISV的客服电话
ISV小程序名称
ISV小程序APPID

（3）ISV小程序审核上线

由于一脸通行平台只有生产环境，ISV的小程序需要发布上线后才能跟一脸通行平台进行对接，小程序中的注意事项：

• 配置应用网关：需要在小程序中配置应用网关地址，用于接收来自一脸通行平台的请求。应用网关开发参照身份认证数据接口。
• 默认跳转页面：一脸通行平台跳转到ISV小程序的默认页面，需要按照对接规范设置页面地址，否则无法从一脸通行小程序跳转到ISV的小程序

（4）对接一脸通行平台认证接口

• 一定要用ISV的身份来调用一脸通行平台接口，接口中的“app_id”必须为ISV小程序的APPID
• 学校系统要保存一脸通行平台请求过来的学校唯一标识等信息
• 认证成功后，一脸通行小程序会采集人脸信息，支付宝并以学校为单位建立人脸特征库

（5）从一脸通行小程序跳转到ISV小程序默认跳转页面

• 根据从一脸通行小程序跳转带过来的token信息查询出当前采集人脸的用户的支付宝UID
• 在默认跳转页面上引导用户进行代扣签约，建议将默认跳转页面做成代扣签约页面，引导用户完成代扣签约

（6）代扣签约（消费场景接入）

    ISV在接入每所学校之前，都需要将学校（商户）的支付宝账户给到对应的BD，支付宝BD会为学校（商户）签约代扣协议，签约成功后才能上线

• 代扣接口的对接采用第三方应用授权模式，ISV代学校（商户）进行对接
• 需要在开放平台创建一个第三方应用，用新的APPID来进行代扣开发，跟当前的小程序的APPID区分开来，因为当前小程序不支持第三方应用授权模式
• 代扣签约完成后，需要保存代扣签约协议号等信息，用于后续向签约用户发起扣款

     核身场景ISV需要完成核身功能的页面提示。

第三步：支付场景/核身场景人脸app对接

• 支付场景人脸app对接

ISV需要在刷脸机具上开发收银APP，收银APP需要对接支付场景人脸APP。收银APP主要的状态和功能：

（1）开机启动

• 此时机具向校园系统进行注册，系统需要知道刷脸机具所属学校
• 服务端用学校的唯一标识、场景码等信息，请求查询key接口获取groupid。（groupid一般不变，只要获取一次即可。如后续有学校、门店等信息变更需要重新生成）

（2）人脸初始化

• 校园系统将该校的人脸库groupid同步到机具端的收银APP
• 收银APP调用刷脸SDK进行人脸库的初始化

（3）调用摄像头

（4）处理识别结果

识别成功后返回用户的支付宝UID、ftoken，根据支付宝UID找到该用户在校园系统中的信息

• 核身场景人脸app对接

ISV需要在刷脸机具上开发核身APP，核身APP需要对接支付宝核身场景人脸APP。核身APP主要的状态和功能：

（1）开机启动

• 此时机具向校园系统进行注册，系统需要知道刷脸机具所属学校
• 服务端用学校的唯一标识、场景码等信息，请求查询key接口获取groupid。（groupid一般不变，只要获取一次即可。如后续有学校、门店等信息变更需要重新生成）

（2）人脸初始化

• 校园系统将该校的人脸库groupid同步到机具端的核身APP
• 核身APP调用刷脸SDK进行人脸库的初始化

（3）调用摄像头

（4）处理识别结果

识别成功后返回用户的支付宝UID、ftoken，根据支付宝UID找到该用户在校园系统中的信息，校验通过，核身完成。

第四步：代扣交易传参（消费场景接入）

代扣交易是需要传入ISV的标识和刷脸机具上的签名信息，否则无法进行返佣统计。具体必传参数参见K12一脸通行方案——商户代扣接入指引

• 代扣交易接口的参数“sys_service_provider_id”中传入ISV的PID
• 代扣交易接口的参数“ terminal_params”参数中传入IoT签名数据

第五步：建议扣款处理逻辑（消费场景需关注）

在校园系统根据用户的代扣协议信息发起扣款，建议扣款采用异步模式，当刷脸识别成功后，即可让用户进行消费，收银APP侧生成和存储消费订单，然后再向用户发起扣款，扣款异常处理：

• 由于机具可能断网，所以收银APP必须要存储消费订单，然后再将消费订单及时同步到校园系统，网络正常的情况下要立即将订单发送到服务端进行扣款，禁止在存储在机具上再批量发起。
• 扣款失败，在校园系统中为用户设置一个最大的欠费上线金额，记录用户的欠费信息，同时建立黑名单机制，根据欠费次数、欠费总金额来建立黑名单：

1. 对于触发规则的用户，则放入黑名单，同时黑名单需要存储在机具端和服务器端，两边的黑名单需要保持一致
2. 对于欠费的用户，校园系统需要建立追讨机制，每天向欠费用户追讨一次，根据欠费订单进行扣款
3. 如果欠费用户的欠费订单都已经结清，则将该用户从黑名单中移除

• 如果学校不采用欠费机制，则建议在用户开通刷脸服务时，向用户支付宝账户扣款20~50元存入余额账户作为服务保证金，每次刷脸后都检查用户的余额账户

第六步：设备绑定

- 刷脸支付设备：

（1）ISV帮学校（商户）创建门店并获取门店ID

• 请登陆支付宝开放平台->运营中心->商家管理->我的商家->我的商家门店->代商家创建门店->开始创建门店
• 业务场景必须选择“K12”，如果是学校主体，则选择的门店类目必须为“教育-学校-高中/初中/小学/幼儿园”；如果商户非学校主体，而是在学校承包食堂的 “校园团餐”或者“企业团餐”商户，则选择的门店类目必须为“美食-团餐-校园团餐-高中/初中/小学/幼儿园”

（2）建立“ISV PID->学校PID->门店 ID->学校外标->设备SN”映射关系

• ISV调用设备绑定接口（alipay.commerce.iot.mdeviceprod.device.bind）将设备SN跟商户的门店关联起来，建立“ISV PID->学校PID->门店 ID->学校外标（新增）->设备SN”绑定关系。

 - 核身设备：

（1）建立“ISV PID->学校外标->设备SN”映射关系

• ISV调用设备绑定接口（alipay.commerce.iot.mdeviceprod.device.bind）建议“ISV PID->学校外标（新增）->SN”的绑定关系。

备注：

1.ISV系统一定要管理“学校->门店->学校外标->设备->绑定状态”维度的数据，便于后续核对返佣数据。如果暂时没有设备管理平台，务必通过excel文件记录“学校名称、学校门店ID、学校外标、设备SN、设备是否已经绑定门店”的信息，后续对于没有绑定门店的设备，可以再调用绑定接口进行绑定。

2.在设备绑定接口（alipay.commerce.iot.mdeviceprod.device.bind）中增加school_stdcode参数传入学校编码（组织机构代码），此参数为k12行业使用，入参时需增加，未体现在文档上。

第七步：验收

按照一脸通行方案中的要求进行验收，保证数据准确，确保不会影响到返佣结算。验收文档从接入指引文档中下载获取checklist，了解验收点，整个方案全部集成后，ISV发起验收申请，完成验收用例的填写。

备注：没有通过验收，不能上线，避免后续返佣出现问题，影响到返佣结算

附录：

1.ISV人员需要准备的事项

1）.准备ISV入驻信息，学校入驻信息，按照上面的表填写，学生测试数据，用于测试。（联调阶段，支付宝可创建测试学校，ISV需要准备两个企业支付宝账户，一个是ISV角色支付宝账户，一个是学校角色支付宝账户）

2）.准备小程序appid，第三方应用appid，应用都要发布上线。

3）.开发认证网关，上传到小程序appid的应用网关处。

4）.开发第三方应用授权链接，授权回调页面，并配置应用的授权回调页面。用于学校签约商户代扣的支付宝账户给ISV做授权。

5）.准备小程序入口地址及小程序跳转地址（在消费场景中，小程序跳转地址可以认为是用户签约页面地址）

6）.ISV收银app与支付宝封闭场景刷脸交互UI需要联系@从彦一起评审。

2.支付宝业务需要操作事项

1).在支付宝业务后台配置ISV、学校信息，同时配置刷脸支付等服务，以PD信息为准。（联调初期需协调PD创建测试学校并开通服务）

2).推进ISV小程序审批，配置小程序跳转地址等。

3).为学校账户签约商户代扣、垫资保付协议，同时为第三方应用appid挂商户代扣接口包。

3.返佣政策说明

对影响返佣的关键因素进行说明

签约要求	ISV签约的返佣销售方案：K12一卡通协作费方案
返佣对象	1，返佣政策用包括了新账户激励、刷脸账户促活激励、核身账户促活激励、机具返佣、交易返佣 2，系统根据对应的角色进行返佣 -         新账户激励：该用户所在一脸通行平台上的学校的认证服务的关联ISV -         刷脸账户促活激励：该用户所在一脸通行平台上的学校的刷脸支付服务的关联ISV -         核身账户促活激励：该用户所在一脸通行平台上的学校的刷脸核身服务的关联ISV -         刷脸支付机具返佣：“ISV PID->商户PID->门店ID->SN”的绑定关系中的ISV -         交易返佣：交易传参中的ISV（sys_service_provider_id）
返佣范围	1.新账户激励： -    数据关联关系： K12场景下的一脸通行&电子学生卡的新用户数据，根据用户数据找到对应的学校数据，学校数据中有认证服务关联的ISV -    政策条件： 1) 学生本人自主注册支付宝账号的时间，不早于学生首次使用K12业务场景 时间7个自然日；  2) 家长端协助学生注册并开通支付宝一脸通行； 3) 开通的学生账号年龄须小于等于20周岁，同一身份证号视为同一用户只激 励一次；  4) 通过支付宝风控模型过滤后排重的真实用户； 5) 学生身份信息经学校或相关教育机构验证通过； -    特殊备注：      同一用户只返佣一次，如果出现多场景（一脸通行，电子学生卡），以最新的创建场景为准   2.刷脸支付活促活激励： -    数据关联关系： K12场景刷脸支付用户数据，根据刷脸支付数据关联刷脸行为表，找到对应的刷脸用户，根据刷脸用户数据找到对应的学校数据，学校数据中有刷脸支付服务关联的ISV -    政策条件 1) 满足K12学生账号新账号条件； 2) K12刷脸支付设备上至少一次有效的刷脸支付IOT交易；   3.刷脸核身活促活激励： -    数据关联关系： K12场景刷脸行为数据，根据用户数据找到对应的学校数据，学校数据中有刷脸核身关联的ISV -    政策条件 1) 满足K12学生账号新账号条件；  2) 基于支付宝IOT SDK和人脸算法SDK，有过至少一次刷脸报活；   4.刷脸支付设备补贴： -   数据关联关系 走当前通用的IoT机具返佣链路，用IoT机具绑定关系的数据，其中机具绑定的 ISV，还有绑定的商户PID，在业务平台上学校有关联支付宝账户（PID需要补充） -   政策条件 刷脸支付设备需来源于支付宝准入条件的邀约合作厂商，其支付设备须采 用奥比摄像头，且支付设备须采用支付宝人脸算法； -  行业限制条件 1）商米海马刷脸设备的行业场景是“泛行业”，非海马机的行业场景是“K12” 2）如果是海马机，设备绑定的门店必须为“教育-学校-高中/初中/小学/幼儿园”或者“美食-团餐-校园团餐-高中/初中/小学/幼儿园”，或者收款的商户主体MCC为中小学校   5.交易返佣： -   数据关联关系 当前通用的交易返佣链路 -   行业限制条件 1）代扣交易接口的参数“sys_service_provider_id”中传入ISV的PID 2）代扣交易的” terminal_params”参数中传入加签的IoT签名数据 3）收款商户所属的行业MCC类目必须为中小学校，或者校园团餐，  4）刷脸交易在支付宝IOT后台必须为刷脸支付交易，在IoT平台判断交易为刷脸支付交易

ISV业务人员作业主要流程：

（1）收集学校学校信息提交给到支付宝业务人员

学校名称		事业单位法人证书，或者民办非企业单位登记证书中的学校名称
地区		省、市、区
学校支付宝账户		刷脸支付学校，需要提供学校支付宝账户，或者学校食堂承包商的支付宝账户；刷脸核身学校，不需要提供支付宝账户
统一社会信用代码		事业单位法人证书，或者民办非企业单位登记证书中的信息
学校类型		跟证件中的业务范围保持一致
客服电话		学校或者ISV的客服电话
ISV小程序名称
ISV小程序APPID

（2）支付宝业务人员通知服务商业务人员学校签约成功

（3）服务商业务人员通知学校或者食堂承包商登陆支付宝账户确认签约

（4）将实现代扣的第三方应用的授权链/二维码接发给学校或者食堂商进行支付宝授权

（5）代学校或者食堂承包商创建门店，在门店审批通过后获取到门店ID信息

FAQ

关于此文档暂时还没有FAQ