La source de référence de ces données est
serialize_catalog() dans le service de vérification, exposé en direct à GET /v1/sandbox/scenarios/. Une copie testée contre les dérives est générée dans docs/sandbox/SANDBOX_REFERENCE.md du dépôt service-didit-verification via pipenv run python scripts/generate_sandbox_reference.py. Cette page reprend cette référence : si quelque chose semble obsolète ici, fiez-vous toujours à l’endpoint du catalogue en direct. Cet endpoint nécessite une authentification : envoyez votre clé API (x-api-key) comme pour n’importe quel autre appel, ou un token de session si vous le consultez depuis une session en cours.Modèle d’environnement
Le sandbox est un mode par application (ApplicationDetail.mode == SANDBOX), selon le même principe que le mode test de Stripe. Pendant qu’une session s’exécute sous une application sandbox :
- Tous les fournisseurs externes (OCR, AML, correspondance faciale, détection du vivant, NFC, téléphone, e-mail, IP, justificatif de domicile, validation en base de données, Document AI) sont simulés : aucun tiers n’est jamais sollicité.
- La détection du vivant fonctionne exactement comme en production. Un workflow de détection active du vivant exécute la capture active réelle dans le sandbox, que ce soit dans le flux hébergé ou via la transmission web des SDK natifs, afin que vous puissiez tester l’expérience que vos utilisateurs obtiendront. Seul le résultat de la détection du vivant est simulé, par le scénario ou la valeur magique, et le rapport enregistre la méthode configurée dans votre workflow.
- Les domaines personnalisés sont réservés à la production. Une application sandbox ne peut pas ajouter de domaine personnalisé : les sessions sandbox fonctionnent toujours sur le domaine par défaut de la page de vérification hébergée.
- Les sessions ne sont jamais facturées et la vérification du solde est ignorée.
- Un quota par application de 500 créations de session par 24 h est appliqué.
- Les webhooks contiennent
"environment": "sandbox"(les sessions en production contiennent"environment": "live"). - Le flux hébergé expose l’environnement de la session afin que l’interface puisse avertir les utilisateurs de ne pas téléverser de vraies données personnelles.
- Les résultats ne dépendent jamais des pixels : les données extraites et les statuts proviennent du scénario ou de la valeur magique. Les médias capturés eux-mêmes (documents, selfie, vidéo, fichiers de justificatif de domicile) sont effectivement stockés, exactement comme pour une session en production.
Transaction Monitoring in sandbox
Sandbox est orienté session : il simule les fournisseurs qu’une session de vérification appellerait. La Surveillance des transactions n’a pas de fournisseur à simuler, donc une application sandbox suit une autre voie : la transaction est enregistrée, mais rien de ce qui décide, filtre, notifie ou facture ne s’exécute sur elle. Une transaction créée sur une application sandbox est enregistrée et renvoyée comme d’habitude, et aucun des points suivants ne lui arrive :- Aucune évaluation de règles.
rule_runsest vide, quel que soit le mode de vos règles. Une règleACTIVEsur une application sandbox ne se déclenche jamais : la transaction resteAPPROVEDavec un score de0, et aucune alerte ni aucun dossier n’est ouvert. - Aucun filtrage AML ni filtrage des portefeuilles.
provider_resultsest vide, même pour les transactions crypto sur une application où la surveillance est activée. - Aucun webhook. Ni
transaction.creatednitransaction.status.updatedne sont livrés pour une transaction sandbox. - Aucune facturation. Un événement d’usage est enregistré au prix de
0.0000et votre solde n’est pas modifié.
environment ("live" ou "sandbox"), de sorte qu’un rule_runs vide n’est jamais ambigu : "sandbox" signifie que les règles n’ont pas été évaluées, et non qu’aucune ne correspond. La Business Console indique la même chose dans la carte Risques et décision de la transaction, au lieu d’un simple « Aucune règle évaluée ».
Travel Rule est la seule exception à « rien ne s’exécute ». Sur une application où Travel Rule est activée, une transaction
travelRule en sandbox exécute quand même le moteur d’échange : l’enregistrement du transfert est créé et passe par ses statuts.
Ce que le sandbox ne fait jamais, c’est communiquer avec quiconque en dehors de Didit.
Sa seule contrepartie est le Didit Test VASP, intégré à la plateforme : aucun message de conformité n’atteint un VASP contrepartie réel, quel que soit le canal (TRP, une adhésion à un réseau que vous avez connectée, e-mail ou INTERNAL), le filtrage de l’attribution du VASP contrepartie est ignoré, et une annulation n’envoie rien à la contrepartie.
Les webhooks travel_rule.status.updated sont livrés, marqués "environment": "sandbox".Sortant : une transaction travelRule que vous soumettez.
La vérification du threshold_amount s’effectue en premier. En sandbox, elle ne s’applique que si vous envoyez transaction_details.amount_in_default_currency, car le sandbox ne convertit pas les devises : sans ce champ, chaque transfert sandbox dépasse le seuil.
Un transfert sans réponse expire après confirmation_timeout_hours, et votre timeout_outcome s’applique alors à la transaction.
Au-delà du seuil, la vérification du portefeuille auto-hébergé déclaré s’applique normalement : un transfert vers un portefeuille auto-hébergé déclaré passe à UNCONFIRMED_OWNERSHIP sans rien être envoyé, et vous pouvez le finaliser en sandbox avec le widget de confirmation de propriété du portefeuille, ou via confirmer la propriété lorsque le portefeuille de destination figure déjà dans votre carnet d’adresses de portefeuilles.
Tout autre transfert au-delà du seuil est envoyé au Didit Test VASP sur le canal TEST_VASP, qui y répond au sein de Didit avec le scénario que vous choisissez selon le portefeuille ou le nom du bénéficiaire : il est finalisé, refusé, présente une incohérence, passe à COUNTERPARTY_VASP_NOT_REACHABLE, expire (votre timeout_outcome s’applique alors à la transaction) ou attend la vérification de la propriété du portefeuille.
Consultez Tester Travel Rule en sandbox pour chaque scénario.Entrant : POST /v3/travel-rule/inbound/. L’enregistrement n’envoie jamais rien via un canal, donc rien à son sujet n’est simulé : le sandbox rapproche le dépôt de votre carnet d’adresses de portefeuilles et le règle de façon synchrone, exactement comme en production. Il aboutit à un résultat réel plutôt qu’à AWAITING_COUNTERPARTY : ON_HOLD (aucune correspondance dans le carnet d’adresses), UNCONFIRMED_OWNERSHIP (l’entrée correspondante n’a pas de propriété vérifiée), COUNTERPARTY_MISMATCHED_DATA (le nom du bénéficiaire ne correspond pas au titulaire du portefeuille), ou COMPLETED puis FINISHED (correspondance avec une entrée vérifiée).
Pour recevoir un transfert du Didit Test VASP, utilisez Déclencher un transfert entrant du Test VASP avec l’un de vos propres portefeuilles du carnet d’adresses.Scénarios du Test VASP pour la Travel Rule
Letravel_rule.scenarios du catalogue liste ces scénarios sortants. Indiquez le nom du bénéficiaire ci-dessous dans une transaction travelRule sortante, après avoir activé Travel Rule sur votre application sandbox. Les vérifications du seuil et du portefeuille auto-hébergé déclaré décrites ci-dessus s’exécutent en premier.
Vous pouvez aussi choisir un scénario avec l’adresse du portefeuille du bénéficiaire au lieu du nom (le portefeuille prime lorsque les deux sont renseignés), et un transfert qui n’indique ni l’un ni l’autre se termine avec
accept. Tester Travel Rule en sandbox liste le portefeuille de chaque scénario et son résultat exact.
Le déclencheur de Test VASP entrant n’accepte que accept et name_mismatch dans son champ scenario.
Comment tester une règle avant sa mise en production. Utilisez
Backtest : il rejoue la règle sur votre historique réel de transactions et renvoie
evaluated / matched / affected_entities sans modifier le statut d’une transaction. Associez-le au mode TEST sur l’application en production : une règle TEST s’évalue sur chaque nouvelle transaction réelle et enregistre les correspondances qu’elle aurait produites, sans modifier le score ni le statut, puis passez au mode ACTIVE une fois la sélectivité jugée satisfaisante.Comment basculer entre le mode live et le mode sandbox
Live et sandbox sont des applications distinctes, afin que le trafic de test et les données de production ne se mélangent jamais. Chaque application possède unmode égal à live ou sandbox :
- Utilisez la clé API d’une application en mode sandbox pour obtenir des sessions simulées, non facturées et simulables.
- Utilisez la clé API d’une application en mode live pour les vérifications réelles.
sandbox_scenario (lors de la création d’une session et sur l’API AML autonome) ainsi que les endpoints de simulation ne sont acceptés que sur les applications sandbox ; ils sont rejetés sur les applications live.
Sandbox dans le flux de vérification hébergé
Les sessions créées sous une application sandbox affichent une interface supplémentaire dans le flux de vérification hébergé (l’url renvoyée par POST /v3/session/) :
- Bandeau sandbox dans la carte. Chaque écran affiche un bandeau à l’intérieur de la carte, avec le texte « Données de test uniquement, aucun appel réel », afin qu’il soit toujours évident que la session n’appelle jamais de fournisseurs réels et ne touche jamais à votre solde. Les médias capturés sont stockés comme pour toute session ; utilisez donc les documents d’exemple et les données de test plutôt que de vrais documents d’identité ou des informations personnelles.
- Sélecteur de scénario préalable au flux. Avant le début de la capture, un sélecteur intégré à la carte guide l’utilisateur dans le choix d’un résultat de test : il sélectionne d’abord un résultat, puis un déclencheur pour ce résultat. La confirmation appelle
POST /v3/session/{session_id}/sandbox/arm/(voir Armer (ou réarmer) la session avant le début du flux ci-dessous), puis poursuit le flux avec les valeurs magiques de ce scénario déjà appliquées. - Bande de documents d’exemple. Une rangée de documents d’exemple sandbox (jusqu’à 3) s’affiche juste sous le composant de téléversement et de capture des documents. Appuyez sur l’un d’eux pour l’utiliser à la place d’un téléversement réel.
Scénarios
Chaque scénario est un ensemble nommé de valeurs prédéfinies. Transmettez son slug commesandbox_scenario lors de la création de la session (ou à l’endpoint de simulation) pour reproduire le résultat.
Les scénarios
review_* existent pour vous permettre de tester le parcours d’examen manuel (la file d’attente d’examen dans la console, les webhooks In Review, les actions d’approbation et de refus du réviseur) sans avoir besoin d’une entrée qui justifie un refus. Les deux scénarios kyb_* ci-dessus définissent expected_details.registration_number au lieu de expected_details.first_name : ils ne s’appliquent qu’aux sessions de vérification d’entreprise (KYB).
Valeurs magiques
Une valeur magique est une entrée spécifique qui amène une fonctionnalité simulée à émettre un risque donné. Renseignez le champ d’entrée avec la valeur magique (directement ou via un scénario) pour déclencher ce risque.Consultation sans document et portefeuilles d’identité
Les applications sandbox peuvent activer tous les portefeuilles d’identité du catalogue par pays, y compris ceux qui ne sont pas disponibles sur les applications en production. Le scénario par défautapprove simule une identité vérifiée sans connexion à un portefeuille externe.
Le résultat est enregistré dans la session et suit l’étape suivante normale du workflow.
Le sandbox ne valide aucun justificatif de portefeuille réel et ne facture pas les tentatives simulées.
Les requêtes de consultation valident toujours les champs saisis et appliquent la limite de tentatives configurée, qui est fixée à une tentative par défaut.
Utilisez les scénarios suivants pour tester les nouvelles tentatives et les règles de repli :
Les échecs liés au portefeuille suivent le paramètre du pays : repli vers la capture du document ou refus.
Les tentatives de consultation terminées sont enregistrées séparément : deux tentatives autorisées produisent donc deux résultats avant le repli.
Toute l’utilisation du sandbox reste gratuite.
Contrôle de compte de la vérification bancaire
Une étape de vérification bancaire en sandbox propose les deux méthodes dans chaque pays, dans l’ordre défini par l’étape, sur un service simulé sans banque et sans frais. Avec l’ordre par défaut, la personne commence par la connexion bancaire et choisit Saisissez les coordonnées de votre compte pour lancer le contrôle de compte ; définissezbank_method_order sur ["account_lookup", "open_banking"] pour commencer directement par celui-ci.
Les quatre derniers caractères du numéro de compte saisi déterminent la réponse ; voir Tester dans le sandbox pour chaque terminaison et un compte valide par format.
L’API de contrôle de compte renvoie une clé sandbox à partir des mêmes terminaisons.
Les documents d’exemple
Le flux hébergé propose trois documents d’exemple, un par type de document :
Sélectionnez un exemple dans la bande pour l’utiliser à la place d’une capture réelle. Les données extraites et le résultat de la session proviennent toujours du scénario ou de la valeur magique sélectionnés ; n’importe quel exemple fonctionne donc avec n’importe quel scénario.
Identité d’exemple et test de expected_details
Chaque document sandbox est fabriqué à partir d’une seule identité fixe.
Les valeurs extraites sont identiques d’une session à l’autre et ne sont jamais calculées à partir de la date du jour. Vous pouvez donc pré-remplir expected_details avec ces valeurs et vérifier de bout en bout la comparaison des champs et la gestion des avertissements. Transmettez les valeurs ci-dessous et les contrôles de comparaison passent ; transmettez autre chose et l’avertissement *_MISMATCH_WITH_PROVIDED correspondant se déclenche volontairement.
Les dates sont communes à tous les documents d’exemple :
Le reste de l’identité dépend du document utilisé :
first_name et last_name font exception : le sandbox reprend sur le document fabriqué les noms que vous transmettez dans expected_details, de sorte que la comparaison des noms réussit quel que soit le nom envoyé.
Utilisez la valeur magique SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED pour simuler une non-concordance de nom, et SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED pour une non-concordance de date de naissance.
Si votre workflow restreint
documents_allowed à un pays ou à un type de document qui exclut le passeport électronique brésilien, le sandbox fabrique à la place un document à partir du premier pays autorisé. Ainsi, nationality, id_country et le nom du document suivent ce pays. Les dates ci-dessus restent les mêmes.Ce que le document fabriqué ne contient pas
Le document fabriqué est le modèle générique du pays et du type de document autorisés. Les champs que seul un document réel délivré par un État fournit restent donc vides. L’élément qui importe pour le routage est la région / l’État américain (kyc.region) : un permis de conduire américain ou une carte d’identité américaine fabriqués en sandbox n’a pas d’État. Une condition de branche telle que Region equals IL ne peut donc jamais correspondre en sandbox. Si aucune autre branche du nœud ne correspond non plus, le flux emprunte la branche de repli (celle sans condition). Ce n’est pas un examen ni un échec de la branche : la condition n’a simplement rien à lire. Un champ absent fait aussi échouer not equals et not in. Voir comment les conditions de branche lisent les données de session pour la différence entre un champ absent et une chaîne vide.
Pour tester un flux qui dépend de l’État en sandbox, pilotez la décision à partir d’une valeur que vous contrôlez sur la session plutôt qu’à partir du document :
- Envoyez l’État dans
metadatalors de la création de la session (par exemple"metadata": {"credential_state": "IL"}) et branchez surmetadata.credential_state. Les métadonnées sont évaluées en sandbox exactement comme en production. - Conservez la condition
kyc.region, dérivée du document, pour le trafic réel si vous avez aussi besoin que le document prouve l’État. En production, la région est lue sur le document réel.
metadata et de expected_details, les nœuds d’action et les nœuds de statut fonctionnent tous réellement. Le sandbox ne force jamais une session en examen de lui-même : une session en sandbox passe En cours d’examen uniquement lorsque le workflow l’y achemine (un scénario review_*, une valeur magique associée à une action d’examen, ou un nœud de statut dans le graphe).
Codes OTP et consentement à recevoir des e-mails
- OTP téléphone : la vérification du téléphone du sandbox accepte n’importe quel code bien formé (4 à 8 chiffres ;
123456inclus). Une saisie mal formée renvoie toujours400. - OTP e-mail : la vérification de l’e-mail du sandbox accepte n’importe quel code bien formé (
123456inclus). Une saisie mal formée renvoie toujours400.
Pilotage des résultats : scénarios, valeurs magiques, armement et endpoint de simulation
Il existe cinq façons de contrôler le résultat d’un sandbox.1. sandbox_scenario à la création de la session
Renseignez le slug du scénario lors de la création de la session (POST /v3/session/). Le flux de création insère les valeurs magiques regroupées dans le scénario dans les champs de saisie de la session, afin que les fournisseurs simulés produisent le résultat voulu via le pipeline de workflow réel.
2. Valeurs magiques saisies à la main
Renseignez vous-même les champs de saisie (par exempleexpected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED", ou user_email = "sandbox+aml_hit@didit.test"). Consultez le tableau des valeurs magiques ci-dessus pour le registre complet.
3. Armer (ou réarmer) la session avant le démarrage du parcours
Définissez ou remplacez le scénario armé sur une session existante, tant qu’elle n’a pas dépassé le statutNot Started. C’est l’endpoint appelé par le sélecteur de scénario avant le parcours. Vous pouvez également l’appeler vous-même pour créer un sélecteur personnalisé ou un banc de test :
- Authentifiez-vous avec le
Session-Tokenpropre à la session (renvoyé sous forme desession_tokenlors de la création de la session), et non avec votre clé API applicative : il s’agit d’un endpoint destiné au client. - Renvoie
400pour un slug de scénario inconnu, et400lorsque la session a dépassé le statutNot Started("Scenario can only be armed before the verification starts."). - Renvoie
404lorsque leSession-Tokenappartient à une application de production (hors sandbox), ou ne correspond pas ausession_iddu chemin. - Réarmer remplace le scénario précédent. Seules les valeurs magiques écrites par le scénario précédent sont effacées ; les informations saisies à la main par l’utilisateur (e-mail, prénom, etc.) restent intactes. Par exemple : armez
decline_phone_high_risk, puis armezapprove: le numéro de téléphone redevient non renseigné, mais un e-mail saisi par le client survit aux deux appels.
4. L’endpoint de simulation
Forcez un statut final après coup :- Console / clé API (nécessite l’autorisation
write:sessions; une clé API à portée restreinte doit avoir un accès en écriture aux sessions) :POST /v3/session/{session_id}/simulate/ - Flux hébergé (en-tête
Session-Token) :POST /v3/session/{session_id}/sandbox/simulate/
404, de même qu’un Session-Token qui ne correspond pas au session_id du chemin.
Tous les champs du corps sont facultatifs, mais au moins l’un de new_status, scenario ou risk est requis :
send_webhooks: true envoie exactement les webhooks qu’envoie un vrai changement de statut : status.updated, ainsi que les événements user.status.updated et user.data.updated (ou business.status.updated et business.data.updated pour une session d’entreprise) que ce changement déclenche, vers les destinations qui y sont abonnées.
Avec send_webhooks: false, le statut change quand même, mais aucun webhook n’est journalisé ni envoyé.
La récupération des webhooks manqués ne renvoie jamais cette décision, et la console se met tout de même à jour en direct.
Le changement de statut suivant de la session envoie les webhooks normalement.
statusest le statut défini par la simulation, etprevious_statuscelui que la session avait auparavant.scenarioreprend votre slug etriskest le dossier de risque appliqué ; chacun vautnulllorsqu’il n’y en a pas.send_webhooksreprend la valeur appliquée.- Renvoie
400pour un scénario ou un risque inconnu, lorsqu’aucunnew_statusne peut être déduit, pour tout autrenew_status, et lorsque la session possède déjà le statut demandé (["The new status is the same as the current status."]).
5. sandbox_scenario sur l’API AML autonome
Le filtrage AML côté back-end n’a pas d’utilisateur final ni de session à armer : le slug doit donc figurer directement dans la requête de filtrage (POST /v3/aml/) :
decline_aml_hitrenvoie une correspondance au format de production et clôt le filtrage avec le statutDeclined;review_aml_possible_matchle clôt avec le statutIn Review. Un scénario qui n’arme aucun résultat AML laisse le filtrage sans alerte.- Avec
save_api_request: true(valeur par défaut), le filtrage est enregistré exactement comme avec une clé de production, de sorte que lerequest_idrenvoyé se résout viaGET /v3/session/{request_id}/decision/etGET /v3/session/{request_id}/generate-pdf/. - Renvoie
400pour un slug de scénario inconnu, et400lorsque la clé API appartient à une application de production.
Où apparaît sandbox_scenario
Le slug du scénario armé (null si aucun n’est armé) est renvoyé sur certaines surfaces et volontairement omis sur d’autres :
Si votre intégration doit se baser sur le scénario armé côté serveur, lisez-le dans l’enveloppe du webhook ou dans l’un des deux endpoints de décision (
v1 ou v3).
Utilisation et facturation
L’utilisation du sandbox est suivie, mais jamais facturée :- Chaque appel simulé enregistre tout de même un événement d’utilisation (
is_sandbox: true, au tarif de0.0000) afin que le volume du sandbox reste visible pour le débogage. Cet événement n’est cependant jamais ajouté à vos totaux d’utilisation, n’est jamais déduit de votre solde et n’apparaît jamais sur une facture. - Les éléments de la Business Console consacrés au solde, à la recharge et à l’utilisation en production excluent par défaut l’utilisation du sandbox. Les endpoints de consultation de l’utilisation liée à la recharge acceptent un paramètre
environment(live, valeur par défaut, ousandbox) afin d’examiner séparément le volume du sandbox, toujours à coût nul et sans consommer l’offre gratuite. - La Vérification de l’e-mail et la Vérification du téléphone sont facturées par requête et non par résultat de session, et le sandbox ne peut pas reproduire entièrement ce mode de facturation au niveau des webhooks. Les contrôles e-mail et téléphone en sandbox enregistrent tout de même un événement d’utilisation par requête au tarif de
0.0000, comme toutes les autres fonctionnalités simulées. Il s’agit d’un écart connu et accepté avec le comportement de facturation en production, et non d’un bogue. - La structure de réponse de la Validation en base de données dans le sandbox diffère volontairement de la structure propre à chaque fournisseur en production, puisqu’il n’existe aucun fournisseur réel à imiter. Considérez les payloads de Validation en base de données du sandbox comme un substitut du résultat (statut et code d’avertissement), et non comme un aperçu octet pour octet de la réponse d’un fournisseur réel.