دع الأشخاص يسجلون الدخول باستخدام
الهوية التي يمتلكونها بالفعل.

# Didit digital ID wallets — integrate in 5 minutes

You are adding digital ID wallet sign-in to my_stack. The user signs in with a
government or bank digital identity and the wallet returns signed attributes.
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).
- Grab the API key for your application from the console.

## 2. Read the methods catalog first
Wallet availability is server-driven per country. Never hard-code a wallet list.

The catalog is not a public REST endpoint. Read it one of two ways:
  - Business Console (signed in): your application -> ID Verification ->
    Countries tab. https://docs.didit.me/console/id-verification-methods
  - Didit MCP server tool didit_workflow_get_id_verification_methods_catalog,
    authenticated with the same x-api-key; pass country (ISO 3166-1 alpha-3)
    to narrow it to one country. https://docs.didit.me/integration/mcp/tools
  - Public mirror of the coverage table (no auth, read-only):
    https://docs.didit.me/core-technology/id-verification/verification-methods#coverage

The catalog gives you, per wallet id: the display name, the countries it
covers, the issuing authority, the level of assurance, the availability state,
and the attributes it returns. MitID, Smart-ID, Mobile-ID and Finnish Trust
Network are available. Read the Finnish Trust Network integration guide:
https://docs.didit.me/core-technology/id-verification/finnish-trust-network
iDIN and other wallets remain coming soon until the catalog in
your environment marks them available. Re-read it; do not hard-code a date.

## 3. Create a workflow with the ID Verification (OCR) feature
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 enum;
there is no ID_VERIFICATION alias and the API rejects it). Wallets are its
wallet method, accepted per country under config.methods on that same
feature entry, in the same request. Keys are ISO 3166-1 alpha-3.

{
  "workflow_label": "Wallet onboarding",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "methods": {
          "DNK": {
            "document": { "enabled": true },
            "wallet": {
              "enabled": true,
              "providers": ["mitid"],
              "on_failure": "fallback_to_document"
            }
          },
          "FIN": {
            "document": { "enabled": true },
            "wallet": {
              "enabled": true,
              "providers": ["ftn"],
              "on_failure": "fallback_to_document"
            }
          }
        }
      }
    }
  ]
}

Response: the workflow uuid — use it as workflow_id in step 4.

Rules that the API enforces:
  - providers is an accept-list, not a ranking. Order carries no meaning and
    the end user picks
  - on_failure is either fallback_to_document or decline. It covers all three
    cases: no wallet, cancelled, sign-in failed
  - a wallet id the catalog does not mark available for that country is
    rejected, and the rejection fails the whole save — including any lookup
    configuration next to it. For unavailable wallets, keep wallet.enabled
    false (or omit the wallet block) so the save succeeds
  - unknown wallet ids already saved on a workflow are preserved untouched, so
    a config written by a newer console version is never silently dropped
  - a country with no method enabled is rejected at publish time

## 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 url (the hosted verification link), session_token and
session_id. Redirect the user to url, or open it in the SDK. The field is
named url — there is no session_url and no verification_url. Didit
shows the accepted wallets for the user's country with their brand marks,
hands off to the wallet, and waits for the signed assertion to come back.

## 5. Webhooks
Register a destination (console -> API & Webhooks, or
POST https://verification.didit.me/v3/webhook/destinations/ with
webhook_version "v3" and subscribed_events ["status.updated"]) and store the
secret_shared_key it returns. 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
               — the sender's Python json.dumps(sort_keys=True,
               separators=(",", ":"), ensure_ascii=False) after whole-valued
               floats become ints. Reproduce those bytes EXACTLY; do NOT
               "parse, sort keys, JSON.stringify", which fails in four ways:
               numbers come from the wire TEXT, never from parsed doubles
               (read the body with express.text, not express.json(),
               registered ABOVE any global app.use(express.json()), and
               re-emit integers through BigInt(source) — JSON.parse rounds
               1000000000000000129); floats use Python's repr (1e-05, not
               0.00001; 27.0 becomes 27); keys sort by Unicode CODE POINT as
               strings ("10" before "2", U+FF21 before U+1F642, which
               JavaScript's default .sort() reverses); and the bytes come
               straight from the sorted entries, never from a rebuilt object.
               Do NOT hash the raw request bytes — that is the v1
               X-Signature algorithm and fails for V2 whenever whitespace or
               key order differs from the canonical form.
  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. The header is not
               covered by the signature, so it must never be the only replay
               check: a captured delivery replays with just that header
               refreshed.
  Compare:     constant-time (crypto.timingSafeEqual)

Reference handler (Express) — use it as written:

// 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);
});

Body fields you will use: session_id, status, webhook_type, workflow_id,
vendor_data, decision.
Status values: Approved, Declined, In Review, In Progress, Not Started,
Abandoned.

## 6. Reading the result
The decision is the V3 shape: every feature result is a plural array with one
entry per workflow node. ID Verification results live in
decision.id_verifications[] — there is no singular decision.kyc (that is the
V2 shape) and no decision.id_verification. Select your entry by node_id (the
id of your ID Verification node in the workflow graph); with a single ID step,
take index 0. Each entry carries, next to the document fields:

  verification_method    "document" | "id_lookup" | "wallet"
  assurance              "documentary" | "data_match" | "cryptographic"
  wallet_provider        the catalog wallet id the user signed in with; null
                         on document and id_lookup entries
  wallet_verification    provider, provider_name, issuing_authority,
                         issuing_country, credential_type, level_of_assurance
                         (low | substantial | high), verified_at,
                         signature_valid, attributes (what the wallet shared),
                         portrait when the wallet shares one; null otherwise
  fallback_from          { method, reason, action } when the session fell
                         back to document capture or was declined; else null

A wallet entry that succeeds is assurance cryptographic — the highest of the
three. Check wallet_verification.signature_valid before you trust attributes.
Field-by-field reference: https://docs.didit.me/reference/data-models#id-verification

## 7. Billing
  - published customer prices in USD per completed wallet verification:
    - MitID personal: $0.25; production availability: Available
    - BankID Sweden: $0.20; production availability: Available
    - Finnish Trust Network: $0.25; production availability: Available
    - Smart-ID: $0.20; production availability: Available
    - Mobile-ID: $0.20; production availability: Available
    - BankID Norway High: $0.35; production availability: Coming soon
    - Vipps Plus: $0.25; production availability: Coming soon
    - Buypass ID: Coming soon; production availability: Coming soon
    - itsme: Coming soon; production availability: Coming soon
    - iDIN full identification: $0.85; production availability: Coming soon
    - Personalausweis Profile 2: $0.45; production availability: Coming soon
    - Freja eID: $0.25; production availability: Coming soon
    - UAE PASS: Coming soon; production availability: Coming soon
    - gov.br: Coming soon; production availability: Coming soon
    - OneID: $2.50; production availability: Coming soon
    - GOV.UK Wallet: Coming soon; production availability: Coming soon
    - Bank iD: Coming soon; production availability: Coming soon
    - MojeID: Coming soon; production availability: Coming soon
    - Diia: Coming soon; production availability: Coming soon
    - FranceConnect: Coming soon; production availability: Coming soon
    - Auðkenni: Coming soon; production availability: Coming soon
    - ConnectID: Coming soon; production availability: Coming soon
    - EUDI Wallet: Coming soon; production availability: Coming soon
    - Estonian ID-card: Coming soon; production availability: Coming soon
    - eParaksts: Coming soon; production availability: Coming soon
  - an announced price does not enable a wallet; check the live workflow catalog
  - wallet checks are outside the document free tier; other checks are billed separately
  - full pricing: https://docs.didit.me/core-technology/id-verification/digital-id-wallets#pricing
  - document capture bills its own price when the user falls back

## 8. Hard rules — do not change
  - base URL for v3 endpoints: verification.didit.me
  - auth header: x-api-key (lowercase, hyphenated)
  - webhook headers: X-Signature-V2 plus X-Timestamp; canonical JSON, never
    raw bytes; freshness from the signed body timestamp
  - feature enum: OCR (uppercase) — the ID Verification feature; per-country
    methods go under its config.methods
  - method keys: document, id_lookup, wallet (lowercase, snake_case)
  - wallet ids come from the catalog verbatim, lowercase, snake_case
  - country keys: ISO 3166-1 alpha-3, uppercase
  - result path: decision.id_verifications[] (array), never decision.kyc

## 9. Verify your integration
  - run one session per accepted wallet in sandbox
  - assert the id_verifications[] entry for your node has verification_method
    wallet and wallet_verification.signature_valid true
  - cancel a wallet sign-in and assert your on_failure setting actually fires
  - assert your webhook accepts a correctly signed payload with reordered
    keys, whitespace and integer-like metadata keys ("10" before "2"), and
    rejects a wrong X-Signature-V2, a payload whose signed timestamp is older
    than 300 seconds, and that same stale payload with only the X-Timestamp
    header refreshed

Docs: https://docs.didit.me/integration/integration-prompt