Real-time fraud rules.
Fiat. Crypto. One engine.

# Didit Transaction Monitoring — integrate in 5 minutes

You are integrating Didit's Transaction Monitoring into the my_stack codebase.
Follow these steps exactly. Every URL, header, and enum value below is
canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Enable Transaction Monitoring on an application from
  Console -> Applications -> [app] -> Transactions.
- The moment you enable it, the 150+ preset rule library is auto-created on
  the application. You can tune thresholds in the console — there is no
  public rule-CRUD API by design (compliance teams own rule config).

## 2. Submit transactions
Every transaction is screened in real time. One POST, one verdict.

POST https://verification.didit.me/v3/transactions/
Headers:
  x-api-key: YOUR_API_KEY
  Content-Type: application/json

Body (minimum viable shape — see docs for full schema):
{
  "txn_id": "finance0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "1200.00",
    "currency": "EUR",
    "currency_kind": "fiat"
  },
  "subject": {
    "role": "applicant",
    "entity_type": "individual",
    "vendor_data": "user-123"
  },
  "counterparty": {
    "role": "counterparty",
    "entity_type": "individual",
    "full_name": "Jane Doe",
    "country_code": "DE"
  }
}

Response (synchronous): JSON with the computed risk score, the matched
rules, and the verdict status (see step 3).

## 3. Read the verdict
Every transaction lands on one of four statuses (UPPERCASE, strict enum):
- APPROVED       — below all thresholds
- IN_REVIEW      — score >= review threshold (default 60) OR a rule
                   set change_status to IN_REVIEW
- DECLINED       — score >= decline threshold (default 85) OR a rule
                   set change_status to DECLINED, OR an entity matched
                   a blocklist (blocklist always wins, evaluated first)
- AWAITING_USER  — a rule fired with change_status AWAITING_USER; Didit
                   created a remediation Know Your Customer (KYC) session automatically and
                   the verification_url is included in the response

The response also includes:
- score (number)              — cumulative risk score
- rule_runs[]                 — every rule evaluated, with match/no-match
- screening_results           — Anti-Money Laundering (AML), wallet, and IP enrichment outcomes
- decision_reason             — short string when DECLINED
- remediation_session_url     — only when status is AWAITING_USER

## 4. Crypto + Travel Rule
For crypto transfers, set currency_kind to "crypto" and put the wallet
addresses in payment_method.account_id. Didit screens on-chain wallet
risk automatically — no extra API call.

For VASP transfers requiring FATF R.16 (Travel Rule), set
transaction_category to "travel_rule" and include travel_rule_details
with status, protocol (TRISA / TRP / OpenVASP), originator_data, and
beneficiary_data. 12 regional regimes ship with their own rule sets
(EU, UK, Singapore, Hong Kong, Japan, etc.).

## 5. Webhooks
Register one webhook destination once (you can reuse the same destination
for KYC, AML, and Transaction Monitoring events):
POST https://verification.didit.me/v3/webhook/destinations/
Body: url, subscribed_events: [
  "transaction.created",
  "transaction.updated",
  "transaction.status.changed",
  "transaction.alert.generated"
]

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 secret_shared_key
  5. Hex-encode, compare to X-Signature-V2.

## 6. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Auth header is x-api-key (lowercase, hyphenated).
- Status enums are UPPERCASE: APPROVED, IN_REVIEW, DECLINED, AWAITING_USER.
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Do NOT create rules via API — rules are configured in the Business
  Console only. This is a design choice: compliance teams own rule config.

## 7. Pricing reference (public)
- Transaction Monitoring: $0.02 per transaction monitored.
- AML screening fired by a Transaction Monitoring rule: billed at
  $0.20 per AML check (separate line item).
- Wallet Screening (KYT) fired by a crypto rule: $0.15 per screening —
  or bring your own screening provider and run it inside Didit.
- 500 free verifications every month, forever, on every account.
- No minimums, no contracts, no overage surprises.

## 8. Verify your integration
- Send a sandbox transaction with amount 9500 EUR — this trips the
  single-transaction-just-below-threshold preset (+25 score) so you can
  confirm the response carries rule_runs and a non-zero score.
- Trip a structuring pattern by submitting 20 sandbox transfers under
  10,000 EUR for the same vendor_data within 30 days — the
  structuring-outbound preset returns IN_REVIEW.
- Check the Business Console -> Transactions -> Cases tab to confirm an
  alert was generated for every IN_REVIEW.

When in doubt: https://docs.didit.me/transaction-monitoring/overview