金融级活体检测方案服务端接入_实人认证(ID Verification)-阿里云帮助中心

本文介绍活体检测方案PC或移动端H5网页认证方案的接入流程。

发起认证请求

接口名：InitFaceVerify

全局接入地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET

传输协议：HTTPS

接口说明：每次开始认证前通过本接口获取CertifyId，用来串联认证请求中的各个接口。

QPS限量：API独享QPS限量，详情请参见服务端接口QPS限量说明。

请求参数

名称	类型	是否必选	描述	示例值
SceneId	Long	是	认证场景ID。您可以在控制台创建认证场景后获得的场景ID。	100000****
OuterOrderNo	String	是	客户服务端自定义的业务唯一标识，用于后续定位排查问题使用。值最长为32位长度的字母数字组合，请确保唯一。	e0c34a77f5ac40a5aa5e6ed20c******
ProductCode	String	是	认证方案。唯一取值：LR_FR。	LR_FR
Model	String	是	活体检测类型，取值：说明活体检测类型仅支持下列取值，暂不支持自定义动作或组合。 LIVENESS（默认）：眨眼 PHOTINUS_LIVENESS：眨眼 + 炫彩 MULTI_ACTION：眨眼 + 摇头（眨眼和摇头顺序随机） MULTI_PHOTINUS：眨眼 + 摇头（眨眼和摇头顺序随机）+ 炫彩活体检测。 MOVE_ACTION（推荐）：远近移动 + 眨眼（远近和眨眼顺序随机） MULTI_FAPTCHA：眨眼 + 形迹说明形迹判断是一种动作活体的检测方式，按规则移动鼻尖完成指定动作。形迹判断通过增加随机性，提升了安全能力。	PHOTINUS_LIVENESS
ReturnUrl	String	是	客户业务页面回跳的目标地址。	http://www.aliyun.com
MetaInfo	String	是	MetaInfo环境参数。实际环境需要通过JS文件，调用函数getMetaInfo()获取，详情请参见H5网页集成。	`{ "zimVer": "3.0.0", "appVersion": "1", "bioMetaInfo": "4.1.0:1150****,0", "appName": "com.aliyun.antcloudauth", "deviceType": "ios", "osVersion": "iOS 10.3.2", "apdidToken": "", "deviceModel": "iPhone9,1" }` 说明该示例仅供参考，实际集成中不能直接应用，否则会导致无法正常获取到认证URL。
Mobile	String	否	用户手机号码。	130xxxxxxxx
Ip	String	否	用户IP。	114.XX.XX.XX
UserId	String	是	您自定义的用户ID（最长100个字符），请保持唯一。	12345****
CallbackUrl	String	否	认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以`https`开头。平台在完成认证后会回调该地址，并自动添加`certifyId`、`passed`字段，`passed`字段值返回的是subcode值，示例：`https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200`。重要仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。该值的传入会在调用接口前做可访问校验，如果传入的地址不能在公网访问，会返回401。接口在回调后务必返回 HTTP 状态码 200，否则会触发重试，3秒内两次回调。	https://www.aliyundoc.com
CallbackToken	CallbackToken	否	安全Token，由您自行生成，用于防重复、防篡改校验。如果设置了该值会在回调地址显示CallbackToken字段。	NMjvQanQgplBSaEI0sL86******
CertifyUrlType	String	否	Web SDK设备类型。取值WEB或者H5。说明只支持Web SDK设备类型。	WEB
CertifyUrlStyle	String	否	返回certifyUrl类型，包括： L：原始长链 S（默认）：短链	L
ProcedurePriority	String	否	移动端H5方式认证出现WebRTC或者Webassembly不兼容时的降级配置。默认值：url。 keep：不支持降级，直接返回。 url：支持降级，返回认证URL，用户使用此URL打开或者切换浏览器进行认证。 video：支持降级，使用系统相机录制一段3~5秒的眨眼视频进行认证。说明当降级模式为Video时如下功能将失效，且产品安全性会降低，建议仅面向安全场景配置。活体检测的类型设置将不生效。视频存证VideoEvidence功能不支持。	url
FaceGuardOutput	String	否	设备助手标签种类，取值：DeviceRisk。说明选择输出设备助手会产生额外的费用，详情请参见付费增值服务。如果不需要输出设备助手标签，可以不传递参数或者传入空值。	DeviceRisk
uiCustomUrl	String	否	UI配置文件URL。关于Web SDK自定义UI说明，请参见Web SDK UI自定义配置说明。	www.aliyundoc.com
VideoEvidence	String	否	是否开启视频存证。 true：开启 false：不开启（默认）说明因为视频文件较大，当网络不稳定时系统会丢弃视频文件优先保障认证必要图片传输，建议您业务上设置为弱依赖视频。	false
CameraSelection	String	否	是否开启摄像头选择功能： Y：开启 N：不开启（默认）说明该功能仅针对PC端集成模式生效，开启后支持用户自主选择摄像头认证。	N
SuitableType	String	否	适老化配置参数，针对每笔认证请求生效，您可以根据自有App的业务属性、客群分布、操作特性等条件对于每笔认证请求选择不同的参数，包括以下选项，默认为0。 0：不开启，表示当前认证请求不开启适老化。 1：开启，表示当前认证请求开启适老化。 2：用户选择。支持终端用户选择认证模式，产品引导页提供“开启认证”和“长辈认证模式”两种认证入口，当用户选择“长辈认证模式”系统进入适老化模式。说明适老化参数仅在活体检测类型Model取值 LIVENESS 或者 MULTI_ACTION时生效。适老化主要是通过增加语音提示、字体放大、UI优化等方式针对老年人或身体机能存在缺陷的群体提供友好操作体验的认证模式。 Navite SDK支持适老化模式，SDK版本需要大于或等于2.2.5。 Web SDK 支持适老化模式，建议使用最新版本SDK。开启适老化，人脸验证时间会变长。当移动设备开启系统无障碍模式，SDK不支持开启适老化模式。	0
needMultiFaceCheck	String	否	终端检测到多人脸时是否拦截，取值： Y：拦截，客户端提示需要重新刷脸。 N（默认）：不拦截，取刷脸画面中的最大脸发送服务端进行安全检测。	Y

返回数据

名称	类型	描述	示例值
RequestId	String	请求ID。	130A2C10-B9EE-4D84-88E3-5384FF******
Code	String	返回码：200为成功，其他为失败。	200
Message	String	请求参数的响应信息。	success
ResultObject.CertifyId	String	实人认证唯一标识。重要 CertifyId字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。	91707dc296d469ad38e4c5efa6******
ResultObject.CertifyUrl	String	Web浏览器进行实人认证的URL，认证结束后根据入参ReturnUrl进行跳转。警告初始化接口返回的认证CertifyUrl在30分钟有效且仅能认证提交一次，请您在有效期内使用，避免重复使用。此参数需要入参中MetaInfo正确传入，以返回与客户端匹配的CertifyUrl。如无法获取，请检查MetaInfo以及其他传入参数是否正确。此地址域名可能会随服务更新而变更，为保证服务正常可用，建议不要对此地址域名进行访问控制。浏览器跳转时尽量不要使用无痕模式或改变 URL，否则可能会出现签名异常的错误。	https://t.aliyun.com/****

返回Code和Message说明

Code	Message	描述
200	success	成功。
400	参数不能为空	参数不能为空。
401	参数非法	非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402	应用配置不存在	应用配置不存在。
404	认证场景配置不存在	认证场景配置不存在，请先在控制台上创建认证场景。
410	未开通服务	未开通OSS产品或未完成OSS读写授权，请登录控制台完成授权。关于开通OSS产品和完成OSS读写授权，请参见授权金融级实人认证访问OSS存储空间。
411	RAM无权限	需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
412	欠费中	金融级实人认证或OSS存在欠费，请充值后操作。
414	设备类型不支持	当前移动设备不支持刷脸认证，请更换设备后操作。
415	SDK版本不支持	当前认证SDK版本不支持刷脸认证，请升级SDK后操作。
416	系统版本不支持	当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。
417	无法使用刷脸服务	当前身份信息比对源不可用。若信息正确，建议人工审核。
418	刷脸失败次数过多	当天刷脸认证次数过多，请明天再试。
500	系统错误	系统内部错误，请反馈工程师排查。

查询认证结果

接口名：DescribeFaceVerify

全局接入地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET

传输协议：HTTPS

接口说明：当您收到回调通知之后，可以在服务端通过该接口获取相应的认证状态和认证资料。

请求参数

名称	类型	是否必选	描述	示例值
SceneId	Long	是	认证场景ID。	1000000006
CertifyId	String	是	实人认证唯一标识。	91707dc296d469ad38e4c5efa6a0f24b

返回数据

名称	类型	描述	示例值
RequestId	String	请求ID。	130A2C10-B9EE-4D84-88E3-5384FF039795
Code	String	返回码，200 指接口响应成功。您可以在Code中查看不同 Code 的详细描述。	200
Message	String	请求信息的响应消息，对 Code（返回码）的简短描述。	success
ResultObject.Passed	String	认证结果，取值： T：通过 F：未通过说明判断认证结果请以ResultObject.Passed字段为准。	T
ResultObject.SubCode	String	认证结果描述。您可以在ResultObject.SubCode错误码说明中查看不同状态码的描述和处理建议。说明判断认证结果请以 ResultObject.Passed 字段为准。	200
ResultObject.DeviceRisk	String	设备风险标签。	VirtualBrowser 说明多个设备风险标签以半角逗号（,）分隔。您可以通过设备风险标签了解所有标签及其含义。
ResultObject.MaterialInfo	String	人脸认证主体附件信息，包含人脸质量、人脸攻击、人脸或OCR图片以及意愿认证等数据信息。	MaterialInfo