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