# L'API Verification Sessions Découvrez l'API Verification Sessions qui propulse Stripe Identity. Utilisez l’[API Verification Session](https://docs.stripe.com/api/identity/verification_sessions.md) pour collecter des informations de façon sécurisée et effectuer des [contrôles de vérification](https://docs.stripe.com/identity/verification-checks.md). 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](https://docs.stripe.com/identity/verify-identity-documents.md). ## Création d’une VerificationSession Lorsque vous [créez la VerificationSession](https://docs.stripe.com/api/identity/verification_sessions/create.md), déterminez le [contrôle de vérification](https://docs.stripe.com/identity/verification-checks.md) à effectuer en spécifiant le [type](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-type) de la session : - [document](https://docs.stripe.com/identity/verification-checks.md?type=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](https://docs.stripe.com/identity/verification-checks.md?type=id-number) : permet de vérifier le nom, la date de naissance et le numéro national d’identité de l’utilisateur. ```curl curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -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](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md). 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-client_secret), 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 : #### 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')('<>'); // 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 : ```javascript (async () => { const response = await fetch('/create-verification-session'); const {client_secret: clientSecret} = await response.json(); // Call stripe.verifyIdentity() with the client secret. })(); ``` > La clé secrète du client est un token sensible que vous pouvez utiliser pour réaliser la vérification. Vous ne devez pas l’enregistrer, l’intégrer à des URL ni la dévoiler à d’autres personnes que l’utilisateur que vous vérifiez. Veillez à avoir *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) sur toutes les pages qui contiennent la clé secrète du client. ## 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](https://docs.stripe.com/api/identity/verification_reports/object.md). 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](https://docs.stripe.com/api/expanding_objects.md) le champ [verified_outputs](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) pour afficher les données vérifiées. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error) de la session. La valeur de [last_error.code](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) peut être utilisée pour gérer programmatiquement les échecs de vérification courants. Le [last_error.reason](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) contient une chaîne expliquant la raison de l’échec, qui peut être affichée à votre utilisateur. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": {"code": "document_expired", "reason": "The document is expired.", }, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md) 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](https://docs.stripe.com/identity/access-verification-results.md). ## 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 curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/cancel \ -u "<>:" ``` ## Expurgation d’une VerificationSession Vous pouvez vouloir supprimer les données d’une session de vérification, par exemple si un utilisateur vous demande la suppression de ses données. Vous pouvez expurger une session afin que Stripe supprime les informations personnelles. Une fois les informations personnelles supprimées, elles ne sont plus renvoyées par l’API Stripe ni visibles dans le Dashboard. Vous pouvez toujours [récupérer](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md) des sessions dont les données ont été supprimées via l’API, mais vous ne pouvez plus les mettre à jour. Vous pouvez supprimer les données d’une session dans le Dashboard ou via l’API : ```curl curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/redact \ -u "<>:" ``` Les sessions expurgées contiennent des valeurs de substitution dans tous les champs qui contenaient auparavant des informations personnelles identifiables (PII). La session inclut un champ [redaction.status](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-redaction-status) indiquant l’état du processus d’expurgation. Nous envoyons un webhook [identity.verification_session.redacted](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.redacted) lorsque la session est expurgée. L’expurgation peut prendre jusqu’à quatre 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. ```json { "id": "vs_orWziM4j7CiRL8J4vQmXgW2w", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w", "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 } ``` Nous expurgeons tous les objets [VerificationReports](https://docs.stripe.com/api/identity/verification_reports.md), [Events](https://docs.stripe.com/api/events.md) et [Request Logs](https://dashboard.stripe.com/logs) associés à la `VerificationSession`. Une fois le contenu des objets [File](https://docs.stripe.com/api/files.md) supprimé, vous ne pouvez plus le télécharger. 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](https://docs.stripe.com/api.md#metadata) à 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 curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -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](https://docs.stripe.com/api/events.md) sont créés lorsqu’une session change d’état. Voici la liste complète des [types d’événement](https://docs.stripe.com/api.md#event_types) d’une VerificationSession : | Type d’événement | Description | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identity.verification_session.created` | La session a été [créée](https://docs.stripe.com/identity/verification-sessions.md#create). | | `identity.verification_session.processing` | L’utilisateur a correctement communiqué ses informations et les contrôles de vérification sont en cours de traitement. | | `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. | | `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é. | | `identity.verification_session.canceled` | La session a été annulée et les futures tentatives de soumission ont été désactivées. Cet événement est envoyé lorsqu’une session est [annulée](https://docs.stripe.com/identity/verification-sessions.md#cancel) ou [expurgée](https://docs.stripe.com/identity/verification-sessions.md#redact). | | `identity.verification_session.redacted` | La session a été [expurgée](https://docs.stripe.com/identity/verification-sessions.md#redact). Pour y accéder, vous devez créer un [endpoint de webhook](https://docs.stripe.com/api/webhook_endpoints.md) qui s’abonne explicitement à ce type d’événement. Les endpoints de webhook abonnés à tous les événements n’incluront pas ce type d’événement. | 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](https://docs.stripe.com/identity/handle-verification-outcomes.md). ## See also - [Vérifier les pièces d’identité de vos utilisateurs](https://docs.stripe.com/identity/verify-identity-documents.md)