ZOLOZ eKYC SaaS FAQs
Here is the list of relevant FAQs for ZOLOZ eKYC SaaS products.
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:
Refer to Real ID API Reference: initialize
Using 2 random multi-action detection, a
high-level liveness check is performed.
Using blink detection, a full liveness check is
performed. This service level also provides the
ability to capture closed-eye images for the Web
Refer to Face Capture API Reference:
Refer to ID Recognition API Reference:
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:
Optional. Specifies the liveness level for face liveness detection check. The following values are supported:
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:
Note: Enabling injection attack detection will slightly increase false positive rates and runtime.
Optional. User action detection range. For better user experience, it is not recommended to use two or more actions. The following values are supported:
Optional. Specifies whether user action detection range is random. Valid values include:
Optional. The following value is supported:
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.
For iOS SDK, the following solutions are supported:
- Manually set
self.navigationController.navigationBarHidden = YESto 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
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.
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.
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.
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:
Your demo app should look like this:
Here are the definitions for IDN and Velocity:
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:
** Note that the portal environment has to be consistent with the endpoint/url environment.
** Note that this misconfiguration would usually result in an INVALID_SIGNATURE error rather than a MERCHANT_NOT_FOUND error.
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.
Two possible reasons could have occured:
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:
- Open the ZOLOZ portal in your web browser and attempt a login.
- A 'system error' pop-up should appear if there is a login error.
- Open the developer tools panel. In most web browsers, you can access it by:
- Right-clicking the page and clicking on 'Inspect' or 'Inspect Element' from the drop-down menu
- Using keyboard shortcuts Ctrl + Shift + I (Windows) or Cmd + Opt + I (Mac)
- Alternatively for Chrome users: you can also click the top right menu on the address bar > More Tools > Developer Tools
- 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.
- Under the 'Name' table, find a request titled 'Login'. When you click on the 'Headers' tab, it'll be shown as a POST request.
If you do not see a 'Login' request, please initiate the error by attempting another login.
- Please send the following information to ZOLOZ's technical support:
- Response Headers
- Request Headers
- 'Response' tab's code information
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:
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 integration prompt Z7011
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:
- Run the Native Demo locally
- After the server has successfully started, configure it with the “ZOLOZ SaaS Example” tool
- Once the configuration is complete, click 'START ZOLOZ' so that the server can receive the metaInfo content through the Request object
- Call the initialize API again
What should I do if the document display is blurred?
Blur will be prompted if the document is:
- 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.