Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous
AperçuAccepter un paiementMettre votre intégration à niveau
Paiements en ligne
PrésentationTrouver votre cas d'usagePaiements récurrents
Paiements par TPE
Moyens de paiement
Opérations de paiement
Soldes et délai de règlementReçusRemboursements et annulations
Intégrations avancées
Au-delà des paiements

Remarque

Cette page n'est pas encore disponible dans cette langue. Nous faisons tout notre possible pour proposer notre documentation dans davantage de langues et nous vous fournirons la version traduite dès qu'elle sera disponible.

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é. 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.
  2. Gérer les réussites et les échecs des vérifications.
  3. Activer votre gestionnaire d’événements en mode production.

Les contrôles de vérification 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 à chaque changement d’état d’une session. Dans ce guide, nous allons implémenter des webhooks 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 :

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# 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

Un webhook 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 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 :

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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 incluent l’objet VerificationSession, lequel contient des informations sur les contrôles de vérification effectués. Voir Accéder aux résultats de la vérification 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énementDescriptionÉtapes suivantes
identity.verification_session.verifiedLe 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_inputLe 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.

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 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 :

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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;
    }
  }

  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 les résultats vérifiés 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 de la session de vérification pour gérer des motifs d’échec spécifiques :

  • Vous pouvez utiliser le champ last_error.code pour gérer les échecs de vérification de manière programmatique.
  • Le champ last_error.reason contient une description du motif de l’échec, que vous pouvez présenter à l’utilisateur.

Codes d’erreur d’événements

Code d’erreurDescription
consent_declinedL’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_ageStripe ne vérifie pas les utilisateurs mineurs.
country_not_supportedStripe ne vérifie pas les utilisateurs du pays indiqué.

Ajoutez du code à votre gestionnaire d’événements pour gérer les échecs des contrôles de vérification :

server.js
Node.js
Ruby
Python
PHP
Java
Go
.NET
No results
// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

// 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 afin que la mise en service de votre intégration se passe au mieux.

Les endpoints Webhook sont configurés dans Workbench ou de manière programmatique via l’API.

Ajouter un endpoint dans le Dashboard

  1. Dans l’onglet Webhooks de Workbench, cliquez sur Ajouter une destination pour ajouter un nouveau endpoint webhook.
  2. Entrez la version de l’API Stripe.
  3. Sélectionnez les événements à écouter. Voir la liste complète des événements de la session de vérification.
  4. Cliquez sur Continuer et sélectionnez Endpoint Webhook dans la liste des types de destination disponibles.
  5. Cliquez sur Continuer et entrez l’URL de votre endpoint, un nom optionnel et une description optionnelle.
  6. Cliquez sur Créer une destination.

Ajouter un endpoint avec l’API

Vous pouvez également créer des endpoints webhook 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.

Command Line
curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \
  -d "enabled_events[]"="identity.verification_session.verified" \
  -d "enabled_events[]"="identity.verification_session.requires_input"

Voir aussi