Face Capture APIs

2021-04-15 14:55

API Overview

This page provides the capability of face capturing in client mode, along with the face liveness detection results.

Please refer to the ZOLOZ Gateway Document for the correct way of invocation.

API Name	Description
v1.zoloz.facecapture.initialize	This initializes a capture session between ZOLOZ SDK and ZOLOZ server, and will return a transaction ID which shall be used in subsequent interactions.
v1.zoloz.facecapture.checkresult	This is to retrieve the Face Capture results, including the image itself from ZOLOZ.

initialize

Request Sample

copy
{
    "bizId":"test-bizId",
    "metaInfo": "{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}",
    "merchantUserId": "not mandatory"
}

Request Fields Specification

Name	Type	Max Length	Mandatory	Description	Sample Value
bizId	string	32	true	business unique ID for tracing purpose	"abc-1234"
metaInfo	string	512	true	meta info from zoloz SDK
merchantUserId	string	32	false	user id from merchants	"abc-1234"

The value range of "result.resultCode" at business level:

resultCode	Description
SUCCESS	success
SYSTEM_ERROR	other internal errors
INVALID_ARGUMENT	input parameters are illegal
DEVICE_NOT_SUPPORT	device type is not supported
SDKVERSION_NOT_SUPPORT	sdk version is not supported
OS_NOT_SUPPORT	os is not supported
HIGH_RISK	high risk cases, cooled down by strategy

Response Sample

copy
{
  "clientCfg":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "transactionId": "G00000000192c672ce7cacf18dbeb6b4d3da8760f0"
}

checkresult

Request Sample

copy
{
    "bizId":"test-bizId",
    "transactionId":"G0000000012df8e84a8eb1e81706817c7038eaddbe"
}

Request Fields Specification

Name	Type	Max Length	Mandatory	Description	Sample Value
bizId	string	32B	false	business unique ID for tracing purpose	"abc-1234"
transactionId	string	64B	true	the unique id for tracing each transaction	"abc-1234"

Response Sample

copy
{
  "extInfo": {
    "imageContent": "base64string.....",
    "faceAttack": false,
    "rect": {
      "top": 233,
      "left": 165,
      "bottom": 479,
      "right": 410
    },
    "quality": 97.61517973846627
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "transactionId": "G0000000012df8e84a8eb1e81706817c7038eaddbe"
}

Response Fields Specification

Name	Type	Mandatory	Description	Sample Value
extInfo.imageContent	string	false	base64 string of captured image
extInfo.faceAttack	boolean	false	liveness check result	false
extInfo.rect	map	false	coordinate of face
extInfo.quality	double	false	image quality score	88.8
result	CommonResult	true	gateway common result, please refer to appendix
transactionId	string	true	the unique id for tracing each transaction	"abc-1234"