H5-Lite_Pro-Callbacks

Return_url and Notify_url

The return_url and notify_url that you use in the GetToken method will be invoked after the FaceID Lite face comparison is complete.

• return_url: You can configure action_http_method to choose the POST or GET callback method. This is invoked by redirecting to the page.
• notify_url: The callback method is POST. This is invoked by the FaceID server. For security reasons, the FaceID verification service only supports ports 443, 5000, 16003, 8883, and 8028 for server callbacks (if the callback URL does not use HTTPS, we recommend that you use a signature to verify the request).

1、 POST callback requests contain form data, including the following fields.

Field	Type	Description	Example
data	String	The return value of face comparison (JSON). For details, see the "Return value" section.
sign	String	The signature of the data. The signature is calculated by using the formula sign = sha1(API_SECRET + json_data), where the characters returned by sha1 are lowercase.	ac041f49940c5afb2640a251633a8029ae69c1d5

Return value example

Return value	Type	Description	Example	return_url	notify_url
status	String	The status of FaceID Lite. Valid values: NOT_STARTED: The do method is not called after get_token. PROCESSING: The FaceID Lite verification is in progress. WEBRTC_UNSUPPORTED: This indicates that the browser is not supported, which leads to a failed verification. OK: The FaceID Lite verification is completed (OK indicates that the process is completed properly and does not indicate that the user passes the verification). FAILED: The verification process is incomplete or an error has occurred. CANCELLED: The user has canceled the verification process. TIMEOUT: The process has timed out.	"OK"	√	√
fail_reason	String	If "get_fail_reason" is set to 1, the value of this field indicates the reason for the "WEBRTC_UNSUPPORTED" failure.   •NETWORK_ERROR: Network connection issue.   •PERMISSIONS_ERROR: The user has denied the camera permission or the browser (app) cannot use the camera.   •SUPPORT_ERROR: The browser does not support WebRTC APIs or other compatibility issues.	"NETWORK_ERROR"	√	√
biz_info	JSON	This field contains biz_id, biz_no, and biz_extra_data.   •biz_id: The business ID used to query comparison results.   •biz_no: The serial number of the customer business, which is returned in notify and return.   •biz_extra_data: The additional data returned when notify_url and return_url are invoked. You can use this to pass additional information.	{ "biz_extra_data": "...", "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1", "biz_no": "cc47190f-502-44a2-ab74-ea4f0f649f61" }	√	√
liveness_result	JSON	The result of the liveness detection. If the user cancels the liveness detection process before it is completed, this field is not returned.   •result: The result of the liveness detection. Valid values:     PASS: The user passes the liveness check.     FAIL: The user fails to pass the liveness check.   •procedure_type: The method of the liveness detection. Valid values:     flash:Flash-based liveness detection.     still: Passive liveness detection with a video selfie.   •details: The detailed result of the liveness detection. Fields include:     If procedure_type is "flash":       FACE_NOT_FOUND: The number of times where no face is detected       SIDE_FACE:The number of times where the user does not face the screen (tilting to the side).       UPDOWN_FACE:The number of times where the user does not face the screen (tilting upward or downward)       EYE_OCCLUSION: The number of times where the user's eyes are covered       MOUTH_OCCLUSION: The number of times where the user's mouth is covered       AWAY_FROM_CAMERA: The number of times where the user is too far away from the camera       CLOSE_TO_CAMERA: The number of times where the user is too close to the camera       FACE_OUT_OF_CAMERA: The number of times where the user's face is out of view       HIGH_BRIGHTNESS: The number of times where the lighting is too bright       LOW_BRIGHTNESS: The number of times where the lighting is too dark       LOW_FACE_QUALITY:The number of times where the face quality of the video is too low     If procedure_type is "distance":       FACE_NOT_FOUND: The number of times where no face is detected       SIDE_FACE:The number of times where the user does not face the screen (tilting to the side).       UPDOWN_FACE:The number of times where the user does not face the screen (tilting upward or downward)       EYE_OCCLUSION: The number of times where the user's eyes are covered       MOUTH_OCCLUSION: The number of times where the user's mouth is covered       AWAY_FROM_CAMERA: The number of times where the user is too far away from the camera       CLOSE_TO_CAMERA: The number of times where the user is too close to the camera       FACE_OUT_OF_CAMERA: The number of times where the user's face is out of view       HIGH_BRIGHTNESS: The number of times where the lighting is too bright       LOW_BRIGHTNESS: The number of times where the lighting is too dark       LOW_FACE_QUALITY:The number of times where the face quality of the video is too low     If procedure_type is "still":       UPLOAD_TIMES: The number of video uploads       FACE_NOT_FOUND: The number of times where no face is detected in the video       LOW_FACE_QUALITY: The number of times where the face quality of the video is too low        INVALID_VIDEO_DURATION: The number of times where the video duration is invalid        SR_ERROR: The number of times where voice recognition results are incorrect (ignore this for passive liveness detection)        NOT_SYNCHRONIZED: The number of times where lip reading results are incorrect (ignore this for passive liveness detection)       NO_AUDIO: The number of times where the video has no sound       VIDEO_FORMAT_UNSUPPORTED: The number of times where the video format is invalid       VIDEO_FACE_INCONSISTENT: Face inconsistencies in the video   •face_genuineness: This identifies spoof attacks with four sets of confidence scores and thresholds ranging from 0 to 1. If a confidence score is greater than its threshold, a spoof attack in that category is identified.     synthetic_face_confidence: The confidence score for synthetic faces     synthetic_face_threshold: The threshold for synthetic faces     mask_confidence: The confidence score for masks     mask_threshold: The threshold for masks     screen_replay_confidence: The confidence score for screen replays     screen_replay_threshold: The threshold for screen replays	{ "result": "PASS/FAIL", "procedure_type": "still", "details": { "UPLOAD_TIMES": 5, "FACE_NOT_FOUND": 0, "LOW_FACE_QUALITY": 0, "INVALID_VIDEO_DURATION": 1, "SR_ERROR": 2, "NOT_SYNCHRONIZED": 1, "VIDEO_FORMAT_UNSUPPORTED": 0, "NO_AUDIO": 0 }, "face_genuineness": { "synthetic_face_confidence": 0.88, "synthetic_face_threshold": 0.5, "mask_confidence": 0.32, "mask_threshold": 0.5, "screen_replay_confidence": 0, "screen_replay_threshold": 0.5 } }	√	√
verify_result	JSON	The result of the face comparison. If the user interrupts the process of liveness check midway or the comparison_type selected by the user is -1, this field will not be returned.   •error_message: The error that occurs during face comparison. Valid values:     null: No error has occurred.NO_FACE_FOUND: No face detected in the image. Fees are incurred even if this error has occurred.     DATA_SOURCE_ERROR: An error has occurred while comparing data. Generally, this indicates a data error. If this error occurs, please stop the service and contact FaceID customer service or business support. Wait until this issue is addressed to start the service again.     INTERNAL_ERROR: Internal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support.   •result_ref[x]: The comparison result between the face collected in liveness detection and the uploaded image_ref[x].     "confidence": The overall confidence score ranging from 0 to 100 in float. A larger number indicates a lower risk.     "thresholds": A set of reference thresholds for the confidence score. The value of this field is an object and contains the following four float fields that range from 0 to 100.       "1e-3": The confidence threshold for a risk level of one in a thousand.       "1e-4": The confidence threshold for a risk level of one in ten thousand.       "1e-5": The confidence threshold for a risk level of one in a hundred thousand.       "1e-6": The confidence threshold for a risk level of one in a million.   •verify_time: The timestamp of the verification in seconds. This field is returned only if return_verify_time=1.	{ "verify_time": 1462259763, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } } }	√	√
multifaces_tag	String	This field is returned only if the return_multifaces_tag parameter is 1.   •0: A single face.   •1: Multiple faces.	"0" (A single face.)	√	√

2. For GET callbacks, the biz_id parameter is attached to the return_url, and you can use the biz_id in the URL as the parameter for get_result.

such as

1.https://yourdomainname/xxx?biz_id=xxx

2.https://yourdomainname/xxx?xxx=xxx&biz_id=xxx

3.https://yourdomainname/xxx?biz_id=xxx&xxx=xxx#xxx

Parameter	Type	Description	Example
biz_id	String	The liveness detection business ID returned by get_token.	"1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1"