合作伙伴扫脸解决方案
名词解释
| 名词 | 解释 |
| 机具厂商 | 指机具提供商，即机具硬件和收银软件提供方。 |
| 支付ISV | 支付服务提供方，基于机具厂商收银软件上送到ISV网关的数据，发起支付宝API调用完成支付。 |
| 开放平台 | 蚂蚁金服开放平台，蚂蚁金服产品能力统一的出口。 |
一.业务介绍
团餐扫脸支付是应用在高校食堂场景，学生点餐完成收银员输入结账金额后学生通过扫脸+手机号确认输入方式完成支付宝账户支付。
整个支付流程中涉及到厂商和支付ISV两个开发角色。厂商负责硬件设备提供和收银软件开发，ISV负责支付链路开发。其中收银软件需要支持采集人脸信息，扫脸支付整个过程中涉及到客户端部分需要由厂商开发，在收银软件中完成，服务端接口由支付ISV完成开发。
1.1 收银软件介绍：
收银软件在设备出厂时内置到设备中，由厂商完成开发。具备采集人脸信息、获取订单金额、扫描付款码等能力。自助收银app首页效果图：
UI同学设计中，待产出后补充。
1.2 支付流程介绍：
扫脸支付步骤：
1）学生食堂选菜完成点餐。
2）点餐完成到达收银台 结账，收银员手工录入结算金额。
3）用户在展示屏上选择扫脸支付并开始扫脸。
4）输入11位手机号确认付款，扣款成功。
二.准备工作
1、商户根据自己的场景选择硬件设备。可联系支付宝BD了解详情。
2、签约：ISV联系行业BD替商户完成扫脸签约；ISV后台替商户完成当面付自助签约。
3、挂包：BD邮件提供签约扫脸的Pid和用于刷脸付/扫码付的appid给到松也，松也完成内部挂包申请，挂包完成后通知BD接口权限已开通。
4、登录开放平台，配置应用环境，包括应用功能，RSA2的公钥、授权回调地址等。
三.技术接入流程
由于对接扫脸支付过程中存在不同角色，为方便合作伙伴对整体流程有所了解，我们按各角色的实际操作进行流程说明。
系统对接按角色可分为机具厂商和支付应用ISV，如果一个机具厂商完全包办机具生产以及支付程序的开发和对接支付宝当面付的工作，那么他同时也是一个支付应用ISV。机具厂商负责提供机具（机具需要对接管控SDK）并开发收银软件（扫脸SDK客户端调用由厂商开发）；支付应用ISV负责完成扫脸服务端接口和支付接口调用（所有服务端接口均由支付ISV开发）。
流程说明：
1）厂商收银软件需要调用扫脸SDK客户端，获取metainfo信息，通过支付应用isv网关透传给到支付isv服务端。
2）支付ISV服务端调用zoloz.authentication.customer.smilepay.initialize接口进行刷脸初始化，获取zimid相关信息回传给收银软件。
3）厂商收银软件调用zolozVerify接口唤起人脸识别，获取foken信息透传给支付isv服务端网关，ftokn为加密字符串，ftoken能映射用户相关信息。
4）支付ISV调用当面付alipay.trade.pay接口完成支付。
四.详细技术方案
4.1.产品架构设计
用户在点餐结账时，金额由收银员录入，用户可以选择扫脸支付或者扫码支付，厂商收银软件采集人脸或付款码、金额信息上送到isv服务端，支付功能由ISV对接支付宝能力完成。
4.2.网络拓扑设计
基于常见移动支付链路，集成链路如下。如商户链路不属于这种情况可以另做考量。
ps:唤起扫脸apk是通过外网直连支付宝上传人脸，所以针对扫脸功能，门店必须具备外网环境，如现有情况不符合，请联系支付宝技术人员支持。
4.3.开始开发
4.3.1.扫脸开发
客户端sdk:
所有摄像头的唤起需由厂商将SmileService1.9.3.jar集成入收银软件中，由收银软件调用SmileService1.9.3.jar的扫脸Api客户端人脸采集。
| 程序包 | 发布时间 | 备注 |
| SmileService1.9.3.jar | 2018/3/14 | 点击下载 |
客户端apk:
根据机具配备的不同摄像头型号，自行下载对应的apk进行测试。
| 适用摄像头型号 | apk版本 | 备注 |
| 奥比p1 | AstraP1-3.10.0.346.apk |
点击下载 |
| 奥比pro | AstraPro-3.10.0.345.apk |
点击下载 |
客户端demo:
| demo名称 | 开发语言 | 备注 | 下载 |
| smiledemo.zip | Java | 不带账密，需要ISV填上账密后再运行。 | 点击下载 |
客户端演示应用：
| 演示程序 | apk | 演示环境 | 下载 |
| smiledemo.apk | 2D-3.1.2.2018040901.apk | 手机 | 点击下载demo 点击下载apk |
服务端sdk:
| sdk名称 | 开发语言 | 备注 |
| alipay-sdk-JAVA-ALL20180326160736 | java | 点击下载 |
| alipay-sdk-NET-ALL20180409182104 | .net | 点击下载 |
| alipay-sdk-PHP-ALL20180426105257 | php | 点击下载 |
详见：扫脸集成指南
4.3.2.支付开发
请各方开发者根据自身角色分别仔细阅读相关接口文档。
1、扫脸sdk接入指南(厂商开发客户端接口，支付isv开发服务端接口)
2、IoTSDK厂商集成指南（厂商开发）
3、当面付API列表（支付isv开发）
扫脸支付部分调用当面付alipay.trade.pay接口，注意事项如下：
- extend_params/sys_service_provider_id参数中传入isv签约返佣协议账户的pid。
- 扫脸支付部分也是调用当面付alipay.trade.pay接口，与扫码支付不同有两个参数需要调整：收银软件扫脸成功后获取ftoken透传给支付isv服务网关，调用alipay.trade.pay时auth_code取值为ftoken,且scene=security_code。
- 需在alipay.trade.pay接口中增加一个与out_trade_no平级的参数terminal_params，取值为“业务签名”以json字符串传递。该参数取值需isv与机具厂商沟通确认如何获取（与智能机具平台对接的机具该参数必传）。
//terminal_params参数样例：
"terminal_params":"{\"signature\":\"1FnjoEBasB8ullbr9xsy8E4XfhA6vXWVHm8rpzQ+XXXX\",\"credential\":\"280027188815876XXX:1521360763:F5WcujpCJeLwFrVB/sJWdrZLHrKey38gag/d0kn/7U1x+NozYgEAAA==\",\"terminalType\":\"IOT\"}"
- 建议在alipay.trade.pay接口中增加传递alipay_store_id参数，该参数取值为在开放平台中创建门店时生成的“门店ID”。
注意事项:
1、调用扫脸接口与支付接口的appid需要保持一致，支持开发者调用和第三方应用授权调用两种模式。
场景一:支付接口调用时为isvappId+商户app_auth_token。
- 调用扫脸初始化接口(zoloz.authentication.customer.smilepay.initialize)时也需要使用同样的isvappId+商户app_auth_token。
注意商户必须要重新给ISV做次应用授权,app_auth_token才会有扫脸初始化接口权限,否则调用接口会报40006,接口权限不足。- 同理,如果调用接口报
40006错,isv这边也可以留意下使用的app_auth_token前8位,这个是年月日。- 如果在isvappid挂扫脸功能包之前,则令牌肯定没有扫脸功能,调用接口报40006.
- 如果在isvappid挂扫脸功能包之后,则可能授权时isvappid还没有挂扫脸的包,需要联系支付宝客户经理挂扫脸接口包并重新授权。
- 重新授权是敏感操作,服务端同学最好先摸清自己系统环境,明确商户重新授权后令牌会发生变化,并且线上在使用的令牌也会跟着更新之后,在做重新授权的操作，否则可能会导致线上接口调用失败的问题。
场景二:支付接口调用时为商户appID。
- 调用扫脸接口也同样使用商户的appID.
注意保证商户的账密体系安全,不能在客户端保存商户账户密钥信息。
2、需要特别注意的是isv账号下可以有多个应用,即使是同一pid下的不同appid,商户分别对不同的appid做了应用授权,一个用作扫脸,获取的ftoken在另一个拿去支付也不行。
如：ISV同一个支付宝账号A下面有两个appid(a,b).商户S分别授权,则A拿到商户令牌aToken、bToken。扫脸时a+aToken,调用成功获取Ftoken(支付时使用,类似用户付款码)，支付时b+bToken+Ftoken调用失败。原因就是ftoken是应用a替商户生成的，只能a替商户核销。则改造方案就是统一替换成一致的调用方式。
3、支付接口中的store_id(门店编号，如有门店)=扫脸接口中的storeCode，支付接口中terminal_id(终端编号)=扫脸接口中的deviceNum.如果是测试阶段，以上参数请以TEST_ZOLOZ_开头，如strore_id=TEST_ZOLOZ_11111,terminal_id=TEST_ZOLOZ_11111，每台测试机具的terminal_id要保持唯一，不能重复。
4.3.3.机具管控开发：
接入背景：蚂蚁金服智能机具平台可以提供机具全流程的管理能力，消除人肉统计机具信息的工作，在未来为机具提供统一的智能化运营平台。合作机具厂商可通过开放平台物料平台网页版或物料平台API接口具备蚂蚁金服物料平台能力，从而串联起机具申请、审批、生产、调拨和使用的全流程。ISV和服务商可自助在蚂蚁金服开放平台为自己拓展的商户申请机具。商户收到的机具就能确认是否是ISV为其申请的机具（机具每次开机时会发起激活指令，完成业务信息一致性的确认），并且机具交易的计算也有规可循（通过机具支付报文中的业务签名信息保证）。
机具管控sdk接入对象：由厂商开发。
机具管控sdk作用：配合服务端完成机具设备的识别、激活、状态同步等功能，下发机具业务签名给支付isv。
sdk接入方案：机具管控sdk接入方法。
注意：
- 机具业务签名参数需在当面付请求的报文中传递，验收时作为必验标准。
- 业务异常处理提醒，管控sdk有两种返回情况：
- 正常返回:返回正确的交易信息加签，当面付支付接口通过termnal_params参数传入业务签名即可；
- 异常返回:管控sdk将所有异常统一返回为空，支付isv需对此异常做判断，允许交易正常支付。这种情况会影响到交易不能计入返佣，需要及时排查解决，一般情况是由于门店没有绑定机具导致。
- 另外： 当扫脸支付或者扫码支付失败的后，重新下单时，需要重新调用管控sdk业务签名，获取新的业务签名传入支付请求数据中。
五.验收
厂商/ISV下载扫脸支付技术验收checklist验收业务参数是否传递正确。
六.售后保障
上线后出现技术问题，请走售后保障流程：
一、在线IM（保证处理时效，工作日9:00-18:00）
https://cschannel.alipay.com/newPortal.htm?scene=mt_zczx
打开链接输入pid，系统识别大商户，自动分配值班技术同学支持
二、技术邮箱（保证处理时效，工作日9:00-18:00，解决上线后疑难杂症）
techservices@alipay.com