Face Verification Flow

Current Flow Version - v1.2

Available Since - 1 Mar 2026

Overview

Face Verification is a comprehensive biometric security layer engineered to deliver rigorous identity assurance without compromising on a seamless user experience. By consolidating two critical technologies Passive Liveness Detection and 1:1 Face Matching into a single, synchronized workflow, this solution provides absolute confidence in user authentication. In one swift motion, the system guarantees that the individual interacting with your digital service is not only the legitimate owner of the registered profile (Matching) but is also a real human physically present at that exact moment. This unified approach effectively neutralizes both identity fraud and sophisticated presentation attacks in real-time.

Common Use Cases

New Device Authorization
To protect users against Account Takeover (ATO) fraud, Face Verification can be triggered whenever an existing account is accessed from a new or unrecognized device. Even if an attacker compromises a user's password or intercepts an SMS OTP, they cannot bypass the biometric gate. The synchronized liveness and matching check ensures that only the genuine account holder can authorize and bind a new device.
Automated Account Recovery (Reset PIN/Password)
Handling "Forgot PIN" or locked account requests typically requires expensive, manual customer service verification. Integrating Face Verification allows platforms to fully automate the account recovery lifecycle. Users can securely reset their credentials in seconds by proving their live physical presence and matching it against their onboarding baseline, eliminating manual back-office overhead while maintaining top-tier security.

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: launchSelfieVerification(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.
1. Partner FE calls Partner BE to get User Token. Partner BE calls IAB Gateway to get user Token using the Initiate Flow API.
2. Partner User Id
3. Partner User Id Type
4. Onboarding partner tied to the flow, which partner wants to launch.
5. Partner FE initializes the Digital Identity FE SDK (IAB FE):
Use the initialise method to initialize the SDK.
1. Partner FE calls launchSelfieVerification() method of Digital Identity SDK to launch Selfie Verification flow with the following parameters:
2. baseURL: This is the server URL specific to the partner using the format https\://<domain>.
  Example: https://onekyc.ky.id.sandbox.gopayapi.com
3. correlationId: A unique ID used to create a Selfie Verification request and track the specific instance of the Selfie Verification request helpful for logging and event tracking.
4. token: The unique user token, different for each user.
5. theme(optional): The theme parameter is optional, and its default value is null. If not provided, the SDK uses the default theme (DefaultOneKycSelfieVerificationFlowTheme).
  The theme parameter is an instance of the OneKycSelfieVerificationFlowTheme class. It allows you to customize the look and feel of the Selfie Verification 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.
6. IAB FE will capture users' selfies and will upload it to IAB Gateway for Face verification processing.
7. IAB Gateway initiates Face verification processing.
8. Partner needs to expose an API, which IAB BE will call to get the reference Image. The selfie captured by IAB FE will be compared against this reference image. This reference image can be either selfie or ktp based on the flow which the partner launched.

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 8 days ago

Documentations

Face Verification Flow - User Experience