Cómo Usar la API de Stripe Identity: Guía para Desarrolladores sobre Verificación de Identidad

Verificar la identidad real de un usuario puede parecer simple en teoría, pero la implementación requiere captura de documentos, OCR, coincidencia facial, detección de vida, señales de fraude y soporte para muchos tipos de identificación en varios países. Stripe Identity reúne todo esto en una integración lista para producción que puedes desplegar en una tarde.

Prueba Apidog hoy

Esta guía cubre paso a paso cómo implementar Stripe Identity: habilitación en el panel, creación de una VerificationSession, opciones de integración (redirección alojada o Stripe.js embebido), manejo de webhooks y lectura de resultados verificados. Incluye ejemplos en curl y Node, gestión de errores y pruebas locales con Apidog. Si buscas alternativas, revisa nuestro resumen de las mejores API de KYC.

Stripe Identity es ideal para quienes ya usan Stripe, pero funciona también como producto independiente. La documentación oficial cubre lo básico; aquí profundizamos en la experiencia real de implementación: cómo conectar, campos clave y errores comunes.

TL;DR

• Stripe Identity verifica usuarios con documento oficial y selfie; desde $1.50 por verificación en EE. UU.
• El objeto central es VerificationSession: créalo en backend, luego redirige al usuario o integra Stripe.js.
• Solicita campos con options.document.require_matching_selfie, require_id_number y allowed_types.
• Usa webhooks identity.verification_session.verified y identity.verification_session.requires_input para actualizar el estado.
• Los datos verificados (verified_outputs) solo se exponen si los defines explícitamente.
• Soporta más de 35 países y documentos localizados.

¿Qué es la API de Stripe Identity?

Stripe Identity es una solución de verificación sobre la API principal de Stripe. Ofrece endpoints bajo /v1/identity/verification_sessions para captura de documentos, extracción de datos, coincidencia facial y scoring de fraude. El resultado es un registro firmado: nombre verificado, fecha de nacimiento, dirección, número de identificación y las imágenes del documento (almacenadas en Stripe).

El patrón sigue el modelo de sesión más webhook: creas la sesión en backend, Stripe gestiona la UI para el usuario, y recibes notificaciones cuando el proceso termina. Si ya usaste Checkout, te resultará familiar.

Autenticación y configuración

Antes de usar la API, habilita Stripe Identity en el panel:

1. Ve a Panel de control > Configuración > Identidad.
2. Acepta los términos y completa los datos de tu negocio.

Esto activa Identity en modo prueba y producción.

La autenticación usa tu clave secreta de Stripe (empieza con sk_test_ o sk_live_). No necesitas credenciales adicionales.

Instala el SDK de Node:

npm install stripe

Inicializa el cliente especificando la versión de la API:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

Ahora puedes usar todos los endpoints en stripe.identity.verificationSessions.

Endpoints principales

Creando una VerificationSession

VerificationSession es el objeto que representa cada intento de verificación. Define tipos de documento aceptados, si se requiere selfie y qué campos se devolverán.

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 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" },
});

// Para el cliente usa uno de estos:
// session.url              -> redirección alojada
// session.client_secret    -> componente incrustado Stripe.js

Puntos clave:

• type: "document" activa verificación con documento. Alternativa: id_number para validación tipo SSN en EE. UU.
• allowed_types restringe los documentos aceptados.
• verified_outputs controla los campos que recibirás: solo se exponen los que pidas.

Redirección alojada vs Stripe.js incrustado

Tienes dos opciones de integración:

• Redirección alojada: Envía al usuario a session.url (dominio de Stripe), Stripe gestiona la experiencia y retorna a tu return_url.
• Stripe.js incrustado: Usa el paquete @stripe/stripe-js, pasa session.client_secret al frontend y llama a stripe.verifyIdentity(clientSecret). El usuario se queda en tu app.

Usa redirección para flujos simples; Stripe.js para experiencias integradas (ej. onboarding).

Webhooks

No confíes solo en el frontend para saber si la verificación fue exitosa. Configura webhooks en Dashboard > Desarrolladores > Webhooks y escucha:

• identity.verification_session.verified: sesión verificada y datos listos.
• identity.verification_session.requires_input: error en la verificación, pide reintento.
• identity.verification_session.processing: Stripe está procesando.
• identity.verification_session.canceled: sesión cancelada.

Ejemplo en Express:

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

Para acceder a los datos verificados, haz un 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;

El id_number solo se devuelve una vez; guárdalo cifrado. Las imágenes del documento se mantienen en Stripe para auditoría.

Errores comunes y límites de tasa

Errores frecuentes:

• verification_session.requires_input con códigos como document_unverified_other o selfie_face_mismatch. Permite reintento al usuario.
• Reutiliza la sesión cancelando y creando una nueva, o redirige al usuario mientras la sesión siga activa.
• Stripe limita la API a 100 req/s en producción y 25 req/s en test; si excedes, responde HTTP 429 con Retry-After.
• Otros errores: unsupported_document_type (documento no permitido) y country_not_supported (país no soportado).

Precios de Stripe Identity

• $1.50 por verificación en EE. UU.
• Precios internacionales varían ($1.50-$2.00 en Europa).
• Solo las sesiones completadas (verified) se cobran; los intentos fallidos no.
• Para volúmenes altos (>10,000/mes), consulta precios personalizados con Stripe.

Probando Stripe Identity con Apidog

Usar un entorno dedicado supera a los comandos curl, especialmente para pruebas de webhooks. Apidog importa la especificación OpenAPI de Stripe, mostrando cada campo documentado. Puedes enviar peticiones reales al entorno de pruebas de Stripe y revisar las respuestas.

Para pruebas con webhooks, Apidog permite simular eventos como identity.verification_session.verified localmente y enviarlos a tu servidor de desarrollo, facilitando el testing de tus manejadores sin completar una verificación real. Si comparas flujos, consulta la guía sobre pruebas de API sin Postman en 2026. Descarga Apidog para el cliente de escritorio.

Preguntas frecuentes

¿Cuál es la diferencia entre Stripe Identity y el KYC regular de Stripe?

El KYC de Stripe verifica propietarios de negocios para cuentas Connect y Pagos. Stripe Identity es una API para verificar usuarios finales; los resultados no se comparten entre sistemas.

¿Puedo reutilizar una identidad verificada en varias sesiones?

Sí, los verified_outputs permanecen en la sesión. Si necesitas otra verificación, crea una nueva sesión y relaciónala a tu usuario.

¿Funciona Stripe Identity fuera de pagos?

Sí. Muchos lo usan solo como capa de KYC, sin procesar pagos. Para cribado AML adicional, combínalo con una API de cribado AML.

¿Cómo se compara Stripe Identity con Plaid Identity Verification?

Stripe se basa en documento + selfie; Plaid utiliza datos bancarios verificados. Consulta la guía de la API de Plaid para ese enfoque.

¿Es obligatoria la detección de vida con selfie?

No. Puedes poner options.document.require_matching_selfie en false. Sin embargo, normalmente es recomendable mantenerlo activado.

¿Qué países cubre Stripe Identity?

Más de 35 países en América del Norte, Europa y Asia-Pacífico, con soporte localizado. Stripe publica la lista actualizada en su documentación.