المنشئ والمستفيد، في كل تحويل.

You are integrating Didit into a Virtual Asset Service Provider (VASP) / Crypto-Asset Service Provider (CASP) to satisfy the Travel Rule on every crypto transfer. Two obligations:

  1. Verify the user (KYC) — identity, liveness, face match, device + IP, AML. The originator data on every outbound transfer comes from this verified profile.
  2. Submit each transfer with originator + beneficiary fields (IVMS-101) AND screen the counterparty wallet — one /v3/transactions/ call.

Bundle pricing (verified live 2026-05-16):
  - User Verification (KYC) bundle: $0.33 per user (Sessions API)
  - Transactions API call: $0.02 base + $0.15 managed wallet screen = $0.17 per managed transfer
  - With Bring Your Own Key (BYOK) on the wallet provider: $0.04 per transfer ($0.02 + $0.02)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60 seconds, no credit card).
  - Webhook endpoint with HMAC SHA-256 verification of the X-Signature-V2 header.
 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.  - A workflow_id from the no-code Workflow Builder with ID Verification + Passive Liveness + Face Match 1:1 + Device & IP Analysis + AML Screening.
  - Transaction Monitoring + Wallet Screening enabled in the Business Console (Transactions > Settings).

STEP 1 — Verify the user with the Sessions API (one-time onboarding)

  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/onboard/callback",
      "metadata": {
        "purpose": "casp_onboarding"
      }
    }

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

STEP 2 — Read the signed webhook on KYC completion

  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.

  Capture the user's full name, date of birth, address, and any registered identity-document number from the decision payload. These fields populate the IVMS-101 originator block on every subsequent transfer.

STEP 3 — Submit every transfer with IVMS-101 + wallet screen in one call

  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 transfer reference>",
      "transaction_category": "finance",
      "include_crypto_screening": true,
      "transaction_details": {
        "direction": "OUTBOUND",
        "amount": "0.45",
        "currency": "ETH",
        "currency_kind": "crypto",
        "action_type": "transfer"
      },
      "subject": {
        "entity_type": "individual",
        "vendor_data": "<your user id>",
        "full_name": "<originator name from KYC>",
        "address": "<originator address from KYC>",
        "dob": "<originator dob from KYC, YYYY-MM-DD>"
      },
      "counterparty": {
        "entity_type": "individual",
        "full_name": "<beneficiary name>",
        "address": "<beneficiary address if known>",
        "payment_method": {
          "method_type": "crypto_wallet",
          "account_id": "<counterparty 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
    - counterparty.payment_method.account_id (the wallet address)

  Didit packages the subject + counterparty fields into an IVMS-101 payload, hands them off to the connected Travel Rule protocol (TRP / Sumsub TR / Notabene / Veriscope), runs Wallet Screening on the counterparty address server-side, and returns one verdict.

  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,
      "travel_rule": { "status": "EXCHANGED", "protocol": "<network>", "ivms_packet_id": "<id>" },
      "props": {
        "wallet_risk_score": 0,
        "sanctions_hit": false,
        "aml_provider": "<provider slug>",
        "aml_screening_type": "WALLET_SCREENING",
        "aml_screening_status": "COMPLETED"
      },
      "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.
  Wallet-screen severity (UPPER): LOW | MEDIUM | HIGH | CRITICAL | UNKNOWN.

  Branch logic:
    APPROVED       → release the crypto.
    IN_REVIEW      → hold the transfer, route to analyst queue.
    DECLINED       → refuse the transfer, log the IVMS attempt for the audit.
    AWAITING_USER  → redirect the user to the remediation URL on the response.

STEP 4 — Inbound transfers: ingest the counterparty's IVMS packet

  When you RECEIVE a transfer from another VASP:
    - The connected Travel Rule protocol delivers the originator IVMS data to you BEFORE the on-chain transfer settles.
    - Submit it via the same POST /v3/transactions/ with direction: "INBOUND" and the originator fields on subject and your own beneficiary on counterparty.
    - Wallet Screening runs on the originator wallet (subject.payment_method.account_id).
    - Verdict drives whether to credit the user.

STEP 5 — Self-hosted (unhosted) wallet transfers

  For transfers TO a self-hosted wallet (no counterparty VASP to exchange with):
    - Collect the beneficiary identity from the user via a custom questionnaire ($0.10).
    - Above local enhanced-due-diligence thresholds, prompt the user to sign a short message with the beneficiary wallet's private key as proof of control.
    - Submit the transaction with the captured beneficiary fields + wallet address.
    - Didit still runs Wallet Screening on the destination and stores the IVMS-format record for the audit.

STEP 6 — Continuous AML on the user is automatic

  Every approved user is re-screened daily against 1,300+ sanctions, PEP, and adverse-media lists. There is NO separate endpoint to call. When a previously-clean user crosses an AML threshold, the session status updates and a signed webhook fires.

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 Title Case With Spaces; transaction statuses UPPER_SNAKE_CASE. Don't mix.
  - EU Transfer of Funds Regulation has NO de minimis threshold for crypto — every transfer carries originator + beneficiary data.
  - US Travel Rule kicks in at $3,000; UK at £1,000; Singapore at SGD 1,500; Switzerland at CHF 1,000. Apply per-workflow.
  - Default record retention is 5 years post-transfer per most AML regimes; extensible per supervisor guidance.
  - Wallet Screening MUST run BEFORE the crypto leaves — a post-transfer screen is useful for audit but useless for blocking.

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