字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

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时，才返回该字段。

{ "ekycResultDoc": "Pending", "docEdition": 1, "frontPageImg": "/9j/4AA..[omitted]..PxA=", "backPageImg": "/9j/4AA..[omitted]..PxA=", "extraImages": { "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=", "CROPPED_FRONT": "/9j/4AA..[omitted]..PxA=", "CROPPED_BACK": "/9j/4AA..[omitted]..PxA=" }, "ocrResult": { ... }, "spoofResult": { "TAMPER_CHECK": "Y", "MATERIAL_CHECK": "Y", "SCREEN_RECAPTURE_CHECK": "Y", "INFORMATION_CHECK": "Y", "SECURITY_FEATURE_CHECK":,"Y" }, "extraSpoofResultDetails": [ { "name": "landmarkCheck", "result": "Y", "spoofType": "SECURITY_FEATURE_CHECK", "components": [ { "name": "kadPengenalan", "subResult": "Y" }, { "name": "mykadLogo", "subResult": "Y" }, { "name": "flagLogo", "subResult": "Y" }, { "name": "mscLogo", "subResult": "Y" }, { "name": "ghostFace", "subResult": "Y" }, { "name": "hibiscusLogo", "subResult": "Y" }, { "name": "coatOfArm", "subResult": "Y" }, { "name": "twinTower", "subResult": "Y" } ] }, { "name": "hologramCheck", "result": "Y", "spoofType": "SECURITY_FEATURE_CHECK", "components": [ { "name": "hologram", "subResult": "Y" } ] }, { "name": "pageInfoCheck", "result": "Y", "spoofType": "INFORMATION_CHECK", "components": [ { "name": "id", "subResult": "Y" }, { "name": "symbol", "subResult": "Y" }, { "name": "name", "subResult": "Y" } ] } ], "securityFeaturesResult": { "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": "BLUR" }

extRiskInfo

ExtRiskInfo

否

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

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

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

字段名称

数据类型

必须返回

描述

示例值

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"

   }

字段名称

数据类型

必须返回

描述

示例值

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"

字段名称

数据类型

必须返回

描述

示例值

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结果。

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

{ ... }

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

否

防伪安全特征检测结果，例如身份证件上的激光图像。根据身份证件的类型，检测身份证件中不同的安全特征。详细信息，请参见securityFeaturesResult。

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

字段名称

数据类型

必须返回

描述

示例值

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"

身份证件

证件类型

安全特征示例

字段及字段值示例

中国香港身份证2003版

08520000001

图1. 中国香港身份证2003版示例图片

如图1所示，中国香港身份证2003版是通过Optical variable ink（光学可变油墨）、Multiple laser image（多重激光图像）和Kineprint来检测其安全特征。

以下列表显示了每个安全特征和总体检测结果的字段和示例值。

1. Optical variable ink（光学可变油墨）

• OPTICAL_VARIABLE_INK_SCORE：70
• OPTICAL_VARIABLE_INK_THRESHOLD：60
• OPTICAL_VARIABLE_INK_PASSED：True

2. Multiple laser image（多重激光图像）

• MULTIPLE_LASER_IMAGE_SCORE：95
• MULTIPLE_LASER_IMAGE_THRESHOLD：90
• MULTIPLE_LASER_IMAGE_PASSED：True

3. Kineprint

• KINEPRINT_SCORE：85
• KINEPRINT_THRESHOLD：77
• KINEPRINT_PASSED：True

综上可得出以下结果：

• OVERALL_SCORE：95
• OVERALL_THRESHOLD：90
• OVERALL_PASSED：True

中国香港身份证2018版

08520000002

图2. 中国香港身份证2018版示例图片

如图2所示，中国香港身份证2018版是通过Laser image1（激光图像1）、Hologram（全息图）、Stereo laser portrait（立体激光人像）和Laser image2（激光图像2）来检测其安全特征。

以下列表显示了每个安全特征和总体检测结果的字段和示例值。

1. Laser image1（激光图像1）

• LASER_IMAGE_1_SCORE
• LASER_IMAGE_1_THRESHOLD
• LASER_IMAGE_1_PASSED

2. Hologram（全息图）

• HOLOGRAM_SCORE
• HOLOGRAM_THRESHOLD
• HOLOGRAM_PASSED

3. Stereo laser portrait（立体激光人像）

• STEREO_LASER_PORTRAIT_SCORE
• STEREO_LASER_PORTRAIT_THRESHOLD
• STEREO_LASER_PORTRAIT_PASSED

4. Laser image2（激光图像2）

• LASER_IMAGE_2_SCORE
• LASER_IMAGE_2_THRESHOLD
• LASER_IMAGE_2_PASSED

综上可得出以下结果：

• OVERALL_SCORE
• OVERALL_THRESHOLD
• OVERALL_PASSED

字段名称

数据类型

必须返回

描述

示例值

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}]}

}

字段名称

数据类型

必须返回

描述

示例值

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

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

结果码

结果状态

描述

SUCCESS

S

API调用成功。

INVALID_ARGUMENT

F

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

SYSTEM_ERROR

F

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