Zum Hauptinhalt springen
Die Didit SDKs können überwachte Transaktionen direkt vom Gerät des Endbenutzers übermitteln, einschließlich Travel Rule-Transfers und Krypto-Screening. Ihr Backend erstellt ein kurzlebiges, eingeschränktes Token, und das SDK übernimmt den Rest. Es fügt die Geräteintelligenz automatisch hinzu. Wenn ein Travel-Rule-Transfer einen Nachweis der Wallet-Kontrolle erfordert, startet das SDK diesen Ablauf sofort automatisch. Eine erforderliche Verifizierungssitzung wird niemals automatisch gestartet. Sie wird in der Antwort zurückgegeben, damit Ihre App sie mit Ihrer eigenen Didit-Verifizierungsintegration starten kann. Siehe unten Erforderliche Benutzeraktionen.

Übersicht

Die clientseitige Übermittlung beruht auf drei Garantien:
  • Fälschungssichere Zuordnung des Subjekts. Das Token ist zum Zeitpunkt der Erstellung auf einen vendor_data-Wert (Ihre Benutzer-ID) beschränkt. Die Subjektidentität jeder Transaktion, die damit übermittelt wird, wird serverseitig aus dieser Zuordnung erzwungen. Ein manipulierter Client kann so nicht im Namen eines anderen Benutzers übermitteln, und der Payload muss nie Zugangsdaten enthalten.
  • Automatische Geräteintelligenz. Das SDK erfasst einen Geräte-Fingerprint und sendet ihn zusammen mit der Übermittlung. Didit leitet die Adresse und den User-Agent serverseitig ab. Der kombinierte Gerätekontext wird dem Subjekt der Transaktion ohne zusätzliche Bibliothek, ohne separates Gerätetoken und ohne Aufwand auf Ihrer Seite zugeordnet. Er unterstützt gerätebasierte Regeln sowie die Korrelation verwandter Vorgänge nach Gerät über Sitzungen und Transaktionen hinweg.
  • Automatisch gestarteter Nachweis der Wallet-Kontrolle. Wenn die erstellte Transaktion verlangt, dass der Endbenutzer die Kontrolle über eine Wallet nachweist, enthält die Antwort einen action_required-Block vom Typ wallet_ownership. Das SDK öffnet diesen Ablauf sofort und aktualisiert die Transaktion anschließend, sobald er abgeschlossen ist. Sie müssen dafür keine Polling-Schleifen und keine Linkzustellung selbst implementieren. Eine erforderliche verification_session-Aktion ist anders: Sie wird niemals automatisch gestartet, sondern im selben Block zurückgegeben, damit Ihre App sie mit ihrer eigenen Didit-Verifizierungsintegration starten kann.
Die serverseitige POST /v3/transactions/ bleibt die richtige Wahl, wenn kein Endbenutzer anwesend ist: bei Backoffice-Transfers, Batch-Importen oder Ereignissen, die von Ihren eigenen Systemen gemeldet werden. Beide Wege erstellen dieselben Transaktionsdatensätze, führen dieselben Regeln aus und senden dieselben Webhooks.

Ablauf

1

Transaktions-Token erstellen

Ihr Backend ruft POST /v3/transactions/sdk-token/ mit Ihrem API-Schlüssel und der vendor_data des Benutzers auf und übergibt den zurückgegebenen sdk_token an Ihre App.
2

Vom Gerät übermitteln

Die App ruft submitTransaction im SDK auf. Das SDK sendet den Payload mit dem Header X-Transaction-Token und der automatischen Geräteanreicherung an POST /v1/transactions/.
3

Erforderliche Aktion verarbeiten

Wenn action_required.type wallet_ownership ist, startet das SDK das Widget automatisch und aktualisiert danach die Transaktion über GET /v1/transactions/{transaction_id}/. Ist der Typ verification_session, startet das SDK nichts. Lesen Sie action_required aus und starten Sie Ihren eigenen Verifizierungsablauf mit dessen session_token (im Web mit url).

Transaktions-Token erstellen

Erstellen Sie Token in Ihrem Backend mit POST /v3/transactions/sdk-token/. Die Authentifizierung mit dem API-Schlüssel ist dieselbe wie bei den übrigen Transaktionsendpunkten unter /v3/.
Die camelCase-Aliase (vendorData, ttlSeconds, maxUses) werden ebenfalls akzeptiert, wie in der übrigen /v3/-API.
Liefern Sie Ihren API-Schlüssel niemals in einer App aus. Der API-Schlüssel bleibt in Ihrem Backend und erstellt Token. Nur der kurzlebige sdk_token gelangt auf das Gerät. Erstellen Sie für jede Sitzung des Benutzers ein neues Token, statt langlebige Token wiederzuverwenden. Begrenzen Sie max_uses eng, wenn die Anzahl der erwarteten Übermittlungen bekannt ist.

Vom Gerät aus einreichen

Die SDKs senden Anfragen an POST /v1/transactions/ und übergeben das Token im Header X-Transaction-Token. Das Wire-Payload verwendet camelCase. Die Methoden submitTransaction erstellen es für Sie. Sie arbeiten nur dann direkt damit, wenn Sie den Endpoint über Ihren eigenen HTTP-Client aufrufen:
Jedes Feld auf oberster Ebene entspricht dem jeweiligen Gegenstück in POST /v3/transactions/: Die Antwort entspricht dem Transaktionsdetail im snake_case-Format der /v3/-Endpoints und enthält zusätzlich den Block action_required:

Selbstverwahrte Wallet deklarieren

Das Beispiel oben deklariert das Ziel als selbstverwahrte Wallet des Benutzers: Der paymentMethod.type der Gegenpartei ist unhosted_wallet. Diese Deklaration verändert den Ablauf des Travel-Rule-Austauschs:
  • Didit überspringt das Routing an die VASP der Gegenpartei vollständig, denn hinter einer selbstverwahrten Wallet steht keine VASP. Die Übertragung wird direkt im Status UNCONFIRMED_OWNERSHIP angelegt.
  • Ist auto_wallet_verification in Ihren Travel-Rule-Einstellungen aktiviert (Standardwert), wird automatisch eine Sitzung für das Widget zur Wallet-Eigentumsprüfung erstellt und wie in der obigen Antwort in action_required zurückgegeben.
  • Das SDK startet das Widget automatisch. Sobald der Benutzer nachweist, dass er die Wallet kontrolliert, führt die Übertragung den Namensabgleich durch und wechselt zu COMPLETED. Stimmt der Name nicht mit dem im Adressbuch der Wallet verzeichneten Inhaber überein, wechselt sie zu COUNTERPARTY_MISMATCHED_DATA.
Ohne diese Deklaration versucht Didit stattdessen die Routen der Reihe nach und greift nur dann auf den Eigentumsnachweis zurück, wenn keine VASP der Gegenpartei gefunden wird. Deklarieren Sie die Wallet immer dann, wenn Ihr Produkt bereits weiß, dass das Auszahlungsziel die eigene Wallet des Benutzers ist. So entfällt der fehlgeschlagene Routing-Versuch, und der Benutzer gelangt sofort in den Nachweisablauf.

Verbindliche Vorgaben zum Subjekt

Drei Dinge werden immer durch das Token entschieden, nie durch das Payload:
  • Die Anwendung, unter der die Transaktion angelegt wird.
  • Die Identität des Subjekts: subject.externalUserId im Payload wird ignoriert und durch das vendor_data des Tokens ersetzt.
  • Der Gerätekontext des Subjekts (siehe unten). Bei Konflikten mit allem, was in subject.device übergeben wird, setzen serverseitig abgeleitete Felder sich durch.
Ein 401 von diesem Endpoint bedeutet, dass das Token abgelehnt wurde: fehlend, unbekannt, widerrufen, über seinem max_uses oder abgelaufen. Antworten bei abgelaufenen Tokens enthalten im Fehlerdetail immer das Wort expired. Daran erkennen die SDKs, ob ein Fehler expired_token oder invalid_token lautet.

Transaktion abrufen

GET /v1/transactions/{transaction_id}/ liefert dasselbe Detail und verwendet dieselbe Authentifizierung über X-Transaction-Token. Die SDKs rufen diesen Endpoint automatisch auf, nachdem ein gestarteter Aktionsablauf abgeschlossen ist oder sein Zeitfenster geschlossen wurde. Der endgültige Status hängt daher nie von einem einzelnen Ereignis oder einer einzelnen Benachrichtigung ab. Sie können status und action_required selbst jederzeit erneut prüfen, solange das Token gültig ist. Von Ihrem Backend aus liefert GET /v3/transactions/{transaction_id}/ denselben Datensatz.

Automatische Geräteanalyse

Jede Einreichung enthält Geräteinformationen, ohne dass Sie dafür etwas integrieren müssen:
  • Das SDK erfasst einen datenschutzfreundlichen Geräte-Fingerprint (das Schema didit-fp-v2 mit Plattform- und Navigator-Signalen, einer persistenten Geräte-ID, einem Bot-Score und einem zusammengesetzten Hash) und sendet ihn mit der Anfrage.
  • Didit leitet Adresse, User-Agent und accept-language serverseitig aus der Verbindung selbst ab. Sie lassen sich deshalb nicht über das Payload fälschen.
Das zusammengeführte Ergebnis wird im Gerätekontext des Subjekt-Teilnehmers normalisiert und per Upsert in den Gerätegraphen eingefügt bzw. dort aktualisiert, demselben Graphen, in den auch KYC-Sitzungen einfließen. Dadurch lassen sich Transaktionen über Ihre gesamte Benutzerbasis hinweg nach Gerät verknüpfen („nach Gerät verknüpft“). Geräte- und Netzwerksignale fließen in Regeln und die IP-Anreicherung ein und erscheinen im Transaktionsdetail in der Console. Serverseitig übermittelte /v3/-Transaktionen können für jeden Teilnehmer weiterhin explizite device_context-Objekte übergeben. Über den SDK-Weg erhalten Sie dieselben Daten in umfassenderer Form ohne zusätzlichen Aufwand.

Erforderliche Benutzeraktionen

Bei manchen Transaktionen muss der Endbenutzer etwas tun, bevor sie abgeschlossen werden können: Eine Regel kann eine Verifizierungssitzung verlangen, oder eine Travel-Rule-Überweisung kann einen Nachweis erfordern, dass die Zielwallet tatsächlich dem Benutzer gehört. Beide Fälle erscheinen an derselben Stelle: im Block action_required der Antwort auf die Übermittlung (und bei jedem späteren Abruf der Transaktion).
Wenn beide Fälle auf dieselbe Transaktion zutreffen könnten, hat wallet_ownership Vorrang, weil der fehlende Eigentumsnachweis den Travel-Rule-Austausch selbst blockiert. action_required wird zu null, sobald die ausstehende Aktion abgeschlossen ist. Das bestehende Feld remediation bleibt aus Gründen der Abwärtskompatibilität erhalten; action_required ist der maßgebliche Block.

Regeln für den automatischen Start

autoLaunchAction (Standard true) startet nur die Aktion wallet_ownership automatisch:
  • Web: Sie wird im eigenen Overlay-Modal des SDK geöffnet. Der Abschluss wird über eine Nachrichtenübermittlung mit validiertem Ursprung sowie eine begrenzte Abfrage der Transaktion erkannt, niemals nur über ein einzelnes Ereignis.
  • iOS / Android (sowie die Wrapper für React Native und Flutter, die an die nativen SDKs delegieren): Sie wird als native Oberfläche für den Wallet-Eigentumsnachweis des SDK (SwiftUI / Jetpack Compose) angezeigt, wenn useNativeWalletOwnership auf true steht (Standard). Bei einem Fallback wird SFSafariViewController bzw. ein Chrome Custom Tab verwendet, und zuletzt der Standardbrowser. Nachdem der Ablauf geschlossen wurde oder die App wieder in den Vordergrund kommt, liest das SDK die Transaktion automatisch erneut ein.
Eine verification_session-Aktion wird niemals automatisch gestartet. Sie kommt immer in action_required zurück, damit Ihre App sie mit der eigenen Didit-Verifizierungsintegration startet.
Das Widget für den Wallet-Eigentumsnachweis darf niemals in einer eingebetteten mobilen WebView angezeigt werden. Wallet-Deep-Links können diese nicht verlassen, und der Nachweisablauf endet in einer Sackgasse. Die SDKs verwenden beim automatischen Start bereits die korrekte Browser-Oberfläche. Behalten Sie diese Regel bei, wenn Sie die url selbst verarbeiten. Details finden Sie im Leitfaden zum Widget für den Wallet-Eigentumsnachweis.
Nachdem der automatisch gestartete Ablauf für den Wallet-Eigentumsnachweis des SDK abgeschlossen oder geschlossen wurde, liest das SDK die Transaktion erneut ein und übergibt das aktualisierte Ergebnis an Ihren Callback onActionCompleted. Eine verification_session-Aktion gehört nicht zu diesem Zyklus, da Ihre App sie startet. Siehe dazu den nächsten Abschnitt.

Start einer Verifizierungssitzung

Wenn action_required.type den Wert verification_session hat, lesen Sie den Block aus result.actionRequired und übergeben ihn an Ihre bestehende Didit-Verifizierungsintegration:
Sobald Ihr Verifizierungsablauf abgeschlossen ist, rufen Sie GET /v1/transactions/{transaction_id}/ auf (oder warten Sie auf den Transaktions-Webhook), um den aktualisierten Status der Transaktion abzurufen.

Beispiel: Biometrische Nachprüfung bei einer Auszahlung hoher Beträge

Dies ist der ideale Anwendungsfall: Riskante Transaktionen (hohe Beträge, neue Begünstigte, neue Geräte) werden durch eine biometrische Nachprüfung derselben Person abgesichert, die Sie beim Onboarding verifiziert haben. Eine Kontoübernahme sieht genau so aus: korrektes Passwort, korrekter 2FA-Code (durch Phishing oder SIM-Swap erlangt) und eine Auszahlung an eine Wallet, an die Sie noch nie ausgezahlt haben. Bis dahin sind alle auf Zugangsdaten basierenden Schutzmaßnahmen bereits gescheitert. Ein Gesicht jedoch nicht: Der Angreifer kann keine Liveness-geprüfte Selfie-Aufnahme vorlegen, die mit dem Gesicht übereinstimmen muss, das beim KYC-Onboarding des rechtmäßigen Inhabers erfasst wurde.
1

Regel einmalig in der Konsole anlegen

Transactions → Rules → Create Rule: Bedingung amount gte 5000, Aktion Change status → AWAITING_USER. Wählen Sie bei der Aktion Ihren Workflow Biometrische Authentifizierung aus. Fügen Sie beliebige weitere Risikobedingungen hinzu, etwa eine erstmalige Gegenpartei, einen neuen Geräte-Fingerprint oder einen Wechsel des IP-Landes, als zusätzliche Bedingungen oder zusätzliche Regeln.
2

Auszahlung wie gewohnt einreichen

Ihr Code für die Übermittlung ändert sich nicht. Wenn die Regel auslöst, kommt die Antwort mit status: "AWAITING_USER" und einem Block action_required vom Typ verification_session zurück:
3

Nachprüfung starten

Übergeben Sie den session_token (oder die url) an Ihre bestehende Didit-Verifizierungsintegration, genau wie unter Start einer Verifizierungssitzung beschrieben. Da die Sitzung für dieselbe vendor_data wie das Subjekt der Transaktion erstellt wird, besitzt Didit bereits das verifizierte Referenzgesicht des Benutzers aus dem Onboarding: das genehmigte Liveness-Selfie, das Passfoto aus dem Chip oder das Dokumentporträt. Der Benutzer macht ein einziges Live-Selfie. Didit führt eine Liveness-Prüfung und einen 1:1-Gesichtsabgleich gegen diese gespeicherte Referenz durch. Eine erneute Dokumentenaufnahme oder ein erneutes Onboarding ist nicht nötig. Das bedeutet einige Sekunden Aufwand, und zwar nur bei den Transaktionen, die es verdienen.
4

Auf das Ergebnis reagieren

Wenn die Sitzung abgeschlossen ist, wird die Transaktion automatisch neu bewertet: APPROVED, wenn die Nachprüfung bestanden wurde, DECLINED, wenn sie fehlgeschlagen ist. In beiden Fällen wird ein Webhook transaction.status.updated gesendet (reason: remediation_completed in der Zeitleiste der Transaktion). Ihre App erhält das Ergebnis über Callbacks im Stil von onActionCompleted, über GET /v1/transactions/{transaction_id}/ oder über den Webhook.
Das funktioniert, weil KYC-Onboarding, die erneute biometrische Prüfung und die Transaktionsentscheidung auf einer einzigen Plattform laufen: Das beim Onboarding erfasste Gesicht dient als Referenz für die Step-up-Prüfung, der Geräte-Graph verknüpft die Sitzung mit der Transaktion, und die Regel-Engine bringt beides zusammen – ohne Drittanbieter-Anbindung, ohne Export von Gesichtsbildern und ohne separaten Biometrievertrag. Die erneute Prüfung wird nur dann als Standardfunktion „Biometrische Authentifizierung“ abgerechnet ($0.10), wenn sie tatsächlich ausgeführt wird.

Web-SDK

submitTransaction ist im Web-SDK-Singleton bereits verfügbar:
Das Ergebnis ist { transactionId, status, travelRuleStatus?, actionRequired? }. In der Payload auf SDK-Ebene geben Sie category, details und customProperties an; das SDK ordnet sie für Sie den Wire-Aliasnamen (type, info, props) zu. Fehler werden über DiditTransactionError typisiert:

Native SDKs

Die native API submitTransaction wird mit dem iOS- und Android-SDK 4.1.0 ausgeliefert (sowie mit den React-Native- und Flutter-Releases, die auf diese Version gebunden sind). Anders als beim Web-SDK verwenden die nativen Payloads die Feldnamen des Wire-Formats direkt: type, info und props.
Jedes SDK stellt außerdem getTransaction(transactionToken, transactionId) bereit, um die Transaktion mit demselben Token erneut abzurufen. Die SDKs rufen sie nach einem gestarteten Aktionsablauf für Sie auf, und Sie können sie jederzeit selbst aufrufen. Auf Mobilgeräten wird der Geräte-Fingerprint-Transport bereits auf alle Netzwerkaufrufe des SDK angewendet, sodass Transaktionsübermittlungen automatisch dieselben Geräteinformationen übertragen.

Ohne die SDKs

Alles, was die SDKs tun, läuft über einfaches HTTPS – nichts davon setzt die SDKs voraus. Es gibt zwei gleichwertige Integrationsformen: Nur serverseitig (ohne Tokens). Übermitteln Sie die Transaktion mit POST /v3/transactions/ von Ihrem Backend aus mit Ihrem API-Schlüssel. Die Antwort (und jeder spätere Aufruf von GET /v3/transactions/{transaction_id}/) enthält denselben action_required-Block. Da kein SDK vorhanden ist, das die Geräteinformationen für Sie erfasst, können Sie außerdem pro Teilnehmer einen expliziten device-Kontext übergeben. Clientseitig mit eigenem HTTP-Stack. Erstellen Sie ein Token mit POST /v3/transactions/sdk-token/ und rufen Sie dann vom Gerät aus POST /v1/transactions/ und GET /v1/transactions/{transaction_id}/ mit dem Header X-Transaction-Token auf. Dieselbe Subjektbindung und die serverseitige Ableitung von IP-Adresse und User-Agent gelten auch hier. Behandeln Sie anschließend action_required selbst: Und erkennen Sie den Abschluss ohne Client-Callback:
  • Webhooks (empfohlen). transaction.status.updated wird ausgelöst, wenn die ausstehende Aktion die Transaktion auflöst, und travel_rule.status.updated wird bei jedem Übergang im Austausch ausgelöst. Beide enthalten genug Informationen, um Ihre Datensätze ohne Polling zu aktualisieren.
  • Polling. Lesen Sie die Transaktion erneut aus (/v3/ von Ihrem Backend oder /v1/ mit dem Token, solange es gültig ist): action_required wird nach der Auflösung wieder null, und status bzw. travel_rule.status enthalten das Ergebnis.
In diesem Design gibt es keine einmaligen Abhängigkeiten: Das Widget, die Verifizierungssitzung und Ihr Backend laufen alle auf denselben dauerhaften Transaktionsstatus zusammen. Ein geschlossener Tab oder ein verpasster Webhook lässt sich daher immer wiederherstellen, indem Sie die Transaktion erneut lesen.

Webhooks

Ihr Backend ist nicht auf die App angewiesen, um Rückmeldungen zu erhalten. Wenn eine übermittelte Transaktion eine Aktion des Benutzers erfordert, enthält der Transaktions-Webhook – transaction.created oder transaction.status.updated – denselben action_required-Block. So erfahren Ihre Systeme von der ausstehenden Aktion, auch wenn die App geschlossen wird, bevor der Ablauf abgeschlossen ist. Eine Aktion verification_session geht mit dem Status AWAITING_USER einher, eine Aktion wallet_ownership ändert den Transaktionsstatus jedoch nicht von selbst. Lesen Sie daher action_required statt des Status. Statuswechsel der Travel Rule lösen zusätzlich travel_rule.status.updated aus.

Nächste Schritte

Transaktionen übermitteln

Die serverseitige Create-Transaction-API und die vollständige Payload-Referenz.

Travel Rule

Der verwaltete Austausch zwischen Auftraggeber und Begünstigtem, Einstellungen und Lebenszyklus.

Widget für den Wallet-Eigentumsnachweis

Der gehostete Ablauf zum Kontrollnachweis hinter den wallet_ownership-Aktionen.

Webhooks

transaction.created, transaction.status.updated und Signaturprüfung.

Regeln

Regelaktionen, einschließlich der Aktionen, die Verifizierungssitzungen erstellen.

Status

Was AWAITING_USER im Lebenszyklus der Transaktion bedeutet.
Zuletzt geändert am 7. November 2026