initialize

2022-06-09 09:27

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 purpose. For example，the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness check 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 App SDK mode is used, its value comes from the ZOLOZ SDK in the JSON string format, for example: `"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}"`. 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 `MOB_H5`.
flowType	String	32	Required. Specifies the type of the identity proofing flow. The following values are supported: `REALIDLITE_KYC` : specify this value when the App SDK mode is used. `H5_REALIDLITE_KYC` : specify this value when the H5 mode is used.
docType	String	16	Required. Type of the document, for example, if the document to be uploaded is a passport, set the value of this attribute to `00000001003`. The value of this field must not be null or an empty string. For the document types that are supported by Real ID, see Document types supported and OCR results returned.
userId	String	64	Required. Merchant user ID, or other identifiers that can be used to identify a specific user, for example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field, for example, by hashing the value.
sceneCode	String	64	Optional. Specifies the business scene for data analysis purpose. 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 purpose, for example, registration, withdraw, topUp, transfer, changePassword.
serviceLevel	String	32	Optional. Specifies the service level for spoofing check and face liveness detection. The following values are supported: `REALID0001` : If this value is set, the ZOLOZ SDK asks users to take the photos of the identity document manually. The ZOLOZ server performs basic spoofing check, and basic liveness check with the blink detection method used. `REALID0002` : If this value is set, the ZOLOZ SDK automatically scans the identity document. The ZOLOZ server performs advanced spoofing check, and basic liveness check with the blink detection method used.
operationMode	String	32	Optional. Specifies the operation mode where the identity proofing process runs. The following values are supported: `CLOSED`: All the algorithms and risk control rules are not applied. You can use this operation mode in the test phase so that the algorithms and risk controls rules do not affect the test process. `STANDARD`: A standard recommended level is applied. `LOOSE`: A relatively looser level is applied. You can use this operation mode in low-risk scenarios. `STRICT`: A relatively stricter level is applied. You can use this operation mode in high-risk scenarios.
pages	String	32	Optional. Specify the document page numbers to scan and upload, delimitered by comma. Eg: "1" (scan first page), "1,2" (scan first and second page)
pageConfig	Object		Optional. Specifies the configuration settings for the embedded H5 page. For more information, see pageConfig.
h5ModeConfig	Object		Optional. Specifies the configuration settings for H5 Real ID flow. Set this field when H5 mode is specified with the flowType filed as `H5_REALIDLITE_KYC`. For more information，see h5ModeConfig.
productConfig	Object		Optional. Specify finer control on the Real ID product. For more information, see productConfig.

Response parameters

Field name	Data type	Description
result	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 at the client side, for example, invalid argument, no transaction ID is returned.
clientCfg	String	Optional. The client configuration information, including parameters about SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is `"S"`.

Result

Result process logic

For different request results, different actions are to 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 message for more information about the possible reasons. Error codes

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 a little 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 the 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.

copy
{
  "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.

copy
{
  "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 that the ZOLOZ server returns looks like.

copy
{
   "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 Object.

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 to perform 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 Object.

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.
completeCallbackUrl	String	128	Required. Specifies the callback URL where the browser is redicted 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, only support: en/ zh-CN/ zh-HK / jp / th now
isIframe	String	1	Optional. If the Web Page needs to be open in Iframe, this param should be set as Y. Supported Value: Y / N
uiCfg	String	256	Optional. Custom UI configurations in the JSON string format. Only support `titlebarbgcolor`, `titlebartextcolor`, and `buttoncolor` for now. For example:`"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\"}"`.

productConfig

The following table shows the fields that can be specified in the productConfig Object.

Field name	Data type	Max length	Description
cropDocImage	String	1	Optional. Specify whether to crop the backgroud of captured DOC image. Valid values include: ●Y: crop ●N: (default) do not crop
landmarkCheck	Array		Optional. Specify whether to perform landmark check within DOC spoofing check. Landmark check is only applicable for selected documents. e.g. (MyKad) An array of supported landmark components needs to be specified if landmark check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.
hologramCheck	Array		Optional. Specify whether to perform hologram check within DOC spoofing check. Hologram check is only applicable for selected documents.e.g(MyKad) An array of supported hologram check components needs to be specified if hologram check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.
pageInfoCheck	Array		Optional. Specify whether to perform information check within DOC spoofing check. information check is only applicable for selected documents. An array of supported information check components needs to be specified if information check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.
preciseTamperCheck	String	1	Optional. Specify whether to perform previse precise tamper check. precise tamper check is only applicable for selected documents. Valid values include: ●Y: Yes ●N: (default) do not perform precise tamper check

Change log

Date	Change log
22 May, 2022	A new parameter, productConfig, is added in the request.
8 September，2020	Two more types of identity documents are supported: Malaysia MyKad and Macau identity card. A new parameter, h5ModeConfig, is added in the request.
9 June, 2020	A new parameter, pageConfig, is added in the request.
27 December, 2019	The parameter productLevel is renamed to serviceLevel, and the related description is updated.
20 December, 2019	The following two request parameters are added: productLevel operationMode
06 December, 2019	Released.