Selfie Liveness Flow

Current Flow Version - v1.2

Available Since - 1 Mar 2026

Overview

Selfie Liveness is a sophisticated biometric security layer engineered to validate the physical presence of a legitimate user in real-time. By distinguishing between a live human face and synthetic or inanimate reproductions, it serves as a critical perimeter defense, ensuring that the individual engaging with your platform is a "live" participant and not a fraudulent actor utilizing stolen or generated media.

Key Features

	Technical Implementation	Organizational Impact
Guided Data Acquisition	Provides a dynamic overlay frame and real-time positioning feedback to ensure the card is perfectly aligned.	Minimizes user frustration and "drop-off" by guiding them to a successful scan on the first attempt.
Obstruction & Glare Detection	Actively detects and alerts users to physical obstructions (e.g., fingers covering fields) or environmental interference (e.g., light glare/reflections).	Prevents the ingestion of incomplete or illegible data, ensuring 100% field visibility for the extraction engine.
Intelligent Extraction	Utilizes Optical Character Recognition calibrated for Indonesian ID layouts to capture NIK, Name, and Address.	Enhances data integrity by eliminating human transcription errors.

High Level Flow

sequenceDiagram
    autonumber
    title High Level SDK Flow Overview

    participant PFE as Partner FE
    participant PBE as Partner Backend Service
    participant DIS as Digital Identity SDK

    box rgb(240, 240, 240) IAB Infra
        participant TG as Token Gateway
        participant IBE as IAB Gateway
    end

    rect rgb(230, 245, 255)
        Note over PFE, TG: Get Partner token
        PBE->>TG: Get Partner token (client_id, passkey)
        TG-->>PBE: Partner token
        Note over PBE: Cache Partner token
    end

    PFE->>DIS: Initialize Digital Identity SDK

    rect rgb(230, 245, 255)
        Note over PFE, IBE: Get User token
        PFE->>PBE: Call initiate flow API
        PBE->>IBE: Initiate Flow (partner token, user_details)
        IBE-->>PBE: User token
        PBE->>PFE: User token
    end

    rect rgb(235, 230, 255)
        Note over PFE, IBE: Capture image and Submission processing
        PFE->>DIS: launchSelfieLiveness(user token, correlationId, baseUrl)
        Note over DIS: Capture Image Screens

        rect rgb(255, 245, 230)
            Note over DIS, IBE: Submission Processing
            DIS->>IBE: Start Submission Processing
            Note over IBE: Submission Processing
            IBE-->>PBE: Get Reference Image (User Details)
            PBE-->>IBE: Reference Image (URL)
            Note over DIS: Status Polling
            DIS->>DIS: Do next action:<br/>- RETRY<br/>- STATUS<br/>- EXIT
        end

        DIS->>PFE: on Completion(success/failure)
    end

    rect rgb(230, 245, 255)
        Note over PFE, IBE: Get Result Details
        IBE->>PBE: Submission Processing Compete Callback
        PFE->>PBE: Call "Get Submission Details" API <br/>(correlationId aka partner session id)
        PBE->>IBE: Call "Get Submission Details" API (correlationId, partner token)
        IBE-->>PBE: return submission details
        PBE-->>PFE: Continue processing
    end

    Note over PFE: Show/process result

Detailed Steps:

Partner BE call "Get Partner Token API" through IAB Gateway and caches the Partner Token to be used repeatedly.
Partner FE calls Partner BE to get User Token. Partner BE calls IAB Gateway to get user Token using the Initiate Flow API.
1. Partner User Id
2. Partner User Id Type
3. Onboarding partner tied to the flow, which partner wants to launch.
Partner FE initializes the Digital Identity FE SDK (IAB FE):

Use the initialise method to initialize the SDK.
Partner FE calls launchSelfieLiveness() method of Digital Identity SDK to launch Selfie Liveness flow with the following parameters:
1. baseURL: This is the server URL specific to the partner using the format https\://<domain>. Example: https://onekyc.ky.id.sandbox.gopayapi.com
2. correlationId: A unique ID used to create a Selfie Liveness request and track the specific instance of the Selfie Liveness request helpful for logging and event tracking.
3. token: The unique user token, different for each user.
4. theme(optional): The theme parameter is optional, and its default value is null. If not provided, the SDK uses the default theme (DefaultOneKycSelfieLivenessFlowTheme). The theme parameter is an instance of the OneKycSelfieLivenessFlowTheme class. It allows you to customize the look and feel of the Selfie Liveness flow screen. By providing a custom theme, you can modify various UI elements, such as colors, fonts, and styles, to match your application's branding requirements.
IAB FE will capture users' selfies and will upload it to IAB Gateway for Liveness processing.
IAB Gateway initiates Liveness processing.
Meanwhile, the IAB FE will continuously poll the IAB Gateway to check the processing status and display a loader to the user until the process is complete.
Once the processing is complete, the IAB FE will redirect the user back to the Partner FE using the resultCallback(DocumentVerificationResult) method.

Integration Contracts

Document Name	Link
BE API Guide	BE API Guide
Web SDK Guide	Web SDK Guide
Android SDK Guide	Android SDK Contract
Flutter SDK Guide	Flutter SDK Contract
iOS SDK Guide	iOS SDK Contract

Updated 1 day ago