字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

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

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

"2017839040588699"

transactionId

String

64

是

-

事务ID，由ZOLOZ RealID initialize API的响应消息返回。

"G000000005FID20200304000000000001570702"

isReturnImage

String

1

否

N

是否在响应中返回图片数据。取值如下：

• Y：在响应中返回图片数据。
• N：不在响应中返回图片数据。

"Y"

extraImageControlList

List<String>

-

否

[]

指定需要返回的额外的图片。支持的图片类型如下：

• FACE_EYE_CLOSE：返回闭眼的人脸图片。
• DOC_FRONT_ANGLE：返回从倾斜角度拍摄的证件首页图片。
• DOC_FRONT_FLASH：返回在闪光灯照射下拍摄的证件首页图片。
• DOC_BACK_ANGLE：返回从倾斜角度拍摄的证件背面图片。
• DOC_BACK_FLASH：返回在闪光灯照射下拍摄的证件背面图片。
• CROPPED_FACE：返回裁剪后的人脸图片。

注意：

• 当isReturnImage为Y时，该参数才生效。
• 是否返回额外的图片还取决于这些图片是否已被成功采集，这由集成模式和初始化API中设置的serviceLevel的值决定。
  例如，集成模式为原生App SDK，serviceLevel的值为REALID0002，此时会返回在闪光灯照射下拍摄的证件首页图片。

[ "FACE_EYE_CLOSE", "DOC_FRONT_ANGLE" ]

returnFiveCategorySpoofResult

String

1

否

N

是否返回五类证件防伪检测结果。取值如下：

• Y：证件防伪检测结果将分五类返回，包括：

• TAMPER_CHECK
• MATERIAL_CHECK
• SCREEN_RECAPTURE_CHECK
• INFORMATION_CHECK
• SECURITY_FEATURE_CHECK

• N：证件防伪检测结果将分四类返回，包括：

• TAMPER_CHECK
• MATERIAL_CHECK
• SCREEN_RECAPTURE_CHECK
• OTHER_CHECK

"Y"

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

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

}

ekycResult

String

否

标识整个身份验证进程的运行状态。取值如下：

• Success：身份验证运行成功。
• Pending：身份验证结果待人工确认。
• Failure：身份验证失败，可能是证件验证、人脸验证或风控处理失败导致。
• InProcess：正在身份验证中。
• VoidCancelled：用户取消了身份验证。
• VoidTimeout：身份验证超时。

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

"Pending"

extBasicInfo

ExtBasicInfo

否

基本实名信息。详细信息，请参见ExtBasicInfo。

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

{

"certType": "08530000001", "certNo": "A12345678", "certName": "xxxxxx" }

extFaceInfo

ExtFaceInfo

否

eKYC申请中人脸验证的详细信息。详细信息，请参见ExtFaceInfo。

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

{ "ekycResultFace": "Success", "faceScore": 88, "faceImg": "/9j/4AA..[omitted]..PxA=", "extraImages": { "FACE_EYE_CLOSE": "/9j/4AA..[omitted]..PxA=" }, "faceQuality": 97.61517973846627, "faceLivenessResult": "Success" }

extIdInfo

ExtIdInfo

否

eKYC申请中证件验证的详细信息。详细信息，请参见ExtIdInfo。

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

参考返回示例

extRiskInfo

ExtRiskInfo

否

eKYC申请中风险控制的详细信息。详细信息，请参见ExtRiskInfo。

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

{ "ekycResultRisk": "Pending", "strategyPassResult": "ID_NETWORK_HIGH_RISK", "idNetworkDetails": "..." }

extCustomInfo

ExtCustomInfo

否

eKYC申请中关于定制信息的详情。详细信息，请参见ExtCustomInfo。

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

{"h5Degraded":"Y"}

字段名称

数据类型

必须返回

描述

示例值

certType

String

否

证件类型。

"00860000001"

certNo

String

否

证件号码，即从身份证件中识别到的证件号码。

"420502198012345000"

certName

String

否

姓名，即从身份证件中识别到的姓名。

"李四"

字段名称

数据类型

必须返回

描述

示例值

ekycResultFace

String

否

人脸模块的验证结果。

• Success：人脸验证成功。
• Pending：人脸验证结果待人工确认。
• Failure：人脸验证失败。

"Success"

faceScore

Integer

否

人脸比对分数，取值范围0-100。该分数是将活体人脸与证件脸进行比对得出的结果。

88

faceImg

String

否

返回的人脸图片，采用Base64编码格式。

说明：当isReturnImage的值为Y，且人脸采集成功时才返回该字段。

"/9j/4AA..[omitted]..PxA="

extraImages

Map<String,String>

否

在extraImageControlList中指定的额外需要返回的人脸图片。

• Key是在extraImageControlList中指定的值。
• Value是以Base64编码的图片内容。如果未找到请求的图片，则该值为“”。

{ "FACE_EYE_CLOSE": "/9j/4AA..[omitted]..PxA=" }

faceQuality

Double

否

人脸图片的质量分数，取值范围0-100。

97.61517973846627

faceLivenessResult

String

-

人脸活体检测结果。使用人脸活体检测算法检测人脸图片是否为假脸攻击。

• Success：非假脸攻击。
• Failure：假脸攻击。

"Success"

estimatedAge

Integer

否

根据人脸图片推测出来的年龄，推测年龄和实际年龄的差值小于等于10岁的准确率为95%。

说明：该字段输出的值仅供参考，ZOLOZ不会根据推测的年龄进行业务判断，如需拦截特定年龄的交易请自行增加校验逻辑。

34

faceAttribute

FaceAttribute

否

人脸属性检测结果，详情请参见FaceAttribute。

说明：当在RealID initialize API中传入faceAttributeCheck参数且detectOpen为Y时，才返回该字段。

{

     "occlusionMouthResult": "false",

     "occlusionForeheadResult": "false",

     "occlusionResult": "false",

     "occlusionChinResult": "false",

     "occlusionEyesResult": "false",

     "occlusionNoseResult": "false",

     "occlusionCheekResult": "false",

     "maskResult": "false",

     "glassesResult": "true",

     "hatResult": "false"

   }

deeperFaceResult

String

否

返回的Deeper人脸检测结果。当deeperMode不设置为CLOSED时才返回该参数，具体返回的参数值如下：

• Success：Deeper人脸检测通过，未检测到AIGC攻击风险。
• Failure：Deeper人脸检测失败，检测到有AIGC攻击风险。

"Success"

deeperFaceResultDescription

String

否

Deeper人脸检测结果的详细描述，当deeperMode不设置为CLOSED，且deeperFaceResult为Failure时才返回该参数。

""

deviceRisk

DeviceRisk

否

返回的设备风险信息。当您购买了Deeper产品，且initialize API中的deeperMode不为CLOSED时，才返回该字段，详见DeviceRisk。

{

"riskLevel": 0

}

字段名称

数据类型

必须返回

描述

示例值

occlusionMouthResult

String

否

嘴巴遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionForeheadResult

String

否

额头遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionResult

String

否

遮挡检测总结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionChinResult

String

否

下巴遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionEyesResult

String

否

眼睛遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionNoseResult

String

否

鼻子遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

occlusionCheekResult

String

否

脸颊遮挡检测结果。

• true：有遮挡
• false：无遮挡

"false"

maskResult

String

否

口罩检测结果。

• true：有口罩
• false：无口罩

"false"

glassesResult

String

否

眼镜检测结果。

• true：有眼镜
• false：无眼镜

"true"

hatResult

String

否

帽子检测结果。

• true：有帽子
• false：无帽子

"false"

字段名称

数据类型

必须返回

描述

示例值

riskLevel

Integer

否

风险等级及对应的处理建议如下：

• -1：无法识别人脸注入风险。建议您基于其他情况进行进一步判断。
  说明：新加坡站点暂不支持该能力，riskLevel将返回-1。

• 0：无风险，未检测到人脸注入风险。建议继续进行。
• 1：低风险。建议标记和观察。
• 2：中风险。建议添加安全检查方法，例如短信验证等。
• 3：高风险，建议直接拦截。

0

字段名称

数据类型

必须返回

描述

示例值

ekycResultDoc

String

否

证件模块的验证结果。当证件采集成功时，才返回该字段。

• Success：证件验证成功。
• Pending：证件验证结果待人工确认。
• Failure：证件验证失败。

"Pending"

docEdition

Integer

否

身份证件的版本。

• 1~3：身份证件的版本，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。
• 0：无法对身份证件进行分类或证件类型错误。
• -1：未知错误。

1

frontPageImg

String

否

身份证件的正面照，采用Base64编码格式。

说明：当isReturnImage的值为Y，且证件采集成功时才返回该字段。

"/9j/4AA..[omitted]..PxA="

backPageImg

String

否

身份证件的背面照（如果有），采用Base64编码格式。

说明：当isReturnImage的值为Y，证件采集成功且需要上传身份证件的背面照时，才返回该字段。

"/9j/4AA..[omitted]..PxA="

extraImages

Map<String,String>

否

在extraImageControlList中指定的额外需要返回的图片。

• Key是在extraImageControlList中指定的值。
• Value是以Base64编码的图片内容。如果未找到请求的图片，则该值为“”。

如果cropDocImage为Y，则结果中还会包含以下两个字段：

• CROPPED_FRONT：经过背景裁剪的证件正面图片。
• CROPPED_BACK：经过背景裁剪的证件背面图片。

{ "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=", "CROPPED_FRONT": "/9j/4AA..[omitted]..PxA=", "CROPPED_BACK": "/9j/4AA..[omitted]..PxA=" }

ocrResult

Map

否

OCR识别结果，结果中包含身份相关的信息。

不同的身份证件类型识别出来的身份信息集不同，详细请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。

说明：当证件采集成功时，才返回该字段。

{ ... }

ocrResultDetail

Map<String, OcrResultDetail>

否

OCR识别结果详情，当在initialize API中传入mrzVisualConsistencyCheck时才返回该字段。

参考返回示例

spoofResult

Map

否

证件防伪分项检测结果，包含篡改、材质和屏幕翻拍等检测结果。详细信息，请参见spoofResult。

{ "TAMPER_CHECK": "Y", "MATERIAL_CHECK": "Y", "SCREEN_RECAPTURE_CHECK": "Y", "INFORMATION_CHECK": "Y", "SECURITY_FEATURE_CHECK":,"Y" }

extraSpoofResultDetails

List<ExtraSpoofResultDetail>

否

扩展证件防伪检测细项结果。详细信息，请参见ExtraSpoofResultDetail。

[{

"name": "hologramCheck", "result": "Y", "spoofType": "SECURITY_FEATURE_CHECK", "components": [ { "name": "hologram", "subResult": "Y" } ] }]

securityFeaturesResult

Map

否

该参数已废弃，详见香港证件安全功能升级通知—2024年7月31日。

{ "LASER_IMAGE_1_SCORE":95, "LASER_IMAGE_1_THRESHOLD":90, "LASER_IMAGE_1_PASSED":"True", "HOLOGRAM_SCORE":95, "HOLOGRAM_THRESHOLD":90, "HOLOGRAM_PASSED":"True", "STEREO_LASER_PORTRAIT_SCORE":95, "STEREO_LASER_PORTRAIT_THRESHOLD":90, "STEREO_LASER_PORTRAIT_PASSED":"True", "LASER_IMAGE_2_SCORE":95, "LASER_IMAGE_2_THRESHOLD":90, "LASER_IMAGE_2_PASSED":"True", "OVERALL_SCORE":95, "OVERALL_THRESHOLD":90, "OVERALL_PASSED":"True" }

docErrorDetails

String

否

证件识别不通过明细。

• NO_REQUIRED_ID：证件图片不符合指定的证件类型。
• BLUR：证件图片模糊。
• NO_FACE_DETECTED：未检测到证件上的人脸。
• NOT_REAL_DOC：证件防伪检测不通过。
• EXPOSURE：证件图片过度曝光。
• UNKNOWN：其他错误。

"BLUR"

docErrorDescription

String

否

证件识别失败的原因。

""

字段名称

数据类型

必须返回

描述

示例值

TAMPER_CHECK

String

是

身份证件是否通过了篡改检测。

• Y：通过，即检测结果为未被篡改。
• N：不通过，即检测结果为被篡改。

"Y"

MATERIAL_CHECK

String

是

身份证件是否通过了材质检测。

• Y：通过。
• N：不通过，例如检测结果为黑白材质。

"Y"

SCREEN_RECAPTURE_CHECK

String

是

身份证件是否通过了屏幕翻拍检测。

• Y：通过。
• N：不通过，即上传的图片被检测为从屏幕上翻拍的图片。

"Y"

INFORMATION_CHECK

String

否

身份证件是否通过了信息校验检测。目前仅支持中国香港身份证（包括2003版和2018版）。

• Y：通过。
• N：不通过。

说明：当returnFiveCategorySpoofResult的值为Y时，才返回该字段。

"Y"

SECURITY_FEATURE_CHECK

String

否

身份证件是否通过了防伪安全特征检测。目前仅支持中国香港身份证（包括2003版和2018版）和大马卡。

• Y：通过。
• N：不通过。

说明：当returnFiveCategorySpoofResult的值为Y时，才返回该字段。

"Y"

字段名称

数据类型

必须返回

描述

示例值

name

String

是

扩展证件防伪检测名称。

"landmarkCheck"

result

String

是

扩展证件防伪检测结果。

• Y：检测通过。
• N：检测失败。

"Y"

spoofType

String

是

扩展证件防伪检测所属的分项类别。

• TAMPER_CHECK
• MATERIAL_CHECK
• SCREEN_RECAPTURE_CHECK
• INFORMATION_CHECK
• SECURITY_FEATURE_CHECK

"SECURITY_FEATURE_CHECK"

components

Array

是

扩展证件防伪检测细项的检查结果。该字段一定会被返回。如果只指定了一个细项检查，则数组将只返回一个元素。

[ { "name": "hologram", "subResult": "Y" } ]

components.name

String

是

扩展证件防伪检测细项的检查名称。详细信息，请参见证件防伪检测组件。

"kadPengenalan"

components.subResult

String

是

扩展证件防伪检测单个检测细项的检查结果。

• Y：检查通过。
• N：检查失败。

"Y"

字段名称

数据类型

必须返回

描述

示例值

ekycResultRisk

String

-

风控模块的验证结果。

• Success：风险控制验证通过。
• Pending：风险控制结果待人工确认。
• Failure：风险控制验证失败。

"Pending"

strategyPassResult

String

否

风险检测结果。当风控执行完成时，才返回该字段。

• PASS：身份验证通过了风险检测。
• VELOCITY_HIGH_RISK：风控引擎检测到高风险。
• ID_NETWORK_HIGH_RISK：通过IdNetwork检测到虚假验证风险。例如，检测到识别出的人脸与多个身份证件相关或检测到一个身份证件与多张人脸相关。
  说明：同一用户或同一证件号检测出相同的人脸不会触发该风险。
• BLACKLIST_HIGH_RISK：黑名单扫描检测到高风险。
• AGE_MISMATCH_HIGH_RISK：在年龄验证过程中检测到高风险。

"ID_NETWORK_HIGH_RISK"

idNetworkDetails

String

否

IdNetwork输出的详细信息，该字段是一段JSON字符串，来自于IdNetworkDetails结构的JSON序列化结果，详见IdNetworkDetails结构。

说明：当strategyPassResult的值为ID_NETWORK_HIGH_RISK时，才返回该字段。

"[

{

\"ekyc_id\":\"\",

\"mobile\":\"\",

\"reason_code\":[

\"SIMILAR_FACE\"

],

\"transaction_id\":\"G000000000FRL20231110000000035925247043\",

\"type\":\"Fake ID\",

\"user_id\":\"idn-z8Cuj\"

},

{

\"reason_code\":\"[SIMILAR_FACE]\",

\"score\":\"0.996945100506912\",

\"user_id\":\"0ha6_1692349732313\",

\"mobile\":\"\",

\"ekyc_id\":\"\",

\"type\":\"Duplicated ID\"

}

]"

otherRiskReasonDetails

String

否

除了IdNetwork之外的风险引擎的详细信息。例如在黑名单命中的情况下，该字段的结构如右侧所示。

{

"BLACKLIST_HIGH_RISK": {

"CERT": [

{"listId":"xx","transactionId":"xx","itemId":xx,"similarScore":xx}

],

"FACE":[

{"listId":"xx","transactionId":"xx","itemId":"xx","similarScore":xx}]}

}

deeperRiskResult

String

否

返回的Deeper风险检测结果。当deeperMode不设置为CLOSED时才返回该参数，具体返回的参数值如下：

• Success：Deeper风险检测通过，未检测到AIGC攻击风险。
• Failure：Deeper风险检测失败，检测到有AIGC攻击风险。

"Success"

deeperRiskResultDescription

String

否

Deeper风险检测结果的详细描述，当deeperMode不设置为CLOSED，且deeperRiskResult为Failure时才返回该参数。

""

advancedIdnDetail

AdvancedIdnDetail

否

Advanced IDN结果详情，详见AdvancedIdnDetail。

说明：仅当购买了Advanced IDN，且initialize API的入参checkAdvancedIdn为Y时，才返回该参数。

{

   "itemId": "AIN20220727890204890950",

   "riskDetails": [

       {

           "type": "IDFAKE",

           "subType": "SameFaceDifferentIdNumber",

           "riskData": [

               "AIN20220727890199220364"

           ]

       }

   ]

}

blackListDetails

List<BlackListDetail>

否

黑名单输出的详细信息，详见BlackListDetail。

说明：仅当购买了黑名单功能，且initialize API的入参checkBlacklist为Y时，才返回该参数。

[

   {

       "listId": "10064",

       "itemId": "95c0e4e55d5cd5485edaa573d15e82**",

       "itemType": "FACE",

       "similarScore": 99.99999999999999,

       "transactionId": "G000000001FRL202410100000000109481109**"

   },

   {

       "listId": "10066",

       "itemId": "20015",

       "itemType": "CERT",

       "similarScore": 100

   }

]

字段名称

数据类型

必须返回

描述

示例值

ekyc_id

String

否

eKYC ID，该字段已废弃。

-

mobile

String

否

手机号，该字段已废弃。

-

reason_code

Array

否

触发风险的原因。更多关于Reason Code的描述，请参见RealID IDN Lite风险类型介绍。

• SIMILAR_FACE：从不同用户中检测出相似的人脸。
  说明：同一用户且人脸相同不会触发该风险。
• SAME_CERT_NO：一个证件号被多个用户使用。
  

["SIMILAR_FACE","SAME_CERT_NO"]

type

String

否

触发的风险类型：

• Duplicated ID：同一个人多次认证。
• Fake ID：篡改证件信息。

"Fake ID"

score

String

否

保留字段，请勿依赖该字段。

说明：当type为Duplicated ID时才返回该字段。

"0.996945100506912"

user_id

String

否

用户ID

"idn-z8Cuj"

风险类型

Reason Code

说明

Fake ID

SIMILAR_FACE

相同的人脸，不同证件号（证件类型相同）。

SAME_CERT_NO

不同的人脸，相同证件号（证件类型相同）。

Duplicated ID

SIMILAR_FACE

相同的人脸，不同证件类型。

字段名称

数据类型

必须返回

描述

示例值

itemId

String

否

添加到ID Network数据库的记录ID。请妥善保存该记录ID，用于后续风险查询。

"AIN20220727890204890950"

riskDetails

List<RiskDetail>

否

当前商户存在的风险详情，详见RiskDetail。

[
{
"type": "IDFAKE",
"subType": "SameFaceDifferentIdNumber",
"riskData": [
"AIN20220727890199220364"
]
}
]

字段名称

数据类型

描述

示例值

type

String

返回的风险类型，详情参考IdNetwork风险介绍。

"IDFAKE"

subType

String

返回的子风险类型，详情参考IdNetwork风险介绍。

"SameFaceDifferentIdNumber"

riskData

List<String>

返回的风险数据，内容为itemId数组。

["AIN20220727890199220364"]

字段名称

数据类型

必须返回

描述

示例值

listId

String

否

目标黑名单的名单ID。

"10064"

itemId

String

否

黑名单记录ID。

"95c0e4e55d5cd5485edaa573d15e82**"

itemType

String

否

黑名单记录的类型，包括三种类型：

• FACE：人脸黑名单。
• CERT：证件黑名单，黑名单条目由证件类型和证件号标识。
• DEVICE：设备黑名单。

"FACE"

similarScore

String

否

相似分，分值越高相似度越高。

99.99999999999999

transactionId

String

否

黑名单记录的来源，是由客户通过eKYC的transactionId自行录入的黑名单信息。

"G000000001FRL202410100000000109481109**"

字段名称

数据类型

必须返回

描述

示例值

h5degraded

String

否

是否采用了降级模式。

• Y：已采用降级模式。
• N：未采用降级模式。

说明：当RealID initialize API中的allowDegradation参数为Y时，才返回该字段。

"Y"

结果码

结果状态

描述

SUCCESS

S

API调用成功。

INVALID_ARGUMENT

F

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

SYSTEM_ERROR

F

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