ZOLOZZOLOZDOCS

ZOLOZ eKYC SaaS FAQs

Here is the list of relevant FAQs for ZOLOZ eKYC SaaS products.

General

What document types are currently supported by Real ID?

To see the list of documents supported by Real ID, please refer to Document types supported and OCR results returned.

What are the differences between IDN in RealID and standalone IDN?

In RealID, the IDN can be enabled or disabled through input parameters, with capabilities for automatic data entry and risk detection. The standalone IDN requires clients to manually enter data and actively call the API for risk queries.

For all functions of IDN, please refer to IDN API Documentation.

RealID IDN and IDN API differ in the following aspects:

Item

RealID IDN

Standalone IDN

Scenario

Only supports the KYC scenario in IDN.

Supports both KYC and Verification scenarios.

Risk Detection

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

Requires the client to call the API to query risk based on the data entered in the input 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 180 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 180 days.

Supported Data Volume

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

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

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

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 and other external data, all of which require manual entry into the database by calling the add API.

Database Management

Not supported

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

To integrate the ZOLOZ service, which domain names need to be added to the whitelist so as not to affect normal access to the local environment?

ZOLOZ provides separate sandbox and production environments. You can choose different environment as required. The sandbox environment is meant for integration and testing purposes, while the production environment is meant for live operation.

For different environments, ZOLOZ portal website, wireless gateway domain name, basic API URI and Web SDK URL provide different service endpoints.

Please refer to the following table for detailed information on the supported ZOLOZ portal website, wireless gateway domain name, and basic API URI:

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

Note：

  • If customers use the SDK provided by ZOLOZ during front-end or client development, they do not need to configure the network environment.
  • When the customer initiates a request to ZOLOZ from the server, it is necessary to ensure that the environment-related configuration parameters are configured correctly.

ZOLOZ Web SDK url is specific to the product. In the same environment, different products have different Web SDK urls.

For detailed information on supported Web SDK URLs, please refer to the table below:

Note: It is not imperative for every customer to be included in a whitelist for accessing the ZOLOZ service. However, if your organization subscribes to rigorous network security standards, demanding that every external network be authorized via whitelisting prior to gaining entry into your company's designated network(s), then it becomes essential to enlist the respective ZOLOZ domains within your whitelist framework.

Which types of data can be deleted specifically through privacy deletion?

  • OCR information - document ID, name, etc.
  • Collected identity document and face photo data, including the returned face image (faceImg), additional images to be returned (extraImages), the front side image of the identity document (frontPageImg), and the back side image of the identity document (backPageImg), etc.

As a result, IDN lite related data will be deleted and IDN lite will not be able to reprocess or access any data that has been privacy deleted.

What are the requirements for document image collection?

ZOLOZ has certain requirements for the size and quality of collected document images. Adhering to these requirements can effectively improve the success rate of document image collection.

Collection Requirements

Detailed Description

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.

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.

eKYC Result interpretation

What are the reasons for receiving a 'Pending' result on Real ID?

A 'Pending' result is the result given by Real ID when it detects that the current transaction has potential risks.

The possible reasons for receiving a 'Pending' result are as follows:

  • A fake ID has been detected
  • The selfie face captured does not match the ID photo
  • A risk check failure has occurred

Note that if your ZOLOZ product has been tailored to your specific needs, other reasons may exist. Please contact ZOLOZ's technical support to find out more.

Is the Real ID 'Pending' result the final response given by Real ID?

Yes, it is. Real ID responds by giving either 'Success', 'Pending' or 'Failure' as the final result.

What can I do to manage the 'Pending' result on my end?

You are encouraged to review the application manually and then decide if the transaction should pass or not. If you encounter any issues during your review, please contact ZOLOZ's technical support.

Why is the return value of Risk Control Result in Real ID empty?

When the return value of Risk Control Result is empty, it indicates that risk control policy module is not triggered, which may come from the following reasons:

  • Document verification or face verification failed;
  • Initialization failed;
  • User cancelled identity verification.

Why are transactions flagged as 'Pending' instead of 'Failure' when they fail anti-counterfeiting detection?

Transactions flagged as 'Pending' due to anti-counterfeiting detection failures are not immediately marked as 'Failure'. Directly marking them as 'Failure' could lead to legitimate transactions being wrongly intercepted, as there might be a certain rate of false positives in anti-counterfeiting detection. For example, inadequate lighting or partially blurred document information can make it challenging for the system to make accurate judgments. Therefore, transactions are marked as 'Pending' to allow for manual review. This further verification ensures the accuracy of the decision, protecting customers' interests by minimizing the false positive rate.

ZOLOZ SDK & API Usage

How to Update ZOLOZ SDK?

To update the ZOLOZ SDK on your platform, you can follow these general guidelines, adapted to the specific SDK you are using:

  1. Android SDK Update
  • Open the Gradle Configuration File: Navigate to the app/build.gradle file within your Android project (refer to the Android Integration).
  • Update the Dependency: Find the line that includes the ZOLOZ SDK and update it with the new version number. For example:
copy
implementation 'com.zoloz.android.build:zolozkit:latest-version'

Note: Replace "latest-version" with the actual version number you wish to update to. It's recommended that you use the latest version of the SDK to improve product experience and security. For version release notes, please refer to Release Notes.

  • Sync the Project: After editing the build.gradle file, you need to sync your project to update the Gradle file.
  1. iOS SDK Update
  • Configure the SDK dependency
    • Configure the private spec in Podfile:
copy
source "https://github.com/zoloz-pte-ltd/zoloz-demo-ios"
    • Add the SDK dependency in Podfile:
copy
#zolozkit changelog https://docs.zoloz.com/zoloz/saas/releasenotes/

# #We recommend use our latest version, which includes new features and security improvements. If you need more information about specific version, please check the change log
pod 'zolozkit'  #core modules
pod 'zolozkit/ZolozNfcReader' #nfc reader module

Note: The code "pod 'zolozkit/ZolozNfcReader'" corresponds to the NFC function, Please contact the ZOLOZ team if you need to activate the NFC function. That one line of codes can be omitted if you don't need NFC function.

  • Update the Pod
    • Run the following command to update the SDK.
copy
pod update
  • Handle Errors:
    • If you encounter the following error during the update process：imageYou can use the following commands to update the local repository's index and then attempt the update again:
copy
pod install --repo-update

or

copy
pod repo update
  • Update Completed.
  1. Web SDK Update

For updates to the Web SDK, no action is required on your part, as updates are automatic and do not require manual changes to your codebase.

Why is the Web SDK unable to open the face capture page after sensor access permissions are denied for Face Capture?

Once Face Capture-Deeper is activated, ZOLOZ will request access to the phone's sensor permissions. Due to iOS system restrictions, if the user denies sensor access permissions to ZOLOZ, the Web SDK can no longer open the face capture page. Clients can either restart the WebView based on the returned code or prompt the user to restart the browser to reauthorize. For specific return codes, please see ZLZResponse.

How can I customize the identity proofing process so that Real ID scans only the front of an ID card?

Customize which document pages are required for Real ID scanning by setting up optional request parameters in the Real ID initialize API.

The API may not process the parameter correctly if the wrong format is used. Ensure that you put 'pages' as the field name and specify the document page number (i.e. '1', '2'; or both) that you would like for scanning and uploading.

Here are some examples of what your request parameters should look like:

  • To scan only the front of the document: req.put("page", "1")
  • To scan both sides of the document (i.e. front and back): req.put("page", "1,2")

Note that if you would like to use the single-page scanning function for your documents, this has to be supported by the algorithm first.

What are the types of serviceLevel parameters you can use for Real ID, Face Capture and ID Recognition?

ZOLOZ provides various identity proofing services through Real ID, Face Capture and ID Recognition.

Use different serviceLevel parameter values to customize your desired service levels for the APIs. These parameters are also optional.

Here is a list of service levels for your reference:

Field Name

Product

Description

Reference

serviceLevel

Real ID

  • REALID0001 :
    Users will be asked to take photos of their IDs manually.
    Using blink detection, the ZOLOZ server will perform a basic spoofing check and a basic liveness check.
  • REALID0002 :
    The ID will be automatically scanned.
    Using blink detection, the ZOLOZ server will perform an advanced spoofing check and a basic liveness check.
  • REALID0003:
    The ID will be automatically scanned. 
    Using 2 random multi-action detection, the ZOLOZ server will perform an advanced spoofing check and a liveness check. 
    Note: This service level is only available for Native SDK.
  • REALID0004: 
    The ID will be automatically scanned even when held at an angle. 
    Using blink detection, the ZOLOZ server will perform a basic spoofing check and a basic liveness check.
  • REALID0009:
    The ID will be automatically scanned. 
    Using blink detection, the ZOLOZ sever will perform an advanced spoofing check and a liveness check. This service level provides the ability to capture closed-eye images for Native SDK.
  • REALID0011:
    The ID will be automatically scanned. 
    Using blink detection, the ZOLOZ sever will perform an advanced spoofing check and a liveness check. This service level provides the ability to capture closed-eye images for Web SDK.
  • REALID0012:
    The ID will be automatically scanned. 
    Using blink detection, the ZOLOZ server will perform a basic spoofing check and a liveness check. 
    Note: This service level is only for Web SDK.

Refer to 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.

Refer to 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. 

Refer to ID Recognition API Reference:
initialize

Note: Real ID and Face Capture also supports more flexible configurations via parameters listed in productConfig. If the following parameters are set, they will be prioritized over serviceLevel and operationMode. The original serviceLevel and operationMode will still be maintained and will not be affected if you continue to use them.

Related productConfig parameters for Real ID:

Field name

Data type

Max length

Description

docUiType

String

20

Optional. This parameter refers to methods for taking ID photos. The values are as follows:

  • 1: Self-capture, default value for Web SDK. Users need to manually take ID photos,  and it only has basic anti-spoofing capabilities.
  • 2: Deep-scan, default value for Native SDK and only for Native SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it has advanced anti-spoofing capabilities such as intercepting printed color images.
  • 3: Auto-scan, only for Web SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it only has basic anti-spoofing capabilities.
  • 4: Trace-scan, only for Native SDK. ZOLOZ SDK automatically captures ID photos when the document is detected within the camera range. It can improve user experience, but  it only has basic anti-spoofing capabilities.
  • 5: Multi-angle, only for HKID in Web SDK. Users need to take two document photos from different angles. For the first photo, make the camera directly face the ID document and captures its photo. For the second,  incline the ID document 30° against the camera and capture its photo.
spoofModeString10

Optional. This parameter refers to document anti-spoofing levels, defined as follows:

  • CLOSED: All algorithms are not applied. You can use this anti-spoofing detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
  • STANDARD: Default value. A standard recommended level is applied.
  • LOOSE: Reserved value, not currently supported for use.
  • STRICT: Reserved value, not currently supported for use.

livenessMode

String10

Optional. Specifies the liveness level for face liveness detection check. The following values are supported:

  • CLOSED: All algorithms are not applied. You can use this liveness detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
  • STANDARD: Default value. A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this liveness detection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this liveness detection mode in high-risk scenarios.

antiInjectionMode

String

String

Deprecated field, will no longer be maintained. To ensure API compatibility, this field will be retained. Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-swapping pictures or videos. The following values are supported:

  • CLOSED: Default value. All the anti-injection algorithms are not applied. If the business scenario does not require injection attack detection, you do not need to enable it.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: Reserved value, not currently supported for use.
  • STRICT:Reserved value, not currently supported for use.

Note: Enabling injection attack detection will slightly increase false rejection rate and runtime. Please contact ZOLOZ technical support team before turning on this function. 

actionCheckItems

List<String>

Optional. User actions to be detected. For better user experience, it is not recommended to use two or more actions. The following values are supported:

  • FACEBLINK: Default value. Requires the user to blink their eyes.
  • MOUTHOPEN: Requires the user to open their mouth once.
  • HEADSHAKE: Requires the user to shake their head. Left or right headshake will be specified for the user to perform.
  • HEADLOWER: Requires the user to lower their head once.
  • HEADRAISE: Requires the user to raise their head once.
actionRandomString1

Optional. Specifies whether user actions specified in actionCheckItems are in random order to be detected. Valid values include:

  • Y: Random
  • N: Default value. Not random, action detection is performed following the order in actionCheckItems.

actionFrame

List<String>

Optional. This parameter refers to capturing other frame pictures, defined as follows:

  • EYECLOSE: Set this value to return closed-eye frames collected during the blink detection method.

riskMode

String10

Optional. This parameter refers to multi-dimensional risk control rule verification in RealID. It is used to intercept suspicious transactions. The values are as follows:

  • CLOSED: All algorithms are not applied. You can use this risk detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
  • STANDARD: Default value. A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this risk detection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this risk detection mode in high-risk scenarios.

idnThreshold

Integer

Deprecated field. Optional. The default threshold is 3. This parameter is used to check transactions in which one user uses different ID documents or one ID document is used  by different users. When the number of such transactions (from different userId) exceeds the threshold, the current transaction will be intercepted.  

Any integer larger than 0 is supported. 

Refer to Real ID API Reference for more details: initialize

Related productConfig parameters for Face Capture:

Field name

Data type

Max length

Description

livenessMode

String

10

Optional. Specifies the liveness level for face liveness detection check. The following values are supported:

  • CLOSED: All algorithms are not applied. You can use this liveness detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
  • STANDARD: Default value. A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this liveness detection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this liveness detection mode in high-risk scenarios.

antiInjectionMode

String

10

Deprecated field, will no longer be maintained. To ensure API compatibility, this field will be retained. Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-swapping pictures or videos. The following values are supported:

  • CLOSED: Default value. All the anti-injection algorithms are not applied. If the business scenario does not require injection attack detection, you do not need to enable it.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: Reserved value, not currently supported for use.
  • STRICT:Reserved value, not currently supported for use.

Note: Enabling injection attack detection will slightly increase false rejection rate and runtime. Please contact ZOLOZ technical support team before turning on this function. 

actionCheckItems

List<String>

Optional. User actions to be detected. For better user experience, it is not recommended to use two or more actions. The following values are supported:

  • FACEBLINK: Default value. Requires the user to blink their eyes.
  • MOUTHOPEN: Requires the user to open their mouth once.
  • HEADSHAKE: Requires the user to shake their head. Left or right headshake will be specified for the user to perform.
  • HEADLOWER: Requires the user to lower their head once.
  • HEADRAISE: Requires the user to raise their head once.

actionRandom

String

1

Optional. Specifies whether user actions specified in actionCheckItems are in random order to be detected. Valid values include:

  • Y: Random
  • N: Default value. Not random, action detection is performed following the order in actionCheckItems.

actionFrame

List<String>

Optional. This parameter refers to capturing other frame pictures, defined as follows:

  • EYECLOSE: Set this value to return closed-eye frames collected during the blink detection method.

Refer to Face Capture API Reference for more details: initialize

What types of UI configuration modes does the Web SDK support?

2 types of UI configuration modes are supported:

  • Page jump: redirects you to another page
  • HTML <iframe> tags: embed a page within the current page

What are the requirements to use the Web SDK?

You need to meet the following requirements to use the Web SDK:

  • Minimum OS versions that are supported: Android 5+, iOS 11+
  • Supported browsers:
    • iOS: Safari. From iOS 14.3 onwards, Chrome, Firefox, Microsoft Edge and WKWebView are all supported.
    • Android: We recommend that you use Chrome 60+ and Firefox 58+. For other browsers in Android, the Web SDK support varies from device to device.

The browsers above are currently officially supported. Considering the variety of browsers available on the market, we will review and update them accordingly.

Required permissions: Network and Camera access permissions.

To ensure security, HTTPS deployment is required for "Media capture".

Do I need to change the URL of the corresponding Web SDK to debug in the test environment?

No change is required.

Why am I unable to open/use the capture function when accessing the Web SDK via App?

You may encounter this issue on some device models/systems.

The Web SDK has to be opened in the WebView container of the app and the kernel of WebView is bound to the device system. Some models/systems may have WebView restrictions on the capture function, which results in users being unable to open or use it normally.

We recommend that you:

  • Switch to a mobile browser before accessing.
  • Use the Native SDK integration mode to stably access the capture function in the App.

How do I hide the face guide page's title bar in Native SDK?

For Android SDK, the following solutions are supported:

  • Place the attachment ui.json in the project assets directory to hide the title bar.
    📎UI.json

For iOS SDK, the following solutions are supported:

  • Add the "hiddenTitleBar" parameter to the URL of the face guide page and set the value of "hiddenTitleBar" to "true" (default is "false"). For example, http://url-to-face-guide-page.html?hiddenTitleBar=true

Note: If you hide the title bar of the face guide page, the ZOLOZ's back button will also be hidden. In this case, you need to add a custom back button in your H5 page and implement the required event. Please refer to the "Customize the selfie guidance page for Real ID" for detailed integration steps.

The Main Difference Between SDK Integration Mode and Pure API Mode for ID Recognition:

By comparing the two integration modes in the table below, you can choose the integration mode that suits your actual business needs. The SDK mode provides more comprehensive services and a superior user experience, suitable for you seeking efficient integration. The pure API mode is suitable for you need a highly customized user interface or you have a document-capture system.

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. For more details about Interaction flow, please refer to 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

Can I use Postman's debugging interface?

No, Postman is not currently supported.

To ensure data security, please use the access sample code for debugging instead. You can refer to ZOLOZ integration examples here.

API Call Errors

Error

Possible reasons

Solution

SIGNATURE_INVALID

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

Please refer to ZOLOZ's sample demo for the correct configuration and see 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.

Avoid being detected as high risk when testing in the sandbox environment by disabling the risk controls. You can do this by setting request parameter operationMode of initialize API to different values or select corresponding Risk Level in the demo app:

Here is the details:

  • To disable the Velocity feature, use 'STANDARD_VC_CLOSED' in the initialize API; or select 'Standard Risk Level 1' in the demo app.
  • To disable the IDN feature, use 'STANDARD_IDN_CLOSED' in the initialize API; or select 'Standard Risk Level 2' in demo app.
  • To disable both the Velocity and IDN features, use 'STANDARD_VC_IDN_CLOSED' in initialize API; or select 'Standard Risk Level 3' in the demo app.

       Your demo app should look like this:

                      image.png

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. Please refer to Understand environments and service endpoints.

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

  1. Check that the spelling of the clientID is correct.
  2. 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.

ZOLOZ Portal

What should I do if I encounter a login error and am unable to access my ZOLOZ Portal?

Identify the login error by using the developer tool in your browser to check the page's error message. Afterward, please send the error's request and response information to ZOLOZ's technical support for further investigation.

Here's how you can access your developer tools:

  1. Open the ZOLOZ portal in your web browser and attempt a login.
  2. A 'system error' pop-up should appear if there is a login error.
  3. Open the developer tools panel. In most web browsers, you can access it by:
    1. Right-clicking the page and clicking on 'Inspect' or 'Inspect Element' from the drop-down menu
    2. Using keyboard shortcuts Ctrl + Shift + I (Windows) or Cmd + Opt + I (Mac)
    3. Alternatively for Chrome users: you can also click the top right menu on the address bar > More Tools > Developer Tools
  1. In the developer tools panel, click on the 'Network' tab. A list of network requests and responses that the webpage has made will be shown here.

image

  1. Under the 'Name' table, find a request titled 'Login'. When you click on the 'Headers' tab, it'll be shown as a POST request.

  image

If you do not see a 'Login' request, please initiate the error by attempting another login.

  1. Please send the following information to ZOLOZ's technical support:
    1. General
    2. Response Headers
    3. Request Headers

  image

    1. 'Response' tab's code information

       image

Client-side

Client integration prompt Z7011

Possible reason(s):

The metaInfo passed into the initialize API as a request parameter is incorrect.

Please check that you're not using the sample metaInfo found in the documentation.

Here's how you can access the correct metaInfo:

  1. Run the Native Demo locally

 image

  1. After the server has successfully started, configure it with the “ZOLOZ SaaS Example” tool

  image.png

  1. Once the configuration is complete, click 'START ZOLOZ' so that the server can receive the metaInfo content through the Request object
  2. Call the initialize API again

Algorithm-related

What should I do if the document display is blurred?

Blur will be prompted if the document is:

  • Blurry
  • Reflective
  • Blocked by foreign objects;
  • or if the information on the document cannot be completely identified

If the capture is blurry, please recapture it under normal light conditions. During the recapture, please avoid any obstructions, reflections, and any other issues that could affect the identification and comparison process.

What should I do if tampering has been detected?

Tampering will be prompted when information or face tampering has been detected in the document.

Please initiate a manual review to determine whether fraud has occurred.

If your manual review still regards it as normal document, please contact ZOLOZ's technical support for further investigation.

What should I do if the material check fails?

Material check failure will be prompted when:

  • There are printing issues
  • Fake materials have been detected

First, please check if the failure has occurred due to printing or fake material detection.

If the algorithm has identified a printing error, please recapture the document under normal light conditions. If you still encounter repeated unsuccessful entries, please contact ZOLOZ's technical support.

What should I do when there is a face recognition failure?

Face recognition failure occurs when:

  • The lighting is too bright or too dark
  • The background is mottled or blurred
  • There are border-shaped objects in the background

When initiating face verification, please conduct it with a bright and clear background. If you still encounter repeated unsuccessful entries, please contact ZOLOZ's technical support.