Verificar la identidad real de un usuario es una de esas tareas que parecen sencillas en una pizarra y se convierten en un proyecto de meses en el momento en que se empieza a construir. Necesitas captura de documentos, OCR, coincidencia facial, detección de vida, señales de fraude y cobertura para docenas de tipos de identificación en diferentes países. La API de Stripe Identity agrupa todo esto en una única integración, para que puedas implementar un flujo de verificación de identidad listo para producción en una tarde en lugar de un trimestre.
Esta guía te acompaña a través de cada paso que un desarrollador necesita para implementar Stripe Identity: habilitarlo en el panel de control, crear una VerificationSession, elegir entre el redireccionamiento alojado y el componente incrustado de Stripe.js, manejar los webhooks y leer las salidas verificadas. Verás ejemplos de curl y Node, patrones de manejo de errores y cómo probar todo el flujo localmente con Apidog. Si estás evaluando alternativas primero, echa un vistazo a nuestro resumen de las mejores API de KYC antes de comprometerte.
Stripe Identity es un ajuste natural para los equipos que ya usan Stripe para pagos, pero también funciona como un producto independiente. La documentación oficial de Stripe Identity cubre la superficie del producto, y esta publicación llena los vacíos de la experiencia del desarrollador: qué sucede en la conexión, qué campos importan y dónde se encuentran los errores comunes.
TL;DR
- Stripe Identity verifica a los usuarios con una identificación gubernamental más una verificación de vida con selfie; el precio comienza en $1.50 por verificación en los EE. UU.
- La primitiva central es el objeto
VerificationSession; creas uno en el lado del servidor, luego rediriges al usuario o montas el componente Stripe.js. - Solicita los campos que necesites a través de
options.document.require_matching_selfie,require_id_numberyallowed_types. - Escucha los webhooks
identity.verification_session.verifiedyidentity.verification_session.requires_inputpara impulsar el estado de tu aplicación. - Las salidas verificadas (nombre, fecha de nacimiento, dirección, número de identificación) solo se exponen cuando configuras
verified_outputsal crear la sesión. - Stripe Identity cubre más de 35 países con soporte de documentos localizado.
¿Qué es la API de Stripe Identity?
Stripe Identity es un producto de verificación de identidad construido sobre la superficie de la API principal de Stripe. Te ofrece una única familia de endpoints (/v1/identity/verification_sessions) que orquesta la captura de documentos, la extracción de datos, la coincidencia facial y la puntuación de fraude. El resultado es un registro estructurado y firmado en el que puedes confiar: un nombre completo verificado, fecha de nacimiento, dirección y número de identificación opcional, junto con las imágenes del documento original almacenadas en la bóveda de Stripe.
Internamente, Stripe utiliza el mismo patrón de sesión más webhook que ya conoces de Checkout y Payment Intents. Creas una sesión en el lado del servidor, Stripe maneja la interfaz de usuario de captura orientada al usuario y se te notifica cuando el resultado está listo. Si has creado un flujo de Checkout antes, Identity te resultará familiar en cuestión de minutos.
Autenticación y configuración
Antes de llamar a la API, activa Stripe Identity en el panel de control. Ve a Panel de control > Configuración > Identidad, acepta los términos y rellena los detalles del negocio que Stripe necesita para el cumplimiento de KYC por su parte. El interruptor activa Identity tanto para el modo de prueba como para el modo en vivo en tu cuenta.
La autenticación utiliza tu clave secreta estándar de Stripe. Las claves de prueba comienzan con sk_test_, y las claves en vivo comienzan con sk_live_. Stripe Identity no requiere una credencial separada, lo que mantiene la superficie de integración pequeña.
Instala el SDK de Node:
npm install stripe
Luego inicializa un cliente. Fija la versión de la API para que Stripe nunca te sorprenda con un cambio de esquema:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
Ahora puedes llamar a todos los endpoints bajo stripe.identity.verificationSessions.
Endpoints principales
Creando una VerificationSession
La VerificationSession es el único objeto que creas por cada intento de verificación de usuario. Controla qué tipos de documentos se aceptan, si se requiere una selfie y qué campos se devuelven a tu backend.
Con 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"
Con el SDK de 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
Algunos campos merecen atención. type: "document" le dice a Stripe que realice una verificación de documento; la alternativa, id_number, realiza una búsqueda de tipo SSN solo en EE. UU. sin recopilar una identificación. allowed_types restringe qué categorías de documentos puede cargar el usuario, lo cual es importante para los programas de cumplimiento que solo aceptan identificación con foto emitida por el gobierno. verified_outputs es la lista de campos permitidos que deseas que se devuelvan; Stripe no expondrá ningún dato que no hayas solicitado, lo que mantiene tu postura de minimización de datos limpia.
Redirección de verificación alojada vs. Stripe.js incrustado
Stripe te ofrece dos formas de integración. La redirección alojada es el camino más rápido: envía al usuario a session.url, Stripe maneja toda la experiencia de captura en un dominio de stripe.com, y el usuario regresa a tu return_url. Escribes aproximadamente diez líneas de código.
El flujo incrustado utiliza Stripe.js y el paquete @stripe/stripe-js para montar un modal de verificación dentro de tu propia aplicación. Pasas session.client_secret al frontend y llamas a stripe.verifyIdentity(clientSecret). Esto mantiene a los usuarios en tu producto y te da control de diseño sobre la página circundante. Elígelo cuando la verificación ocurra a mitad de flujo en un paso de registro o KYC; elige la redirección cuando la verificación sea una tarea discreta.
Webhooks
Nunca confíes en el redireccionamiento del cliente para saber si una verificación tuvo éxito; siempre confirma en el backend a través de webhooks. Registra un endpoint en Dashboard > Desarrolladores > Webhooks y suscríbete a:
identity.verification_session.verifiedse activa cuando todas las comprobaciones pasan y los datos verificados están listos.identity.verification_session.requires_inputse activa cuando el usuario falla una comprobación o carga un documento ilegible. Puedes redirigirlos para que lo intenten de nuevo.identity.verification_session.processingse activa mientras Stripe ejecuta comprobaciones asincrónicas; útil para mostrar estados de carga.identity.verification_session.canceledse activa si cancelas la sesión mediante programación.
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 });
});
Recuperando salidas verificadas
La carga útil del webhook te dice que la sesión fue verificada, pero no incluye los campos sensibles. Para leer las salidas verificadas, llama a verificationSessions.retrieve con 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 devuelve el id_number solo una vez; guárdalo cifrado de inmediato por tu parte. Las imágenes del documento en sí permanecen en la bóveda de Stripe y son accesibles a través del panel de control para auditoría.
Errores comunes y límites de tasa
El fallo más frecuente es verification_session.requires_input con un código como document_unverified_other o selfie_face_mismatch. Maneja estos errores mostrando una interfaz de usuario amigable para reintentar; la misma sesión puede ser reutilizada llamando a verificationSessions.cancel y creando una nueva, o redirigiendo a la misma session.url mientras aún esté abierta.
Stripe aplica límites de tasa de API estándar de 100 solicitudes por segundo en modo en vivo y 25 por segundo en modo de prueba. Los endpoints /identity/verification_sessions caen bajo el mismo cubo que el resto de la API. Si alcanzas los límites, verás HTTP 429 con un encabezado Retry-After; utiliza la retirada exponencial y respeta el encabezado.
Otros errores a tener en cuenta: unsupported_document_type cuando el usuario carga una identificación fuera de tu lista de allowed_types, y country_not_supported cuando alguien intenta un documento de uno de los países que Stripe Identity aún no cubre.
Precios de Stripe Identity
Stripe Identity cuesta $1.50 por verificación en los Estados Unidos. Los precios internacionales varían; la mayoría de los países europeos rondan entre $1.50 y $2.00, y Stripe publica el desglose completo por país en su página de precios. Un intento de verificación que termina en requires_input no cuenta como un evento facturable; solo las sesiones completadas verified se facturan.
Para clientes de alto volumen, Stripe ofrece precios personalizados que pueden reducir significativamente la tarifa por verificación. Si procesas más de 10,000 verificaciones al mes, habla con el equipo de ventas.
Probando Stripe Identity con Apidog
Los entornos de pruebas de API siempre superan a los comandos curl manuales, especialmente cuando estás iterando sobre cargas útiles de webhook. Apidog importa la especificación OpenAPI de Stripe directamente, por lo que cada campo del objeto VerificationSession aparece con documentación en línea. Puedes enviar solicitudes reales al entorno de prueba de Stripe, inspeccionar la respuesta y reproducirla tantas veces como sea necesario.
La parte de prueba de webhooks es donde Apidog ahorra más tiempo. Puedes simular eventos identity.verification_session.verified localmente, enviarlos a tu servidor de desarrollo y recorrer tu manejador sin necesidad de completar una verificación real. Si estás comparando flujos de trabajo, nuestra guía sobre pruebas de API sin Postman en 2026 tiene un recorrido más profundo. Descarga Apidog para obtener el cliente de escritorio.
Preguntas frecuentes
¿Cuál es la diferencia entre Stripe Identity y el KYC regular de Stripe? El KYC incorporado de Stripe verifica a los propietarios de negocios para las cuentas de Connect y Pagos. Stripe Identity es una API independiente para verificar a tus usuarios finales; los dos sistemas no comparten los resultados de la verificación.
¿Puedo reutilizar una identidad verificada en varias sesiones? Sí. Una vez que una sesión es verificada, las verified_outputs son permanentes en ese objeto de sesión. Si necesitas volver a verificar para un nuevo evento, crea una nueva sesión y vincúlala al registro de usuario por tu parte.
¿Funciona Stripe Identity fuera de los pagos? Absolutamente. Muchos clientes lo utilizan puramente como una capa de KYC y nunca tocan la superficie de pagos de Stripe. Si necesitas un cribado de sanciones más amplio además de la verificación de identidad, combínalo con una API de cribado AML dedicada.
¿Cómo se compara Stripe Identity con Plaid Identity Verification? Stripe se centra en el documento más la selfie; Plaid se inclina hacia los datos de identidad verificados por el banco. Consulta nuestra guía de la API de Plaid para el otro enfoque.
¿Es obligatoria la detección de vida con selfie? No. Establece options.document.require_matching_selfie en false si solo necesitas una verificación de documento. La mayoría de los equipos de fraude lo mantienen activado, porque la detección de vida pasiva detecta muchos ataques de bajo esfuerzo.
¿Qué países cubre Stripe Identity? Más de 35 países en América del Norte, Europa y partes de Asia-Pacífico, con analizadores de documentos localizados para cada uno. Stripe publica la lista de países en vivo en su documentación y agrega nuevos mercados regularmente.