checkresult

2026-09-24 03:06

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：POST /api/v1/zoloz/realid/reusable/checkresult
API 描述：该接口用于查询Reusable RealID身份验证流程的运行状态和验证结果。验证成功时返回Donor的证件数据，以及Recipient本次新采集的人脸验证结果。

说明：

该接口为只读查询接口，支持使用同一个transactionId重复调用，即符合幂等性。
当交易状态为InProcess（处理中）时，可根据业务需要继续轮询。
该接口不返回recipientApplicantId。Reusable RealID成功后，系统将异步完成Recipient申请人数据的归户，您可以通过/api/v1/zoloz/applicant/query API查询申请人信息。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	2026053000015
transactionId	String	64	是	-	Reusable RealID交易ID，由`/api/v1/zoloz/realid/reusable/initialize`API返回。	G000000005FRR2026053000001
isReturnImage	String	1	否	N	是否返回Base64编码的证件和人脸图片。取值： `Y`：返回 `N`：不返回	Y

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
ekycResult	String	否	Reusable RealID身份验证状态。仅当`result.resultStatus=S`时返回。 `Success`：身份验证运行成功。 `Failure`：身份验证失败。 `InProcess`：正在身份验证中。 `VoidCancelled`：用户取消了身份验证。 `VoidTimeout`：身份验证超时。	Success
donorClientId	String	否	提供本次复用身份数据的Donor Client ID。仅当`ekycResult=Success`时返回。	donor_alg_hk_001
extBasicInfo	ExtBasicInfo	否	Donor证件的基本实名信息。仅当`ekycResult=Success`时返回。	{ "certType": "00000001003", "certNo": "P1234567" }
extIdInfo	ExtIdInfo	否	Donor证件的详细信息。仅当`ekycResult=Success`时返回。	参考ExtIdInfo字段说明
extFaceInfo	ExtFaceInfo	否	Recipient本次新采集人脸的验证结果。其返回内容随`ekycResult`状态不同而有所差异，具体如下： `Success`：返回完整的`extBasicInfo`、`extIdInfo`、`extFaceInfo`和`donorClientId`。 `Failure`/`VoidTimeout`/`VoidCancelled`：仅在已有采集结果时返回人脸结果。 `InProcess`：不返回任何业务信息，请继续轮询。	参考ExtFaceInfo字段说明

ExtBasicInfo字段说明

说明：当证件采集成功时，才返回certType、certNo和certName字段。

字段名称	数据类型	必须返回	描述	示例值
certType	String	否	Donor证件类型。	00000001003
docCategory	String	否	Donor已有证件数据中的证件类别。该字段为结果信息，而非Reusable initialize API中的筛选参数。 `PASSPORT`：护照 `DRIVING_LICENSE`：驾照 `ID_CARD`：身份证 `RESIDENCE_PERMIT`：居住证 `VISA`：签证	PASSPORT
certNo	String	否	从Donor证件中识别出的证件号码。	P1234567
certName	String	否	从Donor证件中识别出的姓名。	ZHANG SAN
certCountry	String	否	Donor证件的签发国家或地区。	Hong Kong
certCountryCode	String	否	Donor证件的签发国家或地区代码。	HKG

ExtIdInfo字段说明

字段名称	数据类型	必须返回	描述	示例值
ekycResultDoc	String	否	Donor证件模块的验证结果。 `Success`：证件验证成功。 `Failure`：证件验证失败。	Success
ocrResult	Map	否	Donor证件的OCR识别结果。不同证件类型返回的字段不同，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。	{ "ID_NUMBER": "P1234567", "NAME": "ZHANG SAN" }
ocrResultFormat	Map	否	标准化后的OCR输出结果，详见Notification on the Standardization of OCR Output Field Names。	{ "DOCUMENT_NUMBER": "P1234567" }
frontPageImg	String	否	Donor证件正面图片，采用Base64编码格式。仅当`isReturnImage=Y`且存在对应图片时返回。	/9j/4AA..[omitted]..PxA=
backPageImg	String	否	Donor证件背面图片，采用Base64编码格式。仅当`isReturnImage=Y`且存在对应图片时返回。	"/9j/4AA..[omitted]..PxA="

ExtFaceInfo字段说明

字段名称	数据类型	必须返回	描述	示例值
ekycResultFace	String	否	Recipient人脸模块的验证结果。 `Success`：人脸验证成功。 `Failure`：人脸验证失败。	Success
matchResult	String	否	Recipient本次新采集人脸与Donor参考人脸的比对结果。 `Success`：人证脸比对通过。 `Failure`：人证脸比对失败。	Success
faceScore	Integer	否	人脸比对分数，取值范围为0-100。	91
faceQuality	Number	否	人脸图片质量分数，取值范围为0-100。	88.5
faceQualityPassed	Boolean	否	人脸质量检测是否通过。 `true`：检测通过 `false`：检测不通过	true
faceLivenessResult	String	否	人脸活体检测结果。 `Success`：未检测到假脸攻击。 `Failure`：检测到假脸攻击。	Success
faceAttribute	FaceAttribute	否	人脸属性检测结果。例如`maskResult`、`glassesResult`、`occlusionResult`；字段值均为`true`或`false`。仅当Reusable RealID产品的initialize请求中传入`faceAttributeCheck`参数，且`detectOpen`设置为`Y`时返回。	{ "maskResult": "false", "glassesResult": "true", "occlusionResult": "false" }
estimatedAge	Integer	否	根据人脸图片推测的年龄。说明：该字段输出的值仅供参考，ZOLOZ不会根据推测的年龄进行业务判断，如需拦截特定年龄的交易请自行增加校验逻辑。	34
actionCheckItems	List	否	本次人脸采集过程中实际执行的人脸动作检测列表。	["FACEBLINK"]
faceImg	String	否	Recipient本次采集的人脸图片，采用Base64编码格式。仅当`isReturnImage=Y`且存在对应图片时返回。	"/9j/4AA..[omitted]..PxA="

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultCode=SUCCESS时，表示查询成功，请根据ekycResult判断Reusable RealID的业务状态。
当result.resultCode=PROCESSING时，表示交易仍在处理中，可继续轮询。
当result.resultStatus=F时，表示查询失败，请根据resultCode和resultMessage排查具体原因。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

Reusable RealID checkresult API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API 调用成功。
PROCESSING	S	Reusable RealID交易仍在处理中，此时`ekycResult=InProcess`。
INVALID_ARGUMENT	F	输入参数无效。关于无效参数的详细信息，请查看返回的`resultMessage`。
SYSTEM_ERROR	F	其他内部错误。有关错误详情，请查看返回的`resultMessage`。

说明：用户活体检测失败、人脸比对失败、用户取消或流程超时不作为独立API错误码返回，请通过ekycResult、extFaceInfo判断。

代码示例

请求示例

copy
{
    "bizId": "2026053000015", 
    "transactionId": "G000000005FRR2026053000001", 
    "isReturnImage": "Y"
}

返回示例

成功返回示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "ekycResult": "Success", 
    "donorClientId": "donor_alg_hk_001", 
    "extBasicInfo": {
        "certType": "00000001003", 
        "docCategory": "PASSPORT", 
        "certNo": "P1234567", 
        "certName": "ZHANG SAN", 
        "certCountry": "Hong Kong", 
        "certCountryCode": "HKG"
    }, 
    "extIdInfo": {
        "ekycResultDoc": "Success", 
        "ocrResult": {
            "ID_NUMBER": "P1234567", 
            "NAME": "ZHANG SAN"
        }, 
        "ocrResultFormat": {
            "DOCUMENT_NUMBER": "P1234567"
        }, 
        "frontPageImg": "<base64-encoded document image>"
    }, 
    "extFaceInfo": {
        "ekycResultFace": "Success", 
        "matchResult": "Success", 
        "faceScore": 91, 
        "faceQuality": 88.5, 
        "faceQualityPassed": true, 
        "faceLivenessResult": "Success", 
        "faceAttribute": {
            "maskResult": "false", 
            "glassesResult": "true", 
            "occlusionResult": "false"
        }, 
        "actionCheckItems": [
            "FACEBLINK"
        ], 
        "faceImg": "<base64-encoded face image>"
    }
}

处理中示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "PROCESSING", 
        "resultMessage": "It is still under processing"
    }, 
    "ekycResult": "InProcess"
}

失败示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "ekycResult": "Failure", 
    "extFaceInfo": {
        "ekycResultFace": "Failure", 
        "matchResult": "Failure", 
        "faceLivenessResult": "Success"
    }
}