1:1刷脸支付

接入流程

接入步骤

请查看下文 Demo 源码快速了解如何接入刷脸支付。

本 Demo 中为了展现完整的接入代码，使用客户端模拟服务端发出支付宝开放接口的请求，将私钥存储在客户端，这是非常不安全的做法，请务必在上线应用中，在服务端发起刷脸初始化和收单接口的请求。另外，本 Demo 中没有填入支付宝公钥参数，请在上线应用中，正确填写。

demo名称	开发语言	备注	下载
smiledemo.zip	Java	不带账密，需要服务商填写账密后再运行。	点击下载

在编译 miledemo 工程之前，请打开原文件 MerchantInfo.java，将以下两个参数填入正确信息。

public class MerchantInfo{
     public final static String appKey1 = "请输入商家／服务商的应用私钥";
     public final static String appId1 = "请输入appid";
}

获取刷脸所需的设备信息

调用接口 getMetaInfo 采集刷脸所需的设备信息并完成刷脸的准备工作。如果 getMetaInfo 返回成功结果，则请求商家服务端调用支付宝开放平台的人脸初始化接口。

mZoloz.getMetaInfo(mockInfo(), new MetaInfoCallback() {
    // 解析getMetaInfo返回的结果，如果成功，则请求商家服务端调用人脸初始化接口
    @Override
    public void onMetaInfo(String metaInfo, Map<String, Object> extInfo) {
        Log.d(TAG, "meta info is:" + metaInfo);
        //获取metainfo成功
        if (TextUtils.isEmpty(metaInfo)) {
            Log.e(TAG, "metainfo is null");
        } else {
            Log.i("zolozTime", "smiletopay init zimid begin");
            // 将metaInfo发送给商家服务端，由商家服务端发起刷脸初始化OpenAPI的调用
            // 参考刷脸初始化
        }
    ｝
/**
  * mock数据，真实商家请填写真实信息.
  */
  private Map mockInfo() {
     Map merchantInfo = new HashMap();
     //以下信息请根据真实情况填写
     //商户 PID
     merchantInfo.put(ZolozConstants.KEY_MERCHANT_INFO_MERCHANT_ID, merchantId);
     //服务商 PID
     merchantInfo.put(ZolozConstants.KEY_MERCHANT_INFO_PARTNER_ID, partnerId);
     //添加刷脸付功能的appid
     merchantInfo.put("appId", appId);
     //机具编号，便于关联商家管理的机具
     merchantInfo.put(ZolozConstants.KEY_MERCHANT_INFO_DEVICE_NUM, "TEST_ZOLOZ_TEST");
    return merchantInfo;
}

关键入参

参数名称	参数说明	必填
merchantId	签约商家的 PID。以 2088 开头	是
partnerId	服务商的 PID。对于自用型商家，填写签约商家的 PID，和 merchantId 保持一致。	否
appId	支付宝分配给开发者的应用 ID，和当面付请求的 appid 保持一致。	否
deviceNum	商户机具终端编号，和当面付请求的 terminal_id 保持一致。	是
storeCode	商户门店编号，和当面付请求的 store_id 保持一致。	否
alipayStoreCode	支付宝内部门店编号，和当面付请求中的 alipay_store_id 保持一致。	否

关键出参

回调函数返回的 metainfo 对象结构，该对象中的参数请不需要做任何值的修改，否则会导致后续刷脸出错。请直接传给商家服务端作为下一步调用的入參。

参数名称	参数说明
apdidToken	设备指纹。
appName	应用名称。
appVersion	应用版本。
bioMetaInfo	生物信息。
osVersion	系统版本。
machineInfo	设备硬件相关信息。
merchantInfo	商户相关信息。
remoteLogID	刷脸调用的事务 ID。
extInfo	扩展参数，用于商家服务端传入信息。

刷脸初始化

调用服务端接口 zoloz.authentication.smilepay.initialize（刷脸支付初始化接口）完成刷脸可用性逻辑判断，该接口为开放平台接口，需要商家的服务端进行调用。

注意：因为初始化接口生成的 zimid 只能在一次刷脸中使用而且有时效限制，重复或者过期使用同一个 zimid 都会导致刷脸失败。所以请务必在每一次刷脸中都调用该接口生成新的 zimid。

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.ZolozAuthenticationSmilepayApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class ZolozAuthenticationSmilepayApiInitialize {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        ZolozAuthenticationSmilepayApi api = new ZolozAuthenticationSmilepayApi();
        ZolozAuthenticationSmilepayInitializeModel data = new ZolozAuthenticationSmilepayInitializeModel();
        data.setOsVersion("7.1.1");
        FaceMachineInfo machineInfo = new FaceMachineInfo();
        machineInfo.setCameraDriveVer("1.0");
        machineInfo.setMachineModel("T2");
        machineInfo.setCameraName("AstraP1");
        machineInfo.setCameraVer("1.0");
        machineInfo.setMachineCode("WyDAz27pfsEDANGk7QnmxZlv");
        machineInfo.setMachineVer("7.1.1");
        machineInfo.setCameraModel("AstraP1");
        machineInfo.setExt("扩展信息");
        data.setMachineInfo(machineInfo);
        data.setDeviceType("android");
        data.setBioMetaInfo("3.13.0:12419136,6");
        data.setDeviceModel("T2");
        data.setRemoteLogId("bcf71c4290f288f4421ee9d49eedbf1e2840ba");
        FaceExtParams extInfo = new FaceExtParams();
        extInfo.setBizType("1");
        data.setExtInfo(extInfo);
        data.setAppName("com.alipay.zoloz.smile");
        data.setZimVer("1.0.0");
        FaceMerchantInfo merchantInfo = new FaceMerchantInfo();
        merchantInfo.setWifiname("Alipay-Test");
        merchantInfo.setAreaCode("华中");
        merchantInfo.setDeviceNum("TEST_ZOLOZ_TEST");
        merchantInfo.setBrandCode("KFC");
        merchantInfo.setStoreCode("TEST");
        merchantInfo.setGeo("120.10785,30.26708");
        merchantInfo.setMerchantId("2088302068579978");
        merchantInfo.setDeviceMac("1c:aa:07:b0:e7:af");
        merchantInfo.setPartnerId("2088302068579978");
        merchantInfo.setWifimac("1c:aa:07:b0:e7:af");
        merchantInfo.setGroup("group1");
        data.setMerchantInfo(merchantInfo);
        data.setAppVersion("3.7.0.201809191618");
        data.setBaseVer("7.1.1");
        data.setApdidToken("40Kl9e97cQcMJka5gfT0arVPq7GTaR6yE5f73mj8zqBW9eOPZQEAAA==");
        try {
            ZolozAuthenticationSmilepayInitializeResponseModel response = api.initialize(data);
        } catch (ApiException e) {
            ZolozAuthenticationSmilepayInitializeDefaultResponse errorObject = (ZolozAuthenticationSmilepayInitializeDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

业务入参

machine_info（机具信息，调用人脸识别SDK获取）参数说明。

参数	是否必填	描述
camera_drive_ver	可选	摄像头驱动版本号
camera_model	可选	摄像头型号
camera_name	可选	摄像头名称
camera_ver	可选	摄像头版本号
machine_code	可选	机具编码
machine_model	可选	机具型号
machine_ver	可选	机具版本号
ext	可选	扩展信息

merchant_info（商户信息）参数说明

area_code	可选	区域编码
brand_code	可选	品牌编码
device_mac	可选	机具Mac地址
group	可选	机具分组编码
device_num	可选	机具编码
geo	可选	经纬度
merchant_id	可选	商户ID
partner_id	可选	服务商 ID
store_code	可选	门店编码
wifimac	可选	WI-FI Mac地址
wifiname	可选	WI-FI 名称

出参

返回结果 JSON 对象，结构如下。

键值	描述
code	统一对外错误码，如果刷脸认证成功返回，则为 CODE_SUCCESS。详情可查看下文表格常见错误码（code）。
msg	返回消息。
ret_code_sub	刷脸返回码。
ret_message_sub	刷脸返回消息。
zim_id	刷脸调用的标识，将作为下一步 verify 接口的入參。
zim_init_client_data	刷脸的下发协议数据，将作为下一步 verify 接口的入參。

常见错误码（code）

统一对外错误码	错误描述	解决方案
SYSTEM_ERROR	系统繁忙	请检查下网络环境
INVALID_PARAMETER	参数有误	请检查参数是否有误
BIZ_ERROR	业务异常	请检查业务参数准确性

唤起人脸识别

调用 verify 接口唤起人脸采集页面并完成比对过程。如果认证成功，将返回一个 ftoken。该 ftoken 用于后续查询被认证用户的信息。

// 将上一步中initialize接口返回的zim_init_client_data对象和zim_id作为入參
Map params = new HashMap();
params.put("zim.init.resp", protocal);
/* 可选：smile_mode用于指定选择刷脸模式,值为int类型，0：主屏幕显示（默认值）；1：双面屏机具，副屏幕显示 */
params.put("smile_mode", 0); 
mZoloz.verify(zimId, params, new VerifyCallback() {
     @Override
    public void onResponse(Smile2PayResponse smileToPayResponse) {
        Log.d(TAG, "verify()...response");
        if (smileToPayResponse != null) {
            int code = smileToPayResponse.getCode();
            String uid = smileToPayResponse.getAlipayUid();
            String fToken = smileToPayResponse.getFaceToken();
            String msg = Smile2PayResponse.CODE_SUCCESS == code ?
                "识别成功" : "识别失败";
            if (CODE_SUCCESS.equalsIgnoreCase(code) && fToken != null) {
                // 发起支付，参考调用收单接口完成支付
                ...       
            } else {
                String subMsg = smileToPayResponse.getSubMsg();
                String subCode = smileToPayResponse.getSubCode();
                Log.d(TAG, "verify()...response failed: code:" + code + " subCode:"
                     + subCode + " subMsg:" + subMsg);
            }
        }
    }
}

params

名称	类型	是否必填	具体说明
serviceId	String	是	取值： pay：支付
appId	String	是	开放平台添加刷脸付功能的appid，为学校/商户应用的appId
phone_number	String	否	用于会员刷脸付方案。填入用户登录会员系统的手机号
smile_mode	String	否	用于指定选择刷脸模式。值为 int 类型。0：主屏幕显示（默认值）；1：双面屏机具，副屏幕显示。
captureUIMode	int	否	CaptureUIMode.CLICK: 拍照付模式(smile5.1.2及以上版本支持，此接口直接传入这个参数)
displayWidth	String	否	刷脸框的宽度
displayHeight	String	否	刷脸框的高度
displayX	String	否	刷脸框的显示位置X坐标，左侧为0
displayY	String	否	刷脸框的显示位置X坐标，上沿为0
tradeAmount	String	否	订单金额，会展示在刷脸页面，单位元
speedy_amount_sound	boolean	否	captureUIMode为CLICK拍照付时，是否打开金额播报，默认为true
speedy_enter_sound	String	否	captureUIMode为CLICK拍照付时，进入拍照付界面，无金额的情况下播放的语音，默认null。需要定义好的eventId
enter_sound	String	否	进入非拍照付界面播放的语音，默认null
expireTime	int	否	拍照付预览页面倒计时时间，单位秒, 默认20
uiConfig	JsonString	否	-
-enableTimeout	int	否	uiConfig的子参数，表示是否开启拍照付页面的预览倒计时，false时表示无倒计时
zolozConfig	string	否	可添加摄像头参数示例：JSONObject jsonObject = new JSONObject(); jsonObject.put("cameraID", 0); jsonObject.put("displayAngle", 0);//显示角度 0，90，270 jsonObject.put("isDisplayMirror", true);//显示镜像 jsonObject.put("isMirror", false); jsonObject.put("algorithmAngle", 270);//算法角度 0，90，270 JSONObject extInfo = new JSONObject(); params.putString("zolozConfig", jsonObject.toJSONString());
delayFinish	int	否	延迟关闭，防止刷脸结束后页面销毁过快，新的结果页没有渲染出来导致的露底问题

对于 1:1人脸比对－用户在刷脸前提供手机号的产品方案，请在入参中增加 phone_number 键值。

// 将上一步中initialize接口返回的zim_init_client_data对象和zim_id作为入參
Map params = new HashMap();
params.put("zim.init.resp", protocal);
/* start: 如果是预输入手机号方案，请加入以下代码,填入会员绑定的手机号，必须与支付宝账号对应的手机号一致 */ 
params.put( "phone_number" ,  "1381XXXXX" ); 
/* end: --------------------------------------------- */ 
/* 可选：smile_mode用于指定选择刷脸模式,值为int类型，0：主屏幕显示（默认值）；1：双面屏机具，副屏幕显示 */
params.put("smile_mode", 0); 
mZoloz.verify(zimId, params, new VerifyCallback() {
     @Override
    public void onResponse(Smile2PayResponse smileToPayResponse) {
        Log.d(TAG, "verify()...response");
        if (smileToPayResponse != null) {
            int code = smileToPayResponse.getCode();
            String uid = smileToPayResponse.getAlipayUid();
            String fToken = smileToPayResponse.getFaceToken();
            String msg = Smile2PayResponse.CODE_SUCCESS == code ?
                "识别成功" : "识别失败";
            if (CODE_SUCCESS.equalsIgnoreCase(code) && fToken != null) {
                // 发起支付，参考调用收单接口完成支付
                ...       
            } else {
                String subMsg = smileToPayResponse.getSubMsg();
                String subCode = smileToPayResponse.getSubCode();
                Log.d(TAG, "verify()...response failed: code:" + code + " subCode:"
                     + subCode + " subMsg:" + subMsg);
            }
        }
    }
}

返回结果示例

在 result 对象中会返回当前认证用户的支付宝 UID，这个 UID 是客户端接口返回的结果，并不安全。如果需要依赖 UID 进行业务决策，请不要使用这个 UID 数据。请通过服务端 ftoken 查询接口（query）得到可信的 UID。

{
 "code":"返回码",
 "subCode":"二级返回码",
 "msg":"返回信息", 
    "ftoken":"ftoken",//用来支付或完成其它操作
 "result":{
 "alipayUid":"alipayUid", //支付宝账号的UID
 }
}

关键入参

参数名称	参数类型	必填	参数说明
zimId	String	是	人脸初始化接口返回的 zimId, 其中包含了唤起人脸验证的关键参数。
params	Map	是	调用服务初始化返回的结果中的协议内容。

phone_number：可选，用于会员刷脸付方案。填入用户登录会员系统的手机号。

smile_mode：可选，用于指定选择刷脸模式。值为 int 类型。0：主屏幕显示（默认值）；1：双面屏机具，副屏幕显示。

关键出参

参数名称	描述
code	错误码，如果刷脸认证成功返回，则为CODE_SUCCESS。
msg	返回信息。
subCode	二级返回码。
ftoken	标识刷脸认证成功，作为查询接口的入參。
result	被认证用户的支付宝账号 UID。

退出刷脸

在人脸采集页面调用 command 接口，可退出人脸采集页面并取消刷脸。

Map<String, Object> command = new HashMap<>(2);
command.put(ZolozConfig.KEY_COMMAND_CODE, CommandCode.EXIT); // exit退出
mZoloz.command(command);

查询接口得到 UID

调用查询接口 zoloz.authentication.customer.ftoken.query（人脸ftoken查询消费接口）得到可信的用户 UID。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.ZolozAuthenticationCustomerFtokenApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class ZolozAuthenticationCustomerFtokenApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        ZolozAuthenticationCustomerFtokenApi api = new ZolozAuthenticationCustomerFtokenApi();
        ZolozAuthenticationCustomerFtokenQueryModel data = new ZolozAuthenticationCustomerFtokenQueryModel();
        data.setBizType("1");
        data.setFtoken("fp0593e8d5c136277f13fd5bc36c13a7db7");
        data.setZimId("3b35b4677de2c69bb5bab69a4a5168d62");
        FaceExtInfo extInfo = new FaceExtInfo();
        extInfo.setMinAge("10");
        extInfo.setMaxAge("30");
        data.setExtInfo(extInfo);
        try {
            ZolozAuthenticationCustomerFtokenQueryResponseModel response = api.query(data);
        } catch (ApiException e) {
            ZolozAuthenticationCustomerFtokenQueryDefaultResponse errorObject = (ZolozAuthenticationCustomerFtokenQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

响应示例

{
    "age_check_result":"true",
    "uid":"2088002842508713",
    "uid_tel_pair_list":[
        {
            "user_id":"2088302193568425"
        }
    ],
    "cert_name":"张三",
    "cert_no":"身份证号码",
    "face_id":"6458f8361582010447730145389650"
}

关键入参

参数名称	参数类型	必填	参数说明
ftoken	String	是	人脸认证调用结果标识，如 fp0593e8d5c136277f13fd5bc。
biz_type	String	否	表明基于姓名和身份证号的刷脸支付场景，固定值为 8。如果是手机号方式，不需要填入该参数。
ext_info	FaceExtInfo	否	人脸产品拓展参数。

关键出参

参数名称	参数类型	必填	参数说明
uid	String	是	支付宝 UID，如 2088XXXX。

常见错误码

统一对外错误码	内部业务错误码	错误描述	解决方案
BIZ_ERROR	BIZ_ERROR	业务异常	排查人脸是否比对成功
INVALID_PARAMETER	INVALID_PARAMETER	参数有误	排查人脸是否比对成功
SYSTEM_ERROR	SYSTEM_ERROR	系统繁忙	排查人脸是否比对成功
FTOKEN_INVALID	FTOKEN_INVALID	ftoken非法	检查 FTOKEN 是否有效以及是否人脸比对通过
TOKEN_NOT_FOUND	TOKEN_NOT_FOUND	ftoken不存在	请检查下 ftoken 是否正确
UID_NOT_FOUND	UID_NOT_FOUND	支付宝用户 ID 匹配不对	请检查 ftoken 是否正确
TOKEN_EXPIRED	TOKEN_EXPIRED	token 已经过期	token 已经过期请重新尝试
TOKEN_CONSUMED	TOKEN_CONSUMED	token 已经消费	token 已经消费请重新尝试

调用收单接口完成支付

扫脸成功后获取 ftoken，传入 alipay.trade.pay 的 auth_code,，且 scene=security_code。

以下示例代码只列出了刷脸支付相关的关键参数，其它收单接口请求参数（如签约返佣协议的 PID），请参考 alipay.trade.pay（统一收单交易支付接口）。

ApiClient apiClient = Configuration.getDefaultApiClient();
// 初始化alipay参数（全局设置一次）
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
apiClient.setAlipayConfig(alipayConfig);
AlipayTradeApi api = new AlipayTradeApi(apiClient);
AlipayTradePayModel model = new AlipayTradePayModel();
model.setOutTradeNo(UUID.randomUUID().toString());
//auth_code和scene填写需要注意
model.setAuthCode(ftoken);  // 人脸zolozVerify接口返回的ftoken
model.setScene( "security_code" ); //对于刷脸付，必须写为security_code
model.setSubject( "smilepay" );
model.setStoreId( "smilepay test" );
model.setTimeoutExpress( "5m" );
model.setTotalAmount(amount);
try {
    AlipayTradePayResponseModel response = api.pay(model);
    System.out.println(response);
} catch (ApiException e) {
    System.out.println("调用失败，code：" + e.getCode() + "，body：" + e.getResponseBody());
}

关键入参

参数名称	参数说明
out_trade_no	商户订单号，需要保证不重复。
scene	刷脸支付固定传入 security_code。
auth_code	用户付款码，刷脸支付传入 ftoken。
subject	订单标题。
store_id	商户门店编号。
total_amount	订单金额。
timeout_express	交易超时时间。

关键出参

参数名称	参数说明
trade_no	支付宝 28 位交易号。

其它支付相关 API 请参考当面付API。

接入指南

1:1刷脸支付#

接入流程#

接入步骤#

获取刷脸所需的设备信息#

关键入参#

关键出参#

刷脸初始化#

业务入参#

出参#

唤起人脸识别#

返回结果示例#

关键出参#

退出刷脸#

查询接口得到 UID#

示例代码#

响应示例#

调用收单接口完成支付#

关键入参#

关键出参#

1:1刷脸支付

接入流程

接入步骤

获取刷脸所需的设备信息

关键入参

关键出参

刷脸初始化

业务入参

出参

唤起人脸识别

返回结果示例

关键出参

退出刷脸

查询接口得到 UID

示例代码

响应示例

调用收单接口完成支付

关键入参

关键出参