Replace SMS one-time-password. Make a selfie the second factor.

You are integrating Didit's Biometric 2FA into <my_stack>. Replace SMS one-time-password (OTP) on sensitive flows — login from a new device, large-value transfer, settings change, account recovery — with a sub-2-second face match against the user's enrolled portrait. Cheaper than SMS. Phishing-resistant. SIM-swap-proof.

  1. Enrol the user's portrait ONCE at sign-up via the standard Know Your Customer (KYC) session.
  2. On every sensitive action, open a Biometric Authentication session that runs Passive Liveness + Face Match 1:1 against the stored portrait. Verdict in sub-2-seconds.

Pricing (public):
  - Biometric Authentication: $0.10 per authentication (Sessions API)
  - Standalone Face Match 1:1: $0.05 per match (server-to-server)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with Hash-based Message Authentication Code (HMAC) SHA-256 verification using the X-Signature-V2 header.
  - The user has previously enrolled — either via a full KYC session (recommended; the portrait is stored automatically and never leaves Didit) or via a portrait you supply on each re-auth.
  - A workflow_id from the Workflow Builder. The workflow MUST contain LIVENESS, and the session must be opened with workflow_type = "biometric_authentication" (or use a workflow that has FACE_MATCH and pass a portrait_image at session creation).

STEP 1 — Enrolment (one-time, at user sign-up)

  Run a standard KYC session at sign-up. Didit stores the portrait (the face captured during the liveness step) as the user's enrolled template, bound to vendor_data.

  POST https://verification.didit.me/v3/session/
  Body:
    {
      "workflow_id": "<your KYC workflow>",
      "vendor_data": "<your user id>"
    }

  No additional code — once the user passes KYC, their enrolled portrait is ready for every future re-auth.

STEP 2 — Re-authentication (on every sensitive action)

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your biometric_authentication workflow>",
      "workflow_type": "biometric_authentication",
      "vendor_data": "<the same user id used at enrolment>",
      "callback": "https://<your-app>/2fa/callback",
      "metadata": {
        "reason": "<login_new_device | high_value_txn | settings_change | account_recovery>",
        "amount": "<optional, for large-value transfers>"
      },
      "portrait_image": "<base64 JPEG of the user's enrolment selfie, ≤ 1 MB — REQUIRED when the workflow has FACE_MATCH active; OMIT for liveness-only mode>"
    }

  Response: 201 Created with the hosted session_url. Redirect the user to it. The hosted UI:
    - Opens the front camera
    - Captures one passive frame
    - Runs Liveness + Face Match 1:1 against the user's enrolled portrait
    - Returns the verdict in sub-2-seconds

STEP 3 — Read the signed verdict on the webhook

  Body (excerpted for a passing re-auth):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": { "status": "Approved", "method": "PASSIVE", "score": 96 },
      "face": {
        "status": "Approved",
        "similarity_score": 0.96
      }
    }

  Verify X-Signature-V2 BEFORE trusting the body — HMAC SHA-256 of the raw bytes with your webhook secret.

  Session status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

  Branch your application:
    Approved      → execute the action (sign in, release the transfer, save settings).
    Declined      → block the action, re-prompt with a higher-friction recovery path (support contact / KYC re-do).
    In Review     → hold; route to your operations queue.
    Not Finished  → user abandoned the capture; safe to re-prompt or fall back.

STEP 4 — Alternate path (server-to-server, when you already have the selfie)

  If you already captured the selfie locally (native mobile SDK, in-app camera):

  POST https://verification.didit.me/v3/face-match/
  Headers:
    x-api-key: <your api key>
  Body (multipart/form-data):
    image_a         <the live selfie>
    image_b         <the enrolled portrait>

  Response: similarity_score (0-1), status (Approved | Declined | In Review).

  Use the standalone path only when you trust your client-side capture pipeline. For browser flows or any surface where the SDK is not embedded, always prefer the hosted session — Didit's liveness check is harder to defeat than a raw camera grab.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Always verify X-Signature-V2 on every payload.

CONSTRAINTS
  - Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
  - Feature enum is UPPERCASE: LIVENESS, FACE_MATCH, ID_VERIFICATION, AML, IP_ANALYSIS, AGE_ESTIMATION.
  - Method enum is UPPERCASE: PASSIVE, FLASHING, ACTIVE_3D.
  - Auth header is x-api-key (lowercase, hyphenated).
  - Webhook signature header is X-Signature-V2 (NOT X-Signature).
  - Status casing matches exactly: Approved, Declined, In Review, Expired, Not Finished, Resubmitted, Kyc Expired, Abandoned.
  - The biometric template is irreversible (a one-way hash) and stored on Didit's infrastructure. You never receive the raw template. Standard data-subject-deletion rules apply.

PRO TIPS
  - Pair Biometric 2FA with Device & IP Analysis (bundled into the 200+ fraud-signal stack). A re-auth that originates from a brand-new device + a brand-new IP should always step up to face.
  - For the strongest possible surface, swap method PASSIVE for ACTIVE_3D — a short motion challenge — on transfers above your operational risk threshold.

Read the docs:
  - https://docs.didit.me/core-technology/biometric-auth/overview
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.