Screen high-risk checkouts in two stages. Cheap signals first. Biometrics only when needed.

You are integrating a Didit buyer-side fraud screen on a marketplace / e-commerce checkout. Goal: catch stolen-card use, account takeover, gift-card stack abuse, geo-mismatch friendly fraud, and bot scalping on high-value carts. Two stages — cheap signals first, biometric step-up only when signals aren't enough.

WHY THIS SHAPE
  - Most checkouts don't need any friction. Day-to-day buyers on trusted devices from residential networks should sail through.
  - A small percentage are high-value or high-risk — cart over a threshold, gift-card stack, payout to a new card, geo mismatch, new device, velocity anomaly. On those, run a screen.
  - Two stages keep the cost and the friction proportional to the risk. Cheap IP + device check ($0.03) is decisive on the obvious cases. Biometric step-up ($0.10) only fires when the cheap signals are inconclusive AND the order is high-value.
  - 500 verifications free every month. The screen runs inside the free tier for most teams while they tune the thresholds.

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.
  - A Workflow Builder workflow with Device & IP Analysis and optionally Passive Liveness + Face Match 1:1 against the stored buyer portrait.
  - A server-side cart-gate that defaults to BLOCK on the high-risk path and only unblocks on a verified webhook with status: Approved.

STEP 1 — Decide WHEN to screen (your code, not Didit's)
  Run your usual checkout signals. Default triggers worth a screen:
    - Cart total above your account-level tier (e.g. > $500)
    - Gift-card stack of three or more cards in one order
    - Shipping country that doesn't match the billing-card country
    - First buy from a new device
    - Velocity anomaly — N orders within window W from the same buyer
    - Payout / refund destination changed mid-flow

  Day-to-day reads from trusted-device + residential-network buyers do NOT need a screen.

STEP 2 — Open the screen session
  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with Device & IP Analysis + optional Passive Liveness + Face Match 1:1>",
      "vendor_data": "<your order id, max 256 chars>",
      "callback": "https://<your-app>/checkout/screen/callback",
      "metadata": {
        "cart_total_cents": 78500,
        "currency": "EUR",
        "trigger": "high_value_cart"
      }
    }

  Response: 201 Created with a hosted session URL. Show inline at checkout (web), or open in a Software Development Kit (SDK) webview (mobile). The order stays in HOLD on your side until the signed webhook lands.

STEP 3 — Read the signed webhook
  Didit POSTs the verdict. Verify X-Signature-V2 (HMAC SHA-256 of the raw body) BEFORE reading the JSON.

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

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

STEP 4 — Branch the cart action
  Approved      → ship the order, capture the auth, send the confirmation.
  In Review     → hold the order. Route to manual review with the per-module signals as the case file.
  Declined      → cancel the order, refund the auth, log warnings (liveness / face-match / ip flags), throttle the source IP.
  Not Finished  → invite the buyer to retry the screen with a fresh session URL. Don't ship.

STEP 5 — (Optional) Reusable Know Your Customer (KYC) for returning trusted buyers
  Once a buyer has passed identity once on the platform, the credential can replay on future checkouts at no cost via Reusable KYC. Look up the buyer's prior session_id; if the credential is valid and recent, skip the live screen.

  That keeps the friction on the unknown traffic only. Free forever.

STEP 6 — Use the decision payload as the chargeback evidence pack
  When a dispute lands, pull the full decision payload via:
    GET https://verification.didit.me/v3/session/{session_id}/decision/
    Headers:
      x-api-key: <your api key>

  Pairs naturally with:
    - 3-D Secure 2.x (3DS2) liability shift on EU cards
    - Visa Compelling Evidence 3.0 (CE3.0) — biometric + IP + device fingerprint + prior-order history meets the "trusted customer" bar
    - Mastercard Identity Check chargeback dispute kit

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

WHAT IT BLOCKS
  - Stolen-card use on first-time-buy + geo mismatch
  - Account takeover on a previously-verified buyer (the step-up is the second-factor)
  - Friendly fraud where the cardholder disputes a charge they actually authorised
  - Bot scalpers running multi-item carts from datacenter Internet Protocol (IP) addresses
  - Gift-card stack drains funded by a stolen card
  - Reshipper / mule patterns (ship-to address inconsistent with prior orders)

CONSTRAINTS
  - Session statuses use Title Case With Spaces. Never UPPER_SNAKE_CASE — that's the Transactions API.
  - Start with IP-only on the cheap cases. Add the biometric step-up only on high-value carts or when IP alone is inconclusive — keeps cost down and friction proportional.
  - 200+ fraud signals are evaluated 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/ip-analysis/overview
  - https://docs.didit.me/core-technology/biometric-auth/overview
  - https://docs.didit.me/core-technology/reusable-kyc/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.