راقب كل معاملة. قدم تقرير الأنشطة المشبوهة (SAR).

You are integrating Didit into a US financial institution (bank, money services business, crypto VASP, broker-dealer, casino, mortgage lender) to satisfy Bank Secrecy Act monitoring + Suspicious Activity Report (SAR) filing under the Financial Crimes Enforcement Network (FinCEN). Three obligations:

  1. Monitor every transaction in real time against the eleven seeded rule bundles (structuring, velocity, mule patterns, geographic risk, sanctioned counterparties, etc.).
  2. Open and manage cases on every flagged transaction.
  3. Export the SAR-ready package matching the FinCEN SAR XML schema for filing via the BSA E-Filing System.

Pricing (verified live 2026-05-16):
  - Transaction Monitoring: $0.02 per transaction call
  - Anti-Money Laundering (AML) Screening on flagged subjects: $0.20 per check, $0.07 per user per year for ongoing monitoring
  - User Verification (Know Your Customer (KYC)) for remediation: $0.33 per check
  - 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 for KYC sessions (used on remediation), and Transaction Monitoring + Case Management enabled in the Business Console.
  - Optional: integration with the BSA E-Filing System on your back-end OR push to your existing investigation tool (Actimize, NICE, Quantexa, ComplyAdvantage Workflow).

STEP 1 — Monitor every transaction with the Transactions API

  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 transaction id>",
      "transaction_category": "finance",
      "transaction_details": {
        "direction": "OUTBOUND",
        "amount": "9500",
        "currency": "USD",
        "currency_kind": "fiat",
        "action_type": "payment"
      },
      "subject": {
        "entity_type": "individual",
        "vendor_data": "<your user id>",
        "full_name": "<user name from verified KYC>"
      },
      "counterparty": {
        "entity_type": "individual",
        "full_name": "<counterparty name if known>",
        "payment_method": {
          "method_type": "wire",
          "account_id": "<counterparty account or routing reference>"
        }
      }
    }

  REQUIRED fields the API rejects if missing:
    - subject.vendor_data + subject.full_name
    - counterparty.full_name
    - transaction_details.direction + currency + currency_kind + amount

  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,
      "cost_breakdown": {
        "total_price": 0.02,
        "items": [{ "usage_type": "transaction_monitoring", "price": 0.02 }]
      }
    }

  Transaction status enum (exact case, UPPER_SNAKE_CASE): APPROVED | IN_REVIEW | DECLINED | AWAITING_USER.

STEP 2 — Branch on the verdict

  APPROVED       → clear the transaction. Webhook may still update later if Ongoing Monitoring catches a delayed signal.
  IN_REVIEW      → hold the transaction. Case opens automatically in the Business Console for analyst triage.
  DECLINED       → refuse the transaction. Case opens at SAR-candidate priority.
  AWAITING_USER  → the workflow needs more data from the customer (source of funds, updated address, refreshed selfie). The response includes a remediation verification URL — send it to the customer.

STEP 3 — Handle AWAITING_USER auto-remediation

  Push the verification URL on the response to the customer (email, app deep-link, push notification). They complete the additional verification in hosted flow on their phone.

  On completion:
    - The remediation session is LINKED to the original transaction (you'll see the linkage in both webhooks).
    - Didit re-runs the relevant rules with the new evidence.
    - The transaction moves to APPROVED (clear) or DECLINED (case opens for SAR consideration).

  The whole loop takes minutes for the user; your team only touches the cases that genuinely need human judgement.

STEP 4 — Case Management — every flagged transaction opens a case

  Cases live in the Business Console with a state machine:

    OPEN          → alert fires, no reviewer yet
    INVESTIGATING → reviewer assigned, gathering context
    SAR_FILED     → SAR exported and filed; case awaits regulator response
    CLOSED        → case resolved, no SAR (with reviewer notes explaining why)

  Each transition is signed, timestamped, and attributed (analyst name + officer name).

  Per case, you get:
    - The flagged transaction(s) + the rule(s) that fired
    - The subject's verified KYC bundle (document, biometric, AML, device + IP)
    - The counterparty data (for crypto: wallet screen; for fiat: counterparty identity if known)
    - Behavioural context (user's transaction history, baseline, velocity)
    - Reviewer narrative (analyst notes, decisions, escalations)

STEP 5 — Export the SAR package

  Two paths:

  Path A — Direct from the Console
    Click "Export SAR XML" on a case. You get a downloadable package matching the FinCEN SAR XML schema. Upload through the BSA E-Filing System manually.

  Path B — Via API + your back-end
    GET https://verification.didit.me/v3/transactions/{id}/
    Headers:
      x-api-key: <your api key>
    The full case payload — every field above — is returned as JSON. Map to the FinCEN schema in your back-end and POST to the BSA E-Filing System programmatically.

STEP 6 — Webhook event names

  Sessions: standard session webhook for remediation completions (verify X-Signature-V2).
  Transactions:
    - transaction.created
    - transaction.updated
    - transaction.status.changed
    - transaction.alert.generated

  Every payload signed with X-Signature-V2 HMAC SHA-256.

STEP 7 — Ongoing AML monitoring is automatic on every verified subject

  Every approved user is re-screened daily against 1,300+ sanctions, PEP, and adverse-media lists at $0.07 per user per year on heavy-volume accounts. When a previously-clean subject crosses an AML threshold, a transaction.alert.generated webhook fires and a case opens automatically.

CONSTRAINTS
  - Session statuses Title Case With Spaces; transaction statuses UPPER_SNAKE_CASE. Don't mix.
  - SAR filing deadlines: 30 days from detection (extendable by 30 days for suspect identification).
  - SAR thresholds: $5,000 aggregate transaction for banks; $2,000 for money services businesses.
  - BSA retention: 5 years on every SAR + supporting documentation.
  - Tipping-off: NEVER disclose the SAR filing to the subject. Encode this in your customer-comms workflow.
  - Default record retention is indefinite while subscribed; configurable per workflow if your supervisor mandates a specific duration.

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.