APIs in Face Authentication flow

Face Authentication (hereafter referred to as Face Authen) is a flow that re-verifies the current user by their face. It is used for transactions or actions that require certainty that the person performing them is a real, live person and is the rightful owner of a previously identified profile.

This flow differs from the eKYC flow used for first-time identification: Face Authen does not read identity documents (OCR/NFC). Instead, it matches the user's face at the time of the transaction against a face image or face vector (a numeric representation of the face) that has been verified and stored in the customer's system.

For each verification, the FPT AI eKYC system performs 2 checks in a single request:

• Liveness check: determines whether the face in the selfie image or video belongs to a real person in front of the camera, and not a printed photo, a photo or video replayed on a screen, a mask, or a synthetically generated face.
• Face matching: compares the face just captured with the face image or vector stored for the user, and returns whether they match along with a similarity score (similarity).

Typical use cases

• High-value money transfers or payments: the user must verify their face before the transaction is executed.
• Confirming the rightful owner of a profile at important steps after identification, for example after application submission, at contract delivery, or when completing additional review steps.
• Periodic verification of users who have been identified before (for example agents or sales partners), to make sure the account is still used by the right person.
• Other sensitive actions where the customer wants an additional biometric verification layer on top of existing measures such as passwords or SMS OTP.

Prerequisites

• The user already has a verified face image or face vector stored in the customer's system (usually collected during the first eKYC, for example the portrait photo on the document chip).
• The moment Face Authen is triggered (for example, when a transaction exceeds a certain amount) is decided by the customer's system. The FPT AI eKYC system only processes the request when it receives a verification call.

Example business flow for a transaction

1. The user enters a transaction in the customer's application.
2. The application checks whether the transaction requires Face Authen and whether the user already has a stored face.
3. If required, the application calls the SDK or API so that the user takes a selfie or records a video; FPT AI eKYC performs the liveness check and face matching.
4. If the verification succeeds, the application proceeds to the next step of the customer's own process (for example confirmation by SMS OTP) and completes the transaction.
5. If it fails, the user may retry within the same session until the allowed number of attempts is used up; beyond that number, the application ends the flow and returns the user to the previous screen.

These APIs include:

• Session initialization API
• Liveness check and face matching API

Base URL:

• Staging: https://api.fpt.ai/vision/ekyc/biometrics-be-stag
• Production: https://api.fpt.ai/vision/ekyc/biometrics-be

Sequence diagram of API calls in the Face Authentication flow

1. Init session API

1.1. Request Url

POST base_url/biometric/init

1.2. Request Headers

Parameter	Required	Default	Description
api-key	Yes		Your API key to authorize to the system of FPT AI eKYC
client_uuid	No		The UUID generated by customer's system to manage eKYC session
device-type	Yes		Your device, values including: android, ios, web-sdk
lang	No		Using language, values including: en, vi
sdk-version	No		Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

1.3. Request Sample

curl --location --request POST 'base_url/biometric/init' \
--header 'api-key: your-api-key' \
--header 'device-type: android' \
--header 'client_uuid: your-uuid' \
--header 'lang: vi'

1.4. Response

1.4.1. Response Sample

Succeeded: http_code = 200

{
    "code": "200",
    "message": "success",
    "session-id": "tsan_ekyc__ef1e2944-91b0-4506-8a1a-8f39a80b309c",
    "sdk_config": {
        "is_show_ekyc_result": true,
        "liveness_type": 1,
        "show_guide": 3,
        "disable_liveness": false,
        "show_switch_button": 1,
        "limit": 5,
        "font_path": {
            "regular": "",
            "medium": "",
            "bold": ""
        }
    }
}

Failed: http_code != 200

1.4.2. Response Description

Parameter	Data type	Description	Note
code	string	Response status of the request	200: Success
message	string	Error message (if any)	200: Success; 401: Unauthorized; 403: Forbidden; 504: Gateway Timeout; 500: Internal Server Error
session-id	string	The UUID of eKYC session generated by eKYC Backend. Then, this session-id must be sent in headers of all following requests in the same session
sdk_config	string	The current configuration of eKYC flow

2. Face Liveness and Face Match API

2.1. Request Url

POST base_url/biometric/verify

2.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Yes	string	Session id get from init session request
api-key	Yes	string	Your API key to authorize to the system of FPT AI eKYC
auto	Yes	string	Set value to True when call from FPT SDK. Otherwise, False
device-type	Yes	string	Your device, values including: android, ios, web-sdk
lang	optional	string	Using language, values including: en, vi	default: en
sdk-version	optional	string	Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

2.3. Request Body

FormData containing the selfies image or video to query.

Parameter	Required	Type	Description
selfies	No. Using selfies or video	Array	Selfie image captured to check liveness and do face matching
video	No. Using selfies or video	File	Selfie video captured to check liveness and do face matching
cmnd	No. Using cmnd or vector	File	File of authenticated user's face stored in the system. This file is used to do face matching
vector	No. Using cmnd or vector	File	Vector of authenticated user's face image stored in the system. This vector is used to do face matching

2.4. Request Sample

curl --location --request POST 'base_url/biometric/verify' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'lang: vi' \
--form 'selfies=@"path-to-selfie-image"' \
--form 'vector="..."'

2.5. Response

2.5.1. Response Sample

Succeeded

{
    "code": "200",
    "message": "Kiểm tra thực thể sống thành công",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "200",
        "message": "face matching successful",
        "isMatch": "true",
        "similarity": "95.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

2.5.2. Response Description

Fields	Types	Description	Note
code	String	Response status code of the request. Code 200 means request success. Details can be found in the document error code
message	String	Error message of the request (if any). Language of message is set by parameter lang in headers
liveness	Object	returned liveness result
face_match	Object	returned face match result
is_complete_session	boolean	Define whether session is completed. If False, user can retry with face verify, otherwise, users have to try with another session

2.5.3. Response Error Samples

{
    "code": "303",
    "message": "Khuôn mặt không khớp với giấy tờ",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "303",
        "message": "face is not matching with document",
        "isMatch": "false",
        "similarity": "5.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

{
    "code": "407",
    "message": "2 faces exist",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "407",
        "message": "2 faces exist",
        "isMatch": "N/A",
        "similarity": "N/A",
        "warning": "N/A"
    },
    "is_complete_session": false
}