Transaktionen übermitteln: API-Payload & Datenmodell

Übermitteln Sie Transaktionen an Didit über die Transaktion erstellen-API. Jede Transaktion enthält strukturierte Daten zu Parteien, Zahlung und Kontext, die die Regel-Engine in Echtzeit auswertet.

Wenn die Transaktion auf dem Gerät eines Endbenutzers entsteht, etwa bei einer Krypto-Auszahlung oder einer In-App-Zahlung, sollten Sie die Transaktionsübermittlung über das SDK in Betracht ziehen. Ein eingeschränkter Token ersetzt dabei den API-Schlüssel, die Geräteintelligenz wird automatisch erfasst, und erforderliche Nutzeraktionen wie der Nachweis des Wallet-Besitzes oder eine Step-up-Verifizierung werden direkt ausgelöst.

Transaktionskategorien

Jede Transaktion hat einen transaction_category, der bestimmt, wie Regeln und Analysen sie behandeln:

Kategorie	Beschreibung
`finance`	Standardmäßige Finanztransaktion (Einzahlung, Auszahlung, Überweisung)
`kyc`	Ereignis im Zusammenhang mit der Identitätsverifizierung
`travel_rule`	Übertragung virtueller Vermögenswerte, die die Einhaltung der Travel Rule erfordert
`user_event`	Benutzerdefiniertes Plattformereignis (Anmeldung, Profiländerung usw.)
`gambling_bet`	Wette oder Platzierung eines Einsatzes beim Glücksspiel
`gambling_limit_change`	Änderung des Einzahlungs-, Verlust- oder Einsatzlimits eines Spielers
`gambling_bonus_change`	Gewährung, Einlösung oder Verfall eines Bonus
`audit_trail_event`	System- oder Compliance-Auditereignis

Transaktionsdetails

Das Objekt transaction_details enthält die Finanzdaten:

Feld	Typ	Beschreibung
`direction`	string	`inbound` oder `outbound`
`amount`	string	Transaktionswert als Dezimalstring (z. B. `"1500.50"`)
`currency`	string	ISO-Währungscode (z. B. `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` oder `crypto` (Alias `currencyType`); bestimmt, ob das Krypto-Screening ausgelöst wird
`action_type`	string	Vom Anbieter definierte Aktionsbezeichnung (z. B. `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Freitextbeschreibung der Zahlung (z. B. `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	Externe Zahlungsreferenzkennung. Für das Krypto-Screening nach der Überweisung verwenden Sie den Blockchain-Transaktionshash.

Subjekt und Gegenpartei

Jede Transaktion hat ein Subjekt (erforderlich) und optional eine Gegenpartei. Beide verwenden dasselbe Parteimodell:

Feld	Typ	Beschreibung
`entity_type`	string	`person` oder `company`
`vendor_data`	string	Ihre Kennung für diese Partei. Sie verknüpft die Transaktion mit einem Benutzer oder einem Unternehmensprofil.
`full_name`	string	Vollständiger Name der Partei
`first_name`	string	Vorname
`last_name`	string	Nachname
`date_of_birth`	string	ISO-Datum (z. B. `1990-01-15`)
`country_code`	string	ISO-3166-1-Alpha-2-Ländercode
`address`	object oder string	Strukturierte Adresse mit `street`, `city`, `state`, `country`, `postal_code`. Akzeptiert auch eine einfache Zeichenfolge, etwa eine Wallet-Adresse für eine Krypto-Gegenpartei. Didit speichert sie unverändert bei der Partei.

Didit leitet den country_code der Partei aus address.country ab, wenn address ein Objekt ist. Wenn address eine Zeichenfolge ist, wird country_code für diese Partei als null zurückgegeben. Wenn vendor_data mit einem bestehenden Benutzer oder Unternehmen übereinstimmt, verknüpft Didit die Transaktion automatisch mit dem Profil dieser Entität. Dadurch werden sitzungsübergreifende Regelauswertungen und Frequenzprüfungen möglich. In der Antwort werden beide Parteien im Array parties mit den Rollen APPLICANT und COUNTERPARTY zurückgegeben.

Zahlungsmethoden

Fügen Sie jeder Partei ein payment_method hinzu, um das Zahlungsinstrument für die jeweilige Seite zu beschreiben:

Feld	Typ	Beschreibung
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` oder `other` (Alias `type`). `ewallet`, `card` und `crypto` werden als Aliase akzeptiert. Ein nicht erkannter Wert wird als `other` gespeichert.
`account_id`	string	Kontonummer, Wallet-Adresse oder Kartentoken
`issuing_country`	string	Land, das das Zahlungsinstrument ausgestellt hat

Bei travelRule-Transaktionen kennzeichnet eine Zahlungsmethode der Gegenpartei mit method_type: "unhosted_wallet" (Alias type) die Wallet der Gegenpartei als selbstverwahrt. Wenn Travel Rule aktiviert ist und der Betrag in der Standardwährung Ihrer Anwendung nicht unter threshold_amount liegt, wird die Überweisung direkt auf den Status UNCONFIRMED_OWNERSHIP gesetzt und der Ablauf zum Nachweis des Eigentums gestartet. Siehe Deklarierte selbstverwahrte Wallets. Nehmen Sie bei Krypto-Transaktionen Wallet-Adressen in account_id auf und setzen Sie currency_kind auf crypto, damit das Blockchain-Screening automatisch ausgeführt werden kann. Die Richtung legt fest, welche Wallet geprüft wird: Beim Screening vor der Überweisung (inbound) wird die Absender-Wallet in counterparty.payment_method.account_id verwendet. Beim Screening ausgehender Transaktionen (outbound) wird die Ziel-Wallet in counterparty.payment_method.account_id verwendet. Wenn Sie in transaction_details.payment_reference_id einen Blockchain-Hash übermitteln, benötigt das Screening eingehender Transaktionen (inbound) Ihre Einzahlungsadresse des Dienstes in subject.payment_method.account_id, während das Screening ausgehender Transaktionen (outbound) die Ziel-Wallet in counterparty.payment_method.account_id benötigt.

Überschreibung des Krypto-Screenings

Verwenden Sie include_crypto_screening auf der obersten Ebene der Anfrage, um den Standardwert zu überschreiben, der unter Transaktionen > Einstellungen in der Console konfiguriert ist:

Wert	Beschreibung
`true`	Krypto-Screening für diese Transaktion erzwingen
`false`	Krypto-Screening für diese Transaktion überspringen
weggelassen oder `null`	Den Standardwert auf Anwendungsebene verwenden

Gerätekontext

Fügen Sie Geräteinformationen zur betreffenden Partei (und optional zur Gegenpartei) hinzu, damit die Regeln zur Geräteintelligenz greifen. Das Anfragefeld heißt device_context in jeder Partei. Der camelCase-Alias device wird ebenfalls akzeptiert und ist das Übertragungsformat des SDK. Die Antwort enthält device in jeder Partei im Array parties.

Feld	Typ	Beschreibung
`device_context.fingerprint`	string	Eindeutiger Geräte-Fingerprint
`device_context.persistent_device_id`	string	Stabile, sitzungsübergreifende Geräte-ID (v2-Fingerprint-Schema)
`device_context.user_agent`	string	User-Agent-String des Browsers oder der App
`device_context.browser_family`	string	Browserfamilie (z. B. `Chrome`, `Firefox`, `Safari`). Muss explizit gesendet werden. Sie wird nicht aus `user_agent` abgeleitet. Unterstützt Regeln wie `subject_browser_family`.
`device_context.browser_version`	string	Browserversion als String (z. B. `131.0`). Muss explizit gesendet werden.
`device_context.platform`	string	Plattformkennung (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Muss explizit gesendet werden. Sie wird nicht aus `user_agent` abgeleitet. Unterstützt Regeln wie `subject_platform`.
`device_context.os_family`	string	Betriebssystemfamilie (z. B. `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	Betriebssystemversion als String
`device_context.accept_language`	string	Wert des Accept-Language-Headers (z. B. `en-US,en;q=0.9`). Im SDK-Ablauf wird er automatisch erfasst.
`device_context.session_id`	string	Sitzungskennung der aktuellen Sitzung des Benutzers. Wird in den Metadaten gespeichert. CamelCase-Alias: `sessionId`.
`device_context.session_age_ms`	number	Alter der Sitzung des Benutzers in Millisekunden zum Zeitpunkt der Transaktion. Unterstützt Regeln wie `subject_session_age_ms`.
`device_context.network_context.ip_address`	string	Client-IP-Adresse
`device_context.network_context.ip_country_code`	string	Über Geolokalisierung ermitteltes Land der IP (ISO 3166-1 Alpha-3)
`device_context.network_context.latitude`	number	Geografischer Breitengrad der IP
`device_context.network_context.longitude`	number	Geografischer Längengrad der IP

browser_family und platform werden nicht aus user_agent abgeleitet. Sie müssen als explizite Schlüssel auf oberster Ebene innerhalb von device_context gesendet werden, damit die Regeln zur Geräteintelligenz auslösen. Wenn Sie das Didit SDK verwenden, werden diese Felder automatisch erfasst.

Für jedes Feld werden CamelCase-Aliase akzeptiert: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. Das Unterobjekt network_context akzeptiert die Aliase ip, countryCode3, lat und lon. Ein Block ipInfo auf oberster Ebene wird ebenfalls in network_context übernommen. Der Gerätekontext ermöglicht Regeln wie die Erkennung von Mehrfachkonten (gleicher Fingerprint bei verschiedenen betreffenden Parteien), die Erkennung der Kombination aus neuem Browser und neuer IP, eine Übertragung mit hohem Wert bei kurzem Sitzungsalter sowie risikobasiertes Scoring auf Basis des Standorts.

Benutzerdefinierte Eigenschaften

Fügen Sie beliebige weitere Schlüssel-Wert-Paare im Objekt custom_properties hinzu. Regeln können diese Felder in ihren Bedingungen referenzieren. Das ist nützlich, um geschäftsspezifischen Kontext zu übergeben, etwa Produktkategorie, Händler-ID oder Kanal.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

In Regelbedingungen verweisen Sie auf jeden Schlüssel mit dem Feldpfad custom_values.<key>. Zum Beispiel erfüllt die obige Payload die Bedingung custom_values.product_category eq "electronics". Im Regel-Builder der Console erscheinen Schlüssel aus kürzlich erfassten Transaktionen im Feldauswahlmenü für Bedingungen unter Benutzerdefinierte Eigenschaften. Mit Benutzerdefinierte Eigenschaft eingeben in derselben Gruppe können Sie jeden Schlüssel manuell eingeben (Groß- und Kleinschreibung wird beachtet). Details finden Sie unter Regeln und Scoring.

Beispielanfrage

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

Antwort

Die API gibt die erstellte Transaktion mit ihren ersten Auswertungsergebnissen zurück:

Feld	Typ	Beschreibung
`uuid`	string	Eindeutige Transaktionskennung von Didit
`txn_id`	string	Ihre übergebene Transaktions-ID
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED` oder `AWAITING_USER`
`score`	number	Kumulativer Risiko-Score aller zutreffenden Regeln
`severity`	string	Höchster Schweregrad der zutreffenden Regeln (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Maschinenlesbarer Grund für die Statusentscheidung
`decision_reason_label`	string	Für Menschen lesbare Beschreibung der Entscheidung

Die vollständige Anfrage- und Antwortstruktur finden Sie in der API-Referenz. Für eine kommentierte Beispiel-Payload siehe die Referenz zum Antwortschema.

Eine Transaktion einem Prüfer zuweisen

Weisen Sie eine zurückgehaltene Transaktion einem Mitglied Ihrer Anwendung zu oder heben Sie die Zuweisung auf. Dafür benötigen Sie einen API-Schlüssel mit der Berechtigung write:transactions. Jede Änderung wird in der Transaktions-Timeline als TRANSACTION_ASSIGNED erfasst.

Aufruf	Verwendung
`POST /v3/transactions/{transaction_uuid}/assign/`	Eine Transaktion zuweisen.
`POST /v3/transactions/assign/`	Bis zu 500 Transaktionen einem Mitglied zuweisen.

Beide Aufrufe nehmen assignee_email entgegen, die E-Mail-Adresse eines Mitglieds der Anwendung, das sich bei Didit angemeldet hat. Senden Sie null oder einen leeren String, um die Zuweisung aufzuheben. Der Sammelaufruf nimmt außerdem transaction_ids entgegen, eine Liste mit 1 bis 500 Transaktions-UUIDs.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

Der Einzelaufruf gibt uuid, transaction_number, assignee und changed (false, wenn die Transaktion diesem Prüfer bereits zugewiesen war) zurück, oder 404, wenn die Transaktion in der Anwendung nicht existiert. Der Sammelaufruf gibt transactions (ein Eintrag wie oben), updated_count und not_found_transaction_ids zurück. Filtern Sie die Transaktionsliste mit assignee. Das ist eine durch Kommas getrennte Liste, bei der jeder Wert zutreffen kann: me, unassigned, rules (allein durch die Regeln entschieden, ohne Beteiligung eines Prüfers) oder die E-Mail-Adresse eines Mitglieds.

Idempotenz

txn_id (die transaction_id, die Sie senden) ist pro Anwendung eindeutig. Wenn Sie eine transaction_id erneut übermitteln, die bereits existiert, gibt die API 400 mit A transaction with this transaction_id already exists. im Feld transaction_id zurück. Zwei identische, gleichzeitig eintreffende Anfragen führen bei der zweiten zu 409. In beiden Fällen wird die bestehende Transaktion nicht zurückgegeben. Um sicher erneut zu versuchen, behandeln Sie ein 400 oder 409 für eine doppelte transaction_id als „bereits erstellt“ und rufen Sie die bestehende Transaktion ab, statt sie erneut zu übermitteln: 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 (z. B. als Ihre eigene Transaktions-DB-ID, UUID oder deterministischen Hash).

Historische Daten nachladen

Übergeben Sie txn_date mit einem Datum in der Vergangenheit, um historische Transaktionen aufzunehmen. Regeln werden standardmäßig trotzdem ausgewertet. Wenn Sie bei umfangreichen Ladevorgängen historischer Daten die Regelauswertung überspringen möchten, verwenden Sie den CSV-Import in der Konsole mit dem Dry-Ingest-Modus. Siehe Integrationsleitfaden.

Nächste Schritte

Regeln und Scoring

Wie eingereichte Transaktionen anhand von Regeln bewertet werden.

Antwortschema

Vollständige, kommentierte Antwort-Payload.

Krypto-Screening

Automatisches Wallet- und Transaktions-Screening für Krypto-Transaktionen.

Travel Rule

Travel-Rule-Compliance-Daten an Transfers virtueller Vermögenswerte anhängen.

IP-Anreicherung

Aus der IP-Adresse abgeleiteter Kontext, der Regeln zur Verfügung steht.

API-Referenz

Vollständiges Anfrageschema für den Create-Transaction-Endpoint.

Erste Schritte

Funktionen

Referenz

Konsole

Transaktionen übermitteln: API-Payload & Datenmodell

Transaktionskategorien

Transaktionsdetails

Subjekt und Gegenpartei

Zahlungsmethoden

Überschreibung des Krypto-Screenings

Gerätekontext

Benutzerdefinierte Eigenschaften

Beispielanfrage

Antwort

Eine Transaktion einem Prüfer zuweisen

Idempotenz

Historische Daten nachladen

Nächste Schritte

Regeln und Scoring

Antwortschema

Krypto-Screening

Travel Rule

IP-Anreicherung

API-Referenz

​Transaktionskategorien

​Transaktionsdetails

​Subjekt und Gegenpartei

​Zahlungsmethoden

​Überschreibung des Krypto-Screenings

​Gerätekontext

​Benutzerdefinierte Eigenschaften

​Beispielanfrage

​Antwort

​Eine Transaktion einem Prüfer zuweisen

​Idempotenz

​Historische Daten nachladen

​Nächste Schritte

Regeln und Scoring

Antwortschema

Krypto-Screening

Travel Rule

IP-Anreicherung

API-Referenz

Transaktionskategorien

Transaktionsdetails

Subjekt und Gegenpartei

Zahlungsmethoden

Überschreibung des Krypto-Screenings

Gerätekontext

Benutzerdefinierte Eigenschaften

Beispielanfrage

Antwort

Eine Transaktion einem Prüfer zuweisen

Idempotenz

Historische Daten nachladen

Nächste Schritte