RealId APIs

    #Overview

    API Name: Zoloz RealId APIs, including the following.

    API URL:

    Initialize

    v1.zoloz.realid.initialize

    CheckResult

    v1.zoloz.realid.checkresult


    API Description:

    2 APIs listed below will be introduced. Requests are described in JSON and the format is as listed below. You need to make sure the format is correct. After a request has been sent successfully, users will be able to proceed to the following stages of eKYC process. Please note these APIs are exposed via Zoloz Gateway. Please refer to the Zoloz Gateway Document for the correct way of invocation. 


    Initialize

    Initialize API  is the first API you need to call from your server side, when a user starts the eKYC process. It will initialize an eKYC application in Zoloz with a unique transaction ID, which shall be used in all the subsequent interactions with Zoloz for the same application.


    CheckResult

    CheckResult API is designed for your server side to request for a result no matter whether an eKYC application is completed successfully or not. CheckResult API will send back to your sever side with eKYC status suggested by Zoloz and other corresponding results.


    #Version

    Date

    Version

    Release Notes

    06 December, 2019

    1.0.0

    The first published version

    20 December, 2019

    1.1.0

    1. Add productLevel and operationMode at the request of the initialize API
    2. Response fields adjustment of the CheckResult API

    27 December, 2019

    1.2.0

    1. Renamed productLevel to serviceLevel of the initialize API and updated the description.
    2. replaced envData.envName with wirelessConfigGroup of the  initialize API.
    3. changed variable naming case of the checkResult API.

    21 May,2020 

    1.3.0

    1.  Current HKID,New HKID  OCR Result Key add SYMBOLS.
    2.  SpoofResult add key OTHER_CHECK.
    3.  add serviceLevel and operationMode detailed information.

    9 June, 2020

    1.4.0

      init request add pageConfig param,merchant can input faceGuide url

    30 July, 2020

    1.5.0

    1.add securityFeaturesResult

    2.add hk ocr fields:ISSUE_DATE,LATEST_ISSUE_DATE

    8 September,2020

    1.6.0

    1. update  Malaysia. MyKad,  Macao Identity Card pages

    2. update realId  api initialize param add h5ModeConfig   

    23 October 2020

    1.7.0

    1.add China ocr fields


    #Initialize

    #Request

    #Native RealId Request Sample

    copy
    {
        "bizId": "2017839040588699",
        "flowType": "REALIDLITE_KYC",   
        "userId": "123456abcd",
        "docType": "08520000001",
        "pageConfig":{
          "urlFaceGuide":"http://url-to-face-guide-page.htm"
        },
        "serviceLevel": "REALID0001",
        "operationMode": "STANDARD",
        "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

    copy
    {
        "bizId": "2017839040588699",
        "flowType": "H5_REALIDLITE_KYC",   
        "userId": "123456abcd",
        "docType": "08520000001",
        "pageConfig":{
          "urlFaceGuide":"http://url-to-face-guide-page.htm"
        },
        "serviceLevel": "REALID0001",
        "operationMode": "STANDARD",
        "metaInfo": "MOB_H5",
        "h5ModeConfig":{
          "completeCallbackUrl":"http://xxx.html",
          "interruptCallbackUrl":"http://xxx.html"
        }
    }




    #Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Description

    Sample Value

    bizId

    String

    32

    Yes

    Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

    2017839040588699

    metaInfo

    String

    512

    Yes

    Meta info from client.

    <metaInfoFromClient>

    flowType

    String

    32

    Yes

    Type of eKYC flow Native must be "REALIDLITE_KYC",

    H5 must be

    "H5_REALIDLITE_KYC"


    REALIDLITE_KYC

    docType

    String

    16

    Yes

    Document type, see definitions below.

    08520000001

    userId

    String

    64

    Yes

    Merchant user id, or something could identify a specific user such as mobile phone or email, a pre-desensitization (such as hashing) is strongly recommended.

    2305940069977

    sceneCode

    String

    64

    No

    Business scene for data analysis purpose, no real business impact.If you want to distinguish the data performance of different scenarios,we suggest setting sceneCode to different value.It is recommended to name sceneCode's value according to business purpose.For example:registration,withdraw,topUp,transfer,changePassword.

    registration

    serviceLevel

    String

    32

    No

    The service level, check following table for details.

    REALID0001

    operationMode

    String

    32

    No

    The operation mode, check following table for details.

    STANDARD

    pageConfig

    Object


    No

    The embedded h5 page configuration.


    pageConfig.urlFaceGuide

    String

    256

    No

    The url to face guide page.

    http://url-to-face-guide-page.html

    h5ModeConfig

    Object


    No

    The configuration for H5 RealId production, only mandatory when H5 mode is specified.


    h5ModeConfig.state

    String

    128

    No

    An identifier used to recover the customer's context, any string is accepted and it will be passed as parameter when callback to the customer's server. If it is not set, the value of transactionId will be passed when callback.


    h5ModeConfig.completeCallbackUrl

    String

    128

    Yes

    The complete callback url, the browser will be redirect to this url when the process is done.


    h5ModeConfig.interruptCallbackUrl

    String

    128

    Yes

    The interrupt  callback url, the browser will be redirect to this url when the process is interrupted.



    The value range of "serviceLevel" at business level:

    serviceLevel

    UI for scanning ID

    UI for scanning face

    Description

    REALID0001

    Maunal Capture

    Cherry(Blink)

    This level has basic anti-spoofing ability and basic liveness detection ability

    REALID0002

    Auto Scanning

    Cherry(Blink)

    This level has advanced anti-spoofing ability and basic liveness detection ability


    The value range of "operationMode" at business level:

    operationMode

    Description

    CLOSED

    Close all algorithm and risk control rule judgments. It is a happy path mode. It is mainly used in the test phase to avoid being easily affected by risk control or algorithm to affect the test process. The overall pass rate is 100% and it is intercepted without risk

    LOOSE

    Relatively looser than standard water level (STANDARD), suitable for low-risk scenarios, overall pass rate is 99%, risk control interception rate is 1%, and bad person interception rate is 80%

    STANDARD

    STANDARD: The standard threshold gear recommended online, the overall pass rate is 90%, and the blocking rate for bad people is 95%

    STRICT

    stricter than the standard water level (STANDARD), suitable for high-risk scenarios, the overall pass rate is 80%, and the bad block interception rate is 99%


    #Response

    #Response Sample

    copy
    {
       "result": {
            "resultStatus": "S",
            "resultCode": "SUCCESS",
            "resultMessage": "Success"
        },
      "transactionId":"G000000005FID20200304000000000001570702", 
      "clientCfg": "……"   
    }


    #Fields Specification

    Name

    Type

    Mandatory

    Description

    Sample Value

    result

    Result

    Yes

    API result.


    result.resultStatus

    String

    Yes

    Result status.

    "S": Successful

    "F": Failed

    S

    result.resultCode

    String

    Yes

    Result code. Refer to the table below for more information.

    SUCCESS

    result.resultMessage

    String

    Yes

    More information to describe the result code.


    transactionId

    String

    No

    Unique ID of the eKYC application.

    when error is client side

    like invalid argument, we won't return txnId

    G000000005FID20200304000000000001570702

    clientCfg

    String

    No

    Client config to be used by Zoloz SDK.



    The value range of "resultCode" at business level: 

    resultCode

    Description

    SUCCESS

    Success.

    HIGH_RISK

    The account is cooled down by the risk engine.

    ACCOUNT_SERVICE_SUSPENDThe account is blacklisted by the risk engine.
    DEVICE_NOT_SUPPORT

    The device is not supported.

    OS_NOT_SUPPORT

    The operating system is not supported.


    SDKVERSION_NOT_SUPPORT

    The APP version is not supported.

    INVALID_ARGUMENT

    Invalid argument.

    SYSTEM_ERROR

    System error.

    #

    #CheckResult

    #Request

    # Request Sample


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


    #Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Description

    Sample Value

    bizId

    String

    32

    Yes

    Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

    2017839XXXXXX699

    transactionId

    String

    64

    Yes

    unique ID that used to start ekyc SDK in client side. Server side need to pass this to calling client for further processing.

    F20191028XXXXXXX134572

    isReturnImage

    String

    1

    No

    A flag indicates whether image data should be returned in the API. Default value is N.

    "Y": yes

    "N": no

    N


    #Response

    #Response Sample

    copy
    {
        "result": {
            "resultCode": "SUCCESS",
            "resultMessage": "Success",
            "resultStatus": "S"
        },
        "ekycResult": "Pending",
        "extBasicInfo": {
            "certType": "08530000001",
            "certNo": "A12345678",
            "certName": "xxxxxx"
        },
        "extFaceInfo": {
            "ekycResultFace": "Success",
            "faceScore": 88,
            "faceImg": "/9j/4AA..[omitted]..PxA=",
            "faceQuality": 97.61517973846627,
            "faceLivenessResult": "Success"
        },
        "extIdInfo": {
            "ekycResultDoc": "Pending",
            "docEdition": 1,
            "frontPageImg": "/9j/4AA..[omitted]..PxA=",
            "backPageImg": "/9j/4AA..[omitted]..PxA=",
            "ocrResult": {
                ...
            },
            "spoofResult": {
                "TAMPER_CHECK": "Y",
                "MATERIAL_CHECK": "Y",
                "SCREEN_RECAPTURE_CHECK": "Y",
                "OTHER_CHECK":,"Y"
            },
            "securityFeaturesResult": {
                "LASER_IMAGE_1_SCORE":95,
                "LASER_IMAGE_1_THRESHOLD":90,
                "LASER_IMAGE_1_PASSED":"True",
                "HOLOGRAM_SCORE":95,
                "HOLOGRAM_THRESHOLD":90,
                "HOLOGRAM_PASSED":"True",
                "STEREO_LASER_PORTRAIT_SCORE":95,
                "STEREO_LASER_PORTRAIT_THRESHOLD":90,
                "STEREO_LASER_PORTRAIT_PASSED":"True",
                "LASER_IMAGE_2_SCORE":95,
                "LASER_IMAGE_2_THRESHOLD":90,
                "LASER_IMAGE_2_PASSED":"True",
                "OVERALL_SCORE":95,
                "OVERALL_THRESHOLD":90,
                "OVERALL_PASSED":"True"
            },
            "docErrorDetails": "BLUR"
        },
        "extRiskInfo": {
            "ekycResultRisk": "Pending",
            "strategyPassResult": "ID_NETWORK_HIGH_RISK",
            "idNetworkDetails": "..."
        },
        "extCustomInfo": {
            ...
        }    
    }


    #Fields Specification

    Name

    Type

    Mandatory

    Description

    Sample Value

    result

    Result

    Yes

    API result.


    result.resultStatus

    String

    Yes

    Result status at system level. "S" or "F". "S" stands for success and "F" stands for failure.

    S

    result.resultCode

    String

    Yes

    Detailed result code. Refer to the table below for more information.

    SUCCESS

    result.resultMessage

    String

    Yes

    Result details. Explanation to result code.

    Success

    ekycResult

    String

    No

    eKYC application result. Only available when result.resultStatus is "S". Values include:

    • Success: eKYC application is successful.
    • Pending: eKYC application is pending.
    • Failure: eKYC application fails.
    • InProcess: eKYC application is in process.
    • VoidCancelled: eKYC application is cancelled.
    • VoidTimeout: eKYC application is timed out.

    Success

    extBasicInfo

    ExtBasicInfo

    No

    Detailed eKYC application basic information. Only available when result.resultStatus is "S". Refer to the table below for details.


    extFaceInfo

    ExtFaceInfo

    No

    Detailed eKYC application face information. Only available when result.resultStatus is "S". Refer to the table below for details.


    extIdInfo

    ExtIdInfo

    No

    Detailed eKYC application Doc information. Only available when result.resultStatus is "S". Refer to the table below for details.


    extRiskInfo

    ExtRiskInfo

    No

    Detailed eKYC application risk information. Only available when result.resultStatus is "S". Refer to the table below for details.


    extCustomInfo

    Map

    No

    Detailed eKYC application custom information such as comparison result against the official data source. Only available when result.resultStatus is "S". Refer to the table below for details.



    extra information Specification 

    Name

    Fields Key

    Description

    Is mandatory if ekyc is successful

    extBasicInfo 

    certType

    ID type.

    Yes

    certNo

    ID number.

    Yes

    certName

    ID name.

    Yes

    extFaceInfo

    ekycResultFace

    Face factor result. Success, Pending or Failure.

    Yes

    faceScore

    Score of live face (selfie) against face on the ID.

    Yes

    faceImg

    Base64 of the face selfie image if isReturnImage in the request is Y.

    No

    faceQuality

    Face quality result score.

    Yes

    faceLivenessResult

    Face liveness check result: Success or Failure.

    Yes

    extIdInfo

    ekycResultDoc

    ID factor result: Success, Pending or Failure.

    Yes

    docEdition

    Edition of the ID. 

    Yes

    frontPageImg

    Base64 of the front page ID image if isReturnImage in the request is Y.

    No

    backPageImg

    Base64 of the back page ID image (if any) if isReturnImage in the request is Y.

    No

    ocrResult

    OCR result extracted by algorithm. It is a map. Refer below for the detailed info. Detailed content is specific to project.

    Yes

    spoofResult

    Anti-spoof result. It is a map. Refer below for the detailed info.

    No

    securityFeaturesResult

    securityFeatures result.It is a map. Refer below for the detailed info.

    No

    docErrorDetails

    ID error details. Possible value includes:

    • NO_REQUIRED_ID
    • BLUR
    • NO_FACE_DETECTED
    • NOT_REAL_DOC
    • EXPOSURE
    • UNKNOWN

    No

    extRiskInfo

    ekycResultRisk

    Risk factor result of the eKYC application: Success, Pending or Failure.

    Yes

    strategyPassResult

    Result of the risk check: PASS, VELOCITY_HIGH_RISK or ID_NETWORK_HIGH_RISK.

    Yes

    idNetworkDetails

    Detailed information of the IdNetwork output, available if IDNETWORK_RESULT is present but not Success.

    No

    extCustomInfo



    No


    The value range of "resultCode" at business level: 

    resultCode

    Description

    SUCCESS

    Success.

    INVALID_ARGUMENT

    Invalid argument.

    SYSTEM_ERROR

    System error.

    #

    #Spoof Result

    Spoof result values further explanation


    Name

    Type

    Mandatory

    Value Range

    Description

    Sample Value

    TAMPER_CHECK

    String

    Yes

    "Y": check passes

    "N": check fails

    Check whether an ID is tampered.

    Y

    MATERIAL_CHECK

    String

    Yes

    "Y": check passes

    "N": check fails

    Check whether an ID's material is correct.

    Will return false if ID is black and white.

    Y

    SCREEN_RECAPTURE_CHECK

    String

    Yes

    "Y": check passes

    "N": check fails

    Check whether the ID image is taken from screen.

    Y

    OTHER_CHECK

    String

    Yes

    "Y": check passes

    "N": check fails

    Check whether the ID image is taken from other.

    Y


    #SecurityFeatures Result


    docType

    security feature example

    fields

    08520000001


    image.png

    (The sample image comes from https://www.smartid.gov.hk/en/Development-of-Hong-Kong-Identity-Cards/index.html)

    1.Optical Variable Ink

    OPTICAL_VARIABLE_INK_SCORE: 70

    OPTICAL_VARIABLE_INK_THRESHOLD: 60

    OPTICAL_VARIABLE_INK_PASSED: True

    2. Multiple Laser Image

    MULTIPLE_LASER_IMAGE_SCORE: 95

    MULTIPLE_LASER_IMAGE_THRESHOLD: 90

    MULTIPLE_LASER_IMAGE_PASSED: True

    3. Kineprint

    KINEPRINT_SCORE: 85

    KINEPRINT_THRESHOLD: 77

    KINEPRINT_PASSED: True

    Overall:

    OVERALL_SCORE: 95

    OVERALL_THRESHOLD: 90

    OVERALL_PASSED: True

    08520000002

    image.png

    (The sample image comes from https://www.smartid.gov.hk/en/Development-of-Hong-Kong-Identity-Cards/index.html)

    1. Laser Image1

    LASER_IMAGE_1_SCORE

    LASER_IMAGE_1_THRESHOLD

    LASER_IMAGE_1_PASSED

    2. Hologram

    HOLOGRAM_SCORE

    HOLOGRAM_THRESHOLD

    HOLOGRAM_PASSED

    3. Stereo Laser Portrait

    STEREO_LASER_PORTRAIT_SCORE

    STEREO_LASER_PORTRAIT_THRESHOLD

    STEREO_LASER_PORTRAIT_PASSED

    4. Laser Image 2

    LASER_IMAGE_2_SCORE

    LASER_IMAGE_2_THRESHOLD

    LASER_IMAGE_2_PASSED

    Overall:

    OVERALL_SCORE

    OVERALL_THRESHOLD

    OVERALL_PASSED



    #Support DocType and Return OCR Result Key

    Country/Region

    Name

    docType

    pages

    ocr result key

    All countries

    Passport

    00000001003

    1

    LAST_NAME

    FIRST_NAME

    ID_NUMBER

    COUNTRY

    SEX

    DATE_OF_BIRTH

    PhilippinesUMID

    00630000001

    1

    ID_NUMBER

    LAST_NAME

    FIRST_NAME

    MIDDLE_NAME

    SEX

    DATE_OF_BIRTH

    Philippines

    TIN00630000002

    1

    ID_NUMBER

    LAST_NAME

    FIRST_NAME

    DATE_OF_BIRTH

    PhilippinesDriver’s License00630000004

    1

    ID_NUMBER

    LAST_NAME

    FIRST_NAME

    MIDDLE_NAME

    SEX

    DATE_OF_BIRTH

    PhilippinesPHILHEALTH00630000024

    1

    ID_NUMBER

    LAST_NAME

    FIRST_NAME

    MIDDLE_NAME

    DATE_OF_BIRTH

    PhilippinesSSS

    00630000020

    1

    ID_NUMBER

    LAST_NAME

    FIRST_NAME

    MIDDLE_NAME

    DATE_OF_BIRTH

    Malaysia MyKad00600000001

    2

    ID_NUMBER

    NAME

    DATE_OF_BIRTH

    Indonesia

    eKTP00620000001

    1

    ID_NUMBER

    NAME

    DATE_OF_BIRTH

    HK

    Current HKID08520000001

    1

    NAME

    NAME_CN

    SEX

    DATE_OF_BIRTH

    ISSUE_DATE

    LATEST_ISSUE_DATE

    ID_NUMBER

    SYMBOLS

    CHINESE_COMMERCIAL_CODE

    HK

    New HKID08520000002

    1

    NAME

    NAME_CN

    SEX

    DATE_OF_BIRTH

    ISSUE_DATE

    LATEST_ISSUE_DATE

    ID_NUMBER

    SYMBOLS

    CHINESE_COMMERCIAL_CODE

    Macao

    Identity Card08530000001

    2

    ID_NUMBER

    PLACE_OF_BIRTH

    SEX

    CNAME1

    CNAME2

    PNAME1

    PNAME2

    DATE_OF_EXPIRE

    DATE_OF_BIRTH

    Bengal

    NID/SmartCard08800000001

    2

    ID_NUMBER

    BNAME_M

    BNAME_F

    BNAME

    BNAME_H

    DATE_OF_BIRTH

    NAME

    China

    Identity Card

    00860000001

    2

    ID_NUMBER

    FULL_NAME

    SEX

    DOB

    RACE

    PLACE_OF_PERMANENT

    PROVINCE

    CITY

    EXPIRY_DATE

    ISSUE_ORGANIZATION


    ZOLOZ Team