Let people sign in with
the ID they already have.

# 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. As of this prompt every wallet is coming soon:
the launch switch is off in production, so the catalog will not let you accept
one yet. Build against the catalog and 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"
            }
          },
          "NOR": {
            "document": { "enabled": true },
            "wallet": {
              "enabled": true,
              "providers": ["bankid_no", "vipps"],
              "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. While every wallet is coming soon, 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:
               parse the body, sort keys recursively, serialise compact with
               Unicode preserved and whole-valued floats as integers. 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:

const crypto = require("crypto");

// X-Signature-V2 signs canonical JSON: keys sorted as strings, compact,
// Unicode preserved. Emit the sorted entries directly - rebuilding an object
// would reorder integer-like keys ("10", "2"). Never hash req.rawBody.
const canonical = (v) =>
  Array.isArray(v) ? "[" + v.map(canonical).join(",") + "]"
  : v && typeof v === "object"
    ? "{" + Object.keys(v).sort()
        .map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}"
    : JSON.stringify(v);

app.post("/webhooks/didit", express.json(), (req, res) => {
  // Freshness: the signed body timestamp (refreshed on retry) must be recent
  // and X-Timestamp must agree - the header alone is unsigned and replayable.
  const ts = Number(req.body?.timestamp);
  if (!ts || String(ts) !== req.headers["x-timestamp"] ||
      Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(401);
  const expected = crypto.createHmac("sha256", SECRET)
    .update(canonical(req.body), "utf8").digest("hex");
  const sig = String(req.headers["x-signature-v2"] ?? "");
  const valid = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);
  const { status, decision } = req.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.35; production availability: Coming soon
    - BankID Sweden: $0.30; production availability: Coming soon
    - BankID Norway High: $0.35; production availability: Coming soon
    - Vipps Plus: $0.28; 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
    - Finnish Trust Network: $0.30; production availability: Coming soon
    - Personalausweis Profile 2: $0.45; production availability: Coming soon
    - Freja eID: Coming soon; production availability: Coming soon
    - UAE PASS: Coming soon; production availability: Coming soon
    - gov.br: Coming soon; production availability: Coming soon
    - OneID: Coming soon; production availability: Coming soon
    - GOV.UK Wallet: Coming soon; production availability: Coming soon
    - Smart-ID: Coming soon; production availability: Coming soon
    - Mobile-ID: 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
    - EUDI Wallet: 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