Stop account takeover with a face check. Step up the moment risk spikes.

You are integrating Didit account-takeover defence into an application that already has the user signed in. Your job: when a sensitive action fires (large transfer, password reset, payout to a new destination, new-device login, geo anomaly), gate it on a Didit biometric step-up. One API call. One signed webhook. Three branches.

WHY THIS SHAPE
  - Credential stuffing, SIM-swap, and stolen-session-cookie attacks all walk past passwords and SMS one-time codes. A face check at the moment of the sensitive action does not.
  - Didit runs Passive Liveness (the user is alive, present, not a deepfake) plus 1:1 Face Match against the portrait captured at sign-up. A stolen selfie cannot pass — the comparison target is locked to the original enrollment.
  - $0.10 per step-up (Biometric Authentication module) + $0.03 IP pre-check (optional) = around $0.13 per event. Sub-two-second verdict on entry-level Android. 500 verifications free every month.

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60 seconds, no credit card).
  - A webhook endpoint with HMAC SHA-256 verification of the X-Signature-V2 header using your webhook secret.
 HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.  - A Workflow Builder workflow that bundles Passive Liveness + Face Match 1:1 (with the user's stored sign-up portrait as the comparison target). Optionally compose Device & IP Analysis ahead of the step-up to pre-gate the check.
  - Persist the user's sign-up portrait — either base64 on your side, or rely on Didit's stored enrollment via vendor_data lookup.

STEP 1 — Decide WHEN to step up (your code, not Didit's)
  Run your usual fraud signals. Common triggers worth a biometric step-up:
    - Wire / crypto transfer above the user's daily limit
    - Password / email reset on a session less than 24h old
    - Payout to a bank account or wallet seen for the first time
    - Login from a new device or new country
    - Velocity anomaly — N actions of type T within window W

  Cheap pre-check (optional, ~100ms, $0.03):
    - Score the user's IP via Device & IP Analysis. If the IP is a residential trusted address with a low risk score AND the device fingerprint matches the user's trusted device, skip the step-up. Otherwise run Step 2.

STEP 2 — Create a biometric step-up session
  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id bundling Passive Liveness + Face Match 1:1>",
      "vendor_data": "<your user id, max 256 chars>",
      "callback": "https://<your-app>/ato/step-up/callback",
      "metadata": {
        "trigger": "high_value_transfer",
        "action_id": "<your internal action reference>"
      },
      "portrait_image": "<base64 JPEG of the user's stored sign-up portrait, ≤ 1 MB — REQUIRED when the workflow has FACE_MATCH active; the step-up matches the new live selfie against this stored reference>"
    }

  Response: 201 Created with a hosted session URL. Redirect the user there inline (or open it in a webview / Didit mobile SDK). The action stays BLOCKED on your side until the signed webhook lands.

STEP 3 — Read the signed webhook on completion
  Didit POSTs the decision to your callback. Verify X-Signature-V2 (HMAC SHA-256 of the raw request body using your webhook secret) BEFORE reading the JSON.

  Payload (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "liveness": { "status": "Approved" },
      "face":     { "status": "Approved", "similarity_score": 0.94 },
      "ip_analysis": { "status": "Approved", "score": 11 }
    }

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

STEP 4 — Branch the original action on status
  Approved      → unblock the sensitive action. Log session_id + similarity score on the audit trail.
  In Review     → hold the action, route to a human review queue.
  Declined      → block the action, log liveness warnings (mask / deepfake / replay / morph), alert the user.
  Not Finished  → invite the user to retry with a fresh session URL.
  Expired       → resend the link; the original session has timed out.
  Abandoned     → the user closed the flow before completing; resend the link.

STEP 5 — (Optional) Pull the full decision payload
  GET https://verification.didit.me/v3/session/{session_id}/decision/
  Headers:
    x-api-key: <your api key>
  Returns the same payload as the webhook plus the structured signals (liveness warnings, face-match similarity, IP / device flags). Use for analyst review.

WEBHOOK EVENT NAMES
  - Sessions: standard session webhook (one endpoint, status field tells you where in the lifecycle).
  - Verify X-Signature-V2 (HMAC SHA-256) on every payload.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Never use UPPER_SNAKE_CASE for session verdicts — that's the Transactions API and lives in a different surface.
  - 1:1 face match's comparison target is the user's STORED sign-up portrait, not a freshly captured one. A stolen selfie cannot pass.
  - iBeta Level 1 Presentation Attack Detection (PAD) certified against the full ISO/IEC 30107-3 catalogue — print, replay, paper / silicone / latex mask, deepfake, morph.
  - The Workflow Builder is where you choose the modules in the step-up — change them in the console without redeploying.
  - 200+ fraud signals are surfaced on every session at no extra cost — read them off the decision payload, don't re-query.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/core-technology/biometric-auth/overview
  - https://docs.didit.me/core-technology/ip-analysis/overview
  - 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.