checkresult

    POST /api/v1/zoloz/idrecognition/checkresult

    The ZOLOZ checkresult API is used to request a result about the ID recognition process running status and other corresponding results, which include basic and detailed document verification results. This API is 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.

    transactionId

    String

    64

    Required. The unique transaction ID that is returned in the response of the initialize API.

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

    extInfo

    ExtInfo

    Optional. Detailed information about document verification. This field is only available when the value of the result.resultStatus field is set to S. For more information, see ExtIDInfo

    #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 checkresult API is invoked successfully, and results about document verification are returned.
    • If the value of the result.resultStatus is F, the invocation of the ZOLOZ checkresult 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 ID recognition checkresult API.

    resultCode

    resultSatus

    Description

    SUCCESS

    S

    User finished the transaction.

    copy
    PROCESSING

    S

    User hasn't finish the whole flow.

    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 or the related log. 

    UNUSABLE

    F

    User is blocked by the cooldown strategy.

    LIMIT_EXCEEDED

    F

    User tried too many times within the same transaction.

    #Sample

    #Request Sample

    The following sample shows what a request that the merchant server sends looks like.

    copy
    {
        "bizId": "2017839040588699",
        "transactionId": "G000000005FID20200304000000000001570702"
    }

    #Response Sample

    The following sample shows what a response that the ZOLOZ server returns looks like.

    copy
    {
      "extInfo": {
        "imageContent": ["base64string.....", "base64string....."],
        "ocrResult": {
          "ID_NUMBER": "xxxx",
          "COUNTRY": "xxxxx",
          "SEX": "M"
        },
        "spoofResult": {
          "TAMPER_CHECK": "Y",
          "MATERIAL_CHECK": "Y",
          "SCREEN_RECAPTURE_CHECK": "Y"
        },
        "recognitionErrorCode": "",
        "recognitionResult": "Y"
      },
      "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
      }
    }

    #More information

    #ExtIdInfo

    The following table shows the fields that can be specified in the ExtIdInfo data model.

    Field name

    Data type

    Description

    recognitionResult

    String

    Specifies the running status of the document verification process. Possible values and their meanings are as below:

    • Y : The document verification process runs successfully.
    • N : The document verification process process fails.

    Required if the document verification process runs successfully. 

    imageContent

    List of String

    The image of the identity document (if any). The image must be encoded in base64. This field is specified only when the document verification process runs successfully.

    ocrResult

    Map

    The OCR result, which contains information about the identity. Required if the document verification process runs successfully. Depending on the type of the identity document, different sets of identity information are recognized. For more information, see Document types supported and OCR results returned

    spoofResult

    Map

    Optional. The spoofing check result, which contains information about the check results in terms of tampering, authenticity of the document material, and screen recapture. For more information, see spoofResult

    recognitionErrorCode

    String

    Optional. Specifies the error details of the document verification process. Possible values and their meanings are as below:

    • NO_REQUIRED_ID : The ID recognized from the uploaded image does not match the specified identity document type.
    • BLUR : The uploaded identity document image is blurred.
    • NO_FACE_DETECTED : A face that should have been recognized from the specified identity document is not detected from the uploaded image as expected.
    • NOT_REAL_DOC : The uploaded identity document image is detected as fake.
    • EXPOSURE : The uploaded identity document image is overexposed.
    • UNKNOWN : All the other recognition errors. 

    #spoofResult

    The following table shows the detailed information that is included in a spoofing check result.

    Field name

    Data type

    Description

    TAMPER_CHECK

    String

    Required. Specifies whether the input identity document passes the tampering check. If the identity document does not pass the check, which means it is detected as tampered, the value of N is returned; otherwise, Y is returned. 

    MATERIAL_CHECK

    String

    Required. Specifies whether the material of the identity document passes the authenticity check. If the material of the identity document does not pass the check, for example, detected in black and white, the value of N is returned; otherwise, Y is returned. 

    SCREEN_RECAPTURE_CHECK

    String

    Required. Specifies whether the identity document passes the screen recapture check. If the identity document does not pass the check, which means the image uploaded is detected as an image recaptured from a screen, the value of N is returned; otherwise, Y is returned. 

    SECURITY_FEATURE_CHECK

    String

    Optional. Currently only support HK identity card. Validate some of the security features on the identity card to recognize fake cards.

    INFORMATION_CHECK

    String

    Optional. Currently only support HK identity card. Validate the information on ID card such as ID number according to government rules.