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

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, 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: 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 and descriptions:

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

Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-changing 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: A relatively looser level is applied. You can use this anti-injection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this anti-injection mode in high-risk scenarios.

Note: Enabling injection attack detection will slightly increase false positive rates and runtime.

actionCheckItems

List<String>

Optional. User action detection range. 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 action detection range is random. Valid values include:

  • Y: Random
  • N: Default value. Not random.

actionFrame

List<String>

Optional. The following value is supported:

  • 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:

  • Manually set self.navigationController.navigationBarHidden = YES to hide the title bar.
    Note: The iOS SDK only supports normal processes when hiding the title bar of the face guide page. If face scanning is interrupted (i.e. the user taps on 'cancel' while scanning), the face guide's title bar will still be shown.

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: 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, 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

Why are uploaded images missing from the Portal?

For ID Recognition and Face Compare, when using the pure API access mode to access and upload PNG images, you will need to disable the Alpha channel for PNG images to be displayed on the Portal.

Here's how you can disable the Alpha channel for PNG images:

When uploading a PNG image, double-click on your Mac computer to open the PNG image (open the image with the default Preview app), select File > Export, and then uncheck the Alpha box, as shown in the following figure:

Screenshot 2023-08-25 at 3.39.57 PM.png

Note: This solution is only applicable for Mac users. For Windows users, as the Preview app is only available for Mac, other image processing softwares will be required to close the Alpha channel for PNG images.

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.