字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

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

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

"1658905294198"

userId

String

64

否

null

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

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

"e9830710-0d70"

itemId

String

64

否

null

待查询的记录ID，该ID是入库时IDN返回的数据记录ID。

说明：如果传入了itemId字段的值，会自动从库中提取详细数据，不再使用本次imageInfo和basicInfo字段中传入的内容。

"AIN20220707717226249562"

checkAllianceRisk

String

-

否

N

是否查询联盟风险。取值：

• Y：同时查询联盟商户。
• N：仅查询当前商户。

"N"

riskDetection

RiskDetection

-

是

-

待查询的风险，详见RiskDetection。

说明：所查询的风险类型（riskTypes）必须与场景（scene）相匹配，否则会导致API调用失败。

kyc场景（scene=kyc）：

{

   "riskTypes":[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

     "DEEPFAKE"

   ],

   "timeWindow":{

      "startTime":1651882535687,

      "endTime":1658902665000

   }

 }

verification场景（scene=verification）：

{

   "riskTypes": [

       "DUPLICATE_VERIFICATION"

   ],  

   "timeWindow": {

       "startTime": 1651882535687,  

       "endTime": 1658902665000

   }

}

imageInfo

ImageInfo

-

否

null

待查询的图片信息，详见ImageInfo。

说明：

• 目前只支持faceImage字段，docImage字段系统暂不支持。
• 图片格式为Base64编码字符串，且图片大小不超过5MB。

{ "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...", "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

}

basicInfo

BasicInfo

-

否

null

待查询的用户的基本信息，详见BasicInfo。

{

"idType":"00000001003", "idNumber":"46082119870811896X", "certName":"李四", "dateOfBirth":"19870811"

}

scene

String

32

否

kyc

记录所属场景。取值：

• kyc：认证场景。
• verification：身份验证场景。

注意：所查询的风险类型（riskTypes）必须与场景（scene）相匹配。由于kyc和verification场景的数据库各自独立，每种风险类型的数据只能在对应场景的数据库中进行录入或查询。

"kyc"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

riskTypes

List<String>

-

是

-

待查询的风险类型。支持以下五大类风险，系统会自动查询其包含的子风险。

kyc场景：

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

verification场景：

• DUPLICATE_VERIFICATION：照片重复。

kyc场景（scene=kyc）：

[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

     "DEEPFAKE"

   ]

verification场景（scene=verification）：

[

   "DUPLICATE_VERIFICATION"

]

timeWindow

TimeWindow

-

否

最近180天

风险查询时间窗口，最长可查询180天的数据，默认查询最近180天的数据，详见TimeWindow。

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

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

riskThreshold

Integer

-

否

1

指定风险查询的阈值，当历史有关联的风险交易笔数超过指定的阈值时将被拦截。相同的itemId只会计数一次。

支持传入大于等于1的任何整数，默认阈值为1。

1

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

startTime

Long

-

否

null

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

1651882535687

endTime

Long

-

否

null

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

1658902665000

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

docImage

String

-

否

null

待传入的证件图片（暂不支持该字段）。

"eA3AW/6dxn6QAAAABJRU5ErkJggg==..."

faceImage

String

-

否

null

待传入的人脸图片。

"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

idType

String

32

否

null

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

"00000001003"

certName

String

32

否

null

姓名。

"李四"

idNumber

String

32

否

null

证件号码。

"46082119870811896X"

dateOfBirth

String

-

否

null

出生日期，格式为yyyyMMdd。

"19870811"

字段名称

数据类型

描述

示例值

result

Result

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

{

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

transactionId

String

IDN生成的唯一业务ID。

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

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

"G00000000817636816"

hasRisk

Boolean

是否存在风险。

• true：存在风险。
• false：不存在风险。

true

riskDetails

List<RiskDetail>

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

[

   {

       "type": "IDFAKE",  

       "subType": "SameFaceDifferentIdNumber",  

       "riskData": [

           "AIN20220727890199220364"

       ]

   }

]

allianceRiskDetails

List<RiskDetail>

联盟风险详情，详见RiskDetail。

[

   {

       "type": "IDFAKE",  

       "subType": "SameFaceDifferentIdNumber",  

       "riskData": [

           "AIN20220727890976220364"

       ]

   }

]

字段名称

数据类型

描述

示例值

type

String

风险类型。

"IDFAKE"

subType

String

子风险类型。

"SameFaceDifferentIdNumber"

riskData

List<String>

风险数据，内容为itemId数组。

["AIN20220727890199220364"]

riskDataDetails

List<RiskDataDetail>

风险数据详情，详见RiskDataDetail。

[

   {

       "itemId": "AIN20220727890199220364",  

       "faceSimilarScore": "90.0"

   }

]

字段名称

数据类型

必须返回

描述

示例值

itemId

String

否

风险itemId。

"AIN20220727890199220364"

faceSimilarScore

String

否

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

"90.0"