字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。

说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。

"2017839040588699"

metaInfo

String

512

是

-

SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。

说明：不要修改返回值，直接传递即可。如果是H5接入模式，则设置为MOB_H5。

"{

\"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

flowType

String

32

是

-

指定身份验证流的类型。取值如下：

• REALIDLITE_KYC：使用App SDK接入模式。
• H5_REALIDLITE_KYC：使用H5接入模式。

"H5_REALIDLITE_KYC"

docType

String

16

是

-

指定证件类型。例如要上传的证件是护照，该字段的值需要设置为00000001003。

RealID支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。

"08520000001"

userId

String

64

是

-

商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏，例如进行哈希处理。

"123456abcd"

sceneCode

String

64

否

null

场景码，用来为数据分析指定不同的业务场景。

当需要区分不同业务场景中的数据表现时，建议根据业务用途为sceneCode字段设置不同的值，例如login、riskVerify、payment、changePassword。

"changePassword"

serviceLevel

String

32

否

REALID0001

防伪检测和人脸活体检测的服务等级。取值如下：

• REALID0001：在身份验证进程中需要用户手动拍摄证件照片。ZOLOZ执行基本的防伪检测，以及使用眨眼检测方法进行基本的活体检测。
• REALID0002：在身份验证进程中ZOLOZ SDK会自动扫描证件。ZOLOZ执行高等级的防伪检测，以及使用眨眼检测方法进行基本的活体检测。
• REALID0003：在身份验证进程中ZOLOZ SDK会自动扫描证件。ZOLOZ执行高等级的防伪检测，并使用多动作检测方法进行活体检测。这些动作从以下列表中随机选择两个：眨眼、张嘴、抬头、低头、左摇头、右摇头。
  说明：该服务等级仅支持在原生SDK模式下使用。
• REALID0004：在身份验证进程中，即使身份证件处于倾斜角度，ZOLOZ SDK也会自动扫描证件。ZOLOZ执行基本的防伪检测，以及使用眨眼检测方法进行基本的活体检测。
• REALID0009：在身份验证进程中ZOLOZ SDK会自动扫描证件。ZOLOZ执行高等级的防伪检测，以及使用眨眼检测方法进行活体检测。
  说明：该服务等级会额外采集一张闭眼的人脸图片，且该服务等级仅支持在原生SDK模式下使用。
  
• REALID0011：在身份验证进程中ZOLOZ SDK会自动扫描证件。ZOLOZ执行高等级的防伪检测，以及使用眨眼检测方法进行活体检测。
  说明：该服务等级会额外采集一张闭眼的人脸图片，且该服务等级仅支持在Web SDK模式下使用。
• REALID0012：在身份验证进程中ZOLOZ SDK会自动扫描证件。ZOLOZ执行基本的防伪检测，以及使用眨眼检测方法进行活体检测。
  说明：该服务等级仅支持在Web SDK模式下使用。

"REALID0001"

operationMode

String

32

否

STANDARD

为身份验证配置操作模式。取值如下：

• CLOSED：所有的算法和风控规则都未开启。该操作模式可用于测试场景，测试进程不受算法和风控规则的影响。
• STANDARD：推荐的标准模式。
• LOOSE：相对宽松的模式，可用于低风险场景。
• STRICT：相对严格的模式，可用于高风险场景。
• STANDARD_VC_CLOSED：使用此模式关闭Velocity功能。

• STANDARD_IDN_CLOSED：使用此模式关闭IDN功能。
• STANDARD_VC_IDN_CLOSED：使用此模式关闭Velocity功能和IDN功能。

说明：当operationMode设置为STANDARD_VC_CLOSED、STANDARD_IDN_CLOSED或STANDARD_VC_IDN_CLOSED时，其他算法能力与STANDARD相同。

以下是IDN和Velocity的含义：

• IDN：表示通过IDN检测到虚假验证风险。例如，检测到识别出的人脸与多个身份证件相关或检测到一个身份证件与多张人脸相关。更多详情，请参见checkresult。
• Velocity：表示通过Velocity检测到虚假验证风险。例如，同一用户（通过userId、证件号或deviceId识别）在一段时间内尝试攻击（例如篡改证件信息或活体攻击）的次数达到一定阈值时，Velocity功能将不允许该用户继续提交，直到冷却期结束为止。

"STANDARD"

pages

String

32

否

证件类型支持的所有页

待扫描和上传的证件页面，多个页面以英文逗号分隔。例如：

• 1：表示扫描第一页。
• 1,2：表示扫描第一页和第二页。

有关证件页面的范围，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。

说明：如果不传该字段，默认值为对应证件类型支持的所有页。

"1,2"

pageConfig

PageConfig

-

否

null

指定H5页面的配置信息。详细信息，请参见PageConfig。

{ "urlFaceGuide":"http://url-to-face-guide-page.html" }

h5ModeConfig

H5ModeConfig

-

否

null

H5 RealID的配置信息。详细信息，请参见H5ModeConfig。

说明：当flowType的值为H5_REALIDLITE_KYC时必须传入该字段。

{ "completeCallbackUrl":"http://xxx.html", "interruptCallbackUrl":"http://xxx.html"

}

productConfig

ProductConfig

-

否

null

为RealID产品提供更精细化的控制。详细信息，请参见ProductConfig。

{

"cropDocImage": "Y", "landmarkCheck": [ {"name":"kadPengenalan"}, {"name":"mykadLogo"}, {"name":"flagLogo"}, {"name":"mscLogo"}, {"name":"ghostFace"}, {"name":"hibiscusLogo"}, {"name":"coatOfArm"}, {"name":"twinTower"} ], "hologramCheck": [ {"name":"hologram"} ], "pageInfoCheck": [ {"name":"id"}, {"name":"symbol"}, {"name":"name"} ], "preciseTamperCheck": "Y" }

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

urlFaceGuide

String

256

否

null

人脸引导页的URL。该页面为H5提示页面，可自定义引导用户进行人脸扫描。
说明：如果您想在定制页面中隐藏ZOLOZ提供的标题栏，请参见如何隐藏Native SDK的人脸引导页标题栏？。

"http://url-to-face-guide-page.html"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

state

String

128

否

transactionId字段的值

用于恢复客户上下文的标识符。

您可以为该字段设置任何值，当ZOLOZ SDK回调商户的移动App时将该值作为参数进行传递。

"G000000005FID20200304000000000001570702"

completeCallbackUrl

String

128

是

-

当整个身份验证完成时，为浏览器指定即将重定向的回调URL。

"http://xxx.html"

interruptCallbackUrl

String

128

是

-

当进程中断时，为浏览器指定重定向到的回调URL。

"http://xxx.html"

locale

String

16

否

en

网页语言，目前支持以下语言：

• en（英语）
• zh-CN（简体中文）
• zh-HK（繁体中文）
• jp（日语）
• th（泰语）
• es（西班牙语）
• pt（葡萄牙语）
• fr（法语）
• id（印度尼西亚语）
• de（德语）
• kr（韩语）
• vi（越南语）

"zh-CN"

isIframe

String

1

否

N

是否需要在iframe中打开网页，如果需要设置为Y，否则设置为N。

"Y"

uiCfg

String

256

否

null

自定义UI配置，采用JSON字符串格式。目前仅支持titlebarbgcolor、titlebartextcolor和buttoncolor。

"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\"}"

字段名称

数据类型

最大长度

是否必填

默认值

描述

特别说明

示例值

cropDocImage

String

1

否

N

是否额外返回一张裁剪掉证件背景的证件图片。取值如下：

• Y：是，如果同时采集了证件的正面和背面图片，则会额外返回两张裁剪后的图片。
• N：否

-

"Y"

cropFaceImage

String

1

否

N

是否额外返回一张裁剪出脸部区域的人脸图片。取值如下：

• Y：是
• N：否

-

"Y"

landmarkCheck

Array

-

否

null

在证件防伪检测中进行landmark检查，详细检查项，请参见证件防伪检测组件。

说明：landmark检查仅适用于大马卡（MyKad）。

-

[{"name":"kadPengenalan"}, {"name":"mykadLogo"}, {"name":"flagLogo"}, {"name":"mscLogo"}, {"name":"ghostFace"}, {"name":"hibiscusLogo"}, {"name":"coatOfArm"}, {"name":"twinTower"}]

hologramCheck

Array

-

否

null

在证件防伪检测中进行全息图检查，详细检查项，请参见证件防伪检测组件。

说明：全息图检查仅适用于大马卡（MyKad）。

-

[{"name":"hologram"}]

pageInfoCheck

Array

-

否

null

在证件防伪检测中进行页面信息检查，详细检查项，请参见证件防伪检测组件。

说明：页面信息检查仅适用于中国香港身份证。

-

[

{"name":"id"}, {"name":"symbol"}, {"name":"name"} ]

preciseTamperCheck

String

1

否

N

是否进行精细篡改检测。精细篡改检测仅适用于中国香港身份证。

• Y：进行精细篡改检测
• N：不进行精细篡改检测

-

"Y"

docUiType

String

20

否

• Native SDK：2
• Web SDK：1

证件照片的采集方式。取值如下：

• 1：手拍版（Self-capture），用户需要手动拍摄证件照片，仅具备基础防伪能力。
• 2：Native防伪版（Deep-scan），仅适用于Native SDK。ZOLOZ SDK将自动对齐并拍摄证件照片，具备拦截彩打等高级防伪能力。
• 3：H5扫描版（Auto-scan），仅适用于Web SDK。ZOLOZ SDK将自动对齐并拍摄证件照片，仅具备基础防伪能力。
• 4：甩证版（Trace-scan），仅适用于Native SDK。当ZOLOZ SDK在摄像头范围内检测到证件时将自动拍摄。该版式可用于提升用户体验，但防伪能力较弱，仅具备基础防伪能力。
• 5：多角度版（Multi-angle），仅适用于Web SDK中的中国香港证件。用户需要分别拍摄正对证件的照片和证件倾斜30°的照片，具备拦截彩打等高级防伪能力。

以下9个参数的优先级高于serviceLevel和operationMode，如果传入了9个参数中的任何一个，其他几个参数的默认值都会生效。此时即使传入了servicelevel和operationmode的值，servicelevel和operationmode也不生效。

• docUiType
• spoofMode
• livenessMode
• antiInjectionMode
• actionCheckItems
• actionRandom
• actionFrame
• riskMode
• idnThreshold

"2"

spoofMode

String

10

STANDARD

证件防伪等级。取值如下：

• CLOSED：所有的防伪算法都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。
• STANDARD：推荐的标准等级。
• LOOSE：预留等级，暂不支持使用。
• STRICT：预留等级，暂不支持使用。

"STANDARD"

livenessMode

String

10

STANDARD

人脸活体检测等级。取值如下：

• CLOSED：所有的算法和风控规则都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

"STANDARD"

antiInjectionMode

String

10

CLOSED

防注入检测等级。防注入检测能够有效抵御使用换脸图片或视频进行的注入攻击。取值如下：

• CLOSED：所有的防注入算法都不开启。如果业务场景不需要注入攻击检测，则不需要开启。
• STANDARD：推荐的标准等级。
• LOOSE：预留等级，暂不支持使用。
• STRICT：预留等级，暂不支持使用。

注意：开启防注入检测会略微增加误报率和运行时间，开启前请先联系ZOLOZ技术支持。

"CLOSED"

actionCheckItems

List<String>

-

FACEBLINK

客户端和Web端的动作检测列表。取值如下：

• FACEBLINK：眨眼
• MOUTHOPEN：张嘴
• HEADSHAKE：摇头
• HEADLOWER：低头
• HEADRAISE：抬头

说明：为了更好的用户体验，不建议使用两种及以上的动作。

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

N

客户端和Web端的动作检测顺序是否随机。取值如下：

• Y：随机。
• N：不随机，则按照actionCheckItems中的顺序进行检测。

"Y"

actionFrame

List<String>

-

null

采集其他帧图片。取值如下：

• EYECLOSE：闭眼帧。

["EYECLOSE"]

riskMode

String

10

STANDARD

RealID中的多维度风控规则校验，用于拦截可疑交易。取值如下：

• CLOSED：所有有关风险检测的算法都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

"STANDARD"

idnThreshold

Integer

-

3

指定阈值，用于拦截同一商户同脸不同证或同证不同脸的交易，当不同userId之间的关联交易笔数超过指定的阈值时将被拦截。
支持传入大于等于1的任何整数，默认阈值为3。

"3"

allowExpiredDocument

String

-

否

不同的证件类型有不同的默认值：

• Y：除护照（docType=00000001003）外的所有证件
• N：护照（docType=00000001003）

已过期的证件是否可以通过验证。取值如下：

• Y：已过期的证件可以通过验证。
• N：已过期的证件不能通过验证。当检测到证件过期时，RealID流程会失败。

说明：如果传入的值为空或无效，此时将使用默认取值。

-

"N"

faceAttributeCheck

FaceAttributeCheck

-

否

null

人脸属性检测，详情请参见FaceAttributeCheck。

说明：faceAttributeCheck的优先级高于livenessMode。例如，当occlusionCheck.detectOpen为N时，即使livenessMode为STRICT，也不会进行人脸遮挡检测。

-

{

     "occlusionCheck": {

       "details": [

         "eyesOcclusion",

         "noseOcclusion",

         "mouthOcclusion",

         "foreheadOcclusion",

         "chinOcclusion",

         "cheekOcclusion"

       ],

       "detectOpen": "Y",

       "needRetry": "Y"

     },

     "maskCheck": {

       "detectOpen": "Y",

       "needRetry": "N"

     },

     "glassesCheck": {

       "detectOpen": "Y",

       "needRetry": "N"

     },

     "hatCheck": {

       "detectOpen": "Y",

       "needRetry": "N"

     }

   }

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

occlusionCheck

FaceAttributeDetails

-

否

null

是否进行人脸遮挡检测，详情请参见FaceAttributeDetails。

{

"details": [

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

],

"detectOpen": "Y",

"needRetry": "Y"

}

maskCheck

FaceAttributeDetails

-

否

null

是否进行口罩检测，详情请参见FaceAttributeDetails。

{

"detectOpen": "Y",

"needRetry": "N"

}

glassesCheck

FaceAttributeDetails

-

否

null

是否进行眼镜检测，详情请参见FaceAttributeDetails。

{

"detectOpen": "Y",

"needRetry": "N"

}

hatCheck

FaceAttributeDetails

-

否

null

是否进行帽子检测，详情请参见FaceAttributeDetails。

{

"detectOpen": "Y",

"needRetry": "N"

}

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

detectOpen

String

1

是

null

是否检测人脸属性并在checkresult API中返回检测结果。取值如下：

• Y：是
• N：否

"Y"

needRetry

String

1

是

null

检测到指定属性时是否重试。取值如下：

• Y：是。当needRetry为Y时，detectOpen必须为Y。
• N：否。当needRetry为N时，eKYC仍可能会因为人脸质量较低而提示重试。

"Y"

details

List<String>

-

否

null

是否返回人脸属性的结果详情。目前仅支持返回occlusionCheck的结果详情，支持的选项如下：

• eyesOcclusion：返回眼睛遮挡结果。
• noseOcclusion：返回鼻子遮挡结果。
• mouthOcclusion：返回嘴巴遮挡结果。
• foreheadOcclusion：返回额头遮挡结果。
• chinOcclusion：返回下巴遮挡结果。
• cheekOcclusion：返回脸颊遮挡结果。

说明：

• 当传入details参数时，detectOpen必须为Y。
• details对应的总结果和特定属性结果将在checkresult API中返回。

[

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

]

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API请求结果，包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

ZOLOZ服务器为身份验证生成的唯一事务ID。此ID将作为RealID checkresult API请求的输入参数。

说明：当在客户端身份验证中出现错误时，例如参数无效，则不返回事务ID。

"G000000005FID20200304000000000001570702"

clientCfg

String

否

客户端配置信息，包括SDK连接和行为参数。

说明：当result.resultStatus的值为S时，才返回该字段。

"……"

结果码

结果状态

描述

SUCCESS

S

API调用成功。

HIGH_RISK

F

检测到高风险。用户账号被风险引擎冻结。

ACCOUNT_SERVICE_SUSPEND

F

用户账号被风险引擎列入黑名单。

DEVICE_NOT_SUPPORT

F

不支持当前的设备类型。

OS_NOT_SUPPORT

F

不支持当前设备的操作系统。

SDKVERSION_NOT_SUPPORT

F

不支持ZOLOZ SDK当前的版本。

INVALID_ARGUMENT

F

输入参数无效。关于无效参数的详细信息，请查看返回的resultMessage。

SYSTEM_ERROR

F

其他内部错误。有关错误详情，请查看返回的resultMessage。