Liveness Detection H5

Liveness detection HTML5 (H5) version, is a critical security feature designed to thwart spoofing attacks during digital authentication processes.

This technology is employed in various web and mobile applications to ensure that the entity attempting access is a live human being rather than a photograph, video, mask, or another form of replicated biometric attack.

The liveness detection H5 leverages the capabilities of modern web browsers, allowing seamless integration into online platforms without the need for additional plugins or software installations. It utilizes sophisticated algorithms that analyze real-time video feeds for subtle movements, texture, and other indicators of physical presence.

Throughout the process, end users are instructed to perform gestures based on prompts like "open your mouth" and "blink your eyes." The outcome of the liveness detection could be retrieved from the backend, and a selfie is provided if it detects a live person.

Integration Steps

There are 3 steps to integrate H5 Liveness Detection:

  1. Use the "Retrieve token API" to configure redirect URLs and other settings, which will generate the liveness detection token and H5 liveness detection URL.
  2. The user completes the liveness detection process through the H5 liveness detection URL, and redirected to success and failure web page URL.
  3. Use the "Retrieve result API" to obtain a selfie if the liveness detection is successful, or receive detailed results in case of failure.

1.Retrieve token API

Base URL

API

URLRequest MethodsContent TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
partner_keyStringPartner KeyRequiredAssigned by TD

Request

ParameterTypeDescriptionRequired/OptionalNotes
success_redirectStringPage redirected after successful liveness detectionRequired
failure_redirectStringPage redirected after liveness detection failureRequired
languageStringPage prompt language
Enumeration value:
en: English
id: Indonesian
es: Espanol
ar: Arabic
tl: Filipino
ko: Korean
pt: Portuguese
ru: Russian
th: Thai
tr: Turkish
vi: Vietnamese
zh-Hans: Simplified Chinese
zh-Hant: Traditional Chinese
Optional1. If a specific language is specified, it will display the prompt in that language.

2. If no language is specified, it will retrieve the browser's language and display the corresponding language prompt.3. If the language is not retrieved in Step 2, or in other exceptional circumstances, it will display the prompt in English (en) as default.
audioBooleanPlay action prompt audioOptionalDefault false.

If set to true:

1. Play the corresponding prompt sound based on the language result.
2. If the language is not retrieved in Step 1, or in other exceptional circumstances, it will play the English prompt sound as default.Currently, we support audios in the following languages: English, Spanish, and Indonesian.

Response Parameters

ParameterTypeDescriptionNotes
codeIntegerAPI status codePlease refer to below API Code list
messageStringStatus Information Detailed reasons will be provided about API status
sequence_idStringUnique response codeA unique ID used to track each request
tokenStringLiveness detection tokenThe token is used to generate the liveness detection URL and to subsequently query the result of this liveness detection process.
urlStringLiveness detection urlThe H5 liveness detection URL will be provided, incorporating any necessary redirect URLs and configurations in the following format:
https://static.tongdun.net/liveness/index.html#/progress?code=token&success_redirect=[successURL]&failure_redirect=[failureURL]&language=xx&audio=true&

Response Example

  • Request

    {
    	"success_redirect": "http://www.google.com",
    	"failure_redirect": "http://www.facebook.com",
    	"language": "en",
    	"audio": true
    }
    
  • Success

{
    "code": 200,
    "message": "success",
    "sequence_id": "17119500882*****29",
    "token": "a41701e4-b2a2-4f62-8cd4-9******3",
    "url": "https://static.tongdun.net/liveness/index.html#/progress?code=a41701e4-b2a2-4f62-8cd4-9******3&success_redirect=http%3A%2F%2Fwww.google.com&failure_redirect=http%3A%2F%2Fwww.facebook.com&language=en&audio=true&"
}
  • Failed
{
    "code": 11350,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Internal error"
}

2.Liveness detection and page redirection

After completing the liveness detection, the page will automatically redirect to the callback page configured by the customer: either the success page [successURL] or the failure page [failureURL].
Callback page URL examples:
● Successful callback example: [successURL]?code=7ac3a964-f540-4aa2-acdf-59ea1639572e&state=0
● Failed callback example: [failureURL]?code=7ac3a964-f540-4aa2-acdf-59ea1639572e&state=2

When the page is redirected, if the customer's callback page receives the parameter "state" with a value of 0 or 2 after the completion of liveness detection, it can proceed to call the API to retrieve the result of the liveness detection. For other values of "state" besides 0 or 2, please refer to the following explanation and suggestions.

Return Value "state"MeaningSuggestions for Subsequent Processes
0Passing liveness detectionCall the API to retrieve the liveness detection results
2Failing liveness detection is usually indicative of a spoofing attemptCall the API to retrieve the liveness detection results
Based on risk preferences, decide whether to initiate liveness detection again (retrieve token)
3Invalid token indicates that the token obtained in the previous steps has already been usedInitiate liveness detection again. Please ask the user to retry
4Unable to open the camera The camera cannot be opened. Please proceed with an alternative verification method, such as manual processing
5, 6Network issueInitiate liveness detection again. Please ask the user to retry
OthersIn case the callback state status code is maliciously tampered with, for example, changed to state=8Based on risk preferences, choose to either terminate the process directly or initiate liveness detection again

3.Retrieve result API

Base URL

API

URLRequest MethodsContent TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
partner_keyStringPartner KeyRequiredAssigned by TD

Request

ParameterTypeDescriptionRequired/OptionalNotes
tokenStringLiveness detection tokenRequired

Response Parameters

ParameterTypeDescriptionNotes
codeIntegerAPI status codePlease refer to below API Code list
messageStringStatus InformationDetailed reasons will be provided about API status
sequence_idStringUnique response codeA unique ID used to track each request
imageStringLiveness Detection face imagesThe best selfie image captured during the liveness detection process, in base64 format.
Will only return if liveness detection is successful.

API Code

CodeMessageCharged
200success (live person)YES
12223No face detectedNO
12224Multiple faces have been detectedNO
12225Detection timeoutNO
12226Person change detectedNO
12227Token has been usedNO
12228User actively cancels liveness detection processNO
12229Liveness detection result not foundNO
12202Identified as a blink attackYES
12203Identified as a mouth movement attackYES
12204Identified as a partial face attackYES
12205Identified as a video replay attackYES
12206Identified as a black and white imageYES
12207Identified as a paper-based attackYES
12208Identified as a frame (including paper or phone frame)YES
12209Identified as a moire pattern attackYES
12210Identified as a face superiority attackYES
12211Identified as a paper-based attack (optical flow)YES
12212Identified as a mask attackYES
12213Identified as an ID card attackYES
12214Identified as a 3D mask attackYES
12215Identified as a synthetic image attackYES
12216Identified as a black-market software attackYES
12217Identified as a T-type mask attackYES
12218Identified as a blurry imageYES
12219Suspected deepfake image attackYES
12220Suspected high-resolution screen attackYES
12222Injection attackYES
12250Verification errorYES
11350Internal errorNO

Response Example

  • Request

    {
        "token":"a41701e4-b2a2-4f62-8cd4-9******3"
    }
    
  • Success

{
    "code": 200,
    "message": "Success",
    "sequence_id": "1711950327713613G109E0A081240931",
    "image": "/9j/4AAFbs64"
}
  • Failed
{
    "code": 11350,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Internal error"
}