Transaction Monitoring Integration Guide

This guide covers the full integration surface of Transaction Monitoring. The quickstart gets you running; this page gets you to production.

Architecture

Authentication

Standard x-api-key header. Same keys used for sessions and entities. See API authentication.

Submitting a transaction

Single endpoint: POST /v3/transactions/. See submitting transactions for the full schema. Minimal payload:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

Richer payload with payment methods, device context, and custom properties:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

camelCase aliases are accepted for every top-level field (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening) - the SDK wire format and the snake_case format land in the same place.

Party modeling

Every transaction has a required subject (your customer - the party you monitor) and an optional counterparty (the other side). Each carries its own payment_method and optional device context. In the response, they come back in the parties array with roles APPLICANT and COUNTERPARTY; a party without vendor_data is stored as an external snapshot (kind: EXTERNAL) with no linked entity. See transactions payload for party fields.

Idempotency

txn_id is unique per application. Re-submitting the same txn_id returns the existing transaction’s current state (not an error) — effectively idempotent for retries. Always generate txn_id on your side before submitting; don’t rely on a Didit-generated ID for idempotency. Use your own database ID, a UUID, or a hash of transaction fields.

Real-time vs batch

Real-time — recommended for most use cases. Submit the transaction the moment it happens in your system. Rules evaluate synchronously and return the decision.
Batch / backfill — for historical ingestion, pass txn_date in the past. Rules still run and can trigger webhooks. To avoid triggering rules on backfill, use the console’s CSV import with the “dry ingest” flag.

Historical ingestion

When you’re migrating from another transaction monitoring system:

Export your historical transactions to a CSV.
Use Transactions → Import history in the console (or submit via API in a loop) with txn_date in the past.
Enable rules only after ingestion finishes, or use dry ingest to skip rule evaluation.

Be deliberate about historical rule evaluation. Feeding 6 months of history through a “20 transfers in 30 days” rule will generate thousands of alerts at once.

Webhooks

Subscribe to:

transaction.created — every submitted transaction.
transaction.status.updated — status changes (e.g. analyst moves from IN_REVIEW to APPROVED, or an async AML check updates the score).

Full details: TM webhooks.

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { event, data } = req.body;
  if (event === 'transaction.status.updated' && data.status === 'DECLINED') {
    suspendTransaction(data.txn_id);
  }
  res.status(200).end();
});

Handling statuses

Status	What to do
`APPROVED`	Process the transaction as normal.
`IN_REVIEW`	Hold the transaction until analyst review or automated re-check resolves.
`DECLINED`	Reject the transaction. Surface a generic error to the user.
`AWAITING_USER`	The user must act before the transaction can settle — read the `action_required` block and deliver its `url` to the user (the SDKs can handle this automatically).

See TM statuses.

Linking transactions to entities

Pass vendor_data on every party. Benefits:

Every transaction aggregates into the User or Business profile.
Velocity and behavioral rules have the full history to evaluate against.
Blocking an entity propagates to future transactions automatically.

Missing vendor_data isn’t a hard error — the transaction is stored as an external snapshot — but you lose entity-level aggregation.

Remediation sessions

When a rule action moves a transaction to AWAITING_USER, Didit automatically creates a remediation session - a standard hosted verification session for the same vendor_data. Custom rules always name the workflow on the action itself; for built-in library rules the workflow falls back to the remediation workflow in your transaction settings, then your application’s Biometric Authentication workflow (when the subject has a stored reference face), then your application’s default workflow. Travel Rule transactions are excluded from this automatic fallback - their pending action is wallet-ownership proof. The transaction (response, every subsequent read, and every webhook) carries it in the canonical action_required block:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation is kept for backward compatibility; action_required is the canonical block (it also carries wallet_ownership actions for Travel Rule transfers). The user completes the verification - for a Biometric Authentication workflow, a liveness-checked selfie matched against the face captured at their original KYC onboarding, the strongest step-up for high-value transactions. Once the session reaches a decision, the transaction follows it automatically - APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined), or IN_REVIEW (user_action_in_review) - and a transaction.status.updated webhook fires.

Any workflow type except KYB can be selected. Biometric Authentication workflows (and workflows where face match runs before ID verification) require the subject to already have a stored reference face from an approved verification; users without one are sent to your application’s default workflow instead, with a note on the transaction recording the substitution.

Best practices

Practice	Why
Always pass `vendor_data`	Enables aggregation.
Use your own `txn_id`	Idempotency.
Subscribe to both `transaction.created` and `transaction.status.updated`	Catch async state changes (e.g. analyst review outcomes).
Set rule thresholds deliberately	Low thresholds = more alerts; high = more missed risk. See risk scoring.
Monitor rule run counts in console	Catch rules that never fire (misconfigured) or fire on everything (too loose).
Test rules in TEST mode before going live	See rules.

Rate limits

See rate limiting. Transaction create is one of the highest-throughput endpoints; typical limits are in the hundreds of requests per second. Burst carefully.

Next steps

Transactions

Full payload reference.

Rules

How rules evaluate.

Webhooks

Event catalog.

Troubleshooting

Common integration issues.

Getting Started

Features

Reference

Console

Transaction Monitoring Integration Guide

Architecture

Authentication

Submitting a transaction

Party modeling

Idempotency

Real-time vs batch

Historical ingestion

Webhooks

Handling statuses

Linking transactions to entities

Remediation sessions

Best practices

Rate limits

Next steps

Transactions

Rules

Webhooks

Troubleshooting

​Architecture

​Authentication

​Submitting a transaction

​Party modeling

​Idempotency

​Real-time vs batch

​Historical ingestion

​Webhooks

​Handling statuses

​Linking transactions to entities

​Remediation sessions

​Best practices

​Rate limits

​Next steps

Transactions

Rules

Webhooks

Troubleshooting

Architecture

Authentication

Submitting a transaction

Party modeling

Idempotency

Real-time vs batch

Historical ingestion

Webhooks

Handling statuses

Linking transactions to entities

Remediation sessions

Best practices

Rate limits

Next steps