Einmal verifizieren. Überall wiederverwenden.

You are integrating Didit's Reusable Identity / eIDAS 2.0 acceptance into your platform. Two flows:

  1. Issue — when a new user runs a full KYC on your platform, they leave with a Didit-signed Reusable Identity credential in their wallet (the Didit app or any EU Digital Identity Wallet).
  2. Accept — when a user arrives at your platform already holding a Didit-signed credential, the session detects it and short-circuits, returning Approved without re-running the full KYC.

Bundle pricing (verified live 2026-05-16):
  - First verification (issuance side): $0.33 per user (Sessions API full KYC bundle)
  - Issuance: free — the signed credential is included with every KYC
  - Reuse on the verifying side: free, forever
  - Selective disclosure: free
  - Continuous Anti-Money Laundering (AML) refresh: $0.07 per user per year (automatic)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60 seconds, no credit card).
  - Webhook endpoint with HMAC SHA-256 verification of the X-Signature-V2 header.
 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_id from the no-code Workflow Builder with:
    * ID Verification + Passive Liveness + Face Match 1:1 + Device & IP Analysis + AML Screening (for issuance)
    * Reusable Identity acceptance turned on (for acceptance — toggle in the Workflow Builder)
  - Optional: the Didit mobile SDK (iOS / Android / React Native / Flutter) for native deep-link wallet handoff.

STEP 1 — Open a session that accepts a Reusable Identity if presented

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with Reusable Identity acceptance on>",
      "vendor_data": "<your user id>",
      "callback": "https://<your-app>/onboarding/callback",
      "metadata": {
        "purpose": "platform_onboarding",
        "request_fields": ["full_name", "age_over_18", "country_of_residence"]
      }
    }

  Optional in body: declare the exact fields you need disclosed via metadata.request_fields. Didit's hosted flow will prompt the user to approve only those specific fields when they present a Reusable Identity credential.

  Response: 201 Created with the hosted session URL. Redirect the user.

STEP 2 — The hosted flow detects (or runs) the verification

  Two paths from this one endpoint:

  Path A — User has a Didit-signed credential
    - The hosted flow detects the credential via a wallet-handoff prompt (universal link on mobile, popup-bridge on desktop)
    - The user approves the disclosure of the requested fields
    - Didit validates the issuer signature + credential freshness server-side
    - Session returns Approved with the disclosed fields populated on the decision payload
    - Cost: $0 on the verifying side

  Path B — User does NOT have a credential
    - The hosted flow runs the full KYC bundle (ID + Liveness + Face Match + Device & IP + AML)
    - At completion, Didit issues a Reusable Identity credential to the user's wallet
    - Session returns Approved with the full decision payload
    - Cost: $0.33 on the verifying-and-issuing side

  Same endpoint, same webhook, same status enum. The path is transparent to your back-end.

STEP 3 — Read the signed webhook

  Didit POSTs to your callback. Session statuses (Title Case With Spaces):

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "id_verification": { "status": "Approved" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "ip_analysis": { "status": "Approved" },
      "aml": { "status": "Approved", "hits": [] },
      "reusable_identity": {
        "presented": true,
        "issuer": "<issuing-platform name>",
        "issued_at": "<timestamp>",
        "disclosed_fields": ["full_name", "age_over_18", "country_of_residence"]
      }
    }

  Status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.
  Verify the X-Signature-V2 header BEFORE reading the body.

  When reusable_identity.presented is true, the user re-presented an existing credential and the verification was free; when false, a fresh KYC was run and billed at $0.33.

STEP 4 — Retrieve the full decision later

  GET https://verification.didit.me/v3/session/{sessionId}/decision/
  Headers:
    x-api-key: <your api key>

  Returns the full payload including: document scan + extracted Machine-Readable Zone (MRZ) data, biometric similarity, AML hits, device + IP risk signals, 200+ fraud signals, HMAC signature, and (if presented) the credential issuance chain.

  Same evidence pack regardless of issuance vs reuse — the verifier never sees less than a fresh KYC would deliver.

STEP 5 — Continuous AML monitoring is automatic

  Every approved user (issued OR presented) is re-screened daily against 1,300+ sanctions, PEP, and adverse-media lists at $0.07 per user per year on heavy-volume accounts. When a previously-clean user crosses an AML threshold, the credential's AML field is updated automatically; every receiving platform sees the refreshed status on next presentation.

  When the user revokes a credential from their wallet, your receiving platform's webhook fires with status: Expired and the credential is dropped from the user's account.

STEP 6 — Selective disclosure at presentation time

  Pass the exact fields you need via metadata.request_fields at session creation. Recommended minimum-disclosure patterns:

  - Age-gate (UK Online Safety Act, France SREN): ["age_over_18"]
  - Country-gate: ["country_of_residence"]
  - Full name + verified-human: ["full_name", "verified_human"]
  - AML-clear gate (lending): ["aml_clear", "full_name"]
  - Full identity (banking, payments): ["full_name", "date_of_birth", "address", "document_number", "aml_clear"]

  The user sees a single approval prompt listing the requested fields. Anything not listed is never disclosed to your platform.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook (verify X-Signature-V2 HMAC SHA-256).
  - Credential lifecycle: status: Expired fires when a holder revokes the credential.

CONSTRAINTS
  - Session statuses use Title Case With Spaces. Don't UPPER_SNAKE_CASE them.
  - Reusable Identity acceptance is OFF by default; turn it on in the Workflow Builder.
  - Selective disclosure is the privacy default — fields not in metadata.request_fields are never returned, even if the credential carries them.
  - Default record retention is 5 years post-relationship per the EU AML package.
  - 200+ fraud signals are evaluated on every session, issued or presented, at no extra cost.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - 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.