Item

Advanced IDN in RealID

IDN Lite in RealID

Standalone IDN

Scenario

Only supports the KYC scenario.

Only supports the KYC scenario.

Supports both KYC and Verification scenarios.

Risk Detection

Enable IDN risk query function through input parameters.

Automatic Query, disable IDN risk query function through input parameters.

When an extremely high threshold is set for the idnThreshold paremeter, all transactions will no longer trigger the IDN Lite risk interception, effectively disabling this feature.

Requires the client to call the API to query risk based on the data entered in the input parameters.

Initialize API parameters

• checkAdvancedIdn: Specify whether to enable IDN risk check.

  • Y: Enable.

  • N: Disable.

Note: You need to purchase IDN before you can enable this function.

• advancedIdnRiskDetection: Risk detection. Details in RiskDetection. 

Note: This parameter takes effect only when checkAdvancedIdn is set to Y.

• advancedIdnThreshold: Specifies the threshold for IDN risk checks, with a range of 1 to 100. Transactions associated with risky historical transactions exceeding the specified threshold will be blocked. The same itemId will only be counted once.

Note: This parameter takes effect only when checkAdvancedIdn is set to Y.

idnThreshold: Sets the threshold to block transactions for the same merchant when the same face is used with different IDs, or the same ID is used with different faces. If the number of linked transactions across different userIds exceeds the threshold, the system blocks the transaction. Accepts any integer >= 1. Default: 3.

This does not involve Initialize API parameters.

Search Time Window

By default, it queries data from the last 30 days. The risk query time window can be adjusted through input parameters, with a maximum query period of 2 years.

It queries data from the last 30 days. 

By default, it queries data from the last 180 days. The risk query time window can be adjusted through input parameters, with a maximum query period of 2 years.

Supported Data Volume

By default, the maximum data volume for a single scan is 500,000 entries. You can purchase a higher data volume tier.

The maximum data volume for a single scan is 500,000 entries.

By default, the maximum data volume for a single scan is 500,000 entries. You can purchase a higher data volume tier.

Risk Scenarios and Types

Supports all functions in the KYC scenario, including IDFAKE, DUPLICATE, BATCH_REGISTER, DEEPFAKE.

IDFAKE:

• SameFaceDifferentIdNumber

• SameFaceDifferentPerson

• SameIdDifferentFace

• SameIdDifferentPerson

• SamePersonDifferentFace

• SamePersonDifferentIdNumber

DUPLICATE:

• SameFaceDifferentIdType

• SameFaceDifferentUserId

BATCH_REGISTER:

• SameFaceBackgroundDifferentFace

DEEPFAKE:

• SameFaceBackgroundDeepfakeFace

Only support some types of risks.

• IDFAKE:

  • SameFaceDifferentIdNumber

  • SameIdDifferentFace

• DUPLICATE:

  • SameFaceDifferentIdType

Supports all functions in the KYC and Verification scenarios.

• KYC Scenario

  • IDFAKE:

    • SameFaceDifferentIdNumber

    • SameFaceDifferentPerson

    • SameIdDifferentFace

    • SameIdDifferentPerson

    • SamePersonDifferentFace

    • SamePersonDifferentIdNumber

  • DUPLICATE:

    • SameFaceDifferentIdType

    • SameFaceDifferentUserId

  • BATCH_REGISTER:

    • SameFaceBackgroundDifferentFace

  • DEEPFAKE:

    • SameFaceBackgroundDeepfakeFace

• Verification Scenario

  • DUPLICATE_VERIFICATION:

    • SamePhotoSameUserId

Data Source

Data collected through RealID, which is automatically stored in the database.

Data collected through RealID, which is automatically stored in the database.

Data collected through RealID and other external data, all of which require manual entry into the database by calling the add API.

Database Management

Not supported

Not supported

Supports Add, Delete, Retrieve and other operations in the database.

Environments

Base API URIs

ZOLOZ portal address

Wireless Gateway Domain Name

Singapore Sandbox

https://sg-sandbox-api.zoloz.com

https://sg-sandbox-portal.zoloz.com/

https://sg-sandbox-api.zoloz.com

Singapore Production

https://sg-production-api.zoloz.com

https://sg-production-portal.zoloz.com/

https://sg-production-zmgs.zoloz.com

Hong Kong Production

https://hk-production-api.zoloz.net

https://hk-production-portal.zoloz.net/

https://hk-production-zmgs.zoloz.net

Indonesia Production

https://id-production-api.zoloz.com/

https://id-production-portal.zoloz.com/

https://id-production-zmgs.zoloz.com

Environment

Product

WEB SDK URL

Singapore Production/Sandbox

RealId

https://sg-production-cdn.zoloz.com/page/zoloz-realid-fe/index.html

FaceCapture/Connect

https://sg-production-cdn.zoloz.com/page/zoloz-face-fe/index.html

ID Recognition

https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html

Hong Kong Production/Sandbox

RealId

https://hk-production-cdn.zoloz.net/page/realid-fe/index.html

FaceCapture/Connect

https://hk-production-cdn.zoloz.net/page/face-fe/index.html

ID Recognition

https://hk-production-cdn.zoloz.net/page/doc-fe/index.html

Indonesia Production

RealId

https://id-production-cdn.zoloz.com/page/realid-fe/index.html

FaceCapture/Connect

https://id-production-cdn.zoloz.com/page/face-fe/index.html

ID Recognition

https://id-production-cdn.zoloz.com/page/doc-fe/index.html

Note: Not every customer needs to whitelist ZOLOZ domains. However, if your organization requires all external networks to be authorized via whitelisting before access, you must add the ZOLOZ domains to your whitelist.

Collection Requirements

Detailed Description

Correct Example

Incorrect Example

Complete Document in Frame

Make sure that all four corners and edges of the document are within the collection frame.

Clear Document Image

Make sure the document image is clear and legible with no blurry areas.

Adequate Lighting

Make sure adequate lighting in the collection environment to effectively recognize the information on the document. Too bright or too dark environments may affect the verification results.

Avoid Glare

Avoid reflections from lights or ambient light, as glare on the document image can interfere with data processing and extraction.

Avoid Laser Pattern Interference

Avoid laser pattern interference caused by lighting or ambient light. Laser patterns on document images can disrupt data processing and extraction.

No Obstructions

Make sure there are no obstructions on the document, and all information on the document is fully visible.

Avoid Tilt

Make sure the document is perfectly flat both horizontally and vertically, with no tilt.

Moderate Distance

Align the four edges of the document with the scanning frame. Being too far or too close can affect the collection results.

Appropriate Tilt Angle (for multi-angle versions only)

Align the four edges of the document with the tilted scanning frame. The tilt angle should generally not exceed 30 degrees.

Avoid damaged ID

Make sure the portrait on your ID is intact.

Avoid the multiple documents

Make sure that only one document is scanned at a time to avoid multiple documents appearing in the frame.

Document Type

OCR Output Fields

List Display Location on Demo (Example: CHINA)

General ID

None

Universal Identification Documents

FIRST_NAME

LAST_NAME

SEX

FULL_NAME

ISSUING_STATE_CODE

ISSUE_STATE

DATE_OF_EXPIRY

DATE_OF_BIRTH

DATE_OF_ISSUE

ID_NUMBER

DOCUMENT_NUMBER

Scenario

Interrupt callback triggered

Handling method

Network/Device issues

Yes

In this scenario, the ZOLOZ authentication interface will display a popup prompt. The user must click Cancel to trigger the interruptCallbackUrl.

Ensure your business callback URL is pre-configured to promptly detect user interruptions and guide users to re-authenticate or proceed with subsequent workflows, thereby improving business conversion rates.

App force-closed or crashed

No

Implement a validation mechanism in your business process. If a transaction initiated via the initialize API remains unresolved for over 45 minutes without receiving a callback, proactively call the checkResult API to query the transaction status. If the query indicates a timeout, it may be due to the app crash. Instruct users to re-initiate authentication.

Note: Network fluctuations may cause completed transactions to lack callbacks (not classified as app crashes). Always use the checkResult response as the final transaction status reference.

Web page force-closed or crashed

No

User can refresh the page within 30 minutes to resume and continue authentication from the interrupted step using the original transactionId.

If the user does not refresh the page to resume, the client side will not receive a callback. In this scenario, the handling method is identical to "App force-closed or crashed". Please use the checkResult API to query the transaction status and execute the subsequent workflow.

Note: Network fluctuations may cause completed transactions to lack callbacks (not classified as app crashes). Always use the checkResult response as the final transaction status reference.

Field Name

Product

Description

Reference

serviceLevel

Real ID

• Specifies the service level for spoofing checks and face liveness detection.These parameters are pre-configured based on different integration modes, including detection levels, facial actions, and frame collection settings. If you need to customize these configurations, please use the productConfig-related fields.

The supported values for serviceLevel can be found in the serviceLevel.

Real ID API Reference: initialize

Face Capture

• FACECAPTURE0001:
  Without using blink detection, a basic liveness check is performed.
  
  

• FACECAPTURE0002:
  Using blink detection, a middle-level liveness check is performed.
  
  

• FACECAPTURE0003:

     Using 2 random multi-action detection, a

     high-level liveness check is performed.

• Multi-action detection methods include: blinks, opened mouth, head facing upwards, head facing downwards, headshakes (left), headshakes (right).

• FACECAPTURE0005:
  Using blink detection, a full liveness check is performed. This service level also provides the ability to capture closed-eye images for Native SDK.
  
  

• FACECAPTURE0010:

     Using blink detection, a full liveness check is

     performed. This service level also provides the

     ability to capture closed-eye images for the Web

     SDK.

Face Capture API Reference:

initialize

ID Recognition

• IDRECOGNITION0002:
  Default value. Basic spoofing check.
  
  

• IDRECOGNITION0003:
  Flashlight spoofing check for Native SDK.
  
  

• IDRECOGNITION0005:
  Multi-angled spoofing check for Web SDK.
  Note: As of now, this service level only supports HK identity cards. 
  
  
  
  
  

ID Recognition API Reference:
initialize

Comparison Item

SDK Mode

Pure API Mode

Capture Page

ZOLOZ provides a document capture page, allowing users to complete document capture guided by the page. Meanwhile, ZOLOZ continuously optimizes the capabilities and performance of the capture page to ensure user experience.

You need to capture the image by yourself from your users before sending to ZOLOZ.

Streamlined Service

A complete, streamlined service is provided through the collaboration of ZOLOZ server, client, and algorithms.

ZOLOZ focuses on verify the image recieved only, and does not control how you capture the image from users.

API Response Time

The API response time is relatively short, and the response speed is fast.

The initialization and result retrieval stages do not involve time-consuming algorithm processing, which ensures a quick response. Interaction flow details: App SDK-mode integration.

The API response time is relatively long and the response speed is slower.

Each API call sends a request to the server over the network and waits for the server to process and return the response.

In the pure API mode, the image to be verified needs to be passed to the server as a parameter. The server processes the image with algorithms, which is time-consuming, thus increasing the total response time of the API.

Document Anti-counterfeiting Detection Security

Verification capabilities across multiple dimensions can be conducted using the additional data collected through the SDK integration mode, resulting in relatively higher security.

• capture Device Information: Supports collecting user device information, which helps in identifying risks.

• Image Quality Detection: During the capture process, it detects image quality in real-time. Only images that meet quality standards will be successfully collected and proceed to the subsequent anti-counterfeiting verification process, ensuring effective anti-counterfeiting.

• Multi-dimensional Anti-counterfeiting Detection: During the capture process, it uses multiple interactive methods and collects multiple frames of document images, analyzing from various dimensions to effectively identify forged documents and enhance anti-counterfeiting capabilities.

capture capabilities vary by device, with relatively lower security.

• Image Quality Detection: The source of image capture is controlled by the customer, and ZOLOZ cannot control image quality.

• Document Anti-counterfeiting Detection: Only supports basic anti-counterfeiting detection for a single image, with very limited detection capabilities.

Network Environment Limitations

Utilizes asynchronous calls, along with retry mechanisms, local caching, and state management techniques. These provide a more flexible solution in poor network conditions, making it easier for users to obtain results in various network environments.

Utilizes synchronous calls, requiring the server response before proceeding to the next operation. In poor network conditions, this may lead to request timeouts, call failures, or long response times, affecting user experience.

Other Aspects

With the ability for real-time interaction between ZOLOZ algorithm and the user's behavior in the page, users can choose to retake photos as needed, which enhances the user experience to some extent and reduces customer costs.

None

Error

Possible reasons

Solution

SIGNATURE_INVALID

The extracted signature string does not match the to-be-validated content string.

Check ZOLOZ's sample demo for correct configuration: Get API credentials ready for use.

ACCESS_DENIED

The account does not have access rights to this specific API at the present moment.

Only access to the Real ID API is enabled by default. For other product APIs such as ID Recognize and Face Compare, you will have to request for additional access.

Please contact ZOLOZ's technical support to enable access rights for other product APIs to be called.

PRODUCT_QUOTA_LIMIT

The test quota limit for API calls may have been reached.

Please contact ZOLOZ technical staff to handle your case.

You will need to provide sandbox environment information, such as the sg-sandbox environment, the clientID, as well as the email used.

HIGH_RISK

The risk control engine may have been triggered.

To prevent your test activities from being identified as high risk in the sandbox environment, you can flexibly adjust risk control strategies as needed. Here are two methods to achieve this:

Method 1: Use the operationMode parameter in the initialize API or select the corresponding risk level in the Demo App.

• Disable Velocity Feature: Use STANDARD_VC_CLOSED in the initialize API or select 'Standard Risk Level 1' in the Demo App.

• Disable IDN Feature: Use STANDARD_IDN_CLOSED in the initialize API or select 'Standard Risk Level 2' in the Demo App.

• Disable Both Velocity and IDN Features: Use STANDARD_VC_IDN_CLOSED in the initialize API or select 'Standard Risk Level 3' in the Demo App.

Your demo app should look like this:

Method 2: Set the riskMode parameter under productConfig in the initialize API.

• Disable Velocity Feature: Use CLOSED in the initialize API or select 'Close' in the Demo App.

• Use Relaxed Velocity Feature: Use LOOSE in the initialize API or select 'Loose' in the Demo App.

• Use Standard Velocity Feature: Use STANDARD in the initialize API or select 'Standard' in the Demo App.

• Use Strict Velocity Feature: Use STRICT in the initialize API or select 'Strict' in the Demo App.

Here are the definitions for IDN and Velocity:

• IDN: indicates that a fake attack risk is detected through the ID network check. For example, a face is detected associated with multiple IDs, or an ID is detected associated with multiple faces. For more details, see .

• Velocity: indicates that a fake attack risk is detected through the velocity check. For example, the number of attack (e.g. fake ID or liveness attacks) attempts by the same user (identified by userId, ID number or deviceId) in the past period of time reaches a certain threshold, the velocity check will not allow user further submission until the cooldown period has passed.

MERCHANT_NOT_FOUND

Error(s) may have occured regarding the clientID, endpoint/url, ZOLOZ public key, or merchant private key.

Please check that each of the following configurations are correct:

1. Check if the environment is correct: Understand environments and service endpoints.

 ** Note that the portal environment has to be consistent with the endpoint/url environment.

2. Check that the spelling of the clientID is correct.

3. If you are still receiving the error, please check the configuration of the API keys i.e. the ZOLOZ public key or merchant private key.

 ** Note that this misconfiguration would usually result in an INVALID_SIGNATURE error rather than a MERCHANT_NOT_FOUND error.

PARAM_MISSING

The required request parameters are missing.

Please check that you are using the correct request parameter values according to the documentation.

If an optional request parameter has been passed in, the parameter value cannot be empty.

SYSTEM_ERROR

Two possible reasons could have occured:

1. The request parameter value is not supported

2. A system exception has been triggered.

1. Please check if you are using the correct request parameter values according to ZOLOZ API Reference. Optional request parameters cannot have empty string values.

2. If you are still unable to solve this issue, please provide the system error's request and response information to ZOLOZ's technical support.