Thibitisha mara moja. Tumia tena popote.

# Didit Reusable KYC: verify a person once, share the finished session with another application

You are adding Reusable KYC to my_stack. A person completes one identity
verification; the finished session is then shared with a second Didit
application, which imports the full decision without running the checks
again. Every URL, header and enum value below is canonical. Do not paraphrase
or "improve" them.

## 0. What exists, and what does not
- Reuse is server to server, between two Didit applications: the source
  application mints a share token for a finished session, the receiving
  application redeems it. Both sides use their own x-api-key.
- There is NO reusable_identity object on the webhook or the decision, NO
  metadata.request_fields or other selective-disclosure parameter, NO
  workflow setting that "accepts" a credential, and NO revocation event. Do
  not invent them. metadata on a session is free-form JSON that Didit echoes
  back, nothing more. The receiving application gets the whole decision.
- This is not an EU Digital Identity (EUDI) Wallet integration. Didit does
  not issue or accept EUDI Wallet credentials through these calls.

## 1. Provision
- Sign up: https://business.didit.me
- Source application: its API key. Receiving application: its API key and its
  application id (a UUID: shown in the console, and sent as application_id
  on every webhook that application receives). They are different
  applications; sharing a session with the application that owns it is
  refused.

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

{
  "workflow_label": "KYC onboarding",
  "features": [
    { "feature": "OCR" },
    { "feature": "LIVENESS" },
    { "feature": "FACE_MATCH" },
    { "feature": "IP_ANALYSIS" }
  ]
}

OCR is the ID Verification feature (uppercase, strict: ID_VERIFICATION is
rejected). Add { "feature": "AML" } for sanctions and PEP screening; it is
priced separately. Response: 201. The workflow id is uuid (workflow_id carries
the same value) and features comes back as one string, "OCR + LIVENESS + ...".
Create the workflow once and keep the id: every call makes a new one.
Prices: https://didit.me/pricing

## 3. Create a session
POST https://verification.didit.me/v3/session/
  -H "x-api-key: <source-api-key>"
  -H "Content-Type: application/json"
  -d '{ "workflow_id": "<uuid from step 2>", "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.
Optional: callback, a URL the user's browser is sent back to when the flow
ends. It is a browser redirect, not a webhook: never trust its query string.

## 4. Webhook
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).
               Never hash the raw request bytes under this header: that is
               the older X-Signature.
  Freshness:   the signed body field timestamp is the dispatch time (Unix
               seconds). 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 { session_id, status, webhook_type, vendor_data, decision } = body;
  // decision is present on Approved, Declined, In Review and Abandoned.
  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.

## 5. Read the decision
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.
The other feature results sit next to it as plural arrays: liveness_checks[],
face_matches[], ip_analyses[], aml_screenings[]. shared_from_session is null
on a session the person completed here.

## 6. Share the finished session (source application)
Only a session whose status is Approved, Declined or In Review can be shared.

POST https://verification.didit.me/v3/session/{session_id}/share/
  -H "x-api-key: <source-api-key>"
  -H "Content-Type: application/json"
  -d '{ "for_application_id": "<receiving application id>", "ttl_in_seconds": 3600 }'

Response: 200 with share_token, for_application_id and session_kind ("user").
ttl_in_seconds: 60 to 86400, default 3600. Each call mints a new token; a
token cannot be revoked, it only expires. Send it to the receiving
application's backend, never to a browser.

## 7. Import it (receiving application)
POST https://verification.didit.me/v3/session/import-shared/
  -H "x-api-key: <receiving-api-key>"
  -H "Content-Type: application/json"
  -d '{
    "share_token": "<share_token from step 6>",
    "trust_review": false,
    "workflow_id": "<a workflow id of the receiving application>",
    "vendor_data": "<user id on the receiving side>"
  }'

share_token, trust_review and workflow_id are required. trust_review true
keeps the source status (Approved stays Approved); false puts the imported
session In Review so the receiving team decides. Response: 201 with the same
decision shape as step 5, a new session_id, and shared_from_session pointing
at the source session.

## 8. Errors to handle
The message is under detail for some errors and under the field name
(for_application_id, share_token) for others: read both.
  - share, 400: "Cannot share a session with the same application."
  - share, 400: "Target application does not exist."
  - share, 400: "Only finished sessions ("Approved", "Declined", "In Review")
    can be shared."
  - import, 400 on share_token: "Invalid share token.", "Share token has
    expired.", "This token is not valid for this application."
  - import, 400: share_token, trust_review or workflow_id missing
  - import, 403: "This session has already been shared with your
    application." Mint a new token.
  - import, 404: "Workflow does not exist for this application."

## 9. Hard rules
  - base URL for v3 endpoints: verification.didit.me
  - auth header: x-api-key, one key per application
  - feature enum: OCR, LIVENESS, FACE_MATCH, IP_ANALYSIS, AML (uppercase)
  - result path: decision.id_verifications[] in the webhook body and
    id_verifications[] on the GET decision response
  - webhook: X-Signature-V2 plus X-Timestamp, canonical JSON, freshness from
    the signed body timestamp

## 10. Verify your integration
Sandbox (an application in sandbox mode: nothing is billed).
https://docs.didit.me/integration/sandbox-testing
  - create the workflow, create a session, and read its decision: expect 201,
    201 with url, and 200 with status "Not Started"
  - to get a finished session without a person, call
    POST https://verification.didit.me/v3/session/{session_id}/simulate/ with
    your x-api-key and { "new_status": "Approved" }. It sets the status and
    sends the webhook; the feature arrays stay null.
  - share that session. With no second application yet, send a random UUID
    as for_application_id and expect the 400 "Target application does not
    exist.": that proves the call is wired. A full share and import needs
    the second application's id and API key; do not fake that step.
  - assert the 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

Docs:
  - https://docs.didit.me/core-technology/reusable-kyc/overview
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/integration/webhooks