快消自助收银解决方案
支付宝自助收银解决方案指南
支付宝自助收银概念：快消，便利店场景摆放独立的支付宝独家收银设备并能完成用户自助扫脸收银。
阅读前须知：
阅读对象：自助收银app开发者，自助收银方案协议商户
本文概览：
一.方案介绍
1.1.支付宝自助收银硬件设备介绍
1.2.支付宝自助收银软件介绍
1.3.支付宝自助收银支付整体流程（含交互素材下载，支付宝logo素材下载，请务必使用官方素材，在上线前验收时必验证这部分。）
二.商户/ISV接入方案详细介绍
2.1.商户/ISV确定拓扑结构方案
2.1.1.商户门店链路&拓扑情况分析
2.1.2.支付宝自助收银总集成架构
2.1.3.商户确定集成拓扑链路
2.2.集成实施
2.2.1.扫脸硬件集成（包含扫脸apk,客户端sdk,服务端sdk，客户端demo,客户端演示应用下载）
2.2.2.支付集成（包含当面付详细对接说明超链接，注意事项说明）
2.2.4.机具管控集成（包含机具管控指南超链接，请务必集成机具管控，在上线前验收时必验证这部分。）
2.2.7.其他外设集成（包含当前支持自助收银方案的所有硬件设备详细参数，硬件如打印机等集成文档，sdk下载）
三.支付宝自助收银验收（请务必确认是按照验收要求的逻辑开发，需重点关注。）
包含最新的验收checklist，注意该文档不断更新补充中，且会更新标题的版本号。每次验收请留意是最新版本。
四.售后保障
提供上线后保障渠道联系方式，以便解决客诉和线上异常问题。
一.方案介绍
1.1.支付宝自助收银硬件设备介绍：
ps:硬件设备有多种型号，包括竖屏，横屏，商户可根据需求选型。硬件选型请联系支付宝BD。
1.2.支付宝自助收银软件介绍：
设备上需要安装自助收银APP，该app由商户/系统商开发。自助收银app首页效果：
1.3.支付宝自助收银支付整体流程：
页面交互展示概览：请以表格中的交互标准为准，必须符合支付宝视觉规范标准，重要！
| 名称 | 版本 | 操作 | 备注 | 历史版本 |
| 自助收银产品规范 | 2018.5.9 | 下载 | 增加每页交互标准文字说明 | 2018.4.25 |
| 自助收银样式规范包（新版） | 2018.11.1 | 下载 | 包含源文件和设计规范文档 | |
| 支付宝logo素材 | 2018.5.10 | 下载 | 补充完善缺失的素材 | 2018.5.2 |
| 佐罗刷脸icon | 2018.9.28 | 下载 | 新集成的app必须使用该icon.已上线APP可以后续迭代更新 |
注意事项：
新集成的app需遵循下列标准，其中标号1的icon见上方表格素材中下载佐罗刷脸icon。验收会校验！存量已上线的app,后续版本升级时可以一并更改。
二.商户/ISV接入方案详细介绍
2.1.商户/ISV确定拓扑结构方案
2.1.1.商户门店链路&拓扑情况分析
线下移动支付常见链路：
商品库&活动数据：门店数据库或门店pos每日定时获取当日的营销活动列表和商品价格明细，供当天营运。
对账：闭店后，门店pos上报报表以供对账。
支付：pos根据本地商品库和营销规则计算订单总价，扫描用户支付宝条码，封装信息，同步给服务端，服务端向支付宝发送支付请求，支付成功后结果原路返回。
2.1.2.支付宝自助收银总集成架构
用户在自助设备结算时，需实时显示商品信息和营销活动后的优惠详情。需要集成的目标架构图如
2.1.3.商户确定集成拓扑链路
基于常见移动支付链路，集成链路如下。如商户链路不属于这种情况可以另做考量。
ps:唤起扫脸apk是通过外网直连支付宝上传人脸，所以针对扫脸功能，门店必须具备外网环境，如现有情况不符合，请联系支付宝技术人员支持。
2.1.4 自助收银时序图
2.2.集成实施
准备工作：
1.商户根据自己的场景选择硬件设备。可联系支付宝BD了解详情。
2.与支付宝BD确认相关协议是否已签约。
2.2.1.扫脸资源下载
客户端sdk:
摄像头由支付宝统一提供，所有摄像头的唤起需由系统商将SmileService1.9.3.jar集成入终端app中，由app调用SmileService1.9.3.jar的扫脸Api唤起apk完成扫脸部分的对接。
| 程序包 | 发布时间 | 备注 |
| SmileService1.9.3.jar | 2018/3/14 | 点击下载 |
客户端apk:
根据不同设备的不同型号屏幕，分别做了差异化封装，系统商根据自助收银硬件设备的选型自行下载对应的apk。
| 适用设备 | 摄像头型号 | apk版本 | 备注 |
| 商米T2 横屏 | 奥比p1 | AstraP1-3.10.0.346.apk |
点击下载 |
| 中科英泰selfpos60、 竖屏海信HS6500、创捷中云-CCL7000-E24A-L03 | 奥比pro | AstraPro2-3.10.0.345.apk |
点击下载 |
客户端demo:
| demo名称 | 开发语言 | 备注 | 下载 |
| smiledemo.zip | Java | 不带账密，需要ISV填上账密后再运行。 | 点击下载 |
客户端演示应用(如果硬件设备还未收到需要联调，可以在手机上进行）：
| 演示程序 | 说明 | 下载 |
| 2D-3.1.2.2018040901.apk | 刷脸程序安装包，仅适用于2D摄像头（比如手机摄像头） | 点击下载apk |
| smiledemo.apk | 唤起刷脸程序的应用，相当于自助收银app，适用于所有Android设备 | 点击下载demo |
服务端sdk:
| sdk名称 | 开发语言 | 备注 |
| alipay-sdk-JAVA-ALL20180326160736 | java | 点击下载 |
| alipay-sdk-NET-ALL20180409182104 | .net | 点击下载 |
| alipay-sdk-PHP-ALL20180426105257 | php | 点击下载 |
详见：扫脸集成指南
扫脸部分集成流程：
- 手机上体验刷脸流程获取ftoken（可跳过）
- 在2.2.1节下载客户端演示应用2D-3.1.2.2018040901.apk （下载的包名称以实际下载的版本为准）和smiledemo.apk，在手机上安装。2D-3.1.2.2018040901.apk安装后在手机桌面不显示应用图标，在应用管理下可以看到应用名称smile。smiledemo.apk安装后可以在桌面看到应用smilepay，启动smilepay点击刷脸按钮，如果提示“抱歉未支付成功，请重新支付”，是因为系统不允许smilepay 唤起 smile，需要在手机管家-启动管理 设置smile为允许关联启动。
- 在Android设备跑demo
- 在2.2.1节下载并安装摄像头对应的客户端smile apk安装包。
- 在2.2.1节下载并安装客户端演示应用smiledemo.apk。
- 如跑通demo，可排除摄像头兼容性问题和smile应用版本问题。
- 确认账号具备接口权限
- 在2.2.1节下载并安装客户端demo smiledemo.zip，demo源码没有测试账号没有支付宝账号秘钥，需要开发者填入isv/商家的支付宝账号秘钥，重新编译后在设备上测试。如能成功获取ftoken并发起当面付交易，说明账号秘钥已有刷脸支付产品权限。
- 把smiledemo相关源码集成到自助收银app工程中。
2.2.2.支付集成：
支付部分调用当面付alipay.trade.pay接口，注意事项如下：
- 扫脸成功后获取ftoken，传入alipay.trade.pay的auth_code,且scene=security_code
- 支付接口中的store_id(门店编号，如有门店)=扫脸接口中的storeCode，支付接口中terminal_id(终端编号)=扫脸接口中的deviceNum.如果是测试阶段，以上参数请以TEST_ZOLOZ_开头，如strore_id=TEST_ZOLOZ_11111,terminal_id=TEST_ZOLOZ_11111，每台测试机具的terminal_id要保持唯一，不能重复。
- 支付接口有机具管控参数样例。详见机具管控集成说明。 "terminal_params":"{\"signature\":\"1FnjoEBasB8ullbr9xsy8E4XfhA6vXWVHm8rpzQ+XXXX\",\"credential\":\"280027188815876XXX:1521360763:
F5WcujpCJeLwFrVB/sJWdrZLHrKey38gag/d0kn/7U1x+NozYgEAAA==\",\"terminalType\":\"IOT\"}"。 - 支付接口中，sys_service_provider_id为系统商新签的《自助收银业务协作激励协议》账号的pid
- 支付接口中需要传入"product_code":"ALIPAY_F2F_PAYMENT"。
- 条码支付时单笔金额超过1000元的会唤起收银台，商家收到的同步返回是10003，需要启用轮询逻辑。详细参考当面付快速接入文档。
2.2.3.会员方案：
- 商户自有的会员体系+支付宝自助收银方案时，可以在会员登录时只输入一次手机号，唤起支付宝扫脸后，会员手机号自动回显在界面上，会员确认手机号后，完成支付。最新的apk版本已支持该功能，调用zolozVerify时，params的map中增加key为phone_number的键值对。详见扫脸集成指南。
- 扫脸完成后，返回用户的支付宝userid(支付宝全局唯一标识)，商户可以基于关联会员权益进行。最新的apk版本已支持该功能。详见扫脸集成指南。
开发人员特别注意:
调用扫脸接口与支付接口的方式需要保持商户账号一致.具体案例如下:
case1:支付接口调用时为isvappId+商户app_auth_token.
- 调用扫脸初始化接口(zoloz.authentication.customer.smilepay.initialize)时也需要使用同样商户账号授权的令牌调用.
注意商户必须要重新给ISV做次应用授权,app_auth_token才会有扫脸初始化接口权限,否则调用接口会报40006,接口权限不足.- 同理,如果调用接口报
40006错,isv这边也可以留意下使用的app_auth_token前8位,这个是年月日.- 如果在isvappid挂扫脸功能包之前,则令牌肯定没有扫脸功能,调用接口报40006.
- 如果在isvappid挂扫脸功能包之后,则可能授权时isvappid还没有挂扫脸的包,可以走上面的找支付宝PD(或者中台同学 楚齐)挂包的动作
- 重新授权是敏感操作,服务端同学最好先摸清自己系统环境,明确商户重新授权后令牌会发生变化,并且线上在使用的令牌也会跟着更新之后,在做重新授权的操作.否则可能会导致线上接口调用失败的问题.
case2:支付接口调用时为商户appID.
- 很简单,调用扫脸接口也同样使用商户的appID.
注意保证商户的账密体系安全,尽量不要在设备端报错商户账密信息(统一通过前置机加密调用支付宝开放平台接口).
2.2.4 支付成功页优惠金额显示
- 支付宝优惠金额 = 商家实收金额 receipt_amount - 买家实际付款金额 buyer_pay_amount
- 商家优惠金额 = 订单总金额 total_amount - 商家实收金额 receipt_amount
2.2.5.机具管控集成：
机具管控介绍：
- 接入背景：蚂蚁金服智能机具平台可以提供机具全流程的管理能力，消除人肉统计机具信息的工作，在未来为机具提供统一的智能化运营平台。合作机具厂商可通过开放平台物料平台网页版或物料平台API接口具备蚂蚁金服物料平台能力，从而串联起机具申请、审批、生产、调拨和使用的全流程。ISV和服务商可自助在蚂蚁金服开放平台为自己拓展的商户申请机具。商户收到的机具就能确认是否是ISV为其申请的机具（机具每次开机时会发起激活指令，完成业务信息一致性的确认），并且机具交易的计算也有规可循（通过机具支付报文中的业务签名信息保证）。
- 机具管控sdk作用：配合服务端完成机具设备的识别、激活、状态同步等功能。
- 机具管控sdk接入对象：由自助收银isv来调用。机具管控sdk作为资源文件在机具出厂时由设备厂商存入系统。
- 机具管控sdk在设备上的存放路径：厂商会放到机具的根文件系统的/system/vendor/alipay/xdevicemanager.aar。自助收银isv调用的时候直接指定此路径即可。
- 机具管控sdk升级方案：sdk必须伴随支付app升级。请ISV确认设备支持以下两种方式之一即可：
- a.直接让支付app拥有升级能力。（需支付isv配合）
- b. 让厂商系统具有升级支付app的能力。
- sdk接入方法：机具管控sdk接入方法。
注意：
- 机具管控参数需在当面付请求的报文中体现，验收时作为必验标准。
- 业务异常处理提醒，管控sdk有两种返回情况：
- 正常返回:返回正确的交易信息加签，当面付支付接口通过termnal_params参数传入业务签名即可；
- 异常返回:管控sdk将所有异常统一返回为空，支付isv需对此异常做判断，允许交易正常支付。这种情况可能会影响到该笔交易不能计入返佣交易。短期内先请ISV设置监控机制，如上线后发现为空，立即做排查处理。
- 另外： 当扫脸支付或者扫码支付失败的后，重新下单时，需要重新调用管控sdk业务签名，获取新的业务签名传入支付请求数据中。
2.2.7.其他外设集成
自助收银在用户交互时除了需调用摄像头，还需调用其他外设，如小票打印机，商品扫描枪，LED等硬件，系统商需根据不同的选型设备调用不同设备厂商的API.
| 自助收银设备型号 | 尺寸 | 集成文档 | 备注 |
| 商米T2 | 带底座的整体尺寸：839.6mm*532mm*1659.2mm 屏幕外形尺寸：323.4mm*519.6mm 显示页面尺寸:267.3mm*464.9mm |
https://docs.sunmi.com | 打印机驱动及demo 点击前往 扫码器：USB接口HID即插即用 |
| 中科英泰selfpos60 | 外形尺寸:381.5mm*251.2mm 显示页面的尺寸：344.23mm*193.54mm |
SelfPOS60_Android外部设备开发包V1.0 | |
| 海信HS6500 | 外形尺寸:381.5mm*251.2mm 显示页面的尺寸：344.23mm*193.54mm |
海信HS6500系列服务接口开发文档 | 点击下载 20190401有更新 |
| 创捷中云-CCL7000-E24A-L03 | 显示外形尺寸 23.8'' 1920*1080 | 创捷中云设备服务接口开发文档 | 点击下载 |
商米T2设备详细参数
商米K1设备详细参数
中科英泰selfpos60设备详细参数
海信HS650设备详细参数
创捷中云-CCL7000-E24A-L03
2.2.8.打印机集成
ISV按照商户需求开发小票打印功能.对于商米的T2设备,出厂时会加装卡槽以支持58mm打印纸(如下图所示).如商户是58mm规格,直接使用即可.如商户是80mm打印纸规格,可将挡板撤掉,即可固定80打印纸.
三.验收
验收非常重要，必须验收，否则无法给出符合上线条件的依据。验收分为三个阶段
1.商户/ISV按照UI标准开发后，可以进行第一轮UI验收。ISV或商户提供扫脸支付和扫码支付主流程的两个视频给到支付宝。要求页面拍摄清晰。
2.商户/ISV下载《自助收银验收checklist3.5》，自行验收业务逻辑。支付宝业务同学到门店现场验收自行下载《自助收银业务验收文档5.18》
验收list版本历史记录
| 验收文档名称 | 版本号 | 修改日期 | 更改内容 |
| 自助收银项目验收v3.5.xlsx | v3.5 | 2018.6.11 | 《ISV技术验收（必验）》sheet中删除页面UI部分，UI交互以《ISV界面流程验收(必验)》为准 |
| 自助收银项目验收v3.4.xlsx | v3.4 | 2018.6.6 | 增加扫脸初始化请求中的alipayStoreCode需要和支付请求中的alipay_store_id(store_id和alipay_store_id二选一传即可，alipay_store_id为口碑店铺的口碑内部门店编号) |
| 自助收银项目验收v3.3.xlsx | v3.3 | 2018.5.23 | 增加说明若无条码商品小于3种的显示情况 |
| 验收文档名称 | 版本号 | 日期 | 备注 |
| 自助收银业务验收文档5.18.xlsx | v5.18 | 2018.05.31 | 增加一列空白，方便业务同学验收时打印纸质版后打对勾打叉 |
| 自助收银业务验收文档5.17.xlsx | v5.17 | 2018.05.28 | 个别细节增加可读性：颜色编码增加样色对照展示，解释sdk是什么等。验收项目无增加。 |
| 自助收银业务验收文档5.16.xlsx | v5.16 | 2018.05.23 | 增加说明若无条码商品小于3种的显示情况 |
3.以上两项验收通过后，联系支付宝人员到门店验收。
四.售后保障
一、在线IM（保证处理时效，工作日9:00-18:00）
https://cschannel.alipay.com/newPortal.htm?scene=mt_zczx
打开链接输入pid，系统识别大商户，自动分配值班技术同学支持
二、技术邮箱（保证处理时效，工作日9:00-18:00，解决上线后疑难杂症）
techservices@alipay.com
如在集成过程中遇到问题，请联系支付宝技术同学。
五.方案补充
一、门店代理方案
https://doc.open.alipay.com/docs/doc.htm?&docType=1&articleId=108557
二、白名单列表：
| 属性 服务器 |
描述 | 直连外 | VPN/白名单 | 代理 |
| 本地pos | 方案 | 正常宽带连接 有线/路由器均可 单次支付100k左右 TIPS:(服务端为本地pos情况下)保证与本地pos在同一网络环境下.比如链接同一个wifi或者在同一路由器/交换机内. |
请添加如下地址: 应用市场访问以及应用下载地址: api.sunmi.com(80/443) apk.cdn.sunmi.com(80/443) http://49.4.66.28:80 http://49.4.66.28:886 机具管控/扫脸访问地址: mdap.alipaylog.com loggw.alipay.com mdap.alipay.com mobilegw.alipay.com myh2.alipay.com iothub.alipay.com |
应用市场访问以及应用下载:目前除添加白名单外无其他方案,可以在设备使用期外通过联公网环境下载后在切换业务网络环境. 机具管控/扫脸访问: 参考文档 https://doc.open.alipay.com/docs/doc.htm?&docType=1&articleId=108557 |
| 责任人 | ISV/商户IT/信息部 | 商户IT/信息部 | ISV 提供代理:ISV 商户提供代理:商户IT/信息部 |
六.常见问题汇总Q&A
Q：调用刷脸初始化接口，出现错误：Insufficient Token Permissions-商户未授权当前接口？
A：这个错误代表请求中的app_auth_token无效，有可能是因为在应用未绑定刷脸功能包之前，商户就已经为ISV的appid进行了授权。解决的办法是确认应用已经绑定支付级刷脸服务功能包，然后商户再进行应用授权。如果问题依然存在，可通过alipay.open.auth.token.app.query接口确认商户是否为正确的appid进行了授权。具体接口的调用方法可参考 https://docs.open.alipay.com/20160728150111277227/intro
Q：调用刷脸初始化接口，无效的appId参数[40002、invalid-app-id]？
A：这个错误有可能由以下原因导致。
(1)app_id在对应环境里未上线或者不存在。
Q：调用刷脸初始化接口，出现错误：Insufficient Conditions[40003、isv.missing-signature-config]？
A：这个错误有可能由以下原因导致。
(1)appId没有在开发者中心配置密钥(openhome.alipay.com)；
(2)appId发起接口调用和实际配置的密钥方式不一致，即传的sign_type和实际配置密钥配置不匹配。如配置了RSA2，但是传了sign_type=RSA。
Q：调用刷脸初始化接口，出现错误："code":"40004","msg":"Business Failed","sub_code":"unknown-sub-code","sub_msg":"未知的错误码SMILE_TO_SIGN_INVALID"？
A：这个错误的原因是调用刷脸接口的商户的签约订单已经失效或者未生效。
(1)对于订单未生效，常见的情况是未完成前台确认；
(2)对于签约订单失效，可以请相关行业的BD进入ABOSS确认原因。
Q：调用刷脸初始化接口，出现错误："code":"40004","msg":"Business Failed","sub_code":"unknown-sub-code","sub_msg":"未知的错误码SMILE_TO_UNSIGNED"？
A：这个错误的原因是调用刷脸接口的商户未完成签约。
(1)如果是ISV授权模式下，这里指的是授权商户未完成签约，提供PID给相关行业的BD，完成ABOSS签约；
(2)如果是自研商户直接调用的模式下，这里指的是自研商户未完成签约，提供PID给相关行业的BD，完成ABOSS签约；
(3)如果是ISV处于测试阶段，不能完成商户签约的情况下调用刷脸初始化接口，可以请对接的BD或者行业技术同学向人脸团队的产品运营同学申请为ISV进行加白；
(4)如果ISV已经申请过白名单，可能是在白名单到期前没有满足测试机具的deviceNum要求（如下），修正后，可以请对接的BD或者行业技术同学向人脸团队的产品运营同学申请为ISV进行延期。
测试机具的deviceNum要求
在调用zolozInstall, zolozGetMetaInfo以及initialize接口的时候，入参Map中的deviceNum子对象的值，必须以“TEST_ZOLOZ_”开头，如“TEST_ZOLOZ_1001”, 用于标识该机具为测试机具。如果存在多台测试机具，要确保deviceNum的唯一性
Q：调用刷脸初始化接口，出现错误：ISV权限不足[40006、isv.insufficient-isv-permissions]？
A：这个错误有可能由以下原因导致。
(1)应用还未上线（常见），请确保应用提交审核并通过；
(2)应用没有挂载对应的接口调用权限，请查看应用的功能列表中存在“支付级刷脸服务”。如果没有的话，请将APPID提供给对接的支付宝同学向人脸团队的产品运营同学申请绑定刷脸功能包；
(3)使用了错误的应用ID（调用的应用ID与业务排查的应用ID不一致）；
(4)应用只挂载了“支付级刷脸服务”功能包，该功能包要求签约开通，而ISV没有完成签约。需要请对接的BD或者行业技术同学向人脸团队的产品运营申请挂载全面开通的功能包。
Q：调用刷脸初始化接口，出现错误：此用户不允许自调用[40006、isv.self-invoke-forbidden]？
A：是由于当前应用是第三方应用，调用接口却用自用型调用模式，解决方案如下。
(1)继续使用当前应用进行联调，调用接口方式换成第三方应用授权模式；
(2)重新新建一个自应用的应用进行联调，需要请对接的BD或者行业技术同学向人脸团队的产品运营申请挂包。
以上Q&A中无法解决的问题 请详见支付宝刷脸支付FAQ
