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

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. Afterwards, 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

ZOLOZ SDK & API Usage

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 and Face Capture?

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

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 test.
  • REALID0002 :
    The ID will be automatically scanned.
    Using blink detection, the ZOLOZ server will perform an advanced spoofing check and a basic liveness check.

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

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.

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 whether it's a sg-sandbox or hk-sit 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: Refers to one userID being used for multiple eKYC documents; or one identity is being used by multiple userIDs
  • Velocity: Refers to attacks such as DDoS where if too many user requests are received in a short amount of time, they will be risk controlled.

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, pleae provide the system error's request and response information to ZOLOZ's technical support.

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.