> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaktionsüberwachung integrieren: KYT-API

> Didit KYT-Architektur: Echtzeit vs. Batch, Parteien, Idempotenz, Webhooks. 1,000 pro Monat inklusive, danach $0.001 pro Aufruf.

Dieser Leitfaden behandelt den gesamten Integrationsumfang von Transaction Monitoring. Der [Schnellstart](https://docs.didit.me/de/transaction-monitoring/quickstart.md) bringt Sie zum Laufen; diese Seite bringt Sie in den Produktivbetrieb.

## Architektur

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Authentifizierung

Standard-`x-api-key`-Header. Dieselben Schlüssel werden für Sitzungen und Entitäten verwendet. Siehe [API-Authentifizierung](https://docs.didit.me/de/getting-started/api-authentication.md).

## Transaktion übermitteln

Einziger Endpoint: `POST /v3/transactions/`. Das vollständige Schema finden Sie unter [Transaktionen übermitteln](https://docs.didit.me/de/transaction-monitoring/transactions.md).

**Minimaler Payload:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](https://docs.didit.me/de/transaction-monitoring/transactions.md).

## 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}/`](https://docs.didit.me/de/management-api/transactions/get) 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:

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

> [!WARNING]
>
> 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](https://docs.didit.me/de/transaction-monitoring/webhooks.md).

```typescript theme={null}
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](https://docs.didit.me/de/transaction-monitoring/sdk-transaction-submission.md#erforderliche-benutzeraktionen)). |

Siehe [TM-Status](https://docs.didit.me/de/transaction-monitoring/statuses.md).

## 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](https://docs.didit.me/de/transaction-monitoring/settings.md#remediation-workflow) 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:

```json theme={null}
{
  "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](https://docs.didit.me/de/transaction-monitoring/travel-rule.md).
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](https://docs.didit.me/de/transaction-monitoring/sdk-transaction-submission.md#beispiel-biometrische-nachprüfung-bei-einer-auszahlung-hoher-beträge).
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.

> [!NOTE]
>
> 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](https://docs.didit.me/de/transaction-monitoring/risk-scoring.md). |
| Ü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](https://docs.didit.me/de/transaction-monitoring/rules.md). |

## Rate-Limits

Siehe [Rate-Limiting](https://docs.didit.me/de/integration/rate-limiting.md). 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

> [card] [Transaktionen](https://docs.didit.me/de/transaction-monitoring/transactions.md)
>
> Vollständige Payload-Referenz.

> [card] [Regeln](https://docs.didit.me/de/transaction-monitoring/rules.md)
>
> Wie Regeln ausgewertet werden.

> [card] [Webhooks](https://docs.didit.me/de/transaction-monitoring/webhooks.md)
>
> Ereigniskatalog.

> [card] [Fehlerbehebung](https://docs.didit.me/de/transaction-monitoring/troubleshooting.md)
>
> Häufige Integrationsprobleme.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.