Verify the buyer. Screen the wallet. In one workflow.

You are integrating Didit into a fiat-to-crypto on-ramp. Two obligations on every buy:

  1. Verify the buyer (KYC) — identity, liveness, face match, device + IP, AML against 1,300+ sanctions / PEP / adverse-media lists. ONE call to the Sessions API.
  2. Screen the destination wallet (KYT) — risk-score the address against sanctioned wallets, mixers, high-risk counterparties BEFORE the crypto leaves. ONE call to the Transactions API with currency_kind: "crypto".

Bundle pricing (verified live against POST /v3/transactions/, 2026-05-16):
  - KYC bundle: $0.33 per buyer (Sessions API)
  - Transactions API call: $0.02 base (transaction-monitoring) + $0.15 wallet screening (Didit's default managed provider) = $0.17 per buy
  - Total managed: $0.33 + $0.17 = $0.50 per fully-screened buy
  - Total with BYOK on the wallet provider: $0.33 + $0.04 = $0.37 per buy
  - First 500 KYC 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 that bundles 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 turned on.

STEP 1 — Verify the buyer 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 buyer id, max 256 chars>",
      "callback": "https://<your-app>/onramp/kyc/callback",
      "metadata": {
        "purpose": "crypto_onramp_buy",
        "buy_id": "<your internal tx reference>"
      }
    }

  Response: 201 Created with the hosted session URL. Redirect the buyer to it. Sub-2-second median verdict on completion.

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 buyer 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 — Screen the destination wallet BEFORE crediting the buy

  POST https://verification.didit.me/v3/transactions/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body (required fields verified live 2026-05-16):
    {
      "transaction_id": "<your internal buy 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 buyer id>",
        "full_name": "<buyer 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: a 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.

  Response shape (excerpted from a real successful 201):
    {
      "uuid": "<server transaction uuid>",
      "txn_id": "<your transaction_id echoed back>",
      "status": "APPROVED",
      "score": 0,
      "severity": null,                       // null when score is 0; LOW | MEDIUM | HIGH | CRITICAL | UNKNOWN otherwise
      "props": {
        "wallet_risk_score": 0,
        "sanctions_hit": false,
        "pep_counterparty": false,
        "aml_provider": "<provider slug>",    // identifies the screening provider used on this call
        "aml_screening_type": "WALLET_SCREENING",
        "aml_screening_status": "COMPLETED"
      },
      "provider_results": [{ "provider": "<provider slug>", "result_type": "WALLET_SCREENING", "status": "SCREENED", ... }],
      "cost_breakdown": {
        "total_price": 0.17,
        "items": [
          { "usage_type": "transaction_aml_monitoring", "price": 0.15 },
          { "usage_type": "transaction_monitoring", "price": 0.02 }
        ]
      }
    }

  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.

  Real per-transaction cost (verified live):
    - Plain fiat transaction monitoring: $0.02
    - Crypto transaction with managed wallet screening: $0.17 ($0.02 TM base + $0.15 wallet screen on Didit's managed flow)
    - Crypto transaction with BYOK wallet screening: $0.04 ($0.02 TM base + $0.02 wallet screen)

  Branch logic:
    APPROVED       → send the crypto.
    IN_REVIEW      → hold the buy, route to analyst queue.
    DECLINED       → refund the fiat, block the address.
    AWAITING_USER  → redirect the buyer to the remediation session URL.

STEP 4 — Ongoing AML monitoring is automatic

  Any session with AML enabled is rescreened DAILY by Didit's continuous monitoring at $0.07 per user per year. There is NO separate endpoint to call — the same workflow does it.

  When a previously-approved buyer crosses an AML threshold, the session status changes to "In Review" or "Declined" automatically and your webhook fires the update.

STEP 5 — Off-ramp uses the same two endpoints

  Selling crypto for fiat:
    - KYC the seller via POST /v3/session/ (same as Step 1).
    - Screen the source wallet via POST /v3/transactions/ with direction: "INBOUND" and the source wallet address on subject.payment_method.account_id.

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.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Transaction statuses use UPPER_SNAKE_CASE (APPROVED, IN_REVIEW). They live in different APIs — don't mix them in the same code path.
  - Wallet Screening MUST run BEFORE the crypto leaves — a post-transfer screen is useful for audit but useless for blocking.
  - Default record retention is 5 years post-relationship per the EU AML package; 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, don't re-query.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/transaction-monitoring/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.