checkresult v1a

2023-09-08 09:52

POST /api/v1a/zoloz/facecapture/checkresult

The ZOLOZ Face Capture checkresult v1a API is an upgraded version of checkresult API. It can be used to request more information of the face capture process results. This API is idempotent.

Structure

Request parameters

Field name	Data type	Max Length	Description
bizId	String	32	Required. A unique business ID for tracing purpose. For example，the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness check on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID.
transactionId	String	64	Required. The unique transaction ID that is returned in the response of the initialize API.
isReturnImage	String	1	Optional. A flag that specifies whether the specified extra image data needs to be returned in the response. The following values are supported: `Y` : The image data needs to be returned in the response. `N` : The image data does not need to be returned in the response. By default, the value of `N` is used.
extraImageControlList	List<String>		Optional. Specify what extra images to be returned if isReturnImage is `Y`. To obtain extra images, specific service level is required for the initialize API. The following values are supported: `FACE_EYE_CLOSE`: return a face image with closed eyes. `CROPPED_FACE`: return an additional face image cropped from the original captured face image. Note: `FACE_EYE_CLOSE`only returns images at a specific serviceLevel (e.g. `FACECAPTURE0010`), see Face Capture initialize API. `CROPPED_FACE`only returns extra images if the cropFaceImage parameter is specified as `Y`, see Face Capture initialize API.

Response parameters

Field name	Data type	Description
result	Result	Required. The API request result, which contains information about the result of the API request, such as status and error codes.
extInfo	ExtInfo	Detailed face capture information. Refer to the table below for details. Optional. Detailed information about face capture. This field is only available when the value of the result.resultCode field is set to `SUCCESS`.
faceCaptureResult	string	Required. The result of the Face Capture process. States the actual results of each transaction in the form of `Success`/`Failure`/`VoidTimeout`/`InProcess` `Success`: Both face quality result and liveness detection have passed. `Failure`: There is a high risk present in this authentication and rejection is recommended. Face quality result or liveness detection has failed. `VoidTimeout`: Face capture results have not been obtained due to timeout. `InProcess`: Face capture results have not been obtained, still in progress.

Result

Result process logic

For different request results, different actions are to be performed. See the following for details:

If the value of the result.resultCode is SUCCESS, the ZOLOZ Face Capture checkresult API is invoked successfully, and results about face capture are returned.
Otherwise, the invocation of the ZOLOZ Face Capture checkresult API fails. Check the error code and message for more information about the possible reasons.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The following table shows the possible error codes that are specific for the Face Capture checkresult API.

resultCode	resultSatus	Description
SUCCESS	S	Success.
PROCESSING	S	Process is still ongoing, waiting for a face image to be uploaded.
INVALID_ARGUMENT	F	Input parameters are invalid. For more information about which parameters, check the result message or the related log.
UNUSABLE	F	The meta information that is returned from the ZOLOZ SDK does not pass the usability check, which indicates the user cannot use the face capture function.
SYSTEM_ERROR	F	Other internal errors. For more information about the error details, check the result message that is returned and the related log.
LIMIT_EXCEEDED	F	User has tried too many times within same transaction

Sample

Request Sample

The following sample shows what a request that the merchant server sends looks like.

copy

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G006600016CN20190114000000009572520355",
    "isReturnImage": "Y",
    "extraImageControlList": ["FACE_EYE_CLOSE"]
}

Response Sample

The following sample shows what a response that the ZOLOZ server returns looks like.

copy
{
  "faceCaptureResult":"Success",
  "extInfo": {
    "imageContent": "base64string.....",
    "faceAttack": false,
    "rect": {
      "top": 233,
      "left": 165,
      "bottom": 479,
      "right": 410
    },
    "quality": 97.61517973846627,
    "qualityPassed": true,
    "extraImages": { "FACE_EYE_CLOSE": "base64string....." }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

More information

ExtInfo

The following table shows the fields that can be specified in the ExtInfo data model.

Field name	Data type	Description
imageContent	string	Optional. The captured face image, which is encoded in base64.
faceAttack	boolean	Optional. Specifies whether the captured face image is detected as a fake face attack by using the face liveness check algorithm. If the image is not a fake face attack, the value of `false` is returned; otherwise, the value of `true` is returned; if qualityPassed is false, value `null` is returned.
rect	Map	Optional. The coordinate data of the face image, for exmaple: `{"top": 233,` `"left": 165,` `"bottom": 479,` `"right": 410}`
quality	double	Optional. The quality score of the image. The value of this field is in the range of 0-100.
qualityPassed	boolean	Required. The total quality result of the image which will be returned in the form of `true` or `false`. Face quality detection supports multiple algorithms for detection, including face quality score, mask detection, and occlusion detection. Face quality score (i.e. whether the face is clear, complete etc) is detected by default, and more algorithms can be enabled according to business needs. `true`: The quality detection has passed. `false`: The quality detection has failed. For example, the image may have been blurred, obscured by something, etc.
extraImages	Map<String,String>	Optional, extra image only available if isReturnImage and extraImageControlList are specified in the request. Contain the extra face images specified in request.extraImageControlList. Key is the value specified in request.extraImageControlList. Value is the image content encoded in base64. If the requested image is not found, the value will be "".