# Gérer les résultats des vérifications Écoutez les résultats des vérifications pour que votre intégration déclenche automatiquement les réactions appropriées. Vous avez écrit du code pour [afficher une fenêtre modale permettant de collecter les pièces d’identité](https://docs.stripe.com/identity/verify-identity-documents.md). Lorsqu’un utilisateur soumet un document, vous pouvez désormais écouter les résultats de la vérification pour déclencher des réactions dans votre application. Dans ce guide, vous apprendrez à : 1. Recevoir une notification d’événement au terme du traitement d’une vérification. 1. Gérer les réussites et les échecs des vérifications. 1. Activer votre gestionnaire d’événements en mode production. Les [contrôles de vérification](https://docs.stripe.com/identity/verification-checks.md) sont asynchrones, ce qui signifie que les résultats de la vérification ne sont pas immédiatement disponibles. Une fois le processus terminé, l’état de la VerificationSession change et les informations deviennent disponibles. Stripe génère des [événements](https://docs.stripe.com/api/events.md) à chaque changement d’état d’une session. Dans ce guide, nous allons implémenter des [webhooks](https://docs.stripe.com/webhooks.md) pour informer votre application de la mise à disposition des résultats de la vérification. ## Configurer Stripe [Côté serveur] Installez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application : #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Créer un webhook et gérer les événements de la VerificationSession [Côté serveur] Consultez le guide relatif à la [création d’un endpoint de webhook](https://docs.stripe.com/webhooks/quickstart.md) pour découvrir comment créer un endpoint de webhook, étape par étape. Un [webhook](https://docs.stripe.com/webhooks.md) est un endpoint sur votre serveur qui reçoit des requêtes de Stripe. Il vous informe des événements qui se produisent sur votre compte. À cette étape, nous allons créer un endpoint pour recevoir des événements concernant les [changements d’état](https://docs.stripe.com/identity/verification-sessions.md) de la VerificationSession. Les endpoints de webhook doivent être publiquement accessibles pour que Stripe puisse envoyer des requêtes non authentifiées. Vous devrez vérifier que Stripe a envoyé l’événement en utilisant la bibliothèque Stripe et l’en-tête de la requête : #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed event res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Maintenant que vous avez mis en place la structure et la sécurité de base nécessaires pour écouter les notifications de Stripe, mettez à jour votre endpoint de webhook pour gérer les événements de la session de vérification. Tous les [évènements de session](https://docs.stripe.com/identity/verification-sessions.md#events) incluent l’objet [VerificationSession](https://docs.stripe.com/api/identity/verification_sessions.md), lequel contient des informations sur les contrôles de vérification effectués. Voir [Accéder aux résultats de la vérification](https://docs.stripe.com/identity/access-verification-results.md) pour apprendre comment récupérer des informations vérifiées non incluses dans les évènements de session. 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](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.verified) | Le traitement de tous les [contrôles de vérification](https://docs.stripe.com/identity/verification-checks.md) 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](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.requires_input) | Le traitement de tous les [contrôles de vérification](https://docs.stripe.com/identity/verification-checks.md) 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. | Le code de votre webhook doit gérer les événements `identity.verification_session.verified` et `identity.verification_session.requires_input`. Vous pouvez vous inscrire à d’autres [événements de session](https://docs.stripe.com/identity/verification-sessions.md#events) afin de déclencher des réactions supplémentaires dans votre application. ### Gérer le passage à l’état « verified » de la VerificationSession Vous recevez l’événement `identity.verification_session.verified` lorsque tous les contrôles de vérification se sont soldés par un succès. Ajoutez du code à votre gestionnaire d’événements pour gérer la réussite de tous les contrôles de vérification : #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed eventswitch (event.type) { case 'identity.verification_session.verified': { // All the verification checks passed const verificationSession = event.data.object; break; } } res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Lorsque vous gérez cet événement, nous vous conseillons également d’effectuer les actions suivantes : - Enregistrer l’état de la vérification dans votre propre base de données - Envoyer un e-mail à votre utilisateur pour l’informer de la réussite de la vérification - [Développer](https://docs.stripe.com/api/expanding_objects.md) les [résultats vérifiés](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) de la VerificationSession et les comparer à une valeur attendue. ### Gérer le passage à l’état requires_input de la VerificationSession Vous recevez l’événement `identity.verification_session.requires_input` lorsqu’au moins un des contrôles a échoué. Vous pouvez inspecter le hachage [last_error](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error) de la session de vérification pour gérer des motifs d’échec spécifiques : - Vous pouvez utiliser le champ [last_error.code](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) pour gérer les échecs de vérification de manière programmatique. - Le champ [last_error.reason](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-reason) contient une description du motif de l’échec, que vous pouvez présenter à l’utilisateur. #### Codes d’erreur d’événements #### Session | Code d’erreur | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `consent_declined` | L’utilisateur a refusé la vérification par Stripe. Vérifiez auprès de votre conseiller juridique si vous avez l’obligation de proposer un autre moyen de vérification non biométrique, par exemple une vérification manuelle. | | `under_supported_age` | Stripe ne vérifie pas les utilisateurs mineurs. | | `country_not_supported` | Stripe ne vérifie pas les utilisateurs du pays indiqué. | #### Document | Code d’erreur | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `document_expired` | La pièce d’identité fournie a expiré. | | `document_unverified_other` | Stripe n’a pas pu vérifier la pièce d’identité fournie. [Voir la liste des types de documents pris en charge](https://docs.stripe.com/identity/verification-checks.md?type=document). | | `document_type_not_supported` | La pièce d’identité fournie ne fait pas partie des [types de documents autorisés](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-options-document-allow_document_types) de la session. | #### Selfie | Code d’erreur | Description | | ------------------------------- | ------------------------------------------------------------------------------ | | `selfie_document_missing_photo` | La pièce d’identité fournie ne contient pas de photo de visage. | | `selfie_face_mismatch` | Le visage pris en photo ne correspondait pas à celui figurant sur le document. | | `selfie_unverified_other` | Stripe n’a pas pu vérifier le selfie fourni. | | `selfie_manipulated` | La photo de visage capturée a été manipulée. | #### Numéro d'identification | Code d’erreur | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id_number_unverified_other` | Stripe n’a pas pu vérifier le numéro d’identification fourni. [Voir la liste des numéros d’identification pris en charge](https://docs.stripe.com/identity/verification-checks.md?type=id-number). | | `id_number_insufficient_document_data` | Le document fourni ne contient pas suffisamment de données pour établir une correspondance avec le numéro d’identification. | | `id_number_mismatch` | Aucune correspondance des informations fournies dans les bases de données internationales | #### Adresse (sur invitation uniquement) | Code d’erreur | Description | | ------------------ | ------------------------------------------------------------------------------------------ | | `address_mismatch` | Aucune correspondance des informations fournies dans les bases de données internationales. | Ajoutez du code à votre gestionnaire d’événements pour gérer les échecs des contrôles de vérification : #### Node.js ```javascript // Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. // Find your keys at https://dashboard.stripe.com/apikeys. const stripe = require('stripe')('<>'); // You can find your endpoint's secret in your webhook settings const endpointSecret = 'whsec_...'; // This example uses Express to receive webhooks const express = require('express'); // Use body-parser to retrieve the raw body as a buffer const bodyParser = require('body-parser'); const app = express(); // Use JSON parser for all non-webhook routes app.use((req, res, next) => { if (req.originalUrl === '/webhook') { next(); } else { bodyParser.json()(req, res, next); } }); app.post('/webhook', bodyParser.raw({type: 'application/json'}), (req, res) => { let event; // Verify the event came from Stripe try { const sig = req.headers['stripe-signature']; event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); } catch (err) { // On error, log and return the error message console.log(`❌ Error message: ${err.message}`); return res.status(400).send(`Webhook Error: ${err.message}`); } // Successfully constructed event switch (event.type) { case 'identity.verification_session.verified': { // All the verification checks passed const verificationSession = event.data.object; break; }case 'identity.verification_session.requires_input': { // At least one of the verification checks failed const verificationSession = event.data.object; console.log('Verification check failed: ' + verificationSession.last_error.reason); // Handle specific failure reasons switch (verificationSession.last_error.code) { case 'document_unverified_other': { // The document was invalid break; } case 'document_expired': { // The document was expired break; } case 'document_type_not_supported': { // document type not supported break; } default: { // ... } } } } res.json({received: true}); }); app.listen(4242, () => { console.log('Running on port 4242'); }); ``` Suivant votre cas d’usage, vous voudrez peut-être autoriser vos utilisateurs à effectuer une nouvelle tentative de vérification en cas d’échec. Nous vous recommandons de limiter le nombre de tentatives. Lorsque vous gérez cet événement, nous vous conseillons également d’effectuer les actions suivantes : - Vérifier manuellement les informations collectées - Envoyer un e-mail à votre utilisateur pour l’informer de l’échec de la vérification - Proposer à votre utilisateur une autre méthode de vérification ## Passer en mode production Une fois que vous avez déployé votre endpoint de gestionnaire d’événements, configurez-le de manière à ce que Stripe sache où envoyer les événements en mode production. Nous vous conseillons également de consulter la [liste de contrôle des développeurs](https://docs.stripe.com/get-started/checklist/go-live.md) afin que la mise en service de votre intégration se passe au mieux. Les endpoints Webhook sont configurés dans [Workbench](https://docs.stripe.com/workbench.md) ou de manière programmatique via l’API. ### Ajouter un endpoint dans le Dashboard 1. Dans l’onglet [Webhooks](https://dashboard.stripe.com/workbench/webhooks) de Workbench, cliquez sur **Ajouter une destination** pour ajouter un nouveau endpoint webhook. 1. Entrez la version de l’API Stripe. 1. Sélectionnez les événements à écouter. Voir la liste complète des [événements de la session de vérification](https://docs.stripe.com/identity/verification-sessions.md#events). 1. Cliquez sur **Continuer** et sélectionnez **Endpoint Webhook** dans la liste des types de destination disponibles. 1. Cliquez sur **Continuer** et entrez l’URL de votre endpoint, un nom optionnel et une description optionnelle. 1. Cliquez sur **Créer une destination**. ### Ajouter un endpoint avec l’API Vous pouvez également [créer des endpoints webhook](https://docs.stripe.com/api/webhook_endpoints/create.md) par programmation. Comme avec le formulaire dans Workbench, vous pouvez entrer n’importe quelle URL comme destination pour les événements et quels types d’événements suivre. ```bash curl https://api.stripe.com/v1/webhook_endpoints \ -u <>: \ -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \ -d "enabled_events[]"="identity.verification_session.verified" \ -d "enabled_events[]"="identity.verification_session.requires_input" ``` ## See also - [Tester un endpoint de webhook](https://docs.stripe.com/webhooks.md#test-webhook) - [Bonnes pratiques en matière d’utilisation des webhooks](https://docs.stripe.com/webhooks.md#best-practices) - [Liste de contrôle pour le développement des webhooks](https://docs.stripe.com/get-started/checklist/go-live.md)