> ## 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.

# Sandbox-Testdaten: Szenarien, Magic Values & Dokumente

> Didit in der Sandbox testen: Szenarien, Magic Values, Arm-Endpoint, Dokumente und Einmalcodes für deterministische Tests ohne Abrechnung.

Die **Sandbox** von Didit ist das Äquivalent zu den Testkarten von Stripe oder den Dokumentvorlagen von Sumsub: Sie ermöglicht es Ihnen, jedes Verifizierungsergebnis deterministisch zu reproduzieren, ohne echte Anbieter aufzurufen, echte PII zu verarbeiten oder Ihr Guthaben zu belasten.

> [!NOTE]
>
> Die maßgebliche Quelle für diese Daten ist `serialize_catalog()` im Verifizierungsdienst, live bereitgestellt unter `GET /v1/sandbox/scenarios/`. Eine auf Abweichungen geprüfte Kopie wird in `docs/sandbox/SANDBOX_REFERENCE.md` im Repository `service-didit-verification` über `pipenv run python scripts/generate_sandbox_reference.py` generiert. Diese Seite spiegelt diese Referenz wider — vertrauen Sie immer dem Live-Katalog-Endpoint, falls hier etwas veraltet erscheint. Der Katalog-Endpoint ist authentifiziert: Senden Sie Ihren API-Schlüssel (`x-api-key`) genauso wie bei jedem anderen Aufruf oder ein Sitzungstoken, wenn Sie ihn aus einer laufenden Sitzung heraus abfragen.

## Umgebungsmodell

Die Sandbox ist ein **Modus pro Anwendung** (`ApplicationDetail.mode == SANDBOX`), ähnlich dem Testmodus von Stripe. Während eine Sitzung unter einer Sandbox-Anwendung läuft:

* Jeder externe Anbieter (OCR, AML, Gesichtsabgleich, Liveness, NFC, Telefon, E-Mail, IP, Adressnachweis, Datenbankvalidierung, Document AI) wird **gemockt** — es wird zu keinem Zeitpunkt ein Drittanbieter aufgerufen.
* **Liveness-Erkennung läuft exakt wie in der Produktionsumgebung.** Ein Workflow mit aktiver Liveness-Erkennung führt die echte aktive Erfassung in der Sandbox aus, sowohl im gehosteten Ablauf als auch über die Web-Übergabe der nativen SDKs, sodass Sie die Benutzererfahrung Ihrer Endbenutzer testen können. Lediglich das Liveness-*Ergebnis* wird durch das Szenario oder den Magic Value simuliert, und der Bericht zeichnet die Methode auf, die Ihr Workflow konfiguriert.
* **Benutzerdefinierte Domains sind nur in der Produktionsumgebung verfügbar.** Eine Sandbox-Anwendung kann keine [benutzerdefinierte Domain](https://docs.didit.me/de/console/custom-domain.md) hinzufügen; Sandbox-Sitzungen laufen immer auf der standardmäßigen gehosteten Verifizierungsdomain.
* Sitzungen werden **nie abgerechnet** und die Guthabenprüfung wird umgangen.
* Es gilt ein Kontingent pro Anwendung von **500 Sitzungserstellungen / 24h**.
* Webhooks enthalten `"environment": "sandbox"` (Live-Sitzungen enthalten `"environment": "live"`).
* Der gehostete Ablauf legt die Sitzungsumgebung offen, sodass die Benutzeroberfläche Benutzer davor warnen kann, echte PII hochzuladen.
* **Ergebnisse hängen niemals von den Pixeln ab**: Extrahierte Daten und Status stammen aus dem Szenario / Magic Value. Die erfassten Medien selbst (Dokumente, Selfie, Video, Adressnachweis-Dateien) werden wie in einer Live-Sitzung tatsächlich gespeichert.

## Transaktionsüberwachung in der Sandbox

Die Sandbox ist **sitzungsbasiert**: Sie simuliert die Provider, die eine Verifizierungssitzung aufrufen würde. Die Transaktionsüberwachung hat keinen zu simulierenden Provider, daher wählt eine Sandbox-Anwendung den anderen Weg: Die Transaktion wird gespeichert, aber **nichts, was Entscheidungen trifft, Screenings durchführt, Benachrichtigungen versendet oder Gebühren berechnet, wird jemals für sie ausgeführt**.

Eine auf einer Sandbox-Anwendung erstellte Transaktion wird wie gewohnt persistent gespeichert und zurückgegeben, und nichts von Folgendem geschieht damit:

* **Keine Regelauswertung.** `rule_runs` ist leer, unabhängig davon, in welchem Modus sich Ihre Regeln befinden. Eine `ACTIVE`-Regel auf einer Sandbox-Anwendung wird niemals ausgelöst, sodass die Transaktion auf `APPROVED` mit einem Score von `0` bleibt und kein Alert oder Fall eröffnet wird.
* **Kein AML-Screening / Wallet-Screening.** `provider_results` ist selbst bei Krypto-Transaktionen auf einer Anwendung mit aktivierter Überwachung leer.
* **Keine Webhooks.** Weder `transaction.created` noch `transaction.status.updated` wird für eine Sandbox-Transaktion zugestellt.
* **Keine Abrechnung.** Ein Nutzungsereignis wird mit einem Preis von `0.0000` erfasst, und Ihr Guthaben bleibt unberührt.

Jede Transaktionsantwort enthält ein `environment`-Feld (`"live"` oder `"sandbox"`), sodass ein leeres `rule_runs` niemals mehrdeutig ist: `"sandbox"` bedeutet, dass die Regeln nicht ausgewertet wurden, nicht, dass keine davon zutraf. Die Business Console weist in der Karte *Risk & decision* der Transaktion ebenfalls darauf hin, anstatt nur ein einfaches „No rules evaluated“ anzuzeigen.

> [!NOTE]
>
> **Travel Rule ist die einzige Ausnahme von „nichts wird ausgeführt“.** Auf einer Anwendung mit aktivierter Travel Rule führt eine `travelRule`-Transaktion in der Sandbox weiterhin die Exchange-Engine aus: Der Transferdatensatz wird erstellt und durchläuft die verschiedenen Status.
> Was die Sandbox niemals tut, ist die Kommunikation mit externen Stellen außerhalb von Didit.
> Ihre einzige Gegenpartei ist der [Didit Test VASP](https://docs.didit.me/de/transaction-monitoring/travel-rule-sandbox.md), der in die Plattform integriert ist: Keine Compliance-Nachricht erreicht einen echten Gegenpartei-VASP über irgendeinen Kommunikationsweg (`TRP`, eine von Ihnen verknüpfte Netzwerkmitgliedschaft, E-Mail oder `INTERNAL`), das Screening zur Zuordnung von Gegenpartei-VASPs wird übersprungen und eine Stornierung sendet nichts an eine Gegenpartei.
> `travel_rule.status.updated`-Webhooks werden zugestellt, gekennzeichnet mit `"environment": "sandbox"`.
>
> **Ausgehend** – eine von Ihnen übermittelte `travelRule`-Transaktion.
> Die Prüfung `threshold_amount` wird zuerst ausgeführt, und in der Sandbox gilt sie nur, wenn Sie `transaction_details.amount_in_default_currency` senden, da die Sandbox keine Währungen umrechnet; ohne diese Angabe zählt somit jeder Sandbox-Transfer als über dem Schwellenwert liegend.
> Ein unbeantworteter Transfer läuft nach `confirmation_timeout_hours` ab, und Ihr `timeout_outcome` wird dann auf die Transaktion angewendet.
> Oberhalb des Schwellenwerts gilt die Prüfung für selbstverwahrte Wallets ganz normal: Ein Transfer an eine [deklarierte selbstverwahrte Wallet](https://docs.didit.me/de/transaction-monitoring/travel-rule.md#deklarierte-selbstverwahrte-wallets) geht in `UNCONFIRMED_OWNERSHIP` über, ohne dass etwas versendet wird, und Sie können ihn in der Sandbox über das [Widget zur Bestätigung der Wallet-Inhaberschaft](https://docs.didit.me/de/transaction-monitoring/wallet-ownership-widget.md) abschließen oder über [Inhaberschaft bestätigen](https://docs.didit.me/de/management-api/travel-rule/confirm-ownership.md), wenn sich die Ziel-Wallet bereits in Ihrem Wallet-Adressbuch befindet.
> Jeder andere Transfer über dem Schwellenwert geht an den Didit Test VASP über den Rail `TEST_VASP`, der ihn innerhalb von Didit mit dem Szenario beantwortet, das Sie anhand der Begünstigten-Wallet oder des Begünstigtennamens auswählen: Er wird abgeschlossen, abgelehnt, stimmt nicht überein, wird zu `COUNTERPARTY_VASP_NOT_REACHABLE`, läuft ab (Ihr `timeout_outcome` wird dann auf die Transaktion angewendet) oder wartet auf die Wallet-Inhaberschaft.
> Unter [Travel Rule in der Sandbox testen](https://docs.didit.me/de/transaction-monitoring/travel-rule-sandbox.md) finden Sie jedes Szenario.
>
> **Eingehend** – `POST /v3/travel-rule/inbound/`. Bei der Registrierung wird niemals etwas über einen Kommunikationsweg versendet, daher wird dabei nichts simuliert: Die Sandbox gleicht die Einzahlung mit Ihrem Wallet-Adressbuch ab und wickelt sie synchron ab, genau wie in der Produktionsumgebung. Sie ergibt ein tatsächliches Ergebnis statt `AWAITING_COUNTERPARTY` – `ON_HOLD` (keine Übereinstimmung im Adressbuch), `UNCONFIRMED_OWNERSHIP` (der übereinstimmende Eintrag ist nicht auf Eigentümerschaft verifiziert), `COUNTERPARTY_MISMATCHED_DATA` (Begünstigtenname stimmt nicht mit dem Wallet-Inhaber überein) oder `COMPLETED` gefolgt von `FINISHED` (stimmte mit einem verifizierten Eintrag überein).
> Um stattdessen einen Transfer vom Didit Test VASP zu empfangen, verwenden Sie [Test-VASP-Eingangstransfer auslösen](https://docs.didit.me/de/management-api/travel-rule/trigger-test-vasp-inbound.md) mit einer Ihrer eigenen Wallets aus dem Adressbuch.

### Szenarien für den Didit Test VASP bei Travel Rule

Unter `travel_rule.scenarios` im Katalog sind diese ausgehenden Szenarien aufgeführt. Legen Sie den unten angegebenen Begünstigtennamen bei einer ausgehenden `travelRule`-Transaktion fest, nachdem Sie Travel Rule auf Ihrer Sandbox-Anwendung aktiviert haben. Die oben beschriebenen Prüfungen für den Schwellenwert und deklarierte selbstverwahrte Wallets werden zuerst ausgeführt.

| Szenario | Begünstigtenname | Ergebnis |
| - | - | - |
| `accept` | `Didit Test VASP` | `COMPLETED` |
| `decline` | `Didit Test VASP Decline` | `COUNTERPARTY_VASP_GENERAL_DECLINE` |
| `name_mismatch` | `Didit Test VASP Name Mismatch` | `COUNTERPARTY_MISMATCHED_DATA` |
| `not_reachable` | `Didit Test VASP Not Reachable` | `COUNTERPARTY_VASP_NOT_REACHABLE` nach Wiederholungsversuchen bei der Zustellung |
| `timeout` | `Didit Test VASP Timeout` | `EXPIRED`, wenn die Ablaufprüfung nach der einminütigen Frist ausgeführt wird |
| `self_hosted` | `Didit Test VASP Self Hosted` | `UNCONFIRMED_OWNERSHIP` |

Sie können ein Szenario auch über die Wallet-Adresse des Begünstigten anstelle des Namens auswählen (die Wallet hat Vorrang, wenn beides angegeben ist), und ein Transfer, bei dem keines von beidem angegeben ist, wird als `accept` abgeschlossen. Unter [Travel Rule in der Sandbox testen](https://docs.didit.me/de/transaction-monitoring/travel-rule-sandbox.md) sind die Wallet für jedes Szenario und das genaue Ergebnis aufgeführt.

Der [Auslöser für eingehende Test-VASP-Transfers](https://docs.didit.me/de/management-api/travel-rule/trigger-test-vasp-inbound.md) akzeptiert in seinem Feld `scenario` nur `accept` und `name_mismatch`.

> [!NOTE]
>
> **So testen Sie eine Regel, bevor sie live geht.** Verwenden Sie
> [Backtest](https://docs.didit.me/de/transaction-monitoring/rules-api.md#erstellen-backtest-durchführen-aktivieren): Es wendet
> die Regel rückwirkend auf Ihren echten Transaktionsverlauf an und meldet `evaluated` /
> `matched` / `affected_entities`, ohne den Status irgendeiner Transaktion zu verändern. Kombinieren Sie dies
> mit dem Modus `TEST` auf der Live-Anwendung – eine `TEST`-Regel wird bei jeder neuen
> Live-Transaktion ausgewertet und zeichnet auf, worauf sie zugetroffen hätte, ohne den
> Score oder Status zu ändern – und wechseln Sie zu `ACTIVE`, sobald die Selektivität passt.

## So wechseln Sie zwischen Live und Sandbox

Live und Sandbox sind **separate Anwendungen**, sodass Test-Traffic und Produktionsdaten niemals vermischt werden. Jede Anwendung hat einen `mode` von `live` oder `sandbox`:

* Verwenden Sie den API-Schlüssel einer Anwendung im **Sandbox-Modus**, um gemockte, nicht abgerechnete und simulierbare Sitzungen zu erhalten.
* Verwenden Sie den API-Schlüssel einer Anwendung im **Live-Modus** für echte Verifizierungen.

Das Feld `sandbox_scenario` (bei der Sitzungserstellung und in der Standalone-AML-API) sowie die Simulations-Endpoints werden nur bei Sandbox-Anwendungen akzeptiert; bei Live-Anwendungen werden sie abgelehnt.

## Sandbox im gehosteten Verifizierungsablauf

Sitzungen, die unter einer Sandbox-Anwendung erstellt wurden, stellen zusätzliche UI-Elemente im gehosteten Verifizierungsablauf bereit (die von `POST /v3/session/` zurückgegebene `url`):

* **Sandbox-Banner in der Karte.** Jeder Bildschirm zeigt ein Banner innerhalb der Karte – „Test data only - no real calls“ –, sodass immer ersichtlich ist, dass die Sitzung niemals echte Anbieter aufruft und Ihr Guthaben nicht anrührt. Erfasste Medien werden wie bei jeder Sitzung gespeichert; verwenden Sie daher die Beispieldokumente und Testdaten anstelle von echten Ausweisdokumenten oder personenbezogenen Daten.
* **Szenario-Auswahl vor dem Ablauf.** Bevor die Erfassung beginnt, führt eine Auswahl innerhalb der Karte den Benutzer durch die Wahl eines Testergebnisses: Wählen Sie ein Ergebnis und anschließend einen Auslöser für dieses Ergebnis. Bei Bestätigung wird `POST /v3/session/{session_id}/sandbox/arm/` aufgerufen (siehe [Sitzung vor Beginn des Ablaufs scharfschalten (oder erneut scharfschalten)](#3-sitzung-vor-start-des-ablaufs-scharfschalten-oder-erneut-scharfschalten) unten), und der Ablauf wird mit den bereits angewendeten Magic-Werten dieses Szenarios fortgesetzt.
* **Leiste mit Beispieldokumenten.** Eine einzelne Zeile mit Sandbox-Beispieldokumenten (bis zu 3) befindet sich direkt unter der Dokument-Upload-/Erfassungskomponente. Tippen Sie auf ein Dokument, um es anstelle eines echten Uploads zu verwenden.

Sandbox-Sitzungen speichern die **echten** erfassten Medien – Dokumente, Selfie, Liveness-Video und Adressnachweis-Dateien werden genau wie bei einer Live-Sitzung hochgeladen und aufbewahrt. Die *extrahierten* Daten (Felder der Ausweisverifizierung, Übereinstimmungswerte, Liveness-Ergebnisse und ähnliches) sowie das Sitzungsergebnis selbst (genehmigt / in Prüfung / abgelehnt) werden durch das Szenario oder den Magic-Wert simuliert – sie werden niemals aus den erfassten Medien abgeleitet. Die Business Console kennzeichnet die Bereiche mit extrahierten Daten einer Sandbox-Sitzung mit einem **Simulated data**-Chip, sodass Prüfer auf einen Blick erkennen können, welche Teile der Sitzung die echte Erfassung darstellen und welche szenariogesteuert sind.

## Szenarien

Jedes Szenario ist ein benanntes Bündel von Magic Values. Übergeben Sie dessen Slug als `sandbox_scenario` bei der Sitzungserstellung (oder an den simulate-Endpoint), um das Ergebnis zu reproduzieren.

| Slug | Titel | Standardstatus | Beschreibung |
| - | - | - | - |
| `approve` | Happy path — alle Funktionen genehmigt | Genehmigt | Standardverhalten der Sandbox: Jede gemockte Funktion gibt ein unauffälliges APPROVED-Ergebnis zurück. Die Sitzung endet mit dem Status APPROVED. |
| `decline_aml_hit` | AML — politisch exponierte Person | Abgelehnt | AML-Mock gibt einen Treffer zurück und die Sitzung wird bei der AML-Funktion abgelehnt. Der Treffer verwendet dasselbe [Hit-Schema](https://docs.didit.me/de/core-technology/aml-screening/report-aml-screening.md#felder-pro-treffer) wie produktive AML-Anbieter — `url`, `match_score`, `risk_score`, `review_status`, `properties`, `pep_matches[]` und `score_breakdown` sind alle befüllt — und ein POSSIBLE\_MATCH\_FOUND-Warnungs-Log wird geschrieben. |
| `decline_document_expired` | Ausweisverifizierung — Dokument abgelaufen | Abgelehnt | Der Ausweisverifizierungs-Mock gibt einen Reisepass zurück, dessen Ablaufdatum in der Vergangenheit liegt. Die Sitzung wird bei der Ausweisverifizierung mit einem DOCUMENT\_EXPIRED-Warnungs-Log abgelehnt. |
| `decline_minimum_age` | Ausweisverifizierung — unterhalb der Mindestalter-Richtlinie | Abgelehnt | Der Ausweisverifizierungs-Mock gibt ein Geburtsdatum zurück, aus dem sich ein Alter des Benutzers von etwa 10 Jahren ergibt. Die produktive Altersprüfung gibt MINIMUM\_AGE\_NOT\_MET aus und der Workflow lehnt ab. |
| `decline_mrz_validation` | Ausweisverifizierung — MRZ-Prüfsummenfehler | Abgelehnt | Der Ausweisverifizierungs-Mock gibt einen Reisepass mit einer beschädigten MRZ-Prüfsumme zurück. Der produktive MRZ-Validator gibt MRZ\_VALIDATION\_FAILED aus und die Sitzung wird abgelehnt. |
| `decline_could_not_recognize_document` | Ausweisverifizierung — unlesbares Dokument | Abgelehnt | Der Ausweisverifizierungs-Mock gibt eine leere Antwort zurück. Die Produktionsumgebung löst COULD\_NOT\_RECOGNIZE\_DOCUMENT aus und leitet dies an das SDK weiter. |
| `decline_face_match_low_similarity` | Gesichtsabgleich — Ähnlichkeit unter dem Schwellenwert für Ablehnung | Abgelehnt | Gesichtsabgleich-Mock gibt einen niedrigen Wert zurück. Die Produktionsumgebung gibt LOW\_FACE\_MATCH\_SIMILARITY aus und das Aktions-Mapping des Workflow-Knotens lehnt ab. |
| `decline_database_no_match` | Datenbankvalidierung — kein Treffer über alle Dienste hinweg | Abgelehnt | Jeder ausgewählte Datenbankdienst gibt NO\_MATCH zurück. Die Produktionsumgebung gibt DATABASE\_VALIDATION\_NO\_MATCH aus und der Workflow lehnt ab. |
| `decline_phone_high_risk` | Telefon — reservierte Hochrisiko-Testnummer | Abgelehnt | Der Telefonverifizierungs-Mock blockiert die Verifizierung (reservierter Testbereich). Die Telefonverifizierung endet als BLOCKED und gibt HIGH\_RISK\_PHONE\_NUMBER aus. |
| `decline_email_breach` | E-Mail — Treffer in Datenleck-Datenbank | Abgelehnt | Der E-Mail-Breach-Mock gibt einen Treffer in einer Datenleck-Datenbank für die Adresse zurück. Die E-Mail-Verifizierung gibt BREACHED\_EMAIL\_DETECTED aus. |
| `decline_ip_blocklist` | IP-Analyse — IP-Adresse in Sperrliste | Abgelehnt | IP-Analyse-Mock lehnt den Standort mit IP\_ADDRESS\_IN\_BLOCKLIST ab. Die Sitzung wird bei der IP-Analyse abgelehnt. |
| `decline_poa_address_mismatch` | Adressnachweis — Adressabweichung von den angegebenen Daten | Abgelehnt | Adressnachweis-Mock lehnt den Nachweis mit ADDRESS\_MISMATCH\_WITH\_PROVIDED ab. Die Sitzung wird beim Adressnachweis abgelehnt. |
| `decline_liveness_attack` | Liveness — Angriffsversuch auf das Gesicht erkannt | Abgelehnt | Passiver Liveness-Mock erkennt ein Signal für einen Gesichtsangriff und gibt LIVENESS\_FACE\_ATTACK aus. Die Sitzung wird bei Liveness abgelehnt. |
| `decline_nfc_chip_not_verified` | NFC — ePass-Chip nicht verifiziert | Abgelehnt | ePass-Mock gibt einen Chip zurück, dessen SOD/DG-Signatur die Integritätsprüfung nicht besteht. Die Produktionsumgebung gibt NFC\_CHIP\_NOT\_VERIFIED aus und die Sitzung wird bei NFC abgelehnt, wenn der Workflow bei nicht verifizierten Chips ablehnt. |
| `decline_nfc_trust_anchor_missing` | NFC — ausstellender Vertrauensanker nicht verfügbar | Abgelehnt | ePass-Mock gibt einen Chip zurück, der von einem DSC signiert wurde, dessen ausstellende CSCA im Vertrauensspeicher fehlt. Die Produktionsumgebung gibt NFC\_TRUST\_ANCHOR\_MISSING aus und die Sitzung wird abgelehnt, wenn der Workflow bei nicht verifizierten Chips ablehnt. |
| `decline_document_ai_unreadable` | Document AI — unlesbares Dokument | Abgelehnt | Document AI-Mock gibt keine lesbaren Felder zurück. Die Produktionsumgebung gibt DOCUMENT\_AI\_UNREADABLE\_DOCUMENT aus und das Dokument wird als abgelehnt eingestuft, sobald das Kontingent an Wiederholungsversuchen erschöpft ist. |
| `review_aml_possible_match` | AML — möglicher Treffer erfordert Prüfung | In Prüfung | AML-Mock gibt einen Treffer mit geringerer Konfidenz zurück. Die Sitzung wird auf In Prüfung gesetzt mit einem POSSIBLE\_MATCH\_FOUND-Log auf Warnungsebene, das von einem Analysten aufgelöst werden muss. |
| `review_face_match_borderline` | Gesichtsabgleich — grenzwertige Ähnlichkeit | In Prüfung | Gesichtsabgleich-Mock gibt einen Wert zwischen den Schwellenwerten für Prüfung und Ablehnung zurück. Die Sitzung wird beim Gesichtsabgleich auf In Prüfung gesetzt. |
| `review_document_borderline_age` | Ausweisverifizierung - Minderjährigkeit zur Prüfung weitergeleitet | In Prüfung | Der Ausweisverifizierungs-Mock gibt ein Geburtsdatum zurück, aus dem sich ein Alter unterhalb des im Workflow konfigurierten Mindestalters ergibt. Die minimum\_age\_action des Workflows ist auf REVIEW statt DECLINE gesetzt, sodass die Sitzung bei der Ausweisverifizierung auf In Prüfung gesetzt wird, anstatt abgelehnt zu werden. |
| `review_poa_partial_match` | Adressnachweis — teilweise Adressübereinstimmung | In Prüfung | Adressnachweis-Mock gibt eine Adresse zurück, die nur teilweise mit der angegebenen übereinstimmt. Die Sitzung wird beim Adressnachweis auf In Prüfung gesetzt. |
| `review_database_partial_match` | Datenbankvalidierung — teilweiser Treffer | In Prüfung | Datenbankdienste geben teilweise Übereinstimmungen bei Name und Geburtsdatum zurück. Die Sitzung wird bei der Datenbankvalidierung auf In Prüfung gesetzt. |
| `decline_kyb_registry_mismatch` | KYB - Abweichung bei den Daten des Unternehmensregisters | Abgelehnt | Mock des Unternehmensregisters gibt ein Unternehmen zurück, dessen Registrierungsdaten nicht mit den erwarteten Angaben übereinstimmen. Die Unternehmenssitzung wird bei der Unternehmensregisterprüfung abgelehnt. |
| `review_kyb_registry_partial` | KYB - Daten des Unternehmensregisters stimmen teilweise überein | In Prüfung | Mock des Unternehmensregisters gibt ein Unternehmen zurück, dessen Name nur teilweise übereinstimmt. Die Unternehmenssitzung wird bei der Unternehmensregisterprüfung auf In Prüfung gesetzt. |

`review_*`-Szenarien existieren, damit Sie die UX der manuellen Prüfung (die Prüfwarteschlange der Konsole, `In Review`-Webhooks, Genehmigungs-/Ablehnungsaktionen von Prüfern) testen können, ohne eine Eingabe zu benötigen, die eine Ablehnung auslöst. Die beiden obigen `kyb_*`-Szenarien setzen `expected_details.registration_number` anstelle von `expected_details.first_name`: Sie gelten nur für Sitzungen der Unternehmensverifizierung (KYB).

## Magische Werte

Ein magischer Wert ist eine spezifische Eingabe, die dazu führt, dass eine gemockte Funktion ein bestimmtes Risiko ausgibt. Setzen Sie das Eingabefeld auf den magischen Wert (direkt oder über ein Szenario), um es auszulösen.

| Funktion | Eingabefeld | Magischer Wert | Risiko | Beschreibung |
| - | - | - | - | - |
| AML | `user_email` | `sandbox+aml_hit@didit.test` | `POSSIBLE_MATCH_FOUND` | AML — politisch exponierte Person; der AML-Mock liefert einen Treffer zurück, die Sitzung wird aufgrund von AML abgelehnt. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOCUMENT_EXPIRED` | `DOCUMENT_EXPIRED` | OCR — Dokument abgelaufen; die Sitzung wird bei der Ausweisverifizierung abgelehnt. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_MINIMUM_AGE_NOT_MET` | `MINIMUM_AGE_NOT_MET` | OCR — das Geburtsdatum führt dazu, dass der Benutzer unter dem konfigurierten Mindestalter liegt; Sitzung wird abgelehnt. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_MAXIMUM_AGE_EXCEEDED` | `MAXIMUM_AGE_EXCEEDED` | OCR — das extrahierte Geburtsdatum führt zu einem Alter über dem konfigurierten Höchstalter. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOCUMENT_NUMBER_FORMAT_MISMATCH` | `DOCUMENT_NUMBER_FORMAT_MISMATCH` | OCR — die extrahierte Dokumentnummer stimmt nicht mit dem erwarteten Format-Regex des Dokuments aus dem Dokumentenregister überein. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_PERSONAL_NUMBER_FORMAT_MISMATCH` | `PERSONAL_NUMBER_FORMAT_MISMATCH` | OCR — die extrahierte persönliche Nummer besteht die Formatprüfung des Dokumentenregisters nicht. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | OCR — der extrahierte Dokumenttyp liegt außerhalb der Richtlinie `documents_allowed` der Anwendung. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED` | `FULL_NAME_MISMATCH_WITH_PROVIDED` | OCR — der Name auf dem Dokument erreicht im Abgleich mit dem vom Kunden in `expected_details` vorausgefüllten Namen nicht den Schwellenwert für die Namensübereinstimmung. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_GENDER_MISMATCH_WITH_PROVIDED` | `GENDER_MISMATCH_WITH_PROVIDED` | OCR — das extrahierte Geschlecht weicht von `expected_details.gender` ab. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED` | `DOB_MISMATCH_WITH_PROVIDED` | OCR — das extrahierte Geburtsdatum weicht von `expected_details.date_of_birth` ab. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_COUNTRY_MISMATCH_WITH_PROVIDED` | `COUNTRY_MISMATCH_WITH_PROVIDED` | OCR — der Ausstellerstaat weicht von `expected_details.country` (oder `id_country`) ab. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_NATIONALITY_MISMATCH_WITH_PROVIDED` | `NATIONALITY_MISMATCH_WITH_PROVIDED` | OCR — die extrahierte Staatsangehörigkeit weicht von `expected_details.nationality` ab. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | OCR — die extrahierte Dokument-/Personen-/Steuernummer stimmt nicht mit `expected_details.identification_number` überein. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_COULD_NOT_RECOGNIZE_DOCUMENT` | `COULD_NOT_RECOGNIZE_DOCUMENT` | Die OCR-Pipeline liefert ein leeres / nicht erkennbares Ergebnis; die Produktion löst COULD\_NOT\_RECOGNIZE\_DOCUMENT aus. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_MRZ_NOT_DETECTED` | `MRZ_NOT_DETECTED` | OCR — das Dokument erwartet eine MRZ, aber die Pipeline konnte keine finden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_MRZ_VALIDATION_FAILED` | `MRZ_VALIDATION_FAILED` | OCR — MRZ wurde gefunden, hat aber die Prüfsummen-/Formatvalidierung nicht bestanden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | OCR — MRZ-Identitätsfelder weichen von den aus der VIZ extrahierten Feldern ab. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_BARCODE_NOT_DETECTED` | `BARCODE_NOT_DETECTED` | OCR — das Dokument erwartet einen Barcode, es wurde jedoch keiner gefunden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_BARCODE_VALIDATION_FAILED` | `BARCODE_VALIDATION_FAILED` | OCR — Barcode wurde decodiert, bestand jedoch die feldübergreifende Validierung nicht. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_QR_NOT_DETECTED` | `QR_NOT_DETECTED` | OCR — das Dokument erwartet einen QR-Code, es wurde jedoch keiner gefunden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_QR_VALIDATION_FAILED` | `QR_VALIDATION_FAILED` | OCR — QR-Code wurde decodiert, bestand jedoch die feldübergreifende Validierung nicht. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DATA_INCONSISTENT` | `DATA_INCONSISTENT` | OCR — interne Konsistenzprüfungen der VIZ-Felder stimmen nicht überein. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOCUMENT_SIDES_MISMATCH` | `DOCUMENT_SIDES_MISMATCH` | OCR — die document\_name-Werte für Vorder- und Rückseite gehören nicht zum selben Dokument. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_NAME_NOT_DETECTED` | `NAME_NOT_DETECTED` | OCR — weder Vor- noch Nachname konnten aus dem Dokument extrahiert werden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DATE_OF_BIRTH_NOT_DETECTED` | `DATE_OF_BIRTH_NOT_DETECTED` | OCR — die Dokumentklasse erwartet ein Geburtsdatum, die Extraktion ergab jedoch keines. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_EXPIRATION_DATE_NOT_DETECTED` | `EXPIRATION_DATE_NOT_DETECTED` | OCR — die Dokumentklasse erwartet ein Ablaufdatum, die Extraktion ergab jedoch keines. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_DOCUMENT_NUMBER_NOT_DETECTED` | `DOCUMENT_NUMBER_NOT_DETECTED` | OCR — weder Dokumentnummer noch persönliche Identifikationsnummer konnten extrahiert werden. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_COULD_NOT_DETECT_DOCUMENT_TYPE` | `COULD_NOT_DETECT_DOCUMENT_TYPE` | OCR — der Klassifikator konnte die Aufnahme keinem unterstützten Dokumenttyp zuordnen. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_PORTRAIT_IMAGE_NOT_DETECTED` | `PORTRAIT_IMAGE_NOT_DETECTED` | OCR — die Pipeline konnte keinen Porträtbereich auf dem Dokument isolieren. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_UNPARSED_ADDRESS` | `UNPARSED_ADDRESS` | OCR – Dokument enthält ein Adressfeld, aber Geocodierung/Parsing lieferte nichts Brauchbares. |
| DATABASE\_VALIDATION | `expected_details.first_name` | `SANDBOX_DB_NO_MATCH` | `DATABASE_VALIDATION_NO_MATCH` | Datenbankvalidierung – jeder Behörden-/Registerdienst gibt NO\_MATCH zurück; Sitzung wird bei der Datenbankvalidierung abgelehnt. |
| FACEMATCH | `expected_details.first_name` | `SANDBOX_FACE_LOW_MATCH` | `LOW_FACE_MATCH_SIMILARITY` | Gesichtsabgleich – Ähnlichkeitswert liegt unter dem Ablehnungsschwellenwert; Sitzung wird beim Gesichtsabgleich abgelehnt. |
| PHONE | `phone_number` | `+15005550009` | `HIGH_RISK_PHONE_NUMBER` | Telefon – reservierte unzustellbare / Hochrisiko-Testnummer; Mock der Telefonverifizierung schlägt fehl. |
| EMAIL | `user_email` | `sandbox+breach@didit.test` | `BREACHED_EMAIL_DETECTED` | E-Mail – die Datenbank zu Datenlecks liefert einen Treffer für diese Adresse. |
| LOCATION | `expected_details.first_name` | `SANDBOX_IP_BLOCKLIST` | `IP_ADDRESS_IN_BLOCKLIST` | IP-Analyse – Aufrufer-IP steht auf der Sperrliste der Anwendung; Sitzung wird bei der IP-Analyse abgelehnt. |
| PROOF\_OF\_ADDRESS | `expected_details.first_name` | `SANDBOX_POA_ADDRESS_MISMATCH` | `ADDRESS_MISMATCH_WITH_PROVIDED` | Adressnachweis – Adresse auf dem hochgeladenen Dokument stimmt nicht mit der vom Kunden in `expected_details` vorausgefüllten Adresse überein; Sitzung wird beim Adressnachweis abgelehnt. |
| LIVENESS | `expected_details.first_name` | `SANDBOX_LIVENESS_ATTACK` | `LIVENESS_FACE_ATTACK` | Liveness – Mock für passive Liveness erkennt ein Signal für einen Gesichtsangriff; Sitzung wird bei der Liveness-Erkennung abgelehnt. |
| NFC | `expected_details.first_name` | `SANDBOX_NFC_CHIP_NOT_VERIFIED` | `NFC_CHIP_NOT_VERIFIED` | NFC – ePass-Mock gibt einen Chip zurück, dessen SOD/DG-Signatur die Integritätsprüfung nicht besteht; Produktion gibt NFC\_CHIP\_NOT\_VERIFIED aus und lehnt ab, wenn der Workflow bei nicht verifizierten Chips ablehnt. |
| NFC | `expected_details.first_name` | `SANDBOX_NFC_TRUST_ANCHOR_MISSING` | `NFC_TRUST_ANCHOR_MISSING` | NFC – das DSC verweist auf eine CSCA, die im Vertrauensspeicher fehlt; Produktion gibt NFC\_TRUST\_ANCHOR\_MISSING aus und wendet die konfigurierte Aktion für nicht verifizierte Chips an. |
| DOCUMENT\_AI | `expected_details.first_name` | `SANDBOX_DOCUMENT_AI_UNREADABLE` | `DOCUMENT_AI_UNREADABLE_DOCUMENT` | Document AI – Extraktion liefert keine lesbaren Felder; Produktion gibt DOCUMENT\_AI\_UNREADABLE\_DOCUMENT aus und das Dokument wird als abgelehnt eingestuft, sobald das Budget für Wiederholungsversuche erschöpft ist. |
| AML | `user_email` | `sandbox+aml_review@didit.test` | `POSSIBLE_MATCH_FOUND` | AML – möglicher Treffer, der eine manuelle Klärung erfordert; Sitzung erhält den Status „in Prüfung“. |
| FACEMATCH | `expected_details.first_name` | `SANDBOX_FACE_BORDERLINE_MATCH` | `LOW_FACE_MATCH_SIMILARITY` | Gesichtsabgleich – grenzwertige Ähnlichkeit zwischen Prüf- und Ablehnungsschwellenwert; Sitzung erhält den Status „in Prüfung“. |
| ID\_VERIFICATION | `expected_details.first_name` | `SANDBOX_OCR_BORDERLINE_AGE` | `MINIMUM_AGE_NOT_MET` | OCR – Geburtsdatum ergibt ein Alter unter dem Mindestalter, aber der Workflow prüft Fehlschläge beim Mindestalter, anstatt sie abzulehnen; Sitzung erhält den Status „in Prüfung“. |
| DATABASE\_VALIDATION | `expected_details.first_name` | `SANDBOX_DB_PARTIAL_MATCH` | `DATABASE_VALIDATION_PARTIAL_MATCH` | Datenbankvalidierung – Identifikation stimmt überein, aber Name/Geburtsdatum nur teilweise; Sitzung erhält den Status „in Prüfung“. |
| PROOF\_OF\_ADDRESS | `expected_details.first_name` | `SANDBOX_POA_PARTIAL_MATCH` | `ADDRESS_MISMATCH_WITH_PROVIDED` | Adressnachweis – Adresse auf dem hochgeladenen Dokument stimmt teilweise mit der angegebenen Adresse überein; Sitzung erhält den Status „in Prüfung“. |
| KYB\_REGISTRY | `expected_details.registration_number` | `SANDBOX-KYB-MISMATCH` | `KYB_REGISTRY_DATA_MISMATCH_WITH_EXPECTED` | KYB – Registerdaten des Unternehmens stimmen nicht mit den erwarteten Details überein; Sitzung wird abgelehnt. |
| KYB\_REGISTRY | `expected_details.registration_number` | `SANDBOX-KYB-REVIEW` | `KYB_REGISTRY_DATA_PARTIAL_MATCH_WITH_EXPECTED` | KYB – Registerdaten des Unternehmens stimmen teilweise überein; Sitzung erhält den Status „in Prüfung“. |

## Abfrage ohne Dokumente und Identitäts-Wallets

Sandbox-Anwendungen können jede Identitäts-Wallet im Länderkatalog aktivieren, einschließlich Wallets, die in Live-Anwendungen nicht verfügbar sind.
Das Standardszenario `approve` simuliert eine verifizierte Identität, ohne dass eine Anmeldung bei einer externen Wallet erforderlich ist.
Das Ergebnis wird in der Sitzung gespeichert und führt zum regulären nächsten Schritt des Workflows.
Die Sandbox validiert keine echten Wallet-Nachweise und stellt simulierte Versuche nicht in Rechnung.

Lookup-Anfragen validieren weiterhin die eingegebenen Felder und nutzen das konfigurierte Versuchslimit, das standardmäßig bei eins liegt.
Verwenden Sie die folgenden Szenarien, um Wiederholungsversuche und Fallback-Regeln zu testen:

| Szenario | Simuliertes Ergebnis |
| - | - |
| `lookup_partial_match` | Teilweise Übereinstimmung im Register; zählt zum Versuchslimit. |
| `lookup_no_match` | Register antwortet ohne Übereinstimmung; zählt zum Versuchslimit. |
| `lookup_provider_error` | Register liefert keine Antwort; der Benutzer wird aufgefordert, es erneut zu versuchen, und nach drei unbeantworteten Versuchen greift der Provider-Fehler-Fallback. |
| `wallet_cancelled` | Benutzer bricht die Wallet-Anmeldung ab. |
| `wallet_timeout` | Wallet-Anmeldung läuft ab. |
| `wallet_provider_error` | Wallet kann die Anmeldung nicht abschließen. |

Wallet-Fehlschläge folgen der Ländereinstellung, um auf die Dokumentenerfassung zurückzugreifen oder abzulehnen.
Abgeschlossene Abfrageversuche werden separat erfasst, sodass zwei zulässige Versuche zwei Ergebnisse vor dem Fallback erzeugen.
Die gesamte Sandbox-Nutzung bleibt kostenlos.

## Kontoprüfung der Bankverifizierung

Ein Schritt zur Bankverifizierung in der Sandbox bietet [beide Methoden](https://docs.didit.me/de/core-technology/bank-verification/verification-methods.md) in jedem Land an, in der im Schritt festgelegten Reihenfolge, auf einem simulierten Dienst ohne Bank und ohne Kosten.
Bei der Standardreihenfolge beginnt die Person bei der Bankanmeldung und wählt **Kontodaten eingeben**, um die [Kontoprüfung](https://docs.didit.me/de/core-technology/bank-verification/account-check.md) durchzuführen; setzen Sie `bank_method_order` auf `["account_lookup", "open_banking"]`, um direkt damit zu beginnen.
Die letzten vier Zeichen des eingegebenen Kontos bestimmen die Antwort; siehe [In der Sandbox testen](https://docs.didit.me/de/core-technology/bank-verification/account-check.md#in-der-sandbox-testen) für jede Endung und ein gültiges Konto pro Format.
Die [Kontoprüfungs-API](https://docs.didit.me/de/standalone-apis/bank-account-check.md) antwortet auf einen Sandbox-Schlüssel anhand derselben Endungen.

## Die Beispieldokumente

> [!WARNING]
>
> Laden Sie in der Sandbox niemals echte Ausweisdokumente hoch. Nutzen Sie stattdessen die integrierten Beispieldokumente.

Der gehostete Ablauf bietet drei Beispieldokumente, eines pro Dokumenttyp:

| Land | Dokumenttyp |
| - | - |
| Spanien | Personalausweis |
| Argentinien | Reisepass |
| Polen | Führerschein |

Tippen Sie in der Leiste auf ein Muster, um es anstelle einer echten Erfassung zu verwenden. Die extrahierten Daten und das Sitzungsergebnis stammen immer aus dem ausgewählten Szenario oder magischen Wert, sodass jedes Muster mit jedem Szenario funktioniert.

## Beispielidentität: Testen von `expected_details`

Jedes Sandbox-Dokument wird anhand einer **fest hinterlegten** Identität generiert.
Die extrahierten Werte sind bei jeder Sitzung gleich und werden niemals vom aktuellen Datum abgeleitet, sodass Sie `expected_details` damit vorbefüllen und Ihre Feldvergleiche sowie den Umgang mit Warnungen durchgängig testen können.
Übergeben Sie die unten aufgeführten Werte, und die Vergleichsprüfungen sind erfolgreich; übergeben Sie etwas anderes, wird die entsprechende Warnung `*_MISMATCH_WITH_PROVIDED` absichtlich ausgelöst.

Die Datumsangaben gelten für jedes Beispieldokument gleichermaßen:

| Feld | Wert |
| - | - |
| `date_of_birth` | `1990-06-15` |
| Ausstellungsdatum | `2025-06-15` |
| Ablaufdatum | `2035-06-15` |

Die restlichen Identitätsdaten hängen davon ab, welches Dokument Sie verwenden:

| `sandbox_sample` | Dokument | `first_name` | `last_name` | `gender` | `nationality` | `id_country` | `identification_number` |
| - | - | - | - | - | - | - | - |
| *(Standard, kein Muster ausgewählt)* | Brasilianischer ePass | `GUSTAVO` | `MATSUMOTO` | `M` | `BRA` | `BRA` | `YC531181` |
| `spain-id-card-2021` | Spanischer Personalausweis | `CARMEN` | `ESPAÑOLA ESPAÑOLA` | `F` | `ESP` | `ESP` | `CAA000000` |
| `argentina-passport-2009` | Argentinischer Reisepass | `MARIA VICTORIA` | `VILLAREAL` | `F` | `ARG` | `ARG` | `AAF794880` |
| `poland-driving-license-2019` | Polnischer Führerschein | `JAN` | `KOWALSKI` | auf diesem Dokument nicht vorhanden | `POL` | `POL` | `SP005/89/5` |

```json theme={null}
{
  "workflow_id": "<your-workflow-uuid>",
  "expected_details": {
    "date_of_birth": "1990-06-15",
    "gender": "M",
    "nationality": "BRA",
    "identification_number": "YC531181"
  }
}
```

`first_name` und `last_name` bilden die Ausnahme: Die Sandbox übernimmt die Namen, die Sie in `expected_details` senden, auf das generierte Dokument, sodass der Namensabgleich mit jedem beliebigen Namen erfolgreich ist.
Verwenden Sie den magischen Wert `SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED`, um eine Namensabweichung zu simulieren, und `SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED` für eine Abweichung beim Geburtsdatum.

> [!NOTE]
>
> Wenn Ihr Workflow `documents_allowed` auf ein Land oder einen Dokumenttyp einschränkt, der den brasilianischen ePass ausschließt, erstellt die Sandbox stattdessen ein Dokument für das erste zulässige Land. Dementsprechend richten sich `nationality`, `id_country` und der Dokumentname nach diesem Land. Die oben genannten Datumsangaben bleiben unverändert.

### Was das generierte Dokument nicht enthält

Das generierte Dokument ist die generische Vorlage für das zulässige Land und den Dokumenttyp, weshalb Felder, die nur ein echtes, behördlich ausgestelltes Dokument bereitstellt, leer bleiben. Das Feld, das für das Routing eine Rolle spielt, ist die **Region / US-Bundesstaat** (`kyc.region`): Ein Sandbox-US-Führerschein oder -Ausweis hat keinen Bundesstaat, daher kann eine Verzweigungsbedingung wie `Region equals IL` in der Sandbox niemals zutreffen. Wenn auch keine andere Verzweigung dieses Knotens zutrifft, nimmt der Ablauf die Fallback-Verzweigung des Knotens (die Verzweigung ohne Bedingungen). Dies ist weder eine Überprüfung noch ein Fehlschlag der Verzweigung – die Bedingung hat schlichtweg nichts zum Auslesen. Ein fehlendes Feld erfüllt auch `not equals` und `not in` nicht; siehe [wie Verzweigungsbedingungen Sitzungsdaten lesen](https://docs.didit.me/de/console/workflows.md#wie-verzweigungsbedingungen-sitzungsdaten-auswerten) für den Unterschied zwischen einem fehlenden Feld und einer leeren Zeichenkette.

Um einen bundesstaatsabhängigen Ablauf in der Sandbox zu testen, steuern Sie die Entscheidung über einen Wert, den Sie in der Sitzung kontrollieren, anstatt über das Dokument:

* Senden Sie den Bundesstaat in den `metadata`, wenn Sie die Sitzung erstellen (zum Beispiel `"metadata": {"credential_state": "IL"}`), und verzweigen Sie auf `metadata.credential_state`. Metadaten werden in der Sandbox genauso wie in der Produktionsumgebung ausgewertet.
* Behalten Sie die vom Dokument abgeleitete Bedingung `kyc.region` für den Live-Betrieb bei, wenn Sie den Nachweis des Bundesstaats ebenfalls über das Dokument benötigen; im Live-Modus wird die Region aus dem echten Dokument gelesen.

Alles andere am Routing ist mit der Produktionsumgebung identisch: Der Workflow-Graph, Verzweigungsbedingungen, `metadata`- und `expected_details`-Werte, Aktionsknoten und Statusknoten werden alle real ausgeführt. Die Sandbox versetzt eine Sitzung niemals von sich aus in Prüfung – eine Sandbox-Sitzung endet nur dann in Prüfung, wenn der Workflow sie dorthin leitet (ein `review_*`-Szenario, ein magischer Wert, der einer Prüfaktion zugeordnet ist, oder ein Statusknoten im Graphen).

## OTP-Codes und E-Mail-Opt-in

* **Telefon-OTP:** Die Sandbox-Telefonprüfung akzeptiert jeden wohlgeformten Code (4–8 Ziffern; einschließlich `123456`). Eine fehlerhafte Eingabe gibt weiterhin `400` zurück.
* **E-Mail-OTP:** Die Sandbox-E-Mail-Prüfung akzeptiert jeden wohlgeformten Code (einschließlich `123456`). Eine fehlerhafte Eingabe gibt weiterhin `400` zurück.

Standardmäßig versenden Sandbox-Sitzungen **keine** E-Mails (Prüf-Alerts, Statusänderungen, OTP, erneutes Einreichen, Link zu einer neuen Sitzung usw.). Um dennoch eine E-Mail zuzustellen, verwenden Sie eines dieser Opt-in-Muster bei der Empfängeradresse:

| Opt-in-Muster | Beispiel |
| - | - |
| `<local>+sandbox@<domain>` | `alice+sandbox@example.com` |
| `*@didit.test` | `alice@didit.test` |

## Ergebnisse steuern: Szenarien, Magic Values, Scharfschalten und der Simulate-Endpoint

Es gibt fünf Möglichkeiten, ein Sandbox-Ergebnis zu steuern.

### 1. `sandbox_scenario` bei der Sitzungserstellung

Geben Sie den Szenario-Slug beim Erstellen der Sitzung an (`POST /v3/session/`). Der Erstellungsablauf überträgt die im Szenario gebündelten Magic Values in die Eingabefelder der Sitzung, sodass die gemockten Provider das beabsichtigte Ergebnis über die echte Workflow-Pipeline ausgeben.

```json theme={null}
{
  "workflow_id": "<your-workflow-uuid>",
  "sandbox_scenario": "decline_document_expired"
}
```

### 2. Manuell eingegebene Magic Values

Legen Sie die einzelnen Eingabefelder selbst fest (z. B. `expected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED"` oder `user_email = "sandbox+aml_hit@didit.test"`). Die vollständige Übersicht finden Sie in der obigen Tabelle der Magic Values.

### 3. Sitzung vor Start des Ablaufs scharfschalten (oder erneut scharfschalten)

Legen Sie das scharfgeschaltete Szenario für eine bereits bestehende Sitzung fest oder ersetzen Sie es, solange diese nicht über `Not Started` hinaus fortgeschritten ist. Dies ist der Endpoint, den die [Szenarioauswahl vor dem Ablauf](#sandbox-im-gehosteten-verifizierungsablauf) aufruft, und Sie können ihn selbst aufrufen, um einen eigenen Picker oder ein Test-Harness zu erstellen:

```
POST /v3/session/{session_id}/sandbox/arm/
Session-Token: <session_token>
```

```json theme={null}
{
  "scenario": "decline_document_expired"
}
```

200-Antwort:

```json theme={null}
{
  "session_id": "<session_id>",
  "scenario": "decline_document_expired",
  "status": "Not Started"
}
```

* Authentifizieren Sie sich mit dem sitzungseigenen `Session-Token` (wird bei der Sitzungserstellung als `session_token` zurückgegeben), nicht mit dem API-Schlüssel Ihrer Anwendung: Dies ist ein clientseitiger Endpoint.
* Gibt `400` bei einem unbekannten Szenario-Slug zurück und `400`, sobald die Sitzung über `Not Started` hinaus fortgeschritten ist (`"Scenario can only be armed before the verification starts."`).
* Gibt `404` zurück, wenn das `Session-Token` zu einer Live-Anwendung (Nicht-Sandbox) gehört oder nicht mit der `session_id` im Pfad übereinstimmt.
* **Ein erneutes Scharfschalten ersetzt das vorherige Szenario.** Es löscht nur die Magic Values, die das vorherige Szenario geschrieben hat, und lässt alles unberührt, was der Benutzer bereits manuell eingegeben hat (E-Mail, Vorname usw.). Beispiel: Sie schalten `decline_phone_high_risk` scharf und danach `approve` – die Telefonnummer wird wieder auf nicht gesetzt zurückgesetzt, eine vom Kunden eingegebene E-Mail bleibt jedoch nach beiden Aufrufen erhalten.

### 4. Der Simulate-Endpoint

Einen finalen Status nachträglich erzwingen:

* Konsole / API-Schlüssel (erfordert die Berechtigung `write:sessions`; ein API-Schlüssel mit Scopes benötigt Schreibzugriff auf Sitzungen): `POST /v3/session/{session_id}/simulate/`
* Gehosteter Ablauf (`Session-Token`-Header): `POST /v3/session/{session_id}/sandbox/simulate/`

Beide funktionieren für KYC- und KYB-Sandbox-Sitzungen.
Eine Live-Sitzung (Nicht-Sandbox) gibt `404` zurück, ebenso wie ein `Session-Token`, das nicht mit der `session_id` im Pfad übereinstimmt.

Jedes Body-Feld ist optional, aber mindestens eines von `new_status`, `scenario` oder `risk` ist erforderlich:

| Feld | Typ | Funktion |
| - | - | - |
| `new_status` | string | `Approved`, `Declined`, `In Review`, `Expired` oder `Abandoned`. Wenn Sie es weglassen, wird standardmäßig der Standardstatus des Risikofalls verwendet (`risk` oder das erste Risiko, das die Magic Values des Szenarios enthalten), andernfalls der Standardstatus des Szenarios. |
| `scenario` | string, bis zu 100 Zeichen | Ein Szenario-Slug. Ohne `risk` wird das erste Risiko angewendet, das in den Magic Values des Szenarios enthalten ist. |
| `risk` | string, bis zu 128 Zeichen | Ein Risikofall. Dessen Warnung wird zur Sitzung hinzugefügt. |
| `node_id` | string, bis zu 128 Zeichen | Der Workflow-Knoten, an den die Warnung angehängt wird. Standardmäßig der aktuelle Knoten der Sitzung. |
| `comment` | string, bis zu 500 Zeichen | Notiz, die dem Aktivitätseintrag hinzugefügt wird, in dem die Statusänderung protokolliert wird. |
| `send_webhooks` | boolean, Standard `true` | Gibt an, ob die Statusänderung Webhooks sendet. |

`send_webhooks: true` sendet genau die Webhooks, die von einer echten Statusänderung gesendet werden: `status.updated` plus die Ereignisse `user.status.updated` und `user.data.updated` (bzw. `business.status.updated` und `business.data.updated` bei einer Unternehmenssitzung), die durch die Änderung ausgelöst werden, an die dafür abonnierten Ziele.
Bei `send_webhooks: false` ändert sich der Status dennoch, es wird jedoch kein Webhook protokolliert oder gesendet.
Die Wiederherstellung verpasster Webhooks sendet diese Entscheidung niemals erneut, und die Konsole wird weiterhin live aktualisiert.
Die nächste Statusänderung der Sitzung sendet Webhooks wie gewohnt.

```json theme={null}
{
  "scenario": "decline_aml_hit",
  "send_webhooks": false
}
```

200-Antwort:

```json theme={null}
{
  "session_id": "<session_id>",
  "previous_status": "In Progress",
  "status": "Declined",
  "scenario": "decline_aml_hit",
  "risk": "POSSIBLE_MATCH_FOUND",
  "send_webhooks": false
}
```

* `status` ist der durch die Simulation festgelegte Status und `previous_status` derjenige, den die Sitzung zuvor hatte.
* `scenario` gibt Ihren Slug wieder und `risk` ist der angewendete Risikofall; beide sind `null`, wenn keine vorhanden sind.
* `send_webhooks` gibt den angewendeten Wert wieder.
* Gibt `400` zurück bei einem unbekannten Szenario oder Risiko, wenn kein `new_status` abgeleitet werden kann, bei jedem anderen `new_status` sowie wenn die Sitzung bereits den angeforderten Status hat (`["The new status is the same as the current status."]`).

### 5. `sandbox_scenario` in der eigenständigen AML-API

Das Backend-AML-Screening hat keinen Endbenutzer und keine Sitzung, die scharfgeschaltet werden müsste; daher wird der Slug direkt in der Screening-Anfrage angegeben (`POST /v3/aml/`):

```json theme={null}
{
  "full_name": "Ada Lovelace",
  "save_api_request": true,
  "sandbox_scenario": "decline_aml_hit"
}
```

* `decline_aml_hit` gibt einen Treffer in produktionsnaher Form zurück und schließt das Screening mit `Declined` ab; `review_aml_possible_match` schließt es mit `In Review` ab. Ein Szenario, das kein AML-Ergebnis scharfschaltet, hinterlässt das Screening ohne Treffer.
* Mit `save_api_request: true` (Standard) wird das Screening genau wie bei einem Live-Schlüssel gespeichert, sodass die zurückgegebene `request_id` über `GET /v3/session/{request_id}/decision/` und `GET /v3/session/{request_id}/generate-pdf/` aufgelöst werden kann.
* Gibt `400` bei einem unbekannten Szenario-Slug zurück und `400`, wenn der API-Schlüssel zu einer Live-Anwendung gehört.

## Wo `sandbox_scenario` vorkommt

Der Slug des scharfgeschalteten Szenarios (`null`, wenn keines scharfgeschaltet ist) wird auf einigen Oberflächen zurückgegeben und auf anderen bewusst weggelassen:

| Bereich | Verfügbar? |
| - | - |
| Payload des aktuellen Schritts (KYC und KYB) | Ja, als `sandbox_scenario` |
| `GET /v1/session/{id}/decision/` | Ja, als `sandbox_scenario` |
| `GET /v3/session/{id}/decision/` (siehe [Sitzung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session.md)) | Ja, `sandbox_scenario` auf oberster Ebene (null, wenn nicht scharfgeschaltet) |
| Sitzungs-Webhooks (`status.updated`, `data.updated`) | Ja, als `sandbox_scenario`, `null` bei Live-Sitzungen oder nicht scharfgeschalteten Sandbox-Sitzungen |

Wenn Ihre Integration serverseitig anhand des scharfgeschalteten Szenarios verzweigen muss, lesen Sie es aus dem Webhook-Envelope oder einem der beiden Entscheidungs-Endpoints (`v1` oder `v3`) aus.

## Abrechnung

Die Sandbox-Nutzung wird nachverfolgt, aber nie in Rechnung gestellt:

* Jeder simulierte Aufruf zeichnet dennoch ein Nutzungsereignis auf (`is_sandbox: true`, zum Preis von `0.0000`), sodass das Sandbox-Volumen zum Debuggen sichtbar ist, es wird jedoch nie zu Ihren Gesamtnutzungswerten addiert, nie vom Guthaben abgezogen und erscheint nie auf einer Rechnung.
* Die Bereiche für Guthaben, Aufladungen und Live-Nutzung in der Business Console filtern die Sandbox-Nutzung standardmäßig heraus. Die Endpoints zur Aufladungsnutzung akzeptieren einen `environment`-Parameter (`live`, der Standardwert, oder `sandbox`), sodass das Sandbox-Volumen separat eingesehen werden kann – immer kostenlos und ohne Verbrauch des kostenlosen Kontingents.
* E-Mail- und Telefonverifizierung werden pro Anfrage und nicht pro Sitzungsergebnis abgerechnet, und die Sandbox kann dies auf der Webhook-Ebene nicht vollständig widerspiegeln. Sandbox-E-Mail-/-Telefonprüfungen zeichnen weiterhin ein Nutzungsereignis pro Anfrage zum Preis von `0.0000` auf, genau wie jede andere simulierte Funktion: Dies ist eine akzeptierte, bekannte Abweichung vom Abrechnungsverhalten in der Produktionsumgebung und kein Fehler.
* Die Struktur der Antwort bei der Datenbankvalidierung weicht in der Sandbox absichtlich von der anbieterabhängigen Struktur in der Produktionsumgebung ab, da es keinen echten Anbieter gibt, der nachgebildet werden könnte. Betrachten Sie die Payloads der Datenbankvalidierung in der Sandbox als Stellvertreter für das Ergebnis (Status und Warncode), nicht als Byte-für-Byte-Vorschau einer echten Anbieterantwort.


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