APIs in money-transfering flow

• This document describes the APIs of the money transfer flow (the flow to identify the current user with information stored in the system) of the FPT AI eKYC system. 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 money transfer 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

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

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
}