Transaktionsüberwachung integrieren: KYT-API

Dieser Leitfaden behandelt den gesamten Integrationsumfang von Transaction Monitoring. Der Schnellstart bringt Sie zum Laufen; diese Seite bringt Sie in den Produktivbetrieb.

Architektur

Authentifizierung

Standard-x-api-key-Header. Dieselben Schlüssel werden für Sitzungen und Entitäten verwendet. Siehe API-Authentifizierung.

Transaktion übermitteln

Einziger Endpoint: POST /v3/transactions/. Das vollständige Schema finden Sie unter Transaktionen übermitteln. Minimaler 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" }
}

Umfangreicher Payload mit Zahlungsmethoden, Gerätekontext und benutzerdefinierten Eigenschaften:

{
  "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_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "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-Aliase werden für jedes Feld der obersten Ebene akzeptiert (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening). Das SDK-Wire-Format und das snake_case-Format landen am selben Ort.

Modellierung der Parteien

Jede Transaktion hat ein Pflichtfeld subject (Ihr Kunde, also die Partei, die Sie überwachen) und ein optionales counterparty (die Gegenseite). Jede dieser Parteien hat eine eigene payment_method und optional einen device-Kontext. In der Antwort werden sie im Array parties mit den Rollen APPLICANT und COUNTERPARTY zurückgegeben. Eine Partei ohne vendor_data wird als externer Snapshot (kind: EXTERNAL) ohne verknüpfte Entität gespeichert. Die Parteifelder finden Sie unter Transaktions-Payload.

Idempotenz

txn_id (die von Ihnen gesendete transaction_id) ist pro Anwendung eindeutig. Das erneute Senden einer bereits vorhandenen transaction_id liefert 400 mit A transaction with this transaction_id already exists. im Feld transaction_id. Wenn zwei identische Anfragen gleichzeitig eintreffen, erhält die zweite 409. Keine der beiden Antworten gibt die bestehende Transaktion zurück. Bei einem 400 oder 409 für eine doppelte transaction_id sollten Sie die bestehende Transaktion nachschlagen, statt erneut zu senden. Lesen Sie sie mit GET /v3/transactions/{uuid}/ und der uuid aus der ersten Antwort, oder verwenden Sie die transaction_id (die Didit-UUID), die der Webhook transaction.created neben Ihrer txn_id mitliefert. Erzeugen Sie txn_id immer auf Ihrer Seite, bevor Sie übermitteln. Verlassen Sie sich für die Idempotenz nicht auf eine von Didit generierte ID. Verwenden Sie Ihre eigene Datenbank-ID, eine UUID oder einen Hash der Transaktionsfelder.

Echtzeit vs. Batch

Echtzeit: empfohlen für die meisten Anwendungsfälle. Übermitteln Sie die Transaktion in dem Moment, in dem sie in Ihrem System stattfindet. Regeln werden synchron ausgewertet und liefern die Entscheidung zurück.
Batch / Backfill: Für historischen Datenimport übergeben Sie txn_date mit einem Datum in der Vergangenheit. Regeln werden trotzdem ausgeführt und können Webhooks auslösen. Um beim Backfill keine Regeln auszulösen, verwenden Sie den CSV-Import der Konsole mit dem Flag „dry ingest“.

Historischer Datenimport

Wenn Sie von einem anderen Transaktionsüberwachungssystem migrieren:

Exportieren Sie Ihre historischen Transaktionen als CSV.
Verwenden Sie Transactions → Import history in der Konsole (oder senden Sie die Daten per API in einer Schleife) mit txn_date in der Vergangenheit.
Aktivieren Sie Regeln erst, nachdem der Import abgeschlossen ist, oder verwenden Sie Dry Ingest, um die Regelauswertung zu überspringen.

Seien Sie bei der historischen Regelauswertung umsichtig. Wenn Sie 6 Monate Historie durch eine Regel „20 Transfers in 30 Tagen“ laufen lassen, entstehen auf einmal Tausende Alerts.

Webhooks

Abonnieren Sie:

transaction.created: jede übermittelte Transaktion.
transaction.status.updated: Statusänderungen (z. B. wenn ein Analyst eine Transaktion von IN_REVIEW zu APPROVED verschiebt oder eine asynchrone AML-Prüfung den Score aktualisiert).

Vollständige Details: TM-Webhooks.

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

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

Umgang mit Status

Status	Was zu tun ist
`APPROVED`	Verarbeiten Sie die Transaktion wie gewohnt.
`IN_REVIEW`	Halten Sie die Transaktion zurück, bis die Prüfung durch einen Analysten oder eine automatische erneute Prüfung abgeschlossen ist.
`DECLINED`	Lehnen Sie die Transaktion ab. Zeigen Sie dem Benutzer eine allgemeine Fehlermeldung an.
`AWAITING_USER`	Der Benutzer muss handeln, bevor die Transaktion abgewickelt werden kann. Lesen Sie den Block `action_required` und übergeben Sie dessen `url` an den Benutzer (die SDKs können dies automatisch übernehmen).

Siehe TM-Status.

Transaktionen mit Entitäten verknüpfen

Übergeben Sie vendor_data bei jeder Partei. Vorteile:

Jede Transaktion wird im Profil des Benutzers oder Unternehmens aggregiert.
Velocity- und verhaltensbasierte Regeln haben die vollständige Historie als Grundlage.
Die Sperrung einer Entität wird automatisch auf künftige Transaktionen übertragen.

Fehlendes vendor_data ist kein harter Fehler: Die Transaktion wird als externer Snapshot gespeichert. Sie verlieren dann aber die Aggregation auf Entitätsebene.

Remediation-Sitzungen

Wenn eine Regelaktion eine Transaktion in AWAITING_USER überführt, erstellt Didit automatisch eine Remediation-Sitzung: eine Standard-Verifizierungssitzung über die gehostete Verifizierungsseite mit demselben vendor_data. Benutzerdefinierte Regeln geben den Workflow immer direkt in der Aktion an. Bei integrierten Bibliotheksregeln greift der Workflow zuerst auf den Remediation-Workflow in Ihren Transaktionseinstellungen zurück, danach auf Ihren Workflow für Biometrische Authentifizierung (sofern der Benutzer ein gespeichertes Referenzgesicht hat) und zuletzt auf Ihren Standard-Workflow. Travel-Rule-Transaktionen sind von diesem automatischen Fallback ausgenommen, da ihre ausstehende Aktion der Nachweis des Wallet-Eigentums ist. Die Transaktion (Antwort, jeder spätere Abruf und jeder Webhook) enthält sie im kanonischen 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 wird aus Gründen der Abwärtskompatibilität beibehalten. action_required ist der kanonische Block und enthält auch wallet_ownership-Aktionen für Transfers nach der Travel Rule. Eine wallet_ownership-Aktion ändert den Transaktionsstatus nicht von selbst: Die Transaktion behält den Status, den Ihre Regeln ihr zuweisen, häufig APPROVED. Prüfen Sie daher action_required bei jeder Antwort, nicht nur bei AWAITING_USER. Der Benutzer schließt die Verifizierung ab. Bei einem Workflow für Biometrische Authentifizierung ist das ein Selfie mit Liveness-Prüfung, das mit dem Gesicht aus dem ursprünglichen KYC-Onboarding abgeglichen wird. Diese Prüfstufe ist die stärkste Zusatzprüfung für Transaktionen mit hohem Wert. Sobald für die Sitzung eine Entscheidung vorliegt, folgt die Transaktion ihr automatisch: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) oder IN_REVIEW (user_action_in_review). Dabei wird ein Webhook transaction.status.updated ausgelöst.

Jeder Workflow-Typ außer KYB kann ausgewählt werden. Workflows für Biometrische Authentifizierung (und Workflows, in denen der Gesichtsabgleich vor der Ausweisverifizierung läuft) setzen voraus, dass der Benutzer bereits ein gespeichertes Referenzgesicht aus einer genehmigten Verifizierung hat. Benutzer ohne ein solches werden stattdessen an den Standard-Workflow Ihrer Anwendung weitergeleitet, und auf der Transaktion wird ein Hinweis zu dieser Ersetzung vermerkt.

Bewährte Verfahren

Praxis	Begründung
Übergeben Sie immer `vendor_data`	Ermöglicht die Aggregation.
Verwenden Sie Ihre eigene `txn_id`	Idempotenz.
Abonnieren Sie sowohl `transaction.created` als auch `transaction.status.updated`	Erfasst asynchrone Statusänderungen (z. B. Ergebnisse der Analystenprüfung).
Legen Sie Regel-Schwellenwerte bewusst fest	Niedrige Schwellenwerte = mehr Alerts; hohe = mehr übersehene Risiken. Siehe Risiko-Scoring.
Überwachen Sie die Ausführungszahlen der Regeln in der Konsole	Erkennt Regeln, die nie greifen (fehlkonfiguriert), oder solche, die bei allem greifen (zu locker).
Testen Sie Regeln im TEST-Modus, bevor Sie live gehen	Siehe Regeln.

Rate-Limits

Siehe Rate-Limiting. Die Transaktionserstellung gehört zu den Endpoints mit dem höchsten Durchsatz. Übliche Limits liegen im Bereich von mehreren Hundert Anfragen pro Sekunde. Gehen Sie bei Lastspitzen behutsam vor.

Nächste Schritte

Transaktionen

Vollständige Payload-Referenz.

Regeln

Wie Regeln ausgewertet werden.

Webhooks

Ereigniskatalog.

Fehlerbehebung

Häufige Integrationsprobleme.

Erste Schritte

Funktionen

Referenz

Konsole

Transaktionsüberwachung integrieren: KYT-API

Architektur

Authentifizierung

Transaktion übermitteln

Modellierung der Parteien

Idempotenz

Echtzeit vs. Batch

Historischer Datenimport

Webhooks

Umgang mit Status

Transaktionen mit Entitäten verknüpfen

Remediation-Sitzungen

Bewährte Verfahren

Rate-Limits

Nächste Schritte

Transaktionen

Regeln

Webhooks

Fehlerbehebung

​Architektur

​Authentifizierung

​Transaktion übermitteln

​Modellierung der Parteien

​Idempotenz

​Echtzeit vs. Batch

​Historischer Datenimport

​Webhooks

​Umgang mit Status

​Transaktionen mit Entitäten verknüpfen

​Remediation-Sitzungen

​Bewährte Verfahren

​Rate-Limits

​Nächste Schritte

Transaktionen

Regeln

Webhooks

Fehlerbehebung

Architektur

Authentifizierung

Transaktion übermitteln

Modellierung der Parteien

Idempotenz

Echtzeit vs. Batch

Historischer Datenimport

Webhooks

Umgang mit Status

Transaktionen mit Entitäten verknüpfen

Remediation-Sitzungen

Bewährte Verfahren

Rate-Limits

Nächste Schritte