Onboard real users. Block fraud in seconds.

# Didit User Verification — integrate KYC in 5 minutes

You are integrating Didit's User Verification product line (KYC) into the_my_stack_block. Follow these steps exactly. Every URL, header, and enum value below is canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Compose the workflow
A workflow is an ordered list of features the user runs through in a single hosted session. The canonical full-KYC bundle is four features:

  - ID_VERIFICATION   — document capture, OCR, MRZ, barcode, authenticity, liveness
  - LIVENESS          — Passive Liveness (iBeta Level 1 PAD certified)
  - FACE_MATCH        — 1:1 match between the document portrait and the live selfie
  - IP_ANALYSIS       — VPN / proxy / Tor / hosting / ASN / abuse-score signals

This bundle bills at $0.33 per completed session (was $0.30 pre-2026-05).

To compose a custom workflow, add or remove features from the array. Every feature in the catalog is independently priced — see Section 5.

  POST https://verification.didit.me/v3/workflows/
  Headers:
    x-api-key: <your-api-key>
    Content-Type: application/json
  Body:
    {
      "workflow_label": "Full KYC",
      "features": [
        { "feature": "ID_VERIFICATION" },
        { "feature": "LIVENESS" },
        { "feature": "FACE_MATCH" },
        { "feature": "IP_ANALYSIS" }
      ]
    }
  Response: { "workflow_id": "wf_..." }

Feature enums are UPPERCASE_SNAKE_CASE — strict. Available enums:
  ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, FACE_SEARCH, AGE_ESTIMATION,
  BIOMETRIC_AUTHENTICATION, AML, ONGOING_AML, IP_ANALYSIS, PROOF_OF_ADDRESS,
  DATABASE_VALIDATION, PHONE_VERIFICATION, EMAIL_VERIFICATION,
  QUESTIONNAIRES, REUSABLE_KYC, WHITE_LABEL.

You can also build the workflow visually in the Business Console — the Console emits the same workflow_id and the same payload shape.

## 3. Create a session for an end user

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your-api-key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "wf_...",
      "vendor_data": "<your-own-stable-user-id>",
      "callback": "https://your-app.example/callback"
    }
  Response 201:
    {
      "session_id": "ses_...",
      "session_url": "https://verify.didit.me/...",
      "expires_at": "..."
    }

Redirect the user to session_url. Didit handles capture (camera, lighting cues, mobile handoff, accessibility) and runs every feature in the workflow.

## 4. Webhooks
Register a destination once per workspace:

  POST https://verification.didit.me/v3/webhook/destinations/
  Body:
    {
      "url": "https://your-app.example/webhooks/didit",
      "subscribed_events": [
        "session.verified",
        "session.review_started",
        "session.declined",
        "kyc_expired"
      ]
    }
  Response: { ..., "secret_shared_key": "wsk_..." }

Every delivery carries an X-Signature-V2 header you MUST verify before trusting the payload.  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.Algorithm:
  1. sortKeys(payload) recursively
  2. shortenFloats (truncate trailing zeros after the decimal point)
  3. JSON.stringify the result
  4. HMAC-SHA256 with the secret_shared_key
  5. Hex-encode, compare to the X-Signature-V2 header

## 5. Reading the report
Fetch the full session report after the webhook fires:

  GET https://verification.didit.me/v3/session/<session_id>/decision/
  Header: x-api-key: <your-api-key>

The response carries one sub-object per feature in the workflow. Top-level status is one of:
  "Approved" | "Declined" | "In Review" | "Expired" | "Not Finished"

Sub-objects you will see on the full-KYC bundle:
  - id_verification:    document_type, document_number, full_name,
                        first_name, last_name, date_of_birth (YYYY-MM-DD),
                        age, expiration_date, date_of_issue, issuing_state
                        (ISO 3166-1 alpha-3), nationality, gender, address,
                        parsed_address (street, city, region, postal_code,
                        geometry coordinates), image quality scores, warnings
  - liveness:           score (0-100), method (Passive/Flash/Active), warnings
  - face_match:         match (true/false), score (0-100), warnings
  - ip_analysis:        vpn, proxy, tor, hosting, asn, abuse_score, country

If you add more features to the workflow you get more sub-objects in the report — same JSON shape, same warning catalog, same risk-policy hooks.

## 6. Pricing reference (public, per success)
  - Full KYC bundle (ID + LIVENESS + FACE_MATCH + IP_ANALYSIS) — $0.33 per session
  - 500 sessions free every month, forever, on every workspace
  - Standalone module prices on https://didit.me/pricing
    - ID Verification          $0.15
    - Passive Liveness         $0.10
    - Active Liveness          $0.15
    - Face Match 1:1           $0.05
    - Face Search 1:N          Free
    - AML Screening            $0.20
    - Ongoing AML Monitoring   $0.07 per user / year
    - NFC Reading              $0.15
    - Device & IP Analysis              $0.03
    - Proof of Address         $0.20
    - Phone Verification       From $0.03
    - Email Verification       $0.03
    - Custom Questionnaires    $0.10
    - Age Estimation           $0.10
    - Biometric Authentication $0.10
    - Database Validation      Variable
    - White Label              $0.20
    - Reusable KYC             Free

Every module bills only on successful completion — abandoned and rejected sessions are free.

## 7. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE_SNAKE_CASE.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Expired", "Not Finished" (title-cased, space-separated).

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test docs: deterministic synthetic IDs returned in sandbox.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/sessions-api/create-session