Reusable RealID enables the reuse of user KYC data between merchants that have established a sharing partnership. The merchant that provides the data is the Donor, and the merchant that receives and uses the data is the Recipient. A merchant can act as both a Donor and a Recipient, forming a mutual data provision and reception relationship.

This document is intended for integration developers. It covers pre-integration preparations, mode selection, API call sequences, and sources of key fields.

Pre-Integration Requirements

Before starting integration, ensure the following requirements are met:

1. An effective KYC sharing partnership must be established between the Donor and the Recipient. A valid agreement is required as proof. Once confirmed, ZOLOZ will configure the partnership in the system.
2. The Donor must have the ShareToken creation permission enabled. Contact ZOLOZ technical support to enable this.
3. The Recipient must have completed product purchase and have the Reusable RealID permission enabled.
4. The Donor must obtain the Recipient's API clientId to create a targeted ShareToken. This value typically starts with 2188 (e.g., 2188499706886568).
5. The Donor must have completed a successful standard RealID verification and attached the verification data to the corresponding Applicant.

Capabilities and Permissions

Applicant Data Isolation

• Applicants are isolated by merchant. Each merchant can only manage Applicants under their own account.
• Other merchants cannot access any data under an Applicant, even if they obtain the applicantId or userId.
• After a successful reuse:

• If no Applicant exists under the Recipient for the given userId, the system automatically creates a new Applicant.
• If an Applicant already exists, the reused KYC data is merged into the existing Applicant.

• The Applicant is independently managed by the Recipient. Subsequent operations (query, update, delete, etc.) are controlled solely by the Recipient.

Choosing an Integration Mode

The Recipient can choose one of the following integration modes based on business scenarios:

Both SDK modes are suitable for scenarios that require user participation in face liveness detection (e.g., login verification, high-risk operation confirmation). Both SDKs share the same set of APIs (initialize + checkresult). The main differences in the initialize request parameters are:

• Different flowType values.
• Different ways of passing the metaInfo and h5ModeConfig parameters.

Complete Integration Flow

Step 1: Donor Prepares and Authorizes Data

The Donor must first create an Applicant, complete standard RealID verification, attach the data, and finally generate a ShareToken and securely deliver it to the Recipient.

Note: The recipientClientId is the API clientId used by the Recipient to authenticate calls to the ZOLOZ OpenAPI. It is provided by the Recipient to the Donor. It is not a user ID, Applicant ID, or a business serial number generated by the merchant.

Step 2: Integration Methods for Different Modes

Recipient Using Native SDK

1. Call v1.zoloz.realid.reusable.initialize with the shareToken, Recipient-side userId, flowType=REUSABLE_REALIDLITE_KYC, and pass through the metaInfo generated by the Native SDK.
2. Save the transactionId from the response. Use the clientCfg from the response to configure and load the Native SDK interface.
3. The user completes face capture in the SDK interface. ZOLOZ automatically performs liveness detection and face matching.
4. Use the transactionId returned from initialize to call v1.zoloz.realid.reusable.checkresult to poll for results.
5. After successful reuse, the system automatically creates a new Applicant if none exists under the Recipient for the userId, or merges the reused KYC data into the existing Applicant if one already exists. The Recipient can then query the data using the userId from the initialize request via v1.zoloz.applicant.query.

Recipient Using H5 SDK

1. Call v1.zoloz.realid.reusable.initialize with the shareToken, Recipient-side userId, flowType=H5_REUSABLE_REALIDLITE_KYC, metaInfo=MOB_H5, and the required h5ModeConfig.
2. Save the transactionId from the response. Use the clientCfg from the response to configure and load the H5 SDK interface.
3. The user completes face capture in the H5 SDK interface. ZOLOZ automatically performs liveness detection and face matching.
4. Use the transactionId returned from initialize to call v1.zoloz.realid.reusable.checkresult to poll for results.
5. After successful reuse, the system automatically creates a new Applicant if none exists under the Recipient for the userId, or merges the reused KYC data into the existing Applicant if one already exists. The Recipient can then query the data using the userId from the initialize request via v1.zoloz.applicant.query.

Key Field Reference

Notes:

• Except for checkresult, all API responses for this product include a transactionId for the call itself. It is recommended to save this for business tracking and issue troubleshooting.
• Do not confuse the two transactionId values:

• The transactionId in the attach request is the standard RealID transaction ID to be attached.
• The transactionId in the attach response is the transaction ID for the attach API call itself (used to track the attach operation).

ShareToken and Data Rules

Integration Checklist

Before starting integration testing, confirm the following items: