La vérification de l'identité réelle d'un utilisateur semble simple en théorie, mais sa mise en œuvre implique la capture de documents, l'OCR, la correspondance faciale, la détection de vivacité, la gestion de nombreux types de pièces d'identité et la conformité internationale. Stripe Identity centralise ces besoins via une seule API, permettant de déployer un flux KYC complet en une après-midi.
Essayez Apidog dès aujourd'hui
Ce guide détaille chaque étape pour intégrer Stripe Identity : activation dans le dashboard, création d'une VerificationSession, choix de l'intégration (redirection ou composant embarqué), gestion des webhooks, et lecture des résultats vérifiés. Vous trouverez des exemples concrets (curl/Node.js), des modèles de gestion d'erreur, et comment tester localement avec Apidog. Si vous hésitez entre plusieurs solutions, comparez d'abord les meilleures API KYC.
Stripe Identity cible principalement les équipes déjà clientes de Stripe, mais fonctionne également en produit autonome. La documentation officielle décrit les endpoints, cet article se concentre sur les usages concrets côté développeur : requêtes, champs à surveiller, et pièges à éviter.
TL;DR
- Stripe Identity vérifie les utilisateurs via pièce d'identité + selfie, à partir de 1,50 $/vérification (US).
- La ressource principale est
VerificationSession: créez-la côté serveur, puis redirigez ou utilisez Stripe.js côté client. - Personnalisez les champs KYC via
options.document.require_matching_selfie,require_id_numberetallowed_types. - Consommez les webhooks
identity.verification_session.verifiedetidentity.verification_session.requires_inputpour piloter votre backend. - Les champs vérifiés (nom, date de naissance, adresse, numéro d'identité) ne sont exposés que si
verified_outputsest défini à la création. - Prise en charge de +35 pays avec reconnaissance documentaire localisée.
Qu'est-ce que l'API Stripe Identity ?
Stripe Identity propose une API unifiée (/v1/identity/verification_sessions) pour capturer des documents, extraire des données, vérifier la correspondance faciale et scorer la fraude. Vous obtenez un enregistrement structuré et signé : nom, date de naissance, adresse, numéro d'identité, et images conservées côté Stripe.
Le modèle repose sur la création d'une session côté backend, Stripe orchestre l'UI côté utilisateur, puis informe votre backend via webhook une fois la vérification terminée. Si vous avez déjà implémenté Stripe Checkout ou Payment Intents, la logique vous sera familière.
Authentification et configuration
Avant tout, activez Stripe Identity dans le dashboard : Paramètres > Identité, acceptez les conditions et renseignez les informations requises. L'activation se fait pour les environnements test et production.
L'API s'utilise avec votre clé secrète standard (sk_test_... ou sk_live_...). Pas de gestion de credentials supplémentaire.
Installation du SDK Node :
npm install stripe
Initialisation du client avec version API épinglée :
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Vous pouvez désormais utiliser tous les endpoints stripe.identity.verificationSessions.
Points de terminaison principaux
Création d'une VerificationSession
Chaque tentative de vérification utilisateur passe par la création d'un objet VerificationSession. Il définit les types de documents acceptés, l'obligation de selfie, et les champs à exposer côté backend.
Exemple avec curl :
curl https://api.stripe.com/v1/identity/verification_sessions \
-u "$STRIPE_SECRET_KEY:" \
-d "type=document" \
-d "options[document][require_matching_selfie]=true" \
-d "options[document][require_id_number]=true" \
-d "options[document][allowed_types][]=driving_license" \
-d "options[document][allowed_types][]=passport" \
-d "verified_outputs[]=first_name" \
-d "verified_outputs[]=last_name" \
-d "verified_outputs[]=dob" \
-d "verified_outputs[]=address" \
-d "verified_outputs[]=id_number" \
-d "metadata[user_id]=usr_7f3k2"
Exemple avec Node.js :
const session = await stripe.identity.verificationSessions.create({
type: "document",
options: {
document: {
require_matching_selfie: true,
require_id_number: true,
allowed_types: ["driving_license", "passport", "id_card"],
},
},
verified_outputs: [
"first_name",
"last_name",
"dob",
"address",
"id_number",
],
metadata: { user_id: "usr_7f3k2" },
});
// À envoyer côté client :
// session.url -> redirection hébergée
// session.client_secret -> Stripe.js embarqué
Points clés :
-
type: "document"déclenche la vérification documentaire ; l'alternativeid_number(recherche SSN US) ne collecte pas de document. -
allowed_typeslimite les documents acceptés (utile pour la conformité). -
verified_outputs: Stripe ne renvoie que les champs explicitement demandés (minimisation des données).
Redirection hébergée vs Stripe.js intégré
Deux modes d'intégration :
-
Redirection hébergée : envoyez l'utilisateur vers
session.url(domaine stripe.com), Stripe gère toute la capture, puis redirige vers votrereturn_url. Rapidité et simplicité. -
Composant Stripe.js : intégrez le modal de vérification dans votre app avec
@stripe/stripe-jsetstripe.verifyIdentity(clientSecret). Idéal pour une UX fluide et contrôlée.
Utilisez Stripe.js en onboarding ou KYC en flux, préférez la redirection pour les vérifications isolées.
Webhooks
Ne vous fiez jamais à la redirection du frontend pour statuer sur la vérification : traitez les statuts côté backend via webhooks.
-
identity.verification_session.verified: succès, outputs disponibles. -
identity.verification_session.requires_input: échec (document non lisible, selfie incorrect...), proposez un réessai. -
identity.verification_session.processing: vérifications asynchrones en cours. -
identity.verification_session.canceled: annulation manuelle.
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
const event = stripe.webhooks.constructEvent(
req.body,
req.headers["stripe-signature"],
process.env.STRIPE_WEBHOOK_SECRET
);
if (event.type === "identity.verification_session.verified") {
const session = event.data.object;
await markUserVerified(session.metadata.user_id, session.id);
}
if (event.type === "identity.verification_session.requires_input") {
await notifyUserToRetry(event.data.object.metadata.user_id);
}
res.json({ received: true });
});
Récupération des sorties vérifiées
Le webhook signale le statut, mais pas les champs sensibles. Pour lire les outputs vérifiés, appelez :
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
id_number n'est retourné qu'une fois : chiffrez-le immédiatement si besoin. Les images de documents restent stockées côté Stripe, accessibles dans le dashboard.
Erreurs courantes et limites de débit
L'échec le plus courant est verification_session.requires_input avec codes document_unverified_other ou selfie_face_mismatch. Gérez ces cas via un message d'erreur et proposez le réessai (nouvelle session ou même URL si encore valide).
Stripe limite à 100 requêtes/sec (live) et 25/sec (test) sur /identity/verification_sessions. Au-delà : HTTP 429 + Retry-After. Implémentez une backoff exponentielle.
Autres erreurs fréquentes : unsupported_document_type (document refusé) et country_not_supported (pays non couvert).
Tarification de Stripe Identity
Comptez 1,50 $/vérification (US). En Europe : 1,50–2,00 $. Seules les sessions verified sont facturées (pas les requires_input). Pour +10 000 vérifications/mois, contactez Stripe pour un tarif négocié.
Tester Stripe Identity avec Apidog
Pour tester et itérer rapidement, Apidog importe la spec OpenAPI Stripe : chaque champ VerificationSession est documenté, avec requêtes en live sur l’environnement test Stripe. Inspectez et rejouez les réponses à volonté.
Côté webhooks, Apidog permet de simuler localement des événements (identity.verification_session.verified) et de tester tout votre handler sans attendre une vraie vérification. Pour comparer les workflows, lisez notre guide sur les tests d'API sans Postman. Téléchargez Apidog pour accéder au client desktop.
<!--kg-card-begin: html-->
<!--kg-card-end: html-->
FAQ
Différence entre Stripe Identity et le KYC Stripe classique ? Le KYC natif Stripe concerne les comptes Connect/Paiements (propriétaires d'entreprise). Stripe Identity est une API KYC pour vos propres utilisateurs finaux, les deux sont indépendants.
Puis-je réutiliser une identité vérifiée ? Oui, les verified_outputs sont persistants sur la session, mais pour un nouvel événement KYC, créez une nouvelle session liée à l'utilisateur.
Stripe Identity pour autre chose que le paiement ? Oui, c'est une couche KYC autonome. Pour un screening AML avancé, combinez avec une API AML dédiée.
Stripe Identity vs Plaid Identity Verification ? Stripe vérifie via document/selfie ; Plaid s'appuie sur des données bancaires. Voir notre guide Plaid pour l'alternative.
Le selfie est-il obligatoire ? Non : options.document.require_matching_selfie: false désactive la vérification selfie. Conservez-la activée pour contrer la fraude.
Pays couverts ? 35+ pays, majoritairement Amérique du Nord, Europe, Asie-Pacifique. Liste à jour dans la doc Stripe, ajout régulier de nouveaux marchés.
Top comments (0)