workflow_id.
Votre backend lance la vérification et récupère son résultat ; votre interface guide la personne dans l’authentification requise par le portefeuille.
Une intégration par API exige toujours que la personne s’authentifie et approuve le partage de son identité.
Vous ne pouvez pas vérifier quelqu’un en envoyant son identifiant personnel sans cette interaction.
Fonctionnement de la vérification
- Votre backend consulte le catalogue des portefeuilles, puis appelle l’endpoint de démarrage d’un portefeuille disponible avec la clé API de votre application.
- Didit renvoie une référence de vérification et l’action que la personne doit effectuer.
- Votre application ouvre la page d’authentification ou affiche les instructions d’approbation du portefeuille.
- La personne s’authentifie avec son portefeuille.
- Votre backend récupère le résultat vérifié et traite les notifications de fin.
Intégration backend
Utilisez Lister les portefeuilles d’identité numérique pour obtenir les endpoints actuels, les champs requis et la disponibilité pour votre application. Conservez votrex-api-key sur votre backend.
Ne la placez pas dans un bundle navigateur ni dans une application mobile.
Utilisez un Idempotency-Key distinct pour chaque nouvelle tentative de vérification, et réutilisez cette clé lorsque vous relancez la même requête de démarrage.
Modifier la requête tout en réutilisant sa clé constitue un conflit, et non une nouvelle tentative de vérification.
Chaque portefeuille a sa propre URL de démarrage, par exemple /v3/id-verification/wallets/ftn/ pour Finnish Trust Network.
Le request_id identifie la vérification autonome pour les opérations suivantes.
Utilisez vendor_data pour votre propre référence, jusqu’à 2,000 octets UTF-8, et metadata pour un objet JSON facultatif.
Les deux sont renvoyés avec le résultat et le webhook de fin.
Ces opérations utilisent la clé API de l’application qui a lancé la vérification.
L’interrogation et la disponibilité de l’authentification dépendent du portefeuille sélectionné.
Une annulation refuse une vérification en attente sans la facturer, et renvoie une vérification terminée sans la modifier.
Pour Smart-ID et Mobile-ID, une annulation reçue pendant qu’une interrogation vérifie l’approbation attend quelques secondes que cette interrogation se termine.
Elle refuse ensuite la vérification, ou la renvoie avec le statut
verified si la personne avait déjà approuvé.
Une vérification que la personne est en train de finaliser à ce moment-là ne peut pas être annulée : la réponse est 409 avec error: "verification_in_progress" et un en-tête Retry-After.
Réessayez après ce nombre de secondes pour lire le résultat final.
Enregistrer votre destination de retour
Les portefeuilles à redirection renvoient la personne vers votre application après l’authentification. Enregistrez le nom d’hôte exact avant de lancer une vérification :return_url HTTPS, par exemple https://app.example.com/identity/complete, dans la requête de démarrage.
Utilisez uniquement les noms d’hôte dans allowed_return_hosts, sans schéma, chemin ni caractère générique.
Enregistrez séparément chaque sous-domaine que vous utilisez, jusqu’à 20 noms d’hôte.
La mise à jour de allowed_return_hosts remplace la liste enregistrée ; incluez donc chaque nom d’hôte que vous souhaitez conserver.
GET /v3/webhook/ renvoie la liste actuelle ; voir Configuration des webhooks.
Vous n’avez besoin ni de workflow ni de domaine en marque blanche pour enregistrer une destination de retour.
Cette destination est une page de retour dans le navigateur ; configurez séparément les webhooks de fin pour votre backend.
Exemple : Finnish Trust Network
Après avoir enregistré votre nom d’hôte de retour, lancez une vérification auprès de Finnish Trust Network :request_id renvoyé et redirigez le navigateur de la personne vers wallet_verification.next_action.url lorsque son type est redirect.
Une fois que la personne revient, récupérez le résultat depuis votre backend :
wallet_verification.outcome :
Utilisez l’identité uniquement lorsque le résultat est
verified et que simulated vaut false pour une vérification d’identité réelle.
Une réponse en attente peut contenir une action suivante ; les réponses finales n’ont aucune action suivante.
Expériences d’authentification
Les portefeuilles avec redirection renvoient une URL d’authentification. Ouvrez cette URL dans le navigateur de la personne, laissez-la effectuer le processus d’authentification du portefeuille, puis renvoyez-la vers la destination enregistrée. Lisez le résultat depuis votre backend au lieu de considérer un paramètre de l’URL de retour comme preuve d’identité. Smart-ID et Mobile-ID utilisent une demande d’approbation sur le téléphone de la personne. Votre interface collecte l’identifiant personnel requis ; Mobile-ID exige également le numéro de téléphone associé. Affichez le code de comparaison et demandez à la personne d’approuver uniquement si celui-ci correspond au code affiché sur son téléphone. Son code PIN doit être saisi dans l’invite d’authentification du portefeuille ou du téléphone, jamais dans votre formulaire ni dans une requête API. Interrogez votre backend toutes lespoll_interval_seconds secondes pour obtenir des informations sur l’invite.
Didit vérifie aussi en arrière-plan les approbations téléphoniques en attente ; la notification de fin de vérification peut donc parvenir à votre webhook après que la personne a fermé votre page.
Google Wallet est sollicité depuis votre propre page ou application via l’API Digital Credentials, sans redirection ; voir Portefeuilles Digital Credentials (Google Wallet).
Le mode d’interaction disponible dépend du portefeuille sélectionné.
Ne partez pas du principe que chaque portefeuille prend en charge un formulaire intégré, un code QR ou une authentification sans navigateur.
Portefeuilles Digital Credentials (Google Wallet)
Google Wallet est sollicité directement par votre page web ou votre application Android, à l’aide de l’API W3C Digital Credentials. Il n’y a ni redirection, ni page hébergée par Didit, ni code QR Didit. Il est disponible en production et dans le sandbox. Les applications sandbox n’ont pas besoin d’enregistrement ; chaque application de production s’enregistre une seule fois depuis la console (étape « Vérification d’identité », ligne Google Wallet, S’enregistrer auprès de Google) avant de pouvoir utiliser Google Wallet. Consultez Lister les portefeuilles d’identité numérique pour savoir ce que votre application peut lancer dès maintenant.1
Commencer par l'origine
Votre backend appelle
POST /v3/id-verification/wallets/google-wallet/ avec le country de la personne (USA, GBR, BRA, SGP ou TWN) et l’origin qui sollicitera le portefeuille.
L’origin est l’origine HTTPS de votre page, par exemple https://app.example.com, dont l’hôte doit figurer parmi vos noms d’hôte de retour enregistrés ou être votre domaine en marque blanche.
Pour une application Android, elle correspond à android:apk-key-hash: suivi du SHA-256 en base64 du certificat de signature de votre application, sans remplissage.
Le portefeuille refuse toute requête émise depuis une autre origine.
Il n’existe pas de return_url.2
Demander le portefeuille lors d'une action de l'utilisateur
La réponse contient
wallet_verification.interaction = "digital_credentials" et next_action.type = "request_digital_credential".
Transmettez next_action.digital_credentials.request au navigateur ou à Android Credential Manager, à partir d’un appui ou d’un clic sur l’origin que vous avez utilisée au départ.
Sur ordinateur, le navigateur affiche son propre code QR lorsque le portefeuille se trouve sur un autre appareil.3
Envoyer la réponse renvoyée par le portefeuille
Envoyez le
{protocol, data} renvoyé à votre backend, puis depuis celui-ci à POST /v3/id-verification/wallets/verifications/{request_id}/response/ sous la forme {"response": {...}}.
La requête ne peut être envoyée qu’une seule fois ; un second envoi renvoie la vérification déjà décidée.4
Lire le résultat
La réponse à l’envoi correspond à la vérification décidée.
Vous pouvez aussi la lire avec
GET /v3/id-verification/wallets/verifications/{request_id}/ ou la recevoir dans le webhook de fin de vérification."DigitalCredential" in window est vrai.
navigator.credentials.get doit s’exécuter dans une action de l’utilisateur ; appelez-le donc depuis le gestionnaire de clic et non après une étape asynchrone.
Sur Android, utilisez Jetpack Credential Manager (androidx.credentials 1.5.0 ou version ultérieure) avec la même requête :
Un justificatif qui échoue à la vérification correspond à une vérification décidée avec un résultat
failed, et non à une réponse d’erreur.
Seuls les champs demandés par la vérification sortent du portefeuille, et le résultat contient les attributs d’identité que le portefeuille a renvoyés.
Un pass d’identité Google Wallet ou un permis de conduire mobile d’un État américain ne renvoie pas de portrait.
Dans une application sandbox, le parcours est simulé avec les mêmes étapes et renvoie simulated: true.
Toute réponse envoyée décide de la vérification selon le sandbox_scenario, ce qui vous permet de construire le parcours complet dans le navigateur ou dans l’application sans justificatif réel.
Webhooks de fin de vérification
Configurez une destination de webhook d’application pourstatus.updated en suivant le guide d’intégration des webhooks.
Utilisez webhook_version: "v3" pour la structure de décision décrite ici.
Vérifiez la signature du webhook sur votre backend avant de le traiter.
Le session_id du webhook correspond au request_id renvoyé par l’API du portefeuille.
Une identité de portefeuille vérifiée apparaît dans le tableau decision.id_verifications du webhook avec verification_method: "wallet".
Vous pouvez aussi utiliser cet identifiant pour récupérer le résultat dédié de l’API du portefeuille.
Traitez les notifications d’approbation et de refus, y compris les vérifications annulées et expirées.
Rendez votre gestionnaire de webhook idempotent, car les envois échoués sont relancés.
Un retour depuis le navigateur n’est pas un webhook de fin de vérification, et ses paramètres de requête ne constituent pas une preuve d’identité.
Identité retournée
Utilisez les champs d’identité normalisés pour les noms et les dates de naissance lorsque ces champs sont retournés. Les attributs propres au portefeuille décrivent les informations d’identité partagées par le portefeuille sélectionné. Les attributs disponibles varient selon le portefeuille et le pays. Une identité authentifiée n’implique pas qu’un portrait, une adresse ou tout autre attribut demandé soit disponible.Test en sandbox
Une application en mode sandbox de Didit simule la vérification par portefeuille sans contacter de fournisseur de portefeuille et sans débiter de crédits. La réponse identifie ces requêtes avecwallet_verification.simulated: true.
Une approbation simulée correspond à des données d’exemple, et non à une identité réelle vérifiée.
Pour un portefeuille à redirection, suivez l’URL retournée afin de tester le rappel et le retour vers votre application.
Pour Smart-ID ou Mobile-ID, utilisez l’endpoint d’interrogation pour finaliser l’approbation simulée ; aucune notification n’est envoyée sur un téléphone.
Pour tester la gestion des échecs, définissez sandbox_scenario sur wallet_cancelled, wallet_timeout ou wallet_provider_error lors du lancement d’une requête.
Les applications en production rejettent sandbox_scenario.
La simulation sandbox de Didit est distincte des tests effectués dans l’environnement de test propre à un fournisseur.
Une simulation réussie n’établit ni l’accès en production auprès d’un fournisseur ni la disponibilité en production.
Sandbox du fournisseur ConnectID
Le sandbox du fournisseur ConnectID utilise des banques de test et est distinct de la simulation sandbox de Didit. Lorsque l’accès au sandbox du fournisseur est configuré pour votre intégration, transmettez l’authorisation_server_id de la banque sélectionnée à l’endpoint de démarrage ConnectID.
Utilisez l’identifiant retourné par le sélecteur de banques ConnectID ; n’envoyez ni URL de banque ni émetteur arbitraire.
Si vous omettez ce champ, la banque de test par défaut est sélectionnée.
Ce champ est propre à ConnectID et ne modifie pas les attributs d’identité demandés.
Le lot initial demande le prénom, le nom de famille et la date de naissance.
Suivez le next_action retourné pour vous authentifier, puis récupérez ou interrogez le résultat de la vérification.
Seul un résultat terminé avec un statut approuvé confirme que la vérification a réussi ; le retour vers votre application ne suffit pas à le confirmer.
ConnectID reste bientôt disponible en production pendant la finalisation de l’onboarding et de la certification.