无需身份证照片，
即可验证个人身份。

# Didit non-document verification — integrate in 5 minutes

You are adding non-document identity verification to my_stack. The user types a
national ID number plus a few personal details, and Didit checks them against
the government database that issued the number. 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
Availability is server-driven per country. Never hard-code a country 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 tells you, per ISO 3166-1 alpha-3 country code:
  - whether id_lookup is available
  - the source label and the public USD rate per answered attempt (36 countries
    are live at the time of this prompt, from Argentina to South Africa)
  - the exact request fields to ask the user for, with their format rules
  - the response fields that come back, and which of them are optional

## 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). Non-document
lookup is its id_lookup method, configured per country under config.methods
on that same feature entry, in the same request. Keys are ISO 3166-1 alpha-3.
An omitted country, or an omitted methods key, means document only.

{
  "workflow_label": "Non-document onboarding",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "methods": {
          "ZAF": {
            "document": { "enabled": true },
            "id_lookup": {
              "enabled": true,
              "max_attempts": 1,
              "skip_liveness_and_face_match": false,
              "on_partial_match": "fallback_to_document",
              "on_no_match": "fallback_to_document",
              "on_provider_error": "fallback_to_document",
              "response_fields": ["gender", "citizenship", "registry_portrait"]
            }
          }
        }
      }
    }
  ]
}

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

Rules that the API enforces:
  - every fallback value is either fallback_to_document or decline
  - max_attempts is an integer from 1 to 5, default 1
  - skip_liveness_and_face_match is only accepted where the source returns a
    portrait; elsewhere it is rejected
  - response_fields lists the OPTIONAL fields you want stored. Required fields
    are always stored and cannot be removed
  - a country whose id_lookup the catalog does not mark available is rejected
  - 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 asks the user for the request fields in plain language, runs the
client-side format check, then queries the registry.

Where the registry returns a portrait (Argentina, Nigeria, Panama, South
Africa), Didit also takes a selfie, runs passive liveness on it, and
face-matches it to that portrait. All of it is inside the lookup price.

## 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"
  id_lookup             source label, checked_at, attempts, outcome, one
                        comparison row per field with match / partial /
                        no_match, and the registry portrait reference when
                        there is one; null on document entries
  fallback_from         { method, reason, action } when the session fell
                        back to document capture or was declined; else null

A non-document entry that succeeds is assurance data_match, never
documentary. The fallbacks only govern unsuccessful lookups (partial match,
no match, provider error): a lookup that matches is accepted as the ID result
and never reaches them, so switching them to decline does not add documentary
evidence. If your risk policy needs documentary assurance for a segment, do
not enable id_lookup for that segment's country: configure
"document": { "enabled": true } alone (omit the id_lookup key, or set its
enabled to false) and route that segment to a workflow of its own when other
users may keep the lookup. As a final guard, treat any id_verifications[]
entry whose assurance is not documentary as failing that policy.
Field-by-field reference: https://docs.didit.me/reference/data-models#id-verification

## 7. Billing — what actually bills
  - a registry that answered bills the lookup. Match, partial match and no
    match all count as answered
  - document capture bills on top when the user falls back
  - a source that never answered is not billed
  - a number that fails the client-side format check never reaches the registry
    and is neither counted nor billed

## 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)
  - 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 configured country in sandbox
  - assert the id_verifications[] entry for your node has verification_method
    id_lookup on the happy path
  - force a no-match and assert the fallback you configured actually fires
  - for a segment that needs documentary assurance, run a lookup that matches
    against that segment's workflow and assert its entry has
    verification_method document and assurance documentary
  - 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