ZOLOZZOLOZDOCS

      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