RealId APIs

2020-10-23 03:43

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	Add productLevel and operationMode at the request of the initialize API Response fields adjustment of the CheckResult API
27 December, 2019	1.2.0	Renamed productLevel to serviceLevel of the initialize API and updated the description. replaced envData.envName with wirelessConfigGroup of the initialize API. changed variable naming case of the checkResult API.
21 May，2020	1.3.0	Current HKID，New HKID OCR Result Key add SYMBOLS. SpoofResult add key OTHER_CHECK. 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_SUSPEND	The 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

(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

(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
Philippines	UMID	00630000001	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME SEX DATE_OF_BIRTH
Philippines	TIN	00630000002	1	ID_NUMBER LAST_NAME FIRST_NAME DATE_OF_BIRTH
Philippines	Driver’s License	00630000004	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME SEX DATE_OF_BIRTH
Philippines	PHILHEALTH	00630000024	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME DATE_OF_BIRTH
Philippines	SSS	00630000020	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME DATE_OF_BIRTH
Malaysia	MyKad	00600000001	2	ID_NUMBER NAME DATE_OF_BIRTH
Indonesia	eKTP	00620000001	1	ID_NUMBER NAME DATE_OF_BIRTH
HK	Current HKID	08520000001	1	NAME NAME_CN SEX DATE_OF_BIRTH ISSUE_DATE LATEST_ISSUE_DATE ID_NUMBER SYMBOLS CHINESE_COMMERCIAL_CODE
HK	New HKID	08520000002	1	NAME NAME_CN SEX DATE_OF_BIRTH ISSUE_DATE LATEST_ISSUE_DATE ID_NUMBER SYMBOLS CHINESE_COMMERCIAL_CODE
Macao	Identity Card	08530000001	2	ID_NUMBER PLACE_OF_BIRTH SEX CNAME1 CNAME2 PNAME1 PNAME2 DATE_OF_EXPIRE DATE_OF_BIRTH
Bengal	NID/SmartCard	08800000001	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