阅读对象

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

集成方案链接

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

关键接入步骤和流程

对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/

第二步：对接高校团餐人脸认证、签约小程序

高校团餐人脸小程序需要跟ISV的校园系统进行对接，对用户进行校园身份认证，同时按照学校维度建立认证、面部向量索引

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

• 学校维度的数据：学校名称、支付宝账户、教育部学校标识码、面部向量索引库下载地址、第三方应用授权、门店ID信息等
• 人员维度的数据：姓名、身份证、身份（学生、教职工、访客等）、照片、支付宝UID、代扣协议信息等
• 机具维度的数据：厂商、型号、SN等

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

ISV信息：只需要提交一次

学校信息：测试学校用ISV的信息创建，首次联调可由业务在后台创建测试学校。每次新增上线学校都需要提交新学校的信息，业务同学需要在支付宝业务后台配置。

（3）ISV小程序审核上线，对接高校团餐人脸小程序

由于高校团餐人脸小程序对接只有生产环境，ISV的小程序需要发布上线后才能跟高校团餐人脸小程序进行对接，小程序中的注意事项：

• 配置应用网关：需要在小程序的appid中配置应用网关地址，用于接收来自高校人脸核身的学生认证请求。应用网关开发参照一卡通认证绑定接口开发。
• 用户授权：ISV小程序需要做用户授权，通过小程序授权获取用户uid。用于关联学生信息。
• 默认跳转页面：高校人脸组件跳转到ISV小程序的页面，小程序跳转页面开发完成后，需提供给支付宝业务同学/产品，在支付宝业务后台配置，否则无法从高校团餐人脸小程序跳转到ISV的小程序。
• 学生信息关联：认证、签约完成后，调用校园卡查询接口获取学生基本信息，完成开通高校人脸支付。
• 高校团餐人脸小程序接入，参考“高校团餐人脸支付集成指引”中，人脸小程序调用及签约集成。

（4）服务端对接学生认证接口

• 一定要用ISV的身份来调用高校团餐人脸小程序及服务端学生认证接口，接口中的“app_id”必须为ISV小程序的APPID
• 学校系统要保存学生认证接口请求过来的学校标识，学生信息等日志信息。
• 认证成功后，高校团餐人脸小程序会核身人脸信息，支付宝并以学校为单位建立面部向量索引

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

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

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

第三步：封闭场景SDK集成

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

（1）开机启动

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

（2）人脸初始化

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

（3）调用摄像头

（4）处理识别结果

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

（5）刷脸日志回流和上报

刷脸支付完成后，需要将刷脸日志等相关的数据回流。通过人脸特征报告上传接口和封闭式教育场景-本地人脸比对成功同步接口进行数据回流和上报。

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

代扣交易是需要传入ISV的标识和刷脸机具上的签名信息，否则无法进行返佣统计。具体必传参数参考“高校团餐人脸支付集成指引”中，商户代扣及先享后付集成。

1.商户代扣

• 代扣交易接口的参数“sys_service_provider_id”中传入ISV的PID
• 代扣交易接口的参数“ terminal_params”参数中传入IoT签名数据
• 还有其他信息，详见“高校团餐人脸支付集成指引”中，商户代扣及先享后付集成。

2.先享后付传参（垫资传参，如不涉及垫资可无需关注）

        先享后付传参是在商户代扣交易接口中业务请求参数中增加参数，返回接口中增加参数。垫资的次数，金额，isv需要累积，终端设备及服务端要保持垫资规则一致。

• 代扣交易接口的入参新增：advance_payment_type，用以指定本次扣款是否需要垫资，需要则传入：ENJOY_PAY_V2
• 代扣交易接口的响应结果和异步通知，新增参数：advance_amount， 改值代表本次交易，垫资主体出资金额。

第五步：扣款处理逻辑建议

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

• • 在有网情况下，机具端在人脸匹配成功后，通过uid判断用户的签约状态及协议号、黑名单机制，都通过之后，机具端提示“消费成功可用餐”，然后发起代扣支付；其中一个判断因子不通过，需要使用其他支付方式。
  • 无网情况下，机具端在人脸匹配成功后，通过uid判断用户的签约状态、黑名单机制，都通过之后，机具端提示“消费成功可用餐”，机具端中收银APP必须要存储消费订单，然后再将消费订单及时同步到校园系统，网络正常的情况下要立即将订单发送到服务端进行扣款，禁止存储在机具上后再批量发起。
  • 在没有前置服务器的情况下，机具端要缓存人脸特征库、用户的签约状态及协议号、黑名单，保持实时或者每天有网的情况下及时更新。
  • 新上线学校，首次使用的用户，可以不用判断黑名单，但需要检查用户的签约状态及协议号，然后再发起支付请求。
  • 解约方式：有同步和异步，这里我们推荐使用异步解约方式。异步解约是用户在支付宝app中提交解约申请，此时支付宝app中显示解约中状态，而支付宝服务端通知ISV,ISV查询用户的黑名单、签约协议、欠费信息等业务逻辑，根据实际情况调用解约接口，解约成功后，支付宝app中显示已解约。
  • 垫资还款通知：此通知是通知到基于开放平台应用网关地址，上传应用网关后，需要在开放平台订阅消息通知。然后会收到还款通知信息。
  • 垫资逻辑：在支付接口中，出入垫资参数，在扣款的时候，支付宝判断用户支付宝账户是否可以付成功，如果支付不成功，并且在符合垫资规则，会代扣垫资账户的款。从而代扣订单支付成功。
  • 在校园系统中为用户设置一个最大的欠费上线金额，记录用户的欠费信息，同时建立黑名单机制，根据欠费次数、欠费总金额来建立黑名单：
    • 对于触发规则的用户，则放入黑名单，同时黑名单需要存储在机具端和服务器端，两边的黑名单需要保持一致
    • 对于欠费的用户，校园系统需要建立追讨机制，每天向欠费用户追讨一次，根据欠费订单进行扣款。
    • 如果欠费用户的欠费订单都已经结清，则将该用户从黑名单中移除
  • 补扣次数建议不超过3次。补扣时间不在3天之内，不能超过15天。对于待支付的订单，支付宝系统内交易订单默认15天关闭，就会无法支付。
  • 异步扣款的模式，对于异步扣款，会涉及到扣款不到的情况，服务商/支付宝为主体进行垫资兜底能力。
  • 发生垫资情况，服务商本地要记录垫资记录，统计垫资次数，垫资金额，垫资规则与支付宝保持一致，根据还款通知信息更新黑名单。

第六步：设备绑定

- 刷脸支付设备：

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

• 请登陆支付宝开放平台->运营中心->商家管理->我的商家->我的商家门店->代商家创建门店->开始创建门店
• 业务场景必须选择“高校团餐”，需与业务同学确认
• 绑定需调用IOT云端API接口完成，不能通过开放平台门店创建页面的绑定入口完成

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

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

（3）参见“高校团餐人脸支付集成指引”中，硬件设备开发及接入IOT管控平台集成

备注：

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

2.在设备绑定接口（alipay.commerce.iot.mdeviceprod.device.bind）中增加school_stdcode参数传入学校标识码（教育部学校标识码），此参数为高校行业使用，入参时需增加，未体现在文档上。

第七步：集成验收

按照高校团餐刷脸支付方案中的要求进行验收，保证数据准确，确保不会影响到返佣结算。参考“高校团餐人脸支付集成指引”中，集成验收。。

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

附录

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.返佣数据说明 业务、产品待完善

FAQ