initialize
POST/api/v1/zoloz/realid/initialize
The ZOLOZ Real ID initialize API is used to initialize the identity proofing process in ZOLOZ. A unique transaction ID is generated for the identity proofing process and used in all the subsequent interactions with the ZOLOZ server. This API is not idempotent.
structure
Request parameters
Field name | Data type | Max length | Description |
bizId | String | 32 | Required. A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness checks on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID. |
metaInfo | String | 512 | Required. The meta information about the SDK and the user's device. When the App SDK mode is used, its value comes from the ZOLOZ SDK in JSON string format, for example:
Note: Do not modify the returned value as it only needs to be passed through directly. When H5 mode is used, simply set the value as |
flowType | String | 32 | Required. Specifies the type of the identity proofing flow. The following values are supported:
|
docType | String | 16 | Required. Type of document. |
userId | String | 64 | Required. Merchant user ID, or other identifiers that can be used to identify a specific user. |
sceneCode | String | 64 | Optional. Specifies the business scene for data analysis purposes. If you want to distinguish the data performance of different scenes, it is recommended to set the sceneCode field to different values according to your business purposes; for example, registration, withdraw, topUp, transfer, changePassword. |
serviceLevel | String | 32 | Optional. Specifies the service level for spoofing checks and face liveness detection. The following values are supported:
|
operationMode | String | 32 | Optional. Specifies the operation mode where the identity proofing process runs. The following values are supported:
|
pages | String | 32 | Optional. Specifies the document page numbers to scan and upload, separated by commas. E.g. "1" (scan the first page), "1,2" (scan the first and second page) |
pageConfig | PageConfig | Optional. Specifies the configuration settings for the embedded H5 page. For more information, see pageConfig. | |
h5ModeConfig | H5ModeConfig | Optional. Specifies the configuration settings for H5 Real ID flow. Set this field when the H5 mode is specified with the flowType filed as | |
productConfig | ProductConfig | Optional. Specifies finer controls for the Real ID product. For more information, see productConfig. | |
allowExpiredDocument | String | Optional. Specifies whether expired documents are allowed. Only used for the docType 00000001003. The following values are supported:
Note: Invalid values will fall back to the default option and pause the Real ID process when an expired document is detected. |
Response parameters
Field name | Data type | Description |
result | Required. The API request result, which contains information about the result of the API request, such as status and error codes. | |
transactionId | String | Optional. A unique transaction ID that is generated by the ZOLOZ server for the identity proofing process. This ID will be used as an input parameter for the Real ID checkresult API request. Note: when an error occurs during the process, for example, an invalid argument, no transaction ID will be returned. |
clientCfg | String | Optional. The client configuration information, including parameters about the SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is |
Result
Result process logic
For different request results, different actions will be performed. See the following for details:
- If the value of the result.resultStatus is
S
, the ZOLOZ Real ID initialize API is invoked successfully and a unique transaction ID is returned. - If the value of the result.resultStatus is
F
, the invocation of the ZOLOZ Real ID initialize API fails. Check the error code and its message for more information on the possible reasons why.
Common error codes
For the full list of common error codes, see the Common error codes section in the Error handling topic.
API-specific error codes
The following table shows the possible error codes that are specific for the Real ID initialize API.
resultCode | resultStatus | Description |
SUCCESS | S | The API call is successful. |
HIGH_RISK | F | High risks are detected. The user account is strategically cooled down by the risk engine. |
ACCOUNT_SERVICE_SUSPEND | F | The user account is blacklisted by the risk engine. |
DEVICE_NOT_SUPPORT | F | The device type is not supported. |
OS_NOT_SUPPORT | F | The operating system of the device is not supported. |
SDKVERSION_NOT_SUPPORT | F | The version of the ZOLOZ SDK is not supported. |
INVALID_ARGUMENT | F | Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log. |
SYSTEM_ERROR | F | Other internal errors. For more information about the error details, check the result message that is returned and the related log. |
Sample
Request sample
For different integration modes, the request structures are slightly different. When the identity proofing process is initiated in the H5 mode, additionally, an object called h5ModeConfig must be specified. Refer to the following two request samples for more detailed information.
Native RealId Request Sample
The following sample shows what a request looks like if the identity proofing process is initiated in the App SDK mode.
{
"bizId": "2017839040588699",
"flowType": "REALIDLITE_KYC",
"userId": "123456abcd",
"docType": "08520000001",
"pages": "1,2",
"pageConfig":{
"urlFaceGuide":"http://url-to-face-guide-page.htm"
},
"serviceLevel": "REALID0001",
"operationMode": "STANDARD",
"productConfig": {
"cropDocImage": "Y",
"landmarkCheck": [
{"name":"kadPengenalan"},
{"name":"mykadLogo"},
{"name":"flagLogo"},
{"name":"mscLogo"},
{"name":"ghostFace"},
{"name":"hibiscusLogo"},
{"name":"coatOfArm"},
{"name":"twinTower"}
],
"hologramCheck": [
{"name":"hologram"}
],
"pageInfoCheck": [
{"name":"id"},
{"name":"symbol"},
{"name":"name"}
],
"preciseTamperCheck": "Y"
},
"metaInfo": "{
\"deviceType\": \"deviceType\",
\"appVersion\": \"1.0\",
\"osVersion\": \"7.1.1\",
\"appName\": \"com.company.wallet\",
\"bioMetaInfo\": \"3.37.0:262144,0\",
\"apdidToken\": \"mock-apdidToken\",
\"deviceModel\": \"MI 6\",
\"zimVer\": \"2.0.0\"
}"
}
H5 RealId Request Sample
The following sample shows what a request looks like if the identity proofing process is initiated in the H5 mode.
{
"bizId": "2017839040588699",
"flowType": "H5_REALIDLITE_KYC",
"userId": "123456abcd",
"docType": "08520000001",
"pageConfig":{
"urlFaceGuide":"http://url-to-face-guide-page.htm"
},
"serviceLevel": "REALID0001",
"operationMode": "STANDARD",
"productConfig": {
"cropDocImage": "Y",
"landmarkCheck": [
{"name":"kadPengenalan"},
{"name":"mykadLogo"},
{"name":"flagLogo"},
{"name":"mscLogo"},
{"name":"ghostFace"},
{"name":"hibiscusLogo"},
{"name":"coatOfArm"},
{"name":"twinTower"}
],
"hologramCheck": [
{"name":"hologram"}
],
"pageInfoCheck": [
{"name":"id"},
{"name":"symbol"},
{"name":"name"}
],
"preciseTamperCheck": "Y"
},
"metaInfo": "MOB_H5",
"h5ModeConfig":{
"completeCallbackUrl":"http://xxx.html",
"interruptCallbackUrl":"http://xxx.html"
}
}
Response Sample
The following sample shows what a response returned from the ZOLOZ server looks like.
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId":"G000000005FID20200304000000000001570702",
"clientCfg": "……"
}
More information
pageConfig
The following table shows the fields that can be specified in the pageConfig data model.
Field name | Data type | Max length | Description |
urlFaceGuide | String | 256 | Optional. Specifies the URL to the face guide page, which is an H5 prompt page that can be customized to guide users during face scanning. For example, http://url-to-face-guide-page.html. |
h5ModeConfig
The following table shows the fields that can be specified in the h5ModeConfig data model.
Field name | Data type | Max length | Description |
state | String | 128 | Optional. An identifier that is used to recover the customer's context. You can set this field to any String value. The value is then passed as a parameter when the ZOLOZ SDK calls back to the merchant's application. If the value is not set, the value of the transactionId field is used instead. |
completeCallbackUrl | String | 128 | Required. Specifies the callback URL where the browser is redirected when the whole identity proofing process is completed. |
interruptCallbackUrl | String | 128 | Required. Specifies the callback URL where the browser is redirected when the process is interrupted. |
locale | String | 16 | Optional. Language of the web page, currently supports: en (English) / zh-CN (Simplified Chinese) / zh-HK (Traditional Chinese) / jp (Japanese) / th (Thai) / es (Español) / pt (Portuguese) / fr (French) / id (Indonesian) / de (German) / kr (Korean). |
isIframe | String | 1 | Optional. If the Web Page needs to be open in Iframe, this parameter should be set as
|
uiCfg | String | 256 | Optional. Custom UI configurations in the JSON string format. Only supports For example: |
productConfig
The following table shows the fields that can be specified in the productConfig data model.
Field name | Data type | Max length | Description | Notes |
cropDocImage | String | 1 | Optional. Specify whether to crop the background of the captured DOC image. Valid values include:
| |
cropFaceImage | String | 1 | Optional. Specify whether to crop the face area of the captured FACE image. Valid values include:
| |
landmarkCheck | Array | Optional. Specify whether to perform landmark checks within a DOC spoofing check. Landmark checks are only applicable for selected documents. E.g. (MyKad) | ||
hologramCheck | Array | Optional. Specify whether to perform hologram checks within a DOC spoofing check. Hologram checks are only applicable for selected documents. E.g. (MyKad) | ||
pageInfoCheck | Array | Optional. Specify whether to perform information checks within a DOC spoofing check. information checks are only applicable for selected documents. | ||
preciseTamperCheck | String | 1 | Optional. Specify whether to perform a precise tamper check. Precise tamper checks are only applicable for selected documents. The following values are supported:
| |
docUiType | String | 20 | Optional. This parameter refers to methods for taking ID photos. The values are as follows:
| The following parameters take precedence over
|
spoofMode | String | 10 | Optional. This parameter refers to document anti-spoofing levels, defined as follows:
| |
livenessMode | String | 10 | Optional. Specifies the liveness level for face liveness detection check. The following values are supported:
| |
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-swapping pictures or videos. The following values are supported:
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:
| ||
actionRandom | String | 1 | Optional. Specifies whether user actions specified in
| |
actionFrame | List<String> | Optional. This parameter refers to capturing other frame pictures, defined as follows:
| ||
riskMode | String | 10 | 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:
| |
idnThreshold | Integer | Optional. The default threshold is Any integer larger than 0 is supported. |
Change log
Date | Change log |
22 November, 2023 | Added new fields for the productConfig parameter. |
22 May, 2022 | A new parameter, productConfig, is added in the request. |
8 September,2020 |
|
9 June, 2020 | A new parameter, pageConfig, is added in the request. |
27 December, 2019 |
|
20 December, 2019 | The following two request parameters are added:
|
06 December, 2019 | Released. |