Reusable RealID 用于在已建立共享伙伴关系的商户之间复用用户 KYC 数据：提供数据的商户为 Donor（数据提供方），接收并使用数据的商户为 Recipient（数据接收方）。商户可以同时扮演 Donor 和 Recipient 两种角色，形成互为数据提供与接收的关系。

本文面向接入开发人员，介绍接入前的准备工作、接入模式选择、接口调用顺序和关键字段的来源。

接入前准备

在开始接入之前，请确保已满足以下要求：

1. Donor 与 Recipient 之间已建立有效的 KYC 共享合作关系。需提供有效协议作为证明，经确认后由 ZOLOZ 在系统中完成共享伙伴关系配置。
2. Donor 已开通 ShareToken 创建权限。请联系 ZOLOZ 技术支持开通。
3. Recipient 已完成产品购买，并开通 Reusable RealID 权限。
4. Donor 已获取到 Recipient 的 API clientId，用于创建定向 ShareToken。该值通常以 2188 开头，例如 2188499706886568。
5. Donor 已完成一笔成功的标准 RealID 认证，并将认证数据挂载到 Applicant。

能力与权限

Applicant数据隔离说明

• Applicant 按商户进行数据隔离，且在商户中唯一，每个商户只能管理自己名下的 Applicant。
• 其他商户即使获得 applicantId 或 userId，也无权限访问该 Applicant 下的任何数据。
• 复用成功后：

• 若 Recipient 商户下不存在该 userId 对应的 Applicant，系统将自动创建新的 Applicant。
• 若已存在，则本次复用的 KYC 数据将归入已有的 Applicant 下。

• Applicant 由 Recipient 商户独立管理，后续操作（查询、更新、删除等）均由 Recipient 自行控制。

选择接入模式

Recipient 可根据业务场景选择一种接入方式：

Native SDK 和 H5 SDK模式均适用于需要用户参与人脸活体检测的场景（如登录验证、高风险操作确认等）。两种SDK共用同一套API（initialize + checkresult），主要区别在于initialize请求参数中的以下参数值不同：

• flowType 参数的取值不同。
• metaInfo 和 h5ModeConfig 参数的传入方式不同。

完整接入流程

步骤一：Donor准备并授权数据

Donor 需先完成 Applicant 创建、标准 RealID 认证、数据挂载，最后生成 ShareToken 并安全传递给 Recipient。

说明：recipientClientId 是 Recipient 调用 ZOLOZ OpenAPI 时用于鉴权的 API clientId，由 Recipient 提供给 Donor。它不是用户 ID、Applicant ID 或商户自行生成的业务流水号。

步骤二：不同模式的接入方法

Recipient 使用 Native SDK

1. 调用 v1.zoloz.realid.reusable.initialize，传入 ShareToken、Recipient 侧 userId、flowType=REUSABLE_REALIDLITE_KYC，并透传 Native SDK 生成的 metaInfo。
2. 保存响应中的 transactionId，使用响应中的 clientCfg 配置并加载 Native SDK。
3. 用户在 SDK 中完成人脸采集。ZOLOZ 自动进行活体检测和人脸比对。
4. 使用 initialize 返回的 transactionId 调用 v1.zoloz.realid.reusable.checkresult 查询结果。
5. 复用成功后，若 Recipient 商户下不存在该 userId 对应的 Applicant，系统会自动创建；若已存在，则将本次复用的 KYC 数据归入已有的 Applicant 下。Recipient 使用 initialize 请求中传入的 userId 调用 v1.zoloz.applicant.query 查询数据。

Recipient 使用 H5 SDK

1. 调用 v1.zoloz.realid.reusable.initialize，传入 ShareToken、Recipient 侧 userId、flowType=H5_REUSABLE_REALIDLITE_KYC、metaInfo=MOB_H5 和必填的 h5ModeConfig。
2. 保存响应中的 transactionId，使用响应中的 clientCfg 配置并加载 H5 SDK。
3. 用户在 H5 SDK 中完成人脸采集。ZOLOZ 自动进行活体检测和人脸比对。
4. 使用 initialize 返回的 transactionId 调用 v1.zoloz.realid.reusable.checkresult 查询结果。
5. 复用成功后，若 Recipient 商户下不存在该 userId 对应的 Applicant，系统会自动创建；若已存在，则将本次复用的 KYC 数据归入已有的 Applicant 下。Recipient 使用 initialize 请求中传入的 userId 调用 v1.zoloz.applicant.query 查询数据。

获取关键字段

说明：

• 除 checkresult 外，本产品所有 API 响应中均包含本次调用的 transactionId，建议保存用于业务追踪和问题排查。
• 请注意区分以下两个 transactionId：

• attach 请求中的 transactionId 是待挂载的标准 RealID 交易 ID。
• attach 响应中的 transactionId 是本次 attach API 调用返回的交易 ID（用于追踪本次挂载操作）。

ShareToken与数据规则

联调检查清单

在开始联调之前，请逐项确认以下事项：