$10 免费 KYC 额度。
每月如此。

# Didit Free KYC — integrate in 5 minutes

You are integrating Didit's full KYC bundle (ID + Passive Liveness +
Face Match + Device & IP Analysis) into <my_stack>. Every account gets $10 of free credit
every month — no credit card, no sales
call. Past the free credit you keep using the same endpoint at $0.33 per session.
Every URL, header, and enum value below is canonical — do not paraphrase.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).
- The $10 monthly free credit is counted at the workspace level.
  It resets at 00:00 UTC on the first of each month and applies to any
  workflow that combines the four bundled features.

## 2. Create the KYC workflow (one time)
POST https://verification.didit.me/v3/workflows/
Authorization header:  x-api-key: <your-api-key>
Body: workflow_label, features array with the four bundled entries
      [
        { feature: "OCR" },
        { feature: "LIVENESS" },
        { feature: "FACE_MATCH" },
        { feature: "IP_ANALYSIS" }
      ]   (UPPERCASE — strict enum, do not lowercase)

This is the same workflow used in production at $0.33 per session.
Sessions paid from the free credit run on the same model
weights, the same edge nodes, the same Spain-Tesoro-attested pipeline.
There is no degraded model on the Free plan.

## 3. Create a verification session for an end user
POST https://verification.didit.me/v3/session/
Body: workflow_id (from step 2), vendor_data (your own user id).
Response: url (the hosted verification link) — redirect the user to it.

The hosted UI walks the user through document capture, selfie capture
(passive liveness), automatic face-match between portrait and selfie,
and Device & IP analysis on the originating connection. End-to-end inference is
sub-2 seconds across the full bundle.

## 4. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined", "kyc_expired"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 5. Reading the session report
The session decision includes one ARRAY per bundled feature — one entry per
workflow node, each with its own node_id. Select an entry by node_id. The
webhook nests these arrays under decision (as written below); on
GET /v3/session/{session_id}/decision/ the same arrays sit at the response
ROOT (response.id_verifications — there is no response.decision):
- decision.id_verifications[] — status, document_type, document_number,
  full_name, date_of_birth, expiration_date, issuing_state, parsed address,
  image quality scores, warnings.
- decision.liveness_checks[] — status, method ("PASSIVE"), score 0-100,
  reference_image, warnings.
- decision.face_matches[] — status, similarity score 0-100, source
  ("DOCUMENT"), target ("SELFIE").
- decision.ip_analyses[] — status, ip, country, city, vpn, proxy, tor,
  hosting, asn, abuse_score, risk warnings.

Statuses use exact casing: "Approved", "Declined", "In Review",
"Expired", "Not Finished".

## 6. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enums are UPPERCASE: OCR, LIVENESS, FACE_MATCH, IP_ANALYSIS.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Expired", "Not Finished" (title-cased, space-separated).

## 7. Pricing reference (public)
- First $10 of usage per workspace per month: free, no credit
  card, on every account. Credit resets 00:00 UTC on the first of each month.
- Usage past the free credit in a month: $0.33 per session, billed only for the
  usage above the free credit. Same workflow, same endpoint, same
  features, same response shape.
- No minimums, no contracts, no overage surprises. The full price table:
  didit.me/pricing.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test data: deterministic synthetic documents and selfies returned in
  sandbox. Sandbox sessions do not count against the monthly free credit.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/sessions-api/create-session