快速接入

本文档面向服务商(ISV)或者自研商户展示如何快速接入刷脸付和当面付产品,提供刷脸付的软件能力。

“刷脸付”软件应用需要部署在带有指定 3D 摄像头并且通过蚂蚁验证的硬件设备上(以下称为 IOT 刷脸设备)才可正常使用。

“刷脸付”软件应用需要配合 支付宝 IoTSDK(点击查看开发文档)使用,IOTSDK 提供多种能力,应用开发者可根据实际需求及业务要求选择使用相应能力接口。


注意:

文档中的代码示例和 Demo 是用来阐述 API 基本使用方法的,仅针对大众场景。供 ISV 参考,特殊情况还请 ISV 自行扩展,确保符合自身业务需求。


第一步:创建应用


要在您的应用中接入电脑网站支付能力,您需要登录支付宝开放平台(open.alipay.com),在开发者中心中创建您的应用,应用审核通过后会生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。

若需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》系统服务商(ISV)入驻请参考 ISV 入驻指南;商户和其他开发者入驻请参考 平台入驻指南


注意:

如果是 ISV 代商户进行应用开发,需要创建第三方应用。如果是自研商户,需要创建自用型应用。


第二步:配置应用

添加功能并签约


应用创建完成后,系统会自动跳转到应用详情页面。开发者可以在 功能列表 中点击 添加功能 来添加“刷脸付”和“当面付”功能。待应用上线后,您可以给添加的功能进行签约。您也可以在商家中心自助完成签约,支持商户自助签约以及 ISV 代签约两种模式。具体操作流程,可参考 刷脸付产品签约SOP



配置密钥


为了保证交易双方(商户和支付宝)的身份和数据安全,开发者在调用接口前,需要配置双方密钥,对交易数据进行双方校验。密钥包含应用私钥(APP_PRIVATE_KEY)和应用公钥(APP_PUBLIC_KEY)。生成密钥后,开发者需要在开放平台开发者中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY),配置的详细步骤请参考《配置应用环境》。您还可以通过观看快速签名教程学习密钥的配置。


说明

支付宝开放平台 SDK 封装了签名和验签过程,只需配置账号及密钥参数,建议开发者使用。开发者还可以通过自助排查流程验签教程自助排查配置应用过程中遇到的问题。


第三步:搭建和配置服务端开发环境

下载服务端SDK

为了帮助开发者调用开放接口,我们提供了开放平台服务端SDK(请下载最新版本),包含 JAVA、PHP、NodeJS、Python 和 .NET 五种,封装了签名&验签、HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。


接口调用配置


在 SDK 调用前需要进行初始化,以 JAVA 代码为例:


1AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);


关键参数说明:

配置参数

示例值解释

获取方式/示例值

URL

支付宝网关(固定)

https://openapi.alipay.com/gateway.do 

APP_ID

APPID即创建应用后生成

获取见上面创建应用

APP_PRIVATE_KEY

开发者应用私钥,由开发者自己生成

获取见配置密钥


FORMAT

参数返回格式,只支持json

json(固定)

CHARSET

请求和签名使用的字符编码格式,支持GBK和UTF-8

开发者根据实际工程编码配置

ALIPAY_PUBLIC_KEY

支付宝公钥,由支付宝生成

获取见配置密钥

SIGN_TYPE

商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2

RSA2

接下来,就可以用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次,后续调用不同的 API 都可以使用同一个 alipayClient 对象。


注意:

ISV/开发者可以通过“第三方应用授权”得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力;具体方法请参考第三方应用授权


第四步:搭建和配置客户端环境

下载刷脸客户端 SDK(安卓系统)


系统商需要将 SmileService1.9.3.jar 集成入商户 APP 中,由 APP 调用 SmileService1.9.3.jar 的扫脸 API 唤起刷脸 APK 完成扫脸部分的对接。(下载后解压获取 jar 文件)

SDK 程序包

备注

SmileService1.9.3.jar

点击下载

下载刷脸 APK(安卓系统)

smile-4.0.0.534.apk  点击下载


第五步:使用SDK快速接入


刷脸付系统交互流程图


流程说明


  1. 调用客户端 SDK 接口(zolozGetMetaInfo)获取当前刷脸所需的设备信息,这些信息由刷脸 APK 进行采集,并通过接口返回。这些数据将直接作为下一步初始化接口的入参传入,请不要对这个参数进行任何修改,否则会影响刷脸的正常使用。

  1. 调用服务端开放接口(zoloz.authentication.customer.smilepay.initialize)进行刷脸初始化,该接口主要根据第二步中获取的设备信息进行刷脸的可用性判断。如果刷脸初始化成功,会返回本次刷脸调用的标识(zimid)以及刷脸所需的协议数据,这些数据将作为下一步中进行人脸识别接口的入參。如果刷脸不可用,商户可对用户进行友好的提示,或者建议用户使用其他非人脸的支付方式(如扫码支付)。此处开发者要特别注意:因为初始化接口生成的 zimid 只能在一次刷脸中使用而且有时效限制,重复或者过期使用同一个 zimid 都会导致刷脸失败。所以请务必在每一次刷脸中都调用该接口生成新的 zimid。

  2. 商户 APP 调用刷脸 SDK接口(zolozVerify)唤起人脸采集页面并进行人脸识别过程,将上一步中返回的 zimId 和协议数据作为该接口的入參,最终返回人脸识别的结果。如果识别成功,会返回当前用户的支付宝账号信息(ftoken),该字符串将直接作为下一步收单接口中的入參完成支付。

  3. 获取 ftoken 后调用当面付接口(alipay.trade.pay),完成支付宝支付流程。
    注意,默认情况下,当面付接口仅支持扫码,如果要完成刷脸付,请修改当面付的两个传入参数:
    • 请求参数中 scene 固定为 security_code

    • 请求参数中 auth_code 为刷脸成功获取到的 ftoken 值。


注意:为了更好地保护消费者权益,充分尊重用户的主观意愿,人脸SDK接入需要满足以下条件:

第三方应用要做到正确地使用刷脸,满足“事先告知”、“给用户其他支付方式选择权”的原则,不可在用户没有明示同意前唤起刷脸SDK。由于人脸应用是由第三方应用被动唤起,关于如何实现“事先告知用户”的方式,需要第三方应用根据自身场景以及设备类型自行设计实现。建议的双屏机方案为,主屏(商家侧)支持开启刷脸支付,副屏接收到开启指令后,弹框明示告知用户,即将开始刷脸支付,用户可选择同意或者取消,用户选择同意后,唤起人脸SDK。建议的单屏机方案为,屏幕上展示“刷脸支付”按钮,由用户主动点击按钮才可唤起人脸SDK。


第六步:调试沙箱


沙箱环境是开放平台提供给开发者调试接口的环境,具体操作步骤见 刷脸付沙箱测试



onlineServer