Các API của luồng chuyển tiền

• Tài liệu này mô tả các API của luồng chuyển tiền (luồng xác định người dùng hiện tại với thông tin đã lưu trong hệ thống) của hệ thống FPT AI eKYC. Các API của luồng này bao gồm:

  • API khởi tạo phiên
  • API kiểm tra liveness và so khớp khuôn mặt

• Base URL:

  • Môi trường Staging: https://api.fpt.ai/vision/ekyc/biometrics-be-stag
  • Môi trường Production: https://api.fpt.ai/vision/ekyc/biometrics-be

• Sơ đồ tuần tự gọi các API trong luồng chuyển tiền

sequenceDiagram
    participant API Caller/Web SDK
    participant Proxy Server
    participant Customer Database
    participant eKYC Backend

    API Caller/Web SDK->>Proxy Server: POST /init_session (Khởi tạo phiên sinh trắc)
    Proxy Server->>eKYC Backend: POST /biometric/init
    eKYC Backend-->>Proxy Server: Trả về session_id
    Proxy Server-->>API Caller/Web SDK: Trả về session_id

    API Caller/Web SDK->>Proxy Server: POST /dmp/liveness/v3 (Gửi yêu cầu kiểm tra liveness & so khớp)
    Proxy Server->>Customer Database: Lấy ảnh selfie khách hàng
    Customer Database-->>Proxy Server: Trả về ảnh selfie

    Note over Proxy Server: Chèn ảnh selfie vào body request

    Proxy Server->>eKYC Backend: POST /biometric/verify (Gửi kèm ảnh từ DB và ảnh chụp liveness)
    eKYC Backend-->>Proxy Server: Trả về kết quả đối chiếu
    Proxy Server-->>API Caller/Web SDK: Trả về kết quả

1. API khởi tạo phiên

1.1. Request Url

POST base_url/biometric/init

1.2. Request Headers

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
api-key	Có		API key để sử dụng hệ thống FPT AI eKYC
client_uuid	Không		UUID sinh ra từ hệ thống của khách hàng để tự quản lý phiên eKYC
device-type	Có		Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk
lang	Không	vi	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: en vi
sdk-version	Không	vi	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

1.3. Mẫu request

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. Mẫu response

• Thành công: 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": ""
            }
    }
}

• Thất bại: http_code != 200

1.4.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
code	String	Mã trạng thái trả về của yêu cầu	200: Thành công
message	String	Thông báo lỗi trả về (nếu có)	200: Thành công 401: Lỗi xác thực 403: Lỗi dùng sai session-id 504: Lỗi kết nối hệ thống 500: Lỗi server hệ thống
session-id	String	Mã ID duy nhất của phiên eKYC được sinh ra bởi eKYC Backend. session-id sau đó phải được gửi kèm trong headers của tất cả các request trong cùng phiên
sdk_config	String	Cấu hình hiện tại của luồng eKYC

2. API kiểm tra liveness và so khớp khuôn mặt

2.1. Request Url

POST base_url/biometric/verify

2.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Có	String	ID duy nhất của phiên eKYC nhận được từ bước khởi tạo phiên
api-key	Có	String	PI key để sử dụng hệ thống FPT AI eKYC
auto	Có	String	Đặt giá trị là True khi gửi từ FPT SDK. Nếu không phải đặt False
device-type	Có	String	Thiết bị đang sử dụng, các giá trị cho phép bao gồm: android ios web-sdk
lang	Không	String	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: en vi	default: en
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

2.3. Request Body

FormData chứa ảnh hoặc video selfie sử dụng để kiểm tra.

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
selfies	Không. Sử selfies hoặc video	Array	Ảnh selfie được thu thập để kiểm tra liveness và thực hiện face matching
video	Không. Sử selfies hoặc video	File	Video selfie được thu thập để kiểm tra liveness và thực hiện face matching
cmnd	Không. Sử dụng cmnd hoặc vector	File	File ảnh khuôn mặt của người dùng đã được xác thực lưu trong hệ thống của khách hàng. Ảnh này sẽ được dùng để thực hiện face matching
vector	Không. Sử dụng cmnd hoặc vector	File	Vector khuôn mặt của người dùng đã được xác thực lưu trong hệ thống của khách hàng. Vector này sẽ được dùng để thực hiện face matching

2.4. Mẫu request

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. Mẫu response thành công

{
    "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. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
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 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. Mẫu response lỗi

{
    "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
}