Verify people with the
eID they already use.

# Didit eID verification, integrate in 5 minutes

You are adding national eID sign-in to my_stack: the user verifies with the
eID they already use (a bank or government digital identity), and anyone
without one falls back to document capture in the same flow. 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
- Create an application and copy its API key from the console.

## 2. Check which eIDs are live, per country
Availability is server-driven. Never hard-code a wallet list.
  - Business Console: your application -> Workflows -> the ID Verification
    step -> Countries -> "Wallets accepted". Coming-soon wallets are listed
    but cannot be switched on. https://docs.didit.me/console/id-verification-methods
  - Didit MCP server (https://mcp.didit.me/mcp), tool
    didit_workflow_get_id_verification_methods_catalog; pass country as ISO
    3166-1 alpha-3 to narrow it. The MCP server signs in with "Log in with
    Didit" (OAuth). It does not accept the x-api-key.
    https://docs.didit.me/integration/mcp/tools
  - Public coverage table (no sign-in, read-only):
    https://docs.didit.me/core-technology/id-verification/digital-id-wallets#supported-wallets
If your code holds only an API key, it cannot read the catalog itself: use the
wallet ids listed in this prompt, and treat the answer of the workflow save as
the check. A live application answers 400 for a wallet that is not available
in that country ("<wallet> is not offered in <ISO3>", "unknown wallet").

At the time this prompt was generated, the catalog marked these available:
  - MitID: wallet id mitid, country keys DNK
  - BankID: wallet id bankid_se, country keys SWE
  - Finnish Trust Network: wallet id ftn, country keys FIN
  - Smart-ID: wallet id smart_id, country keys EST, LVA, LTU, BEL
  - Mobile-ID: wallet id mobile_id, country keys EST, LTU
Coming soon (cannot be enabled yet): BankID, Vipps, Buypass ID, itsme, iDIN, Personalausweis, Freja eID, UAE PASS, gov.br, OneID, GOV.UK Wallet, Bank iD, MojeID, Diia, FranceConnect, Auðkenni, ConnectID, EUDI Wallet, Estonian ID-card, eParaksts.
Check the catalog for your environment before you go live.

## 3. Create the workflow
POST https://verification.didit.me/v3/workflows/
  -H "x-api-key: <your-api-key>"
  -H "Content-Type: application/json"

The ID Verification feature's enum value is OCR (uppercase, strict). eIDs are
its wallet method, set per country under config.methods. Keys are ISO 3166-1
alpha-3. Keep document capture on, so a user without an eID can still finish.

{
  "workflow_label": "eID onboarding",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "methods": {
          "DNK": {
            "document": { "enabled": true },
            "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
          },
          "SWE": {
            "document": { "enabled": true },
            "wallet": { "enabled": true, "providers": ["bankid_se"], "on_failure": "fallback_to_document" }
          }
        }
      }
    }
  ]
}

Response: 201. The workflow id is uuid (workflow_id carries the same value);
the workflow is published straight away. Create it once and keep the id:
every call to this endpoint makes a new workflow.
is_desktop_allowed defaults to false: on a desktop browser the hosted flow
then shows a QR code to continue on a phone. Add "is_desktop_allowed": true
next to workflow_label to let people finish on desktop.

Rules the API enforces:
  - providers is an accept-list, not a ranking; the user picks
  - on_failure is fallback_to_document or decline; it covers a cancelled,
    timed-out or failed sign-in
  - fallback_to_document where document.enabled is false declines instead
  - a wallet the catalog does not mark available in that country rejects the
    whole save (400), including every other method in the same request
  - enabled true with an empty providers list is rejected
  - add { "feature": "LIVENESS" } and { "feature": "FACE_MATCH" } to features
    if you need a selfie: the live eIDs do not share a portrait

## 4. Create a session
POST https://verification.didit.me/v3/session/
  -H "x-api-key: <your-api-key>"
  -H "Content-Type: application/json"
  -d '{ "workflow_id": "<id from step 3>", "vendor_data": "<your user id>" }'

Response: 201 with session_id, session_token, url and status "Not Started".
Redirect the user to url (hosted flow) or open it in the Web, iOS, Android,
React Native or Flutter SDK. The field is named url on this response.
One unfinished session exists per workflow_id and vendor_data pair: calling
create again with the same pair answers 201 again with that same session.
The user picks their eID, then approves in the eID app: same-device hand-off
or a QR code on desktop for MitID, BankID and Finnish Trust Network; a
comparison code approved on the phone for Smart-ID and Mobile-ID. Didit never
asks for the user's PIN. A started sign-in stays valid for 10 minutes by
default.

## 5. Webhooks
Register a destination in the console (API & Webhooks), or over the API:

POST https://verification.didit.me/v3/webhook/destinations/
  -H "x-api-key: <your-api-key>"
  -H "Content-Type: application/json"
  -d '{
    "label": "Verification webhooks",
    "url": "https://<your-public-host>/webhooks/didit",
    "webhook_version": "v3",
    "subscribed_events": ["status.updated", "data.updated"]
  }'

label, url and subscribed_events are required. url must be a public HTTPS
address: Didit does not deliver to localhost or private addresses. Response:
201 with uuid and secret_shared_key. Store secret_shared_key as the webhook
secret (DIDIT_WEBHOOK_SECRET); it is unique to this destination. Remove a
destination with DELETE /v3/webhook/destinations/{uuid}/ (204).

What arrives:
  - webhook_type is "status.updated" (the session changed status) or
    "data.updated" (verification data was corrected after the fact)
  - a destination receives the events of every session of the application,
    so filter on workflow_id or vendor_data when several flows share it
  - creating a session already sends status.updated with status
    "Not Started". The decision key is present only when status is Approved,
    Declined, In Review or Abandoned.

Verify every delivery:

  Header:      X-Signature-V2 (not X-Signature, not X-Signature-Simple)
  Algorithm:   HMAC-SHA256, hex digest, over the canonical JSON of the payload
               (Python json.dumps(sort_keys=True, separators=(",", ":"),
               ensure_ascii=False) after whole-valued floats become ints).
               Use the reference handler below as written: it rebuilds those
               bytes from the raw body text. Never hash the raw request bytes.
  Freshness:   the signed body field timestamp is the dispatch time (Unix
               seconds, refreshed on every retry). Reject when
               abs(now - timestamp) > 300 seconds, and reject when the
               X-Timestamp header does not equal it.
  Idempotency: event_id is the same on every retry of one event, so store it
               and skip a delivery you already processed. One session can
               still send the same status under two event ids, and the
               console's Try Webhook test deliveries carry no event_id, so
               also make the handler safe to run twice for one
               (session_id, status, webhook_type).
  Compare:     constant-time (crypto.timingSafeEqual)

Reference handler (Express). Keep the verification lines as written.
The handler is a fragment. Put this above it and app.listen(process.env.PORT)
below it. It needs Express and Node 21 or newer (an older Node rejects
every delivery). It expects a JSON body: answer 400 yourself if you accept
anything else on this route, and refuse to start without the secret.

const express = require("express");
const app = express();
const SECRET = process.env.DIDIT_WEBHOOK_SECRET; // secret_shared_key of the destination

// Your endpoint receives a signed payload
const crypto = require("node:crypto"); // ESM: import crypto from "node:crypto"
// X-Signature-V2 = HMAC over the canonical JSON, never the raw bytes. Match the sender byte for
// byte: keys sorted by code point, integers digit for digit, floats in Python's repr.
class Num { constructor(src) { this.src = src; } } // a number as written on the wire, not a double
const num = (s) => { if (/^-?\d+$/.test(s)) return BigInt(s).toString(); const n = +s; // ints stay exact
  if (Number.isInteger(n)) return BigInt(n).toString(); const [m, e] = n.toExponential().split("e"); // 27.0 -> 27
  return +e >= -4 ? String(n) : `${m}e-${String(-e).padStart(2, "0")}`; }; // 1e-05, not 0.00001
const byCodePoint = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)); // UTF-8 order = Python's
const canon = (v) => Array.isArray(v) ? `[${v.map(canon)}]` : v instanceof Num ? num(v.src)
  : v && typeof v === "object" ? `{${Object.keys(v).sort(byCodePoint).map((k) => `${JSON.stringify(k)}:${canon(v[k])}`)}}`
  : JSON.stringify(v);
// Read the body as text: express.json() would round 1000000000000000129 to a double first.
// Register this route ABOVE any global app.use(express.json()): the first parser to run
// consumes the stream, and a body it already parsed has lost the digits the signature covers.
app.post("/webhooks/didit", express.text({ type: "application/json" }), (req, res) => {
  const exact = JSON.parse(req.body, (k, v, c) => typeof v === "number" ? new Num(c.source) : v); // Node 21+
  const body = JSON.parse(req.body);
  const mac = crypto.createHmac("sha256", SECRET).update(canon(exact), "utf8").digest("hex");
  const sig = Buffer.from(String(req.headers["x-signature-v2"] ?? ""));
  // Freshness comes from the signed body timestamp; the header alone is unsigned and replayable.
  const ts = body.timestamp, fresh = String(ts) === req.headers["x-timestamp"]
    && Math.abs(Date.now() / 1000 - ts) <= 300;
  if (!fresh || sig.length !== mac.length
    || !crypto.timingSafeEqual(sig, Buffer.from(mac))) return res.sendStatus(401);
  const { status, decision } = body;
  // One entry per ID Verification node; pick yours by node_id when you run several.
  const [idv] = decision?.id_verifications ?? [];
  // idv.verification_method: "document" | "id_lookup" | "wallet"
  res.sendStatus(200);
});

Status values (exact strings): Not Started, In Progress, Approved, Declined,
In Review, Resubmitted, Expired, Abandoned, Kyc Expired. Awaiting User only
appears on business verification sessions.

## 6. Read the eID result
The same V3 decision reaches you two ways:
  - webhook body: body.decision.id_verifications[]
  - GET https://verification.didit.me/v3/session/{session_id}/decision/
      -H "x-api-key: <your-api-key>"
    This response IS the decision object. Read id_verifications at the top
    level: there is no decision wrapper here.
Until the user finishes the ID step, status is "Not Started" or "In Progress"
and id_verifications is null, not an empty array. Guard for it.

id_verifications[] has one entry per ID Verification node; with a single step
take index 0 (its node_id is "ocr" on a workflow made by the call in step 3).
The decision's features list names the step ID_VERIFICATION; the workflow
body still takes OCR. Each entry carries:

  status                 Approved, Declined, In Review or Not Finished
  verification_method    "wallet" for an eID sign-in, "document" after a
                         fallback
  assurance              "cryptographic" for a wallet entry, "documentary"
                         for a document one
  full_name,             the normalised identity fields, on the entry itself
  date_of_birth
  wallet_provider        the catalog wallet id, for example "mitid"
  wallet_verification    provider, provider_name, issuing_authority,
                         issuing_country, credential_type,
                         level_of_assurance (low | substantial | high),
                         verified_at, signature_valid, attributes, portrait,
                         face_match_score
  fallback_from          { method, reason, action } when the wallet sign-in failed
                         and on_failure declined the session; otherwise
                         null. After a document fallback that succeeds the
                         entry reads verification_method "document" with
                         fallback_from null

attributes holds what the scheme shares, and the names vary by scheme: MitID
returns cpr_alias (a pseudonymised identifier, not the CPR number), BankID
Sweden personal_number, Finnish Trust Network personal_identity_code, Smart-ID
and Mobile-ID personal_code. Use full_name and date_of_birth on the entry for
the normalised identity fields. No live eID returns an address or a portrait.

Check wallet_verification.level_of_assurance when your rules depend on it. If
a scheme returns a weaker level than the one requested, the sign-in fails
instead of downgrading.

## 7. Billing
  - only a completed eID sign-in is billed; cancelled, timed-out, refused
    and failed sign-ins are free
  - a document fallback is billed as its own document check
  - eID checks are outside the document free tier
  - published prices per completed sign-in (USD):
    - MitID personal: $0.25
    - BankID Sweden: $0.20
    - Finnish Trust Network: $0.25
    - Smart-ID: $0.20
    - Mobile-ID: $0.20
  - full pricing: https://docs.didit.me/core-technology/id-verification/digital-id-wallets#pricing

## 8. Hard rules
  - base URL for v3 endpoints: verification.didit.me
  - auth header: x-api-key
  - feature enum: OCR; methods: document, id_lookup, wallet
  - wallet ids come from the catalog verbatim (mitid, bankid_se, ftn,
    smart_id, mobile_id)
  - country keys: ISO 3166-1 alpha-3, uppercase
  - webhook: X-Signature-V2 plus X-Timestamp, canonical JSON, freshness from
    the signed body timestamp

## 9. Verify your integration
Sandbox (an application in sandbox mode: nothing is billed and no real eID is
called). https://docs.didit.me/integration/sandbox-testing
  - a sandbox application can enable every wallet in the catalog, the
    coming-soon ones included. A workflow that saves in sandbox can still be
    refused on a live application, so only use wallets marked available.
  - open the session url, pick the wallet and confirm: the default approve
    scenario simulates the sign-in. The entry then has verification_method
    "wallet", assurance "cryptographic" and wallet_provider set, and the
    normalised full_name and date_of_birth are filled. But
    wallet_verification.signature_valid and level_of_assurance are null and
    attributes is { "sandbox": true }: no real credential was checked.
    Assert signature_valid === true and the level of assurance only against
    a live application.
  - to exercise on_failure, create the session with
    "sandbox_scenario": "wallet_cancelled" (also wallet_timeout and
    wallet_provider_error). The wallet sign-in then fails and the flow moves
    to document capture or declines, as on_failure says. A fallback that
    ends in an approved document reads verification_method "document".
  - POST /v3/session/{session_id}/simulate/ forces a final status but writes
    no id_verifications entry, so it cannot stand in for a sign-in.

Checks:
  - create the workflow, create a session, and read its decision: expect 201,
    201 with url, and 200 with status "Not Started"
  - run one sandbox session per accepted eID through the hosted flow and
    assert verification_method is "wallet" and wallet_provider is the eID you
    picked
  - run one session with sandbox_scenario "wallet_cancelled" and assert the
    flow offers document capture
  - assert your webhook accepts a correctly signed payload and rejects a
    wrong X-Signature-V2, a changed body, and a payload whose signed
    timestamp is older than 300 seconds, even when X-Timestamp is refreshed
  - on a live application, assert wallet_verification.signature_valid is true

Docs: https://docs.didit.me/core-technology/id-verification/digital-id-wallets