Vérifier les pièces d'identité de vos utilisateurs

Créez des sessions et collectez leurs pièces d'identité.

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 Stripe
Cô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 Web
Cô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 :

verification.html
<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 :

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

Remarque

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 :

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
    </script>
  </body>
</html>

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 la fenêtre modale 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.

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 :

Command Line
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""

La réponse doit ressembler à ceci sur votre terminal :

Command Line
HTTP/1.1 200 OK
Content-Type: application/json

{ id: "vs_QdfQQ6xfGNJR7ogV6", client_secret: "vs_QdfQQ6xfGNJR7ogV6_secret_live_..."  }

Ajouter un gestionnaire d’événements au bouton de vérification

Now that you have a button and an endpoint to create a VerificationSession, modify the button to show the document upload modal when clicked. Add a call to verifyIdentity using the client secret:

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

      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>

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.

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 confirmation
Cô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 :

submitted.html
<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 :

verification.html
<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('pk_test_TYooMQauvdEDq54NiTphI7jx'
)

      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>

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

Document checks are typically completed as soon as the user redirects back to your site and you can retrieve the result from the API immediately. In some rare cases, the document verification isn’t ready yet and must continue asynchronously. In these cases, you’re notified through webhooks when the verification result is ready. After the processing completes, the VerificationSession status changes from processing to 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.

Créer un webhook personnalisé

Sans code

Utilisez le Dashboard pour consulter toutes vos vérifications, inspecter les données collectées et comprendre les échecs de vérification.

Afficher vos vérifications de test dans le Dashboard