Vérifier les pièces d'identité de vos utilisateurs
Ce guide explique comment utiliser Stripe Identity pour collecter et vérifier de manière sécurisée les pièces d’identité de vos utilisateurs.
Avant de commencer
- Activez votre compte.
- Remplissez votre formulaire d’inscription à Stripe Identity.
- (Facultatif) Personnalisez les paramètres de votre marque sur la page Paramètres de marque.
Affichage d’un modal de chargement de documents sur votre site Web. Voici ce que vous devez effectuer :
- Ajouter un bouton de vérification à votre page Web qui affiche un modal de chargement de documents.
- Afficher une page de confirmation à la soumission d’une pièce d’identité.
- Gérez les résultats de la vérification.
Configurer StripeCôté serveur
Pour commencer, créez un compte Stripe.
Installez ensuite les bibliothèques permettant d’accéder à l’API Stripe depuis votre application :
Ajouter un bouton sur votre site WebCôté client
Ajoutez un bouton à votre site Web permettant de lancer la vérification.
Ajouter un bouton
Commencez par ajouter un bouton de vérification à votre page :
<html> <head> <title>Verify your identity</title> </head> <body> <button id="verify-button">Verify</button> </body> </html>
Ajouter la bibliothèque Stripe.js à votre page
Ajoutez Stripe.js à votre page en incluant une balise de script dans votre document HTML :
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> </body> </html>
Note
Chargez toujours Stripe.js directement depuis https://js.stripe.com
. Vous ne pouvez pas l’inclure dans un lot ni en héberger une copie sur votre propre serveur.
Initialiser Stripe.js
Initialisez Stripe.js avec votre clé API publique en transmettant le JavaScript suivant à votre page :
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Afficher la boîte de dialogue de chargement de documentsCôté clientCôté serveur
Paramétrez le nouveau bouton afin qu’il affiche la boîte de dialogue de chargement de documents. Lorsqu’ils cliqueront sur le bouton, vos utilisateurs pourront capturer et charger une photo de leur passeport, de leur permis de conduire ou de leur carte d’identité.
Le modal réduit les efforts de développement et de maintenance et vous permet de collecter des pièces d’identité dans le cadre de vos flux existants. Il réduit par ailleurs la quantité d’informations privées à gérer sur votre site. Et il vous permet en outre de prendre en charge les utilisateurs sur plusieurs plateformes et dans plusieurs langues, ainsi que de personnaliser le style de la page aux couleurs de votre marque.
Créer une VerificationSession
Une VerificationSession est une représentation programmatique de la vérification. Elle contient des détails concernant le type de vérification, comme les contrôles à effectuer. Vous pouvez développer le champ des résultats vérifiés pour afficher les données qui ont été contrôlées.
Une fois votre VerificationSession
créée, envoyez la clé secrète du client au front-end pour afficher le modal de chargement de documents.
Vous avez besoin d’un endpoint côté serveur pour créer la VerificationSession. La création de la VerificationSession
côté serveur éliminera tout risque de remplacement des options de vérification par des utilisateurs malintentionnés et vous évitera ainsi des frais de traitement sur votre compte. Ajoutez une authentification à cet endpoint en incluant une référence utilisateur dans les métadonnées de la session ou en enregistrant l’ID de session dans votre base de données.
// Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')(
); // In the route handler for /create-verification-session: // Authenticate your user. // Create the session. const verificationSession = await stripe.identity.verificationSessions.create({ type: 'document', metadata: { user_id: '{{USER_ID}}', }, }); // Return only the client secret to the frontend. const clientSecret = verificationSession.client_secret;'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
Mise en garde
La clé secrète du client permet à votre front-end de collecter des informations de vérification sensibles. Elle est à usage unique et expire après 24 heures. Ne la stockez pas, ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne la dévoilez à personne d’autre que votre client. Veillez à ce que le protocole TLS soit activé sur toutes les pages contenant la clé secrète du client. N’envoyez cette dernière qu’à votre front-end pour éviter d’exposer la configuration ou les résultats de la vérification.
Testez votre endpoint en démarrant votre serveur Web (par exemple, localhost:4242
) et en envoyant une requête POST avec curl pour créer une VerificationSession :
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""
La réponse doit ressembler à ceci sur votre terminal :
HTTP/1.1 200 OK Content-Type: application/json { client_secret: "vs_QdfQQ6xfGNJR7ogV6..." }
Ajouter un gestionnaire d’événements au bouton de vérification
Maintenant que vous disposez d’un bouton et d’un endpoint pour créer une VerificationSession, modifiez le bouton afin qu’il affiche le modal de chargement de documents lorsque l’utilisateur cliquera dessus. Ajoutez un appel à verifyIdentity
à l’aide de la clé secrète du client :
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
); var verifyButton = document.getElementById('verify-button'); verifyButton.addEventListener('click', function() { // Get the VerificationSession client secret using the server-side // endpoint you created in step 3. fetch('/create-verification-session', { method: 'POST', }) .then(function(response) { return response.json(); }) .then(function(session) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the localized // error message to your user using `error.message`. if (result.error) { alert(result.error.message); } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Codes d’erreur des événements
Code d’erreur | Description |
---|---|
consent_declined | L’utilisateur a refusé la vérification par Stripe. Consultez votre conseiller juridique pour savoir si vous avez l’obligation de proposer une méthode de vérification non biométrique, par exemple une vérification manuelle. |
device_unsupported | La vérification nécessite un appareil photo, mais l’appareil de l’utilisateur n’en possède pas. |
under_supported_age | Stripe ne vérifie pas les utilisateurs mineurs. |
phone_otp_declined | L’utilisateur ne peut pas vérifier le numéro de téléphone fourni. |
email_verification_declined | L’utilisateur ne peut pas vérifier l’adresse e-mail fournie. |
Tester la boîte de dialogue de chargement
Vérifiez que votre bouton de vérification affiche la boîte de dialogue de chargement de documents :
- Cliquez sur le bouton de vérification et assurez-vous qu’il affiche la boîte de dialogue de chargement de documents Stripe.
- Vérifiez qu’aucun message d’erreur ne s’affiche.
Si votre intégration ne fonctionne pas :
- Ouvrez l’onglet Réseau dans les outils de développement de votre navigateur.
- Cliquez sur le bouton de vérification pour voir s’il effectue bien une requête XHR auprès de votre endpoint côté serveur (
POST /create-verification-session
). - Vérifiez que la requête renvoie bien un état 200.
- Utilisez
console.log(session)
dans l’écouteur du clic sur le bouton pour vous assurer qu’il renvoie les données appropriées.
Afficher une page de confirmationCôté client
Afin de fournir une expérience conviviale, affichez une page de confirmation une fois la pièce d’identité soumise. Hébergez la page sur votre site pour informer l’utilisateur que la vérification est en cours.
Créez une page de confirmation minimale :
<html> <head><title>Your document was submitted</title></head> <body> <h1>Thanks for submitting your identity document.</h1> <p> We are processing your verification. </p> </body> </html>
Ensuite, mettez à jour le gestionnaire de boutons pour qu’il redirige vers cette page :
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> <script type="text/javascript"> // Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe(
) var verifyButton = document.getElementById('verify-button'); verifyButton.addEventListener('click', function() { // Get the VerificationSession client secret using the server-side // endpoint you created in step 3. fetch('/create-verification-session', { method: 'POST', }) .then(function(response) { return response.json(); }) .then(function(session) { // Show the verification modal. return stripe.verifyIdentity(session.client_secret); }) .then(function(result) { // If `verifyIdentity` fails, you should display the error message // using `error.message`. if (result.error) { alert(result.error.message); } else { window.location.href = 'submitted.html'; } }) .catch(function(error) { console.error('Error:', error); }); }); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
Tester la page de confirmation
Vérifiez que votre page de confirmation fonctionne :
- Cliquez sur votre bouton de vérification.
- Soumettez la session en sélectionnant un cas de test prédéfini.
- Confirmez que la nouvelle page de confirmation s’affiche.
- Testez les cas d’échec (comme les refus de consentement ou d’autorisation d’accès à l’appareil photo) sur l’ensemble du flux et assurez-vous que votre application les traite sans problème.
Ensuite, localisez la vérification dans le Dashboard Stripe. Les sessions de vérification sont répertoriées dans la liste des VerificationSessions du Dashboard. Cliquez sur une session pour accéder à la page Détails de la session. La section du récapitulatif contient les résultats de la vérification, dont vous pouvez vous servir dans votre application.
Gérer les événements de vérification
Les vérifications de document sont asynchrones, ce qui signifie que les résultats de la vérification ne sont pas disponibles immédiatement. La vérification d’une pièce d’identité prend généralement entre 1 et 3 minutes. Une fois le traitement effectué, l’état de la VerificationSession passe de processing
à verified
.
Stripe envoie les événements suivants lorsque l’état de la session change :
Nom de l’événement | Description | Étapes suivantes |
---|---|---|
identity.verification_session.verified | Le traitement de tous les contrôles de vérification est terminé. La vérification a été effectuée avec succès. | Déclenchez les actions pertinentes dans votre application. |
identity.verification_session.requires_input | Le traitement de tous les contrôles de vérification est terminé, et au moins un des contrôles a échoué. | Déclenchez les actions appropriées dans votre application et autorisez le cas échéant l’utilisateur à effectuer une nouvelle tentative de vérification. |
Utilisez un gestionnaire de webhook pour recevoir ces événements et automatiser des actions telles que l’envoi d’un e-mail de confirmation, la mise à jour des résultats de la vérification dans votre base de données ou l’exécution d’une étape d’inscription. Vous pouvez également consulter les événements de vérification dans votre Dashboard.
Recevoir des événements et exécuter des actions métier
Avec code
Créez un gestionnaire de webhook pour écouter les événements et créer des flux de vérification asynchrones personnalisés. Testez et déboguez votre intégration de webhook en local avec la CLI Stripe.
Sans code
Utilisez le Dashboard pour consulter toutes vos vérifications, inspecter les données collectées et comprendre les échecs de vérification.