La vérification de l'identité réelle d'un utilisateur est l'une de ces tâches qui semblent simples sur un tableau blanc et se transforment en un projet de plusieurs mois dès que vous commencez à la construire. Vous avez besoin de capture de documents, d'OCR, de correspondance faciale, de détection de vivacité, de signaux de fraude et de couverture pour des dizaines de types de pièces d'identité dans différents pays. L'API Stripe Identity regroupe tout cela en une seule intégration, afin que vous puissiez mettre en place un flux de vérification d'identité prêt pour la production en un après-midi au lieu d'un trimestre.
Ce guide vous accompagne à travers chaque étape dont un développeur a besoin pour déployer Stripe Identity : l'activer dans le tableau de bord, créer une VerificationSession, choisir entre la redirection hébergée et le composant Stripe.js intégré, gérer les webhooks et lire les sorties vérifiées. Vous verrez des exemples curl et Node, des modèles de gestion des erreurs et comment tester l'ensemble du flux localement avec Apidog. Si vous évaluez d'abord des alternatives, parcourez notre récapitulatif des meilleures API KYC avant de vous engager.
Stripe Identity est parfaitement adapté aux équipes qui utilisent déjà Stripe pour les paiements, mais il fonctionne également comme un produit autonome. La documentation officielle de Stripe Identity couvre la surface du produit, et cet article comble les lacunes en matière d'expérience développeur : ce qui se passe sur le réseau, les champs importants et les pièges courants.
TL;DR
- Stripe Identity vérifie les utilisateurs avec une pièce d'identité gouvernementale et une vérification de la vivacité par selfie ; les prix commencent à 1,50 $ par vérification aux États-Unis.
- La primitive principale est l'objet
VerificationSession; vous en créez une côté serveur, puis redirigez l'utilisateur ou montez le composant Stripe.js. - Demandez les champs dont vous avez besoin via
options.document.require_matching_selfie,require_id_numberetallowed_types. - Écoutez les webhooks
identity.verification_session.verifiedetidentity.verification_session.requires_inputpour gérer l'état de votre application. - Les sorties vérifiées (nom, date de naissance, adresse, numéro d'identification) ne sont exposées que si vous définissez
verified_outputslors de la création de la session. - Stripe Identity couvre plus de 35 pays avec un support de documents localisé.
Qu'est-ce que l'API Stripe Identity ?
Stripe Identity est un produit de vérification d'identité basé sur la surface de l'API principale de Stripe. Il vous offre une seule famille de points de terminaison (/v1/identity/verification_sessions) qui orchestre la capture de documents, l'extraction de données, la correspondance faciale et la notation de fraude. Le résultat est un enregistrement signé et structuré auquel vous pouvez faire confiance : un nom complet vérifié, une date de naissance, une adresse et un numéro d'identification facultatif, associés aux images originales des documents stockées dans le coffre-fort de Stripe.
En coulisses, Stripe utilise le même modèle session-plus-webhook que vous connaissez déjà avec Checkout et Payment Intents. Vous créez une session côté serveur, Stripe gère l'interface utilisateur de capture côté utilisateur, et vous êtes informé lorsque le résultat est prêt. Si vous avez déjà construit un flux Checkout, Identity vous semblera familier en quelques minutes.
Authentification et configuration
Avant d'appeler l'API, activez Stripe Identity dans le tableau de bord. Allez dans Tableau de bord > Paramètres > Identité, acceptez les conditions et remplissez les détails commerciaux dont Stripe a besoin pour la conformité KYC de son côté. Le bouton bascule active Identity pour les modes test et live sur votre compte.
L'authentification utilise votre clé secrète Stripe standard. Les clés de test commencent par sk_test_, et les clés live commencent par sk_live_. Stripe Identity ne nécessite pas d'identifiant distinct, ce qui maintient une petite surface d'intégration.
Installez le SDK Node :
npm install stripe
Ensuite, initialisez un client. Épinglez la version de l'API pour que Stripe ne vous surprenne jamais avec un changement de schéma :
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Vous pouvez maintenant appeler chaque point de terminaison sous stripe.identity.verificationSessions.
Points de terminaison principaux
Création d'une VerificationSession
La VerificationSession est l'objet unique que vous créez par tentative de vérification d'utilisateur. Il contrôle les types de documents acceptés, si un selfie est requis et quels champs sont renvoyés à votre backend.
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"
Avec le SDK Node :
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" },
});
// Send one of these to the client:
// session.url -> hosted redirect
// session.client_secret -> Stripe.js embedded component
Quelques champs méritent une attention particulière. type: "document" indique à Stripe d'effectuer une vérification de document ; l'alternative, id_number, effectue une recherche de type SSN uniquement aux États-Unis sans collecter de pièce d'identité. allowed_types restreint les catégories de documents que l'utilisateur peut télécharger, ce qui est important pour les programmes de conformité qui n'acceptent que les pièces d'identité gouvernementales avec photo. verified_outputs est la liste des champs que vous souhaitez voir renvoyés ; Stripe n'exposera aucune donnée que vous n'avez pas demandée, ce qui maintient votre approche de minimisation des données propre.
Redirection de vérification hébergée vs. Stripe.js intégré
Stripe vous propose deux formes d'intégration. La redirection hébergée est le chemin le plus rapide : envoyez l'utilisateur à session.url, Stripe gère toute l'expérience de capture sur un domaine stripe.com, et l'utilisateur est renvoyé vers votre return_url. Vous écrivez environ dix lignes de code.
Le flux intégré utilise Stripe.js et le paquet @stripe/stripe-js pour monter un modal de vérification dans votre propre application. Vous transmettez session.client_secret au frontend et appelez stripe.verifyIdentity(clientSecret). Cela maintient les utilisateurs dans votre produit et vous donne le contrôle du design de la page environnante. Choisissez-le lorsque la vérification se produit au milieu d'un flux d'inscription ou d'une étape KYC ; choisissez la redirection lorsque la vérification est une tâche discrète.
Webhooks
Ne comptez jamais sur la redirection client pour vous informer qu'une vérification a réussi ; confirmez toujours sur le backend via les webhooks. Enregistrez un point de terminaison dans Tableau de bord > Développeurs > Webhooks et abonnez-vous à :
identity.verification_session.verifiedse déclenche lorsque toutes les vérifications passent et que les données vérifiées sont prêtes.identity.verification_session.requires_inputse déclenche lorsque l'utilisateur échoue à une vérification ou télécharge un document illisible. Vous pouvez le rediriger pour qu'il réessaie.identity.verification_session.processingse déclenche pendant que Stripe exécute des vérifications asynchrones ; utile pour afficher des états de chargement.identity.verification_session.canceledse déclenche si vous annulez la session par programmation.
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
La charge utile du webhook vous indique que la session a été vérifiée, mais elle n'inclut pas les champs sensibles. Pour lire les sorties vérifiées, appelez verificationSessions.retrieve avec expand: ["verified_outputs"] :
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
Stripe ne renvoie le id_number qu'une seule fois ; stockez-le immédiatement chiffré de votre côté. Les images des documents elles-mêmes restent dans le coffre-fort de Stripe et sont accessibles via le tableau de bord pour audit.
Erreurs courantes et limites de débit
L'échec le plus fréquent est verification_session.requires_input avec un code comme document_unverified_other ou selfie_face_mismatch. Gérez ces cas en affichant une interface de réessai conviviale ; la même session peut être réutilisée en appelant verificationSessions.cancel et en en créant une nouvelle, ou en redirigeant vers la même session.url tant qu'elle est encore ouverte.
Stripe applique des limites de débit API standard de 100 requêtes par seconde en mode live et 25 par seconde en mode test. Les points de terminaison /identity/verification_sessions relèvent de la même catégorie que le reste de l'API. Si vous atteignez les limites, vous verrez HTTP 429 avec un en-tête Retry-After ; utilisez la reprise exponentielle et respectez l'en-tête.
Autres erreurs à surveiller : unsupported_document_type lorsque l'utilisateur télécharge une pièce d'identité en dehors de votre liste allowed_types, et country_not_supported lorsque quelqu'un essaie un document d'un pays que Stripe Identity ne couvre pas encore.
Tarification de Stripe Identity
Stripe Identity coûte 1,50 $ par vérification aux États-Unis. Les prix internationaux varient ; la plupart des pays européens se situent entre 1,50 $ et 2,00 $, et Stripe publie le détail complet par pays sur sa page de tarification. Une tentative de vérification qui se termine par requires_input ne compte pas comme un événement facturable ; seules les sessions verified terminées sont facturées.
Pour les clients à fort volume, Stripe propose une tarification personnalisée qui peut réduire considérablement les frais par vérification. Si vous traitez plus de 10 000 vérifications par mois, contactez le service commercial.
Tester Stripe Identity avec Apidog
Les environnements de test d'API sont toujours préférables aux commandes curl manuelles, surtout lorsque vous itérez sur les charges utiles des webhooks. Apidog importe directement la spécification OpenAPI de Stripe, de sorte que chaque champ de l'objet VerificationSession apparaît avec une documentation intégrée. Vous pouvez envoyer de vraies requêtes à l'environnement de test de Stripe, inspecter la réponse et la rejouer autant de fois que nécessaire.
Le côté test des webhooks est là où Apidog fait gagner le plus de temps. Vous pouvez simuler des événements identity.verification_session.verified localement, les envoyer à votre serveur de développement et parcourir votre gestionnaire sans avoir besoin qu'une vraie vérification soit terminée. Si vous comparez des workflows, notre guide sur les tests d'API sans Postman en 2026 propose une explication plus approfondie. Téléchargez Apidog pour obtenir le client de bureau.
FAQ
Quelle est la différence entre Stripe Identity et le KYC régulier de Stripe ? Le KYC intégré de Stripe vérifie les propriétaires d'entreprise pour les comptes Connect et Paiements. Stripe Identity est une API autonome pour vérifier vos utilisateurs finaux ; les deux systèmes ne partagent pas les résultats de vérification.
Puis-je réutiliser une identité vérifiée pour plusieurs sessions ? Oui. Une fois qu'une session est vérifiée, les verified_outputs sont permanentes sur cet objet de session. Si vous devez revérifier pour un nouvel événement, créez une nouvelle session et liez-la à l'enregistrement de l'utilisateur de votre côté.
Stripe Identity fonctionne-t-il en dehors des paiements ? Absolument. De nombreux clients l'utilisent purement comme une couche KYC et ne touchent jamais à la surface de paiement de Stripe. Si vous avez besoin d'un filtrage des sanctions plus large en plus de la vérification d'identité, associez-le à une API de filtrage AML dédiée.
Comment Stripe Identity se compare-t-il à Plaid Identity Verification ? Stripe se concentre sur le document et le selfie ; Plaid s'appuie sur les données d'identité vérifiées par la banque. Consultez notre guide de l'API Plaid pour l'autre approche.
La détection de vivacité par selfie est-elle obligatoire ? Non. Définissez options.document.require_matching_selfie sur false si vous n'avez besoin que d'une vérification de document. La plupart des équipes de lutte contre la fraude la maintiennent activée, car la détection de vivacité passive permet de contrer de nombreuses attaques de faible effort.
Quels pays sont couverts par Stripe Identity ? Plus de 35 pays en Amérique du Nord, en Europe et dans certaines régions d'Asie-Pacifique, avec des analyseurs de documents localisés pour chacun. Stripe publie la liste des pays en direct dans sa documentation et ajoute régulièrement de nouveaux marchés.