字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

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

否

null

指定上传证件的类型。例如上传证件为护照，docType设置为00000001003。支持的证件类型，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。

注意：

• docType与autoDocTypes、autoDocCategory、autoDocCountryCode互斥，不可同时使用。
• docType、autoDocTypes、autoDocCategory、autoDocCountryCode可以分别单独使用。

"08520000001"

autoDocTypes

List<String>

200

否

null

指定证件类型列表，由系统对上传证件进行自动分类。该参数可单独使用或与autoDocCountrycode组合使用。

• 港澳入境小票不支持自动分类。
• 如果系统无法分类或分类结果不在传入的autoDocTypes中，checkresult API将返回NO_REQUIRED_ID。

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

["00630000032","00630000004"]

autoDocCategory

List<String>

-

否

null

指定证件类别，由系统对上传证件进行自动分类。该参数可单独使用或与autoDocCountrycode组合使用。

• 支持的证件类别如下：

• PASSPORT：护照
• DRIVING_LICENSE：驾照
• ID_CARD：身份证
• RESIDENCE_PERMIT：居住证
• VISA：签证
• ALL：所有证件

• 如果系统无法分类或分类结果不在传入的autoDocCategory中，checkresult API将返回NO_REQUIRED_ID。

注意：当传入autoDocCategory时，系统可能识别出新的证件类型和类别，此时checkresult API返回的certType和docCategory可能归入新的证件类别。这是由于ZOLOZ正在不断扩展全球证件的覆盖范围，以支持更多证件类型。

举例：当autoDocCategory设置为ALL时，系统会根据上传证件自动分类，分类完成后，certType可能返回一种新的证件类型（例如00000001001），并归类为NEW_CATEGORY。

为确保您的系统平稳适配新的证件类型，建议提前做好兼容性集成措施，例如避免对返回的certType和docCategory进行强校验。

"ID_CARD"

List<String>

300

否

null

指定证件所属国家或地区。支持传ALL或符合ISO 3166-1 alpha-3标准的三位国家码。

支持以下使用方式：

• autoDocCountrycode单独使用：表示传入的证件类型属于某个国家。
• autoDocCountrycode+autoDocCategory：取两个参数的交集，表示传入的证件类型属于某国家某类别的证件。
  举例：autoDocCategory=ID_CARD和DRIVING_LICENSE，autoDocCountrycode=PHL，表示只允许菲律宾的身份证和驾照通过，否则提示证件类型错误。
• autoDocCountrycode+autoDocTypes：取两个参数的交集，表示传入的证件类型列表属于某个国家。
  注意：

• autoDocTypes必须包含通用护照（00000001003或00000001006）才能组合使用，否则系统将拦截该请求。
• autoDocCountrycode必须涵盖传入的autoDocTypes列表中的国家范围，否则系统将拦截该请求。

      举例：

• autoDocTypes=通用护照（00000001003或00000001006）和菲律宾驾照（00630000004），autoDocCountrycode=AUS，系统将拦截该请求。
• autoDocTypes=通用护照（00000001003或00000001006）和澳大利亚永久居民身份证（00610000009），autoDocCountrycode=AUS，表示只允许澳大利亚的护照和永久居民身份证通过，否则系统将提示证件类型错误。

注意：

• 如果系统无法分类或分类的证件国家不在autoDocCountrycode中，checkresult API将返回NO_REQUIRED_ID。
• 当传入autoDocCountrycode时，系统可能识别出新的证件国家，此时checkresult API返回的certCountry和certCountryCode可能归入新的证件国家。这是由于ZOLOZ正在不断扩展全球证件的覆盖范围，以支持更多证件类型。
  为确保您的系统平稳适配新的证件国家，建议提前做好兼容性集成措施，例如避免对返回的certType、docCategory、certCountry和certCountryCode进行强校验。

[

"CHN",

"PHL"

]

autoDocPages

Map<String, String>

-

否

证件类型的默认页数

指定需要扫描和上传的证件页数，仅支持与证件自动分类参数（autoDocTypes、autoDocCategory和autoDocCountrycode）组合使用。参数格式为键值对（Key-Value）：

• Key：传入的证件类型。
• Value：需要扫描的证件页数。

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

不同证件类型的最大支持页数与默认页数，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。

注意：

• 如果不传该参数，默认值为对应证件类型的默认页数。
• 如果需要扫描两页，请传1,2。
• 当和autoDocTypes组合使用时，在autoDocTypes中必须包含autoDocPages中的所有证件类型。

{

   "00630000032": "1",  

   "00630000004": "1,2"

}

userId

String

64

是

-

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

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

"123456abcd"

sceneCode

String

64

否

null

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

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

"changePassword"

serviceLevel

String

32

否

REALID0001

该参数已不再推荐使用，建议设置productConfig中的具体参数。

防伪检测和人脸活体检测的服务等级。该参数基于不同的集成模式，预设了检测等级、人脸动作、采集帧等配置，如需自定义这些配置，请使用productConfig相关字段。

serviceLevel支持的取值，详见serviceLevel配置说明。

"REALID0001"

operationMode

String

32

否

STANDARD

该参数已不再推荐使用，建议设置productConfig中的具体参数。

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

• 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

否

证件类型的默认页数

指定需要扫描和上传的证件页数，仅支持与docType参数组合使用。多个页数间用英文逗号分隔，例如：

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

不同证件类型的最大支持页数与默认页数，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。

注意：

• 如果不传该参数，默认值为对应证件类型的默认页数。
• 如果需要扫描两页，请传1,2。
• 当传入autoDocTypes、autoDocCategory或autoDocCountrycode时，pages必须为空，否则系统将返回INVALID_ARGUMENT。

"1,2"

pageConfig

PageConfig

-

否

null

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

{ "urlFaceGuide":"http://xxxxxx.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" }

serviceLevel

支持的SDK模式

证件采集方式

防伪检测等级

人脸动作

额外采集的图片

REALID0001

Native SDK和Web SDK

手动拍摄

基本

眨眼

无

REALID0002

Native SDK

自动拍摄

高级

眨眼

无

Web SDK

手动拍摄

基本

眨眼

HKID可额外采集多角度帧

REALID0003

Native SDK

自动拍摄

高级

从以下列表中随机选择两个：眨眼、张嘴、抬头、低头、左摇头、右摇头。

无

Web SDK

手动拍摄

基本

HKID可额外采集多角度帧

REALID0004

Native SDK

自动拍摄且无需证件对齐采集框

基本

眨眼

无

REALID0009

Native SDK

自动拍摄

高级

眨眼

闭眼帧

REALID0011

Web SDK

手动拍摄

基本

眨眼

• HKID可额外采集多角度帧
• 闭眼帧

REALID0012

Web SDK

自动拍摄

高级

眨眼

无

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

urlFaceGuide

String

256

否

null

人脸引导页URL。该页面为H5提示页面，可自定义设置，用于引导用户进行人脸扫描。
说明：

• PC端自带人脸引导页，该参数仅适用于移动端。
• 如需在定制页面中隐藏ZOLOZ提供的标题栏，请参见如何隐藏Native SDK的人脸引导页标题栏？。

"http://xxxxxx.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
• isDesktop：是否从PC端初始化证件采集模式。

• Y：从PC端初始化。当isDesktop为Y时，serviceLevel仅支持REALID0001，docUiType仅支持1，否则系统将返回INVALID_ARGUMENT。
• N：从移动端初始化，使用移动Web SDK采集流程。默认值为N。

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

allowDegradation

String

1

否

N

是否允许进入降级模式。取值如下：

• Y：允许进入降级模式。
• N：不允许进入降级模式。

说明：

• 如果将allowDegradation设置为Y，当ZOLOZ检测到用户的浏览器不支持Web SDK时，用户可以选择是否进入降级模式，确认进入降级模式后，ZOLOZ将调用系统原生相机进行拍摄。
• 降级模式可能存在较高风险，对于来自降级模式下的交易，ZOLOZ判定出的最高eKYC结果为Pending，需要您进行二次检查。

"Y"

docFrontPageGuideUrl

String

128

否

null

指定降级模式下证件引导页首页的URL。这是一个可定制的H5提示页面，用于引导用户采集证件的第一页图片。

说明：如果不传该参数，则使用默认页面。

"http://xxx.html"

docBackPageGuideUrl

String

128

否

null

指定降级模式下证件引导页第二页的URL。这是一个可定制的H5提示页面，用于引导用户采集证件的第二页图片。
说明：如果不传该参数，则使用默认页面。

"http://xxx.html"

facePageGuideUrl

String

128

否

null

指定降级模式下人脸引导页面的URL。这是一个可定制的H5提示页面，用于引导用户采集自拍人脸图片。

说明：如果不传该参数，则使用默认页面。

"http://xxx.html"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

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

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

说明：页面信息检查仅适用于以下证件类型：

• 中国香港身份证
• 马来西亚大马卡（MyKad）
• 新加坡国民身份证（Citizen Card）
• 新加坡永久居民卡（Permanent Resident Card）

[

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

preciseTamperCheck

String

1

否

N

该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。

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

• 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将自动对齐并拍摄证件照片，仅具备基础防伪能力。
  建议Web SDK使用自动扫描的采集方式，因为与手拍版相比，自动扫描的用户体验更好且证件图片质量更高。
• 4：甩证版（Trace-scan），仅适用于Native SDK。当ZOLOZ SDK在摄像头范围内检测到证件时将自动拍摄。该版式可用于提升用户体验，但防伪能力较弱，仅具备基础防伪能力。
  说明：该采集方式已废弃并停止维护。
• 5：多角度版（Multi-angle），仅适用于Web SDK中的中国香港证件。用户需要分别拍摄正对证件的照片和证件倾斜30°的照片，具备拦截彩打等高级防伪能力。

说明：Deeper功能依赖Deep-scan和Auto-scan这两种采集方式。当开启Deeper功能时，为确保最佳检测效果，请根据您的实际应用场景选择对应的采集方式，Native端使用Deep-scan，H5端使用Auto-scan，否则会影响检测效果。

"2"

spoofMode

String

10

STANDARD

证件防伪等级。取值：

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

"STANDARD"

livenessMode

String

10

STANDARD

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

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

"STANDARD"

antiInjectionMode

String

10

CLOSED

该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。

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

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

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

"CLOSED"

deeperMode

String

10

否

CLOSED

AIGC攻击检测的Deeper等级，Deeper检测功能的详细介绍，请参见什么是Deeper。该参数支持以下取值：

• CLOSED：Deeper的所有能力均不开启，例如AIGC检测算法、终端风险检测等。如果业务场景不需要AIGC攻击检测，则无需开启。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

注意：需要先购买Deeper产品，才能使用该功能。

"CLOSED"

actionCheckItems

List<String>

-

FACEBLINK

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

• FACEBLINK：眨眼
• MOUTHOPEN：张嘴
• HEADSHAKE：摇头
• HEADLOWER：低头
• HEADRAISE：抬头
• NOACTION：无动作。当actionCheckItems设置为NOACTION时，SDK版本需满足以下要求：

• iOS SDK：使用1.5.5.250519182352及以上版本
• Android SDK：使用1.5.5.250519101845及以上版本

说明：

• NOACTION与其他动作互斥，不能同时设置。当actionCheckItems设置为NOACTION时，actionRandom、actionRandomNumber和actionFrame参数均不生效。
• 为确保更好的用户体验，建议仅选择一种动作，避免同时使用两种及以上动作。
• 每种动作类型只能传入一次，请勿重复传入相同的动作类型。

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

N

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

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

"Y"

actionRandomNumber

String

-

null

从客户指定的动作列表（actionCheckItems）中，定义随机动作检测的数量。

取值范围：actionRandomNumber必须为正整数，且0<actionRandomNumber≤actionCheckItems中指定的动作总数。

说明：

• actionRandomNumber参数的优先级高于actionRandom，如果两者同时传入，优先生效actionRandomNumber。
• 当actionRandomNumber为空，且actionRandom=Y时，则对actionCheckItems中的所有动作进行随机检测。
• 当actionRandomNumber为空，且actionRandom=N或为空时，则按照actionCheckItems中的顺序进行检测。

"3"

actionFrame

List<String>

-

null

用于采集其他帧图片。取值：

• EYECLOSE：设置此值可返回在眨眼检测过程中采集的闭眼帧，但需确保actionCheckItems参数中包含FACEBLINK，否则将导致眨眼检测功能激活失败。
• MULTIACTIONS：对端侧执行的所有动作各采集一帧并返回。如果设置了此值，但端侧未检测到任何动作，则返回的动作帧内容为空。

["EYECLOSE"]

colorFlash

String

-

N

是否开启炫彩活体检测功能。取值：

• Y：开启炫彩活体检测功能。
• N：不开启炫彩活体检测功能。

说明：

• 仅移动端Native SDK（iOS与Android）和Web SDK支持该功能，鸿蒙SDK和PC端设备暂不支持。
• 如果同时设置了多动作检测，炫彩活体检测流程将在多动作流程完成后进行。

"Y"

riskMode

String

10

STANDARD

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

• CLOSED：关闭风控冷却规则。该等级适用于测试场景，测试进程不受风控规则的影响。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

"STANDARD"

idnThreshold

Integer

-

3

该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。

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

"3"

allowExpiredDocument

String

-

否

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

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

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

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

说明：

• 如果传入除Y和N之外的值，系统将返回INVALID_ARGUMENT。
• 中国香港一代身份证（docType=08520000001）的过期拦截机制，将严格按照香港政府身份证换领流程的要求执行。

"N"

faceAttributeCheck

FaceAttributeCheck

-

否

null

人脸属性检测配置，详见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"

     }

   }

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

是否进行一致性检查。一致性检查仅适用于部分证件的特定字段，详见ConsistencyCheckItem。

参考请求示例

checkAdvancedIdn

String

-

否

N

是否开启IDN风险检查。取值：

• Y：开启。
• N：不开启。

说明：需要先购买IDN，才能开启该功能。

"Y"

advancedIdnRiskDetection

RiskDetection

-

RiskDetection

风险检测，详情请参见RiskDetection。

说明：仅当checkAdvancedIdn为Y时，该参数才生效。

{

   "riskTypes":[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

      "DEEPFAKE",

   ],

   "timeWindow":{

      "startTime":1651882535687,

      "endTime":1658902665000

   }

 }

advancedIdnThreshold

Integer

-

3

指定IDN风险检查的阈值，取值范围为1-100，当历史关联的风险交易笔数超过该阈值时将被拦截。默认拦截结果为eKYC风险检查结果（ekycResultRisk）将返回Pending。相同的itemId只会计数一次。

说明：仅当checkAdvancedIdn为Y时，该参数才生效。

3

advancedIdnFailureThreshold

Integer

-

null

客户可定制IDN查询结果为Failure。该参数用于指定IDN风险检查的Failure阈值，取值范围为1-100。当历史关联的风险交易笔数超过该阈值时，eKYC风险检查结果（ekycResultRisk）将返回Failure。相同的itemId只会计数一次。

配置效果：

• 不传该参数：该参数不生效，系统会根据advancedIdnThreshold进行判定，当风险交易笔数超过advancedIdnThreshold阈值时，ekycResultRisk返回Pending。
• 传入该参数：

• 若advancedIdnFailureThreshold > advancedIdnThreshold，两者均生效。当风险交易笔数超过advancedIdnThreshold时先返回Pending，继续超过advancedIdnFailureThreshold时升级为Failure。
• 若advancedIdnFailureThreshold ≤ advancedIdnThreshold，则advancedIdnThreshold失效，当风险交易笔数超过advancedIdnFailureThreshold时直接返回Failure。

说明：仅当checkAdvancedIdn为Y时，该参数才生效。

5

deleteAdvancedIdnImage

String

-

N

是否在数据入库后删除人脸和证件图片。取值：

• Y：删除图片，仅保留人脸特征值和证件OCR提取数据。删除后将产生以下影响，请谨慎设置：

• 删除后图片无法恢复，影响后续业务排查。
• 如果未来算法版本升级，原有人脸特征值将无法再使用，需重新录入全部数据。OCR提取字段不受影响。

• N：保留图片。

"N"

checkBlacklist

String

1

N

是否开启黑名单风险检查。取值：

• Y：开启。
• N：不开启。

说明：需要先购买黑名单能力，才能开启该功能。

"Y"

enableUpload

String

1

N

是否允许上传文件获取证件图片。取值：

• Y：允许上传文件获取证件图片。启用该功能需注意：

• 在此场景下，RealID会将证件模块的总结果置为Pending，最终业务结果由人脸模块和风控模块共同判定。
• Web SDK特殊配置：

• enableUpload=Y且isDesktop=Y：表示启用PC端图片上传功能。
• enableUpload=Y且isDesktop=N：表示启用移动端图片上传功能。

• N：不允许上传文件获取证件图片。

端侧支持说明：

• Web SDK（移动端）：支持手拍版和扫描版。
• Native SDK：仅支持手拍版。

SDK版本要求：

• iOS SDK：需使用2.1.2.260114104408及以上版本。
• Android SDK：需使用2.1.2.260115144712及以上版本。

"Y"

scanDegradation

String

1

N

是否启用扫描降级模式。启用后系统将实时检测扫描状态，当扫描版采集超时或其他原因导致无法正常采集到证件时，自动切换至手拍版进行采集。

• Y：启用降级模式。
• N：不启用降级模式。

说明：该参数仅在证件采集方式为扫描版（即docUiType为2、3或5）时生效。若在其他采集方式下传入或传入Y/N以外的值，系统将返回参数不合法。

"Y"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

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：不开启

说明：不传该参数、传入null或空字符串均视为无效，系统将返回INVALID_ARGUMENT。

"Y"

needRetry

String

1

是

null

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

• Y：允许重试。当needRetry为Y时，detectOpen必须为Y。
• N：不允许重试。即使needRetry为N，eKYC流程仍可能因人脸质量过低而提示重试。

说明：不传该参数、传入null或空字符串均视为无效，系统将返回INVALID_ARGUMENT。

"Y"

details

List<String>

-

否

null

指定需要返回详细结果的遮挡检测部位。目前仅支持返回occlusionCheck的结果详情，可选值如下：

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

说明：

• 传入details时，detectOpen必须为Y。
• 不传details时，checkresult API仅返回occlusionResult总结果，不返回遮挡部位细项结果。传入具体检测部位时，仅返回所传部位的细项结果。
• details总结果和特定属性结果均会在checkresult API中返回。

[

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

]

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型

OCR一致性检查支持字段

type

String

commonConsistencyCheck

对证件防伪检测中的OCR字段进行一致性检查。

大马卡 / 马来西亚 / 00600000001

• 证件正面：ID_NUMBER
• 证件背面：ID_NUMBER_BACK前12位数字

大陆身份证 / 中国大陆 / 00860000001

• 证件正面：PLACE_OF_PERMANENT
• 证件背面：ISSUE_ORGANIZATION

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型

OCR一致性检查支持字段

type

String

mrzVisualConsistencyCheck

对证件防伪检测中机读区和视读区的OCR字段进行一致性检查。

-

-

details

List<String>

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

在details中指定OCR字段进行一致性检查。

• 当type设置为mrzVisualConsistencyCheck时，必须传入details字段。
• 仅允许传入证件类型所支持的OCR字段。

MyVisa / 马来西亚 / 00600000011

• NAME
• SEX

护照（含机读区和视读区）/ 所有国家或地区 / 00000001006

• ID_NUMBER
• COUNTRY_CODE
• EXPIRY_DATE
• DATE_OF_BIRTH

往来港澳通行证 / 中国大陆 / 00860000011

• ID_NUMBER
• DATE_OF_EXPIRY

字段名称

数据类型

取值范围

描述

支持的证件 / 国家或地区 / 证件类型 / OCR一致性检查支持字段 / 默认国家代码

type

String

passportCountryCheck

检查OCR结果中的COUNTRY_CODE与系统检测到的国家是否一致。

-

valueRange

List<String>

应与默认国家代码一致

OCR结果中的COUNTRY_CODE应在valueRange范围内。

当type设置为passportCountryCheck时，必须传入valueRange字段，各证件支持的valueRange，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。

以下证件的valueRange为证件所属国家或地区对应的默认国家或地区代码所组成的列表。

• 中国大陆护照 / 00860000888 / COUNTRY_CODE / CHN
• 中国台湾护照 / 08860000002 / COUNTRY_CODE / TWN
• 中国澳门护照 / 08530000002 / COUNTRY_CODE / CHN
• 菲律宾旧版护照 / 00630000031 / COUNTRY_CODE / PHL
• 菲律宾新版护照 / 00630000032 / COUNTRY_CODE / PHL

每一项都应符合ISO_3166-1_alpha-3标准

以下证件的valueRange为列表，且每一项都应符合ISO_3166-1_alpha-3标准。

• 国际护照（仅含机读区） / 00000001003 / COUNTRY_CODE
• 国际护照（含机读区和视读区）/ 00000001006 / COUNTRY_CODE

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

riskTypes

List<String>

-

否

["IDFAKE","DUPLICATE"]

待查询的风险类型。支持以下四大类风险，系统会自动查询其包含的子风险，详情参考IdNetwork风险介绍。

• IDFAKE：身份冒用。
• DUPLICATE：重复认证。
• BATCH_REGISTER：批量注册。
• DEEPFAKE：人脸伪造。

[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

     "DEEPFAKE"

   ]

timeWindow

TimeWindow

-

否

TimeWindow

风险查询时间窗口，最长可查询2年内的数据，默认查询最近30天的数据，详情请参见TimeWindow。

注意：系统单次扫描的数据量限制为50万条记录。如果在查询时间窗口范围内数据量超过50万条记录，系统会动态调整您所设置的时间窗口。

{ "startTime":1651882535687, "endTime":1658902665000 }

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

startTime

Long

-

否

当前时间

风险查询起始时间，采用13位时间戳。

1651882535687

endTime

Long

-

否

30天前的时间

风险查询结束时间，采用13位时间戳。

1658902665000

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

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

}

transactionId

String

否

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

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

• 请求参数非法，例如入参格式错误或缺失必传参数。
• 请求未能成功到达服务器，例如网络问题或网关故障。
• 系统限流导致请求被拒绝。

"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。