initialize
重要说明：
- 所有请求及返回参数均严格以官网API文档为准。
- API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。
概览
- API URL：POST /api/v1/zoloz/realid/reusable/initialize
- API 描述：Recipient 使用 Donor 提供的一次性
shareToken，初始化 Reusable RealID 身份验证流程。该流程复用 Donor 已授权共享的身份数据，用户本次仅需完成人脸活体采集，无需重新采集证件。
说明：
- 该接口不支持重复调用，不符合幂等性。
shareToken仅可使用一次。初始化成功后，该 Token 将被立即消费并失效，无法再次使用。- 初始化前，请确保 Donor 与 Recipient 之间的 Reusable RealID 合作关系处于生效状态，且 Recipient 已开通 Reusable RealID 能力。
请求参数
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
bizId | String | 32 | 是 | - | 业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。 说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。 | 2026053000001 |
metaInfo | String | 512 | 是 | - | SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。 说明：不要修改返回值，直接传入即可。如果是H5接入模式，则设置为 | MOB_H5 |
flowType | String | 32 | 是 | - | 指定身份验证流的类型。取值：
| REUSABLE_REALIDLITE_KYC |
userId | String | 64 | 是 | - | Recipient 侧的用户 ID 或其他可识别用户的标识。建议对手机号、邮箱等敏感标识进行预脱敏（如哈希处理）。 | u_recipient_88001 |
shareToken | String | 64 | 是 | - | Donor 生成的一次性分享凭证，仅供当前 Recipient 使用。 |
|
acceptedDocTypes | List | 200 | 否 | null | 指定Recipient可接受的证件类型列表，用于筛选Donor证件。该参数可单独使用或与
支持的证件类型，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。 |
|
acceptedDocCategories | List | 50 | 否 | null | 指定Recipient可接受的证件类别，用于筛选Donor证件。该参数可单独使用或与
|
|
acceptedDocCountryCodes | List | 50 | 否 | null | 指定Recipient可接受的Donor证件所属国家或地区列表，支持传入符合ISO 3166-1 alpha-3标准的三位国家码（如 支持以下使用方式：
说明：
|
|
sceneCode | String | 64 | 否 | null | 业务场景码，用于区分不同业务场景的数据表现。 |
|
productConfig | ProductConfig | - | 否 | null | Reusable RealID的人脸活体与风险配置，详见ProductConfig字段说明。 |
|
| PageConfig | - | 否 | null | SDK 页面配置，详见 PageConfig 字段说明。 |
|
| H5ModeConfig | - | H5模式下必填 | - | H5 Reusable RealID 配置。当 |
|
| Map<String, Object> | - | 否 | null | SDK 运行环境参数。当前仅支持 |
|
| String | - | 否 | null | H5 接入模式下的用户设备标识。 |
|
| String | - | 否 | null | H5 接入模式下用户设备的客户端 IP 地址。 |
|
| String | 32 | 否 | null | SDK 无线配置分组，用于为不同业务场景选择对应的 SDK 无线配置。 |
|
证件筛选规则
acceptedDocTypes、acceptedDocCategories、acceptedDocCountryCodes三个维度之间为 AND关系，即 Donor 证件必须同时满足所有传入条件才算匹配。- 每个维度内的多个值为 OR关系（满足任一即可）。
- 不传或传空列表表示该维度不限制。
例如：
acceptedDocTypes=["00000001003"]：只接受护照类型的证件。acceptedDocCategories=["PASSPORT","ID_CARD"]：只接受护照或身份证类别的证件。acceptedDocCountryCodes=["HKG","CHN"]：只接受中国香港或中国大陆签发的证件。acceptedDocCategories=["ID_CARD"]+acceptedDocCountryCodes=["PHL"]：只接受菲律宾的身份证。
注意：若 Donor 证件不满足上述筛选条件，或证件已过期，接口返回 DONOR_DATA_NOT_ACCEPTABLE，且不会消费 shareToken（即 shareToken 仍可继续使用）。
ProductConfig字段说明
Reusable RealID目前仅支持以下与人脸采集、活体检测和风险控制相关的配置。
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
livenessMode | String | 10 | 否 | STANDARD | 人脸活体检测等级。取值：
| STANDARD |
actionCheckItems | List<String> | - | 否 | FACEBLINK | 客户端和Web端的动作检测列表。取值：
说明：
| ["FACEBLINK","HEADLOWER"] |
actionRandom | String | 1 | 否 | N | 客户端和Web端的动作检测顺序是否随机。取值：
| Y |
actionRandomNumber | String | - | 否 | null | 从客户指定的动作列表（ 取值范围： 说明：
| 1 |
actionFrame | List<String> | - | 否 | null | 用于采集其他帧图片。取值：
| ["EYECLOSE"] |
colorFlash | String | - | 否 | N | 是否开启炫彩活体检测功能。取值：
说明：
| Y |
riskMode | String | 10 | 否 | STANDARD | 多维度风控冷却规则校验，用于拦截可疑交易。取值：
| STANDARD |
faceAttributeCheck | FaceAttributeCheck | - | 否 | null | 人脸属性检测配置，详见FaceAttributeCheck字段说明。 说明：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" } } |
cropFaceImage | String | 1 | 否 | N | 是否额外返回一张裁剪出脸部区域的人脸图片。取值：
| Y |
FaceAttributeCheck字段说明
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
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" } |
FaceAttributeDetails字段说明
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
detectOpen | String | 1 | 是 | null | 是否检测人脸属性并在checkresult API中返回检测结果。取值：
| "Y" |
needRetry | String | 1 | 是 | null | 检测到指定属性时是否重试。取值：
| "Y" |
details | List<String> | - | 否 | null | 是否返回人脸属性的结果详情。目前仅支持返回occlusionCheck的结果详情，支持的选项如下：
说明：
| [ "eyesOcclusion", "noseOcclusion", "mouthOcclusion", "foreheadOcclusion", "chinOcclusion", "cheekOcclusion" ] |
PageConfig字段说明
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
urlFaceGuide | String | 256 | 否 | null | 人脸引导页URL。该页面为H5提示页面，可自定义设置，用于引导用户进行人脸扫描。 说明：
| https://example.com/face-guide |
H5ModeConfig字段说明
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
state | String | 128 | 否 | transactionId字段的值 | 用于恢复客户上下文的标识符。您可以为该字段设置任意值，当ZOLOZ SDK回调商户的移动App时会将该值作为参数传递。 | order_2026053000001 |
completeCallbackUrl | String | 128 | 是 | - | 整个身份验证完成后，浏览器重定向的回调 URL。 | https://example.com/complete |
interruptCallbackUrl | String | 128 | 是 | - | 身份验证流程中断后，浏览器重定向的回调 URL。 | https://example.com/interrupt |
locale | String | 16 | 否 | en | 网页语言，目前支持以下语言：
| zh-CN |
isIframe | String | 1 | 否 | N | 是否在iframe中打开网页，如果需要设置为Y，否则设置为N。 | Y |
uiCfg | String | 256 | 否 | null | 自定义UI配置，采用JSON字符串格式。支持以下字段：
| {\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\",\"isDesktop\":\"Y\"} |
allowDegradation | String | 1 | 否 | N | 是否允许进入降级模式。取值：
说明：
| Y |
facePageGuideUrl | String | 128 | 否 | null | 指定降级模式下人脸引导页面的URL。这是一个可定制的H5提示页面，用于引导用户采集自拍人脸图片。 说明：如果不传该参数，则使用默认页面。 | "http://xxx.html" |
返回参数
字段名称 | 数据类型 | 必须返回 | 描述 | 示例值 |
result | 是 | API请求结果，包含结果状态、结果码和结果消息。 | { "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" } | |
transactionId | String | 否 | ZOLOZ 为本次 Reusable RealID 身份验证生成的唯一事务 ID。 说明：仅当交易进入处理阶段后系统才会返回
| G000000005FID2020030400000000000157**** |
clientCfg | String | 否 | 客户端配置信息，包括SDK连接和行为参数。仅当 | …… |
处理结果
根据请求结果执行下一步的响应动作，具体如下：
result.resultStatus为S：初始化成功。使用返回的transactionId和clientCfg启动 Reusable RealID SDK。result.resultStatus为F：初始化失败。请根据resultCode和resultMessage排查原因。
API通用结果码
有关通用结果码的完整列表，请参见API通用结果码。
API特有结果码
Reusable RealID initialize API的结果码见下表。
结果码 | 结果状态 | 描述 |
| S | API 调用成功。 |
| F |
|
| F | Donor 的可共享身份数据不存在或当前不可用。 |
| F | Donor 证件不满足 Recipient 配置的 |
| F | Donor 与 Recipient 之间的 KYC Sharing 合作关系未生效或已暂停。 |
| F | 检测到高风险，用户账号被风险引擎冻结。 |
| F | 用户账号被风险引擎列入黑名单。 |
| F | 不支持当前设备类型。 |
| F | 不支持当前设备的操作系统。 |
| F | 不支持当前 ZOLOZ SDK 版本。 |
| F | 输入参数无效。可能原因包括：缺少必填参数、字段超长或传入了不支持的字段。具体错误信息请查看返回的 |
| F | 系统内部错误。有关错误详情，请查看返回的 |
说明：用户活体检测失败、人脸比对失败或用户取消流程等不属于 initialize API 的结果码，请通过 v1.zoloz.realid.reusable.checkresult 返回的 eKYC 结果判断。
代码示例
请求示例
Native SDK示例：
{
"bizId": "2026053000001",
"metaInfo": "{\"deviceType\":\"android\",\"appVersion\":\"1.0\",\"osVersion\":\"13\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 11\",\"zimVer\":\"2.0.0\",\"appName\":\"com.recipient.wallet\"}",
"flowType": "REUSABLE_REALIDLITE_KYC",
"userId": "u_recipient_88001",
"shareToken": "Ks3LpQa9R7vN2bWxYz8Hf7pK_demo_token_43_chars",
"acceptedDocTypes": [
"00000001003",
"00000001001"
],
"acceptedDocCategories": [
"PASSPORT"
],
"acceptedDocCountryCodes": [
"HKG"
],
"sceneCode": "ONBOARDING_REUSE",
"pageConfig": {
"urlFaceGuide": "https://example.com/face-guide"
},
"productConfig": {
"livenessMode": "STANDARD",
"actionCheckItems": [
"FACEBLINK"
],
"colorFlash": "Y",
"faceAttributeCheck": {
"maskCheck": {
"detectOpen": "Y",
"needRetry": "Y"
}
}
}
}H5示例：
{
"bizId": "2026053000002",
"metaInfo": "MOB_H5",
"flowType": "H5_REUSABLE_REALIDLITE_KYC",
"userId": "u_recipient_88001",
"shareToken": "Ks3LpQa9R7vN2bWxYz8Hf7pK_demo_token_43_chars",
"acceptedDocTypes": [
"00000001003",
"00000001001"
],
"acceptedDocCategories": [
"PASSPORT"
],
"acceptedDocCountryCodes": [
"HKG"
],
"h5ModeConfig": {
"state": "order_2026053000002",
"completeCallbackUrl": "https://example.com/complete",
"interruptCallbackUrl": "https://example.com/interrupt",
"locale": "zh-CN",
"isIframe": "N"
},
"productConfig": {
"livenessMode": "STANDARD",
"actionCheckItems": [
"FACEBLINK"
]
}
}返回示例
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId": "G000000005FRR2026053000001",
"clientCfg": "<base64-encoded SDK config>"
}