L'API Verification Sessions

Utilisez l’API Verification Session pour collecter des informations de façon sécurisée et effectuer des contrôles de vérification. Cette API suit chaque vérification depuis sa création jusqu’à son terme, puis affiche les résultats correspondants une fois l’opération menée à bien.

Pour obtenir des instructions pas à pas sur l’utilisation de l’API Verification Session afin de vérifier les pièces d’identité de vos utilisateurs, consultez le guide correspondant : Vérifier les pièces d’identité de vos utilisateurs.

Création d’une VerificationSession

Lorsque vous créez la VerificationSession, déterminez le contrôle de vérification à effectuer en spécifiant le type de la session :

• document : permet de vérifier l’authenticité et la propriété de pièces d’identité officielles. Peut aussi inclure une vérification de selfie.
• id_number : permet de vérifier le nom, la date de naissance et le numéro national d’identité de l’utilisateur.

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document

Bonnes pratiques

Si le processus de vérification est interrompu et repris plus tard, essayez d’utiliser la même VerificationSession au lieu d’en créer une nouvelle. Chaque VerificationSession dispose d’un ID unique que vous pouvez utiliser pour la récupérer. Dans le modèle de données de votre application, vous pouvez enregistrer l’ID de la VerificationSession pour en faciliter la récupération.

L’avantage de réutiliser la VerificationSession est que l’objet aide à suivre tout échec de tentative de vérification. Si l’un des contrôles échoue, la VerificationSession présentera l’état requires_input.

Nous vous recommandons de fournir une clé d’idempotence lorsque vous créez la VerificationSession afin d’éviter de créer par erreur deux VerificationSessions pour la même personne. Cette clé est généralement basée sur l’ID associé à la vérification sur votre application, comme une référence utilisateur.

Transmission de la clé secrète du client au front-end

La VerificationSession contient une clé secrète du client, une clé unique à la VerificationSession individuelle. Le front-end utilise cette clé secrète du client pour réaliser la vérification.

Pour utiliser la clé secrète du client, vous devez la récupérer dans la VerificationSession sur votre serveur et la transmettre au front-end. Vous pouvez récupérer la clé secrète du client depuis un endpoint sur votre serveur à l’aide de la fonction fetch du navigateur côté client. Cette approche est généralement la plus adaptée lorsque le client est une application monopage, et en particulier si celle-ci a été créée avec un framework front-end récent comme React.

Cet exemple vous montre comment créer l’endpoint de serveur pour la clé secrète du client :

// 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');

// In the route handler for /create-verification-session:
// Authenticate your user.

// Create the session.
const verificationSession = await stripe.identity.verificationSessions.create({
  type: 'document',
  provided_details: {
    email: 'user@example.com',
  },
  metadata: {
    user_id: '{{USER_ID}}',
  },
});

// Return only the client secret to the frontend.
const clientSecret = verificationSession.client_secret;

Cet exemple vous montre comment récupérer la clé secrète du client avec JavaScript côté client :

(async () => {
  const response = await fetch('/create-verification-session');
  const {client_secret: clientSecret} = await response.json();
  // Call stripe.verifyIdentity() with the client secret.
})();

Accès aux résultats de la vérification

L’envoi et le traitement d’une VerificationSession met à jour le status de la session et crée un objet VerificationReport. Cette opération ne nécessite habituellement que quelques minutes.

Une fois que tous les contrôles de vérification ont abouti, l’état passe à verified. Vous pouvez développer le champ verified_outputs pour afficher les données vérifiées.

{
  "id": "vs_fW9NqJrcEeK2DmC7yiPOvBPE",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_sPJhLhO60CUK3jIhYjtfZY3E",
  "livemode": true,
  "metadata": {},
  "options": {
    "document": {},
  },
  "status": "verified",
  "type": "document",
  "redaction": null,
  "url": null,
  "verified_outputs": {
    "first_name": "Jenny",
    "last_name": "Rosen",
    "address": {
      "line1": "1234 Main St.",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94111",
      "country": "US"
    },
    "id_number_type": null
  }
}

Si l’un des contrôles de vérification échoue, la session aura le statut requires_input Les détails de l’échec de la vérification sont disponibles dans le champ last_error de la session. La valeur de last_error.code peut être utilisée pour gérer programmatiquement les échecs de vérification courants. Le last_error.reason contient une chaîne expliquant la raison de l’échec, qui peut être affichée à votre utilisateur.

{
  "id": "vs_wbyrzO3mqCuBZE1XH2yCPVFI",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": {
    "code": "document_expired",
    "reason": "The document is expired.",
  },
  "last_verification_report": "vr_yZNwA6x4E0LkVCELY43oebXf",
  "livemode": true,
  "metadata": {},
  "options": {},
  "status": "requires_input",
  "type": "document",
  "redaction": null,
  "url": null,
}

Si vous souhaitez que votre utilisateur puisse effectuer une nouvelle tentative de vérification, vous devrez récupérer la VerificationSession pour obtenir une autre URL ou une autre clé secrète du client à transmettre à votre client.

Découvrir comment accéder aux résultats de vérification sensibles.

Annulation d’une VerificationSession

Vous pouvez annuler une VerificationSession à tout moment avant qu’elle ne passe à l’état processing ou verified. Cela invalide la session pour toute tentative de soumission ultérieure et ne peut pas être annulé. La session affichera alors le statut canceled.

curl -X POST https://api.stripe.com/v1/identity/verification_sessions/
{{VERIFICATION_SESSION_ID}}
/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Expurgation d’une VerificationSession

Vous pourriez vouloir expurger une session de vérification si vous recevez une demande de suppression des données de la part de votre utilisateur. Vous pouvez expurger une session afin de faire en sorte que les informations collectées ne soient plus renvoyées par l’API Stripe ni visibles dans le Dashboard. Il est toujours possible de récupérer des sessions expurgées avec l’API, mais vous ne pourrez pas les modifier. Les sessions peuvent être expurgées depuis le Dashboard ou via l’API :

curl -X POST https://api.stripe.com/v1/identity/verification_sessions/
{{VERIFICATION_SESSION_ID}}
/redact \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Les sessions expurgées affichent des valeurs d’emplacement pour tous les champs qui contenaient précédemment des informations d’identification personnelle (PII). La session comprend un champ redaction.status qui indique l’état du processus d’expurgation. Un webhook identity.verification_session.redacted sera envoyé une fois la session expurgée. Veuillez noter que l’expurgation peut prendre jusqu’à 4 jours.

Si une VerificationSession qui a été expurgée est récupérée avec des champs PII développés, ces champs apparaîtront quand même dans la réponse mais leurs valeurs ne contiendront aucune PII. Voici par exemple une réponse dont les champs verified_outputs et verified_outputs.dob ont été développés dans une VerificationSession expurgée.

{
  "id": "vs_Cmuc8ACBeqX4prt8nLzO9snh",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_ehsowx1CBWLMludJD6L5U0ac",
  "livemode": true,
  "options": {},
  "status": "verified",
  "type": "document",
  "url": null,
  "client_secret": null,
  "redaction": {
    "status": "redacted"
  },
  "verified_outputs": {
    "first_name": "[redacted]",
    "last_name": "[redacted]",
    "dob": {
      "year": 1,
      "month": 1,
      "day": 1
    },
    "address": {
      "line1": "[redacted]",
      "city": "[redacted]",
      "state": "[redacted]",
      "postal_code": "[redacted]",
      "country": "US"
    },
    "id_number_type": null
  },
  "metadata": {} // Metadata will also be redacted
}

Tous les VerificationReports, Events et logs des requêtes associés à la VerificationSession sont également expurgés et les contenus des fichiers ne sont plus téléchargeables.

Si la VerificationSession est à l’état processing, vous devez attendre qu’elle arrive à son terme avant de l’expurger. Expurger une VerificationSession avec l’état requires_action l’annule automatiquement.

Stockage d’informations sous forme de métadonnées

Stripe vous permet d’ajouter des métadonnées à l’objet VerificationSession. Les métadonnées ne sont pas visibles pour vos clients et n’ont aucune influence sur la réussite ou l’échec d’un contrôle de vérification.

Les métadonnées vous permettent d’associer d’autres informations pertinentes pour vous à votre activité Stripe. Toutes les métadonnées incluses sont visibles dans le Dashboard (par exemple, sur la page d’une session individuelle) et disponibles dans les rapports les plus courants. Par exemple, vous pouvez associer un ID d’utilisateur de votre application à la VerificationSession utilisée pour vérifier cet utilisateur. Ainsi, vous avez la possibilité de rapprocher très simplement les vérifications sur Stripe des utilisateurs de votre système.

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document \
  -d "metadata[user_id]"={{USER_ID}} \
  -d "metadata[reference]"={{IDENTIFIER}}

Nous vous recommandons de ne pas stocker d’informations sensibles (telles que des données personnelles identifiables, des numéros d’identification, etc.) dans les métadonnées de la session. Les métadonnées sont supprimées lorsque vous expurgez une VerificationSession.

Événements de session

Les événements sont créés lorsqu’une session change d’état. Voici la liste complète des types d’événement d’une VerificationSession :

Il est conseillé d’agir en fonction de certains événements, notamment en envoyant un e-mail à l’utilisateur en cas d’échec ou de succès de la vérification.

Stripe vous recommande d’écouter les événements à l’aide de webhooks.