Onboard a crypto user. Stay MiCA-compliant.

You are integrating Didit's MiCA-aligned crypto user-verification workflow. MiCA is the EU's crypto rulebook; a regulated Crypto-Asset Service Provider (CASP) owes three things on every new customer:

  1. Customer Due Diligence (CDD) — verify identity, screen for sanctions, file the evidence.
  2. Ongoing monitoring — re-screen approved users as watchlists update.
  3. Wallet screening for any crypto outflow — score the destination address before the transfer.

Didit ships all three on one workflow:
  - KYC bundle at $0.33 per user (Sessions API)
  - Continuous AML monitoring at $0.07 per user per year (automatic on any session with AML enabled)
  - Wallet screening at $0.17 per crypto transaction managed, or $0.04 BYOK (Transactions API)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder bundling ID Verification + Passive Liveness + Face Match 1:1 + Device & IP Analysis + AML Screening.
  - Transaction Monitoring enabled in the Business Console (Transactions > Settings) with crypto screening on, if you handle crypto outflows.

STEP 1 — Verify the user with the Sessions API

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with KYC + AML modules>",
      "vendor_data": "<your user id>",
      "callback": "https://<your-app>/casp/kyc/callback",
      "metadata": {
        "purpose": "mica_onboarding",
        "casp_reference": "<your internal reference>"
      }
    }

  Response: 201 Created with a hosted-flow URL. Redirect the user. Sub-2-second median verdict.

STEP 2 — Read the signed webhook on KYC completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces.

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "id_verification": { "status": "Approved" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "ip_analysis": { "status": "Approved" },
      "aml": { "status": "Approved", "hits": [] }
    }

  Status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 3 — Continuous AML monitoring is automatic

  Every approved user is re-screened daily against the same 1,300+ sanctions, PEP, and adverse-media lists used at onboarding. There is NO separate endpoint to call.

  When a previously-clean user crosses a threshold, the session status updates to "In Review" or "Declined" and your webhook fires the same payload shape as the original onboarding event with the new AML hits. A case opens automatically in the Business Console.

STEP 4 — Wallet screening on crypto outflows (Transactions API)

  Required only if you transfer crypto on behalf of the user. Run BEFORE the crypto leaves.

  POST https://verification.didit.me/v3/transactions/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body (required fields verified live):
    {
      "transaction_id": "<your internal reference>",
      "transaction_category": "finance",
      "include_crypto_screening": true,
      "transaction_details": {
        "direction": "OUTBOUND",
        "amount": "0.25",
        "currency": "ETH",
        "currency_kind": "crypto",
        "action_type": "withdrawal"
      },
      "subject": {
        "entity_type": "individual",
        "vendor_data": "<your user id>",
        "full_name": "<user full name>"
      },
      "counterparty": {
        "entity_type": "unhosted_wallet",
        "full_name": "<destination wallet label>",
        "payment_method": {
          "method_type": "crypto_wallet",
          "account_id": "<destination wallet address>"
        }
      }
    }

  REQUIRED fields the API rejects if missing:
    - subject.vendor_data + subject.full_name
    - counterparty.full_name
    - transaction_details.direction + currency + currency_kind + amount
    - For crypto: wallet address on counterparty.payment_method.account_id (OUTBOUND) or subject.payment_method.account_id (INBOUND post-transfer)

  Wallet screening runs server-side when currency_kind = "crypto" and there is a wallet address in the right participant. No separate endpoint.

  Transaction status enum (exact case, UPPER_SNAKE_CASE): APPROVED | IN_REVIEW | DECLINED | AWAITING_USER.
  When a transaction enters AWAITING_USER, Didit creates a linked remediation session automatically and returns a verification URL on the response.

  Branch logic:
    APPROVED       → ship the crypto.
    IN_REVIEW      → hold, route to analyst queue.
    DECLINED       → block, refund, log.
    AWAITING_USER  → redirect the user to the remediation session URL.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Transactions: transaction.created · transaction.updated · transaction.status.changed · transaction.alert.generated.

  Verify X-Signature-V2 on every payload.

EVIDENCE + RECORD RETENTION
  Every approved user comes with a signed evidence pack (document, biometric match, AML hits, device + IP) stored in the EU. Default retention 5 years post-relationship; configurable per workflow.

  Didit holds the only formal EU-government attestation for a KYC platform — issued jointly by Spain's Tesoro, Banco de España, and SEPBLAC. The report files directly into the MiCA evidence pack.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Transaction statuses use UPPER_SNAKE_CASE (APPROVED, IN_REVIEW). Don't mix them in the same code path.
  - Default record retention is 5 years post-relationship; extend per your supervisor's guidance.
  - 200+ fraud signals are evaluated on every KYC session at no extra cost — surface the score via the session decision payload.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/core-technology/aml-screening/overview
  - https://docs.didit.me/transaction-monitoring/aml-screening
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.