Configuración Completa de Stripe para SaaS

Guía paso a paso para integrar Stripe en tu aplicación SaaS, desde la creación de la cuenta hasta la implementación de pagos recurrentes, suscripciones y webhooks.

18 min de lectura

Por Equipo 10xDev

Esta guía te llevará paso a paso a través del proceso de integrar Stripe en tu aplicación SaaS, permitiéndote aceptar pagos de tus usuarios. Cubriremos desde la creación de la cuenta hasta la realización de la primera compra en modo de prueba.

Fase 1: Creación y Configuración Inicial de la Cuenta Stripe

1 Registro en Stripe:

Ve a https://dashboard.stripe.com/register.
Completa el formulario con tu correo electrónico, nombre completo y crea una contraseña segura.
Haz clic en "Crear cuenta".
Verifica tu dirección de correo electrónico haciendo clic en el enlace que Stripe te enviará.

2 Activación de la Cuenta (Creación de la Empresa):

Una vez dentro del Dashboard de Stripe, verás un aviso para "Activar tu cuenta" o similar. Este paso es esencial para procesar pagos reales (Live Mode), aunque puedes empezar a integrar y probar en Test Mode sin completarlo al 100% inmediatamente.
Información del Negocio: Deberás proporcionar detalles sobre tu empresa (país, tipo de entidad - autónomo, sociedad limitada, etc., dirección fiscal, número de identificación fiscal si aplica).
Información del Representante: Datos de la persona que opera la cuenta.
Detalles del Negocio: Descripción de tu SaaS, sitio web (puede ser uno provisional si aún no está público), y cómo entregarás el servicio.
Datos Bancarios: La cuenta bancaria donde Stripe depositará los fondos recaudados. Asegúrate de que sea una cuenta a nombre de la entidad o persona registrada.
Verificación: Stripe puede solicitar documentación adicional para verificar tu identidad y la de tu negocio (DNI, pasaporte, escrituras, etc.). Este proceso es estándar para cumplir con regulaciones financieras (KYC - Know Your Customer).

3 Obtención de Claves API (API Keys):

En el Dashboard, ve a la sección "Desarrolladores" (Developers) en el menú lateral izquierdo.
Haz clic en "Claves de API" (API Keys).
Aquí encontrarás dos tipos de claves importantes:
- Clave Publicable (Publishable Key): Empieza con pk_test_... (para modo prueba) o pk_live_... (para modo real). Esta clave se usa en el frontend (tu aplicación web/móvil) de forma segura.
- Clave Secreta (Secret Key): Empieza con sk_test_... (para modo prueba) o sk_live_... (para modo real). ¡NUNCA expongas esta clave en el frontend ni en código de acceso público! Se usa exclusivamente en tu backend (servidor). Haz clic en "Revelar clave de prueba/producción" para verla y copiarla.
IMPORTANTE: Por ahora, copia y guarda de forma segura ambas claves de Modo de Prueba (Test Mode). Asegúrate de que el interruptor "Ver datos de prueba" (View test data) esté activado en el Dashboard.

Fase 2: Configuración de Productos y Precios

Stripe modela lo que vendes como Products (Productos) y cómo los cobras como Prices (Precios). Para un SaaS, típicamente tendrás productos que representan tus diferentes planes (Básico, Pro, Empresa) y precios que definen el coste y la recurrencia (mensual, anual).

1 Crear un Producto:

En el Dashboard (asegúrate de estar en Modo Prueba), ve a "Productos" (Products) en el menú.
Haz clic en "+ Añadir producto" (Add product).
Nombre: Dale un nombre descriptivo a tu plan (ej: "Plan Pro SaaS").
Descripción (Opcional): Añade detalles sobre lo que incluye el plan.
(Opcional) Imagen, Metadatos: Puedes añadir más detalles si lo deseas.
Haz clic en "Guardar producto".

2 Añadir un Precio a ese Producto:

Una vez guardado el producto, serás redirigido a su página. Busca la sección "Precios" (Pricing) y haz clic en "+ Añadir otro precio" (Add another price).
Modelo de precios: Selecciona "Estándar" (Standard) o el que más se ajuste. Para SaaS, lo común es "Estándar".
Importe: Introduce el coste del plan (ej: 29.99).
Moneda: Selecciona la moneda (ej: EUR, USD).
Período de facturación (Billing period): Selecciona "Recurrente" (Recurring).
Intervalo: Elige la frecuencia (ej: "Mensual" - Monthly, "Anual" - Yearly).
(Opcional) ID de Precio: Puedes dejar que Stripe genere uno o poner uno personalizado (útil para referenciarlo fácilmente en tu código).
Haz clic en "Añadir precio".
IMPORTANTE: Copia el ID del Precio (Price ID) que se genera (empieza por price_...). Lo necesitarás en tu código para iniciar el checkout.

3 Repite: Crea todos los productos (planes) y sus correspondientes precios (mensuales/anuales) que ofrezcas.

Fase 3: Integración de Stripe Checkout (Flujo de Pago)

Stripe Checkout es una página de pago preconstruida y alojada por Stripe, ideal para empezar rápido y cumplir con normativas de seguridad (PCI DSS).

1 Instalar la Librería de Stripe en tu Backend:

Necesitarás la librería oficial de Stripe para tu lenguaje de backend (Node.js, Python, PHP, Ruby, Java, .NET, Go).
Ejemplo para Node.js: npm install stripe o yarn add stripe
Ejemplo para Python: pip install stripe

2 Configurar la Clave Secreta en tu Backend:

Inicializa la librería Stripe con tu Clave Secreta de Prueba (sk_test_...). La mejor práctica es guardarla en variables de entorno, no directamente en el código.
Ejemplo (Node.js):
Ejemplo (Python - Flask/Django):

3 Crear un Endpoint en tu Backend para Iniciar el Checkout:

Necesitas una ruta en tu servidor (ej: /create-checkout-session) que reciba una solicitud (normalmente POST) cuando un usuario quiera suscribirse.
Esta ruta usará la librería Stripe para crear una Checkout Session.
Ejemplo (Node.js con Express):
Claves:
- line_items: Define qué se está comprando (usando el Price ID).
- mode: 'subscription' para pagos recurrentes, 'payment' para pagos únicos.
- success_url: Página de tu app a la que Stripe redirige si el pago es exitoso. Incluye {CHECKOUT_SESSION_ID} para poder recuperar detalles de la sesión si es necesario.
- cancel_url: Página de tu app si el usuario cancela el pago.

4 Implementar el Frontend para Redirigir a Checkout:

Necesitas la librería Stripe.js en tu frontend. Inclúyela mediante un script tag o instálala si usas un framework JS (React, Vue, Angular).
Inicializa Stripe.js con tu Clave Publicable de Prueba (pk_test_...).
Cuando el usuario haga clic en un botón "Suscribirse":
- Haz una petición (fetch/axios) a tu endpoint de backend (/create-checkout-session), enviando el Price ID del plan seleccionado.
- Recibe el sessionId de la respuesta del backend.
- Usa stripe.redirectToCheckout({ sessionId: sessionId }) para redirigir al usuario a la página de pago de Stripe.

Fase 4: Configuración y Manejo de Webhooks

Los webhooks son esenciales. Stripe te notifica asincrónicamente sobre eventos que ocurren en tu cuenta (pago exitoso, fallo, suscripción cancelada, etc.) No debes depender únicamente de la redirección success_url para confirmar un pago y dar acceso, ya que el usuario podría cerrar la ventana antes de ser redirigido.

1 Crear un Endpoint de Webhook en tu Backend:

Crea una nueva ruta en tu servidor (ej: /stripe-webhook) que acepte peticiones POST de Stripe.
Este endpoint recibirá los eventos.

2 Configurar el Webhook en el Dashboard de Stripe:

Ve a "Desarrolladores" -> "Webhooks".
Haz clic en "+ Añadir un endpoint" (Add an endpoint).
URL del endpoint: Introduce la URL pública de tu endpoint de webhook (ej: https://tu-saas.com/stripe-webhook). Para desarrollo local, necesitarás una herramienta como ngrok o la Stripe CLI para exponer tu endpoint local a internet o simular eventos.
Eventos a escuchar: Selecciona los eventos que te interesan. Para empezar con suscripciones, los cruciales son:
- checkout.session.completed: Ocurre cuando el usuario completa el pago en la página de Checkout Este es el evento clave para aprovisionar el servicio.
- invoice.paid: Ocurre cuando una factura de suscripción se paga correctamente (incluye renovaciones).
- invoice.payment_failed: Ocurre si falla el pago de una factura (ej: tarjeta caducada). Puedes usar esto para notificar al usuario o restringir el acceso.
- customer.subscription.deleted: Ocurre cuando una suscripción es cancelada (por el usuario desde el portal o por ti). Úsalo para revocar el acceso.
- customer.subscription.updated: Cambios en la suscripción (ej: cambio de plan).
Haz clic en "Añadir endpoint".

3 Obtener el Secreto de Firma del Webhook (Webhook Signing Secret):

Una vez creado el endpoint en el Dashboard, haz clic en él.
Busca la sección "Secreto de firma" (Signing secret) y haz clic en "Revelar".
Copia este secreto (empieza con whsec_...). Guárdalo de forma segura en las variables de entorno de tu backend Es específico para cada endpoint.

4 Implementar la Lógica del Manejador de Webhooks en tu Backend:

En tu endpoint /stripe-webhook:
- Verificar la Firma: ¡CRUCIAL para seguridad! Asegúrate de que la petición realmente viene de Stripe. Usa la librería de Stripe y el Secreto de Firma. Si la firma no es válida, ignora la petición (devuelve un error 400).
- Parsear el Evento: El cuerpo de la petición es un objeto JSON de evento Stripe.
- Manejar el Evento: Usa un switch o if/else if sobre event.type para ejecutar la lógica adecuada:
  - Si event.type === 'checkout.session.completed':
    - Obtén el objeto session de event.data.object.
    - Extrae información relevante como session.customer (ID del cliente Stripe) y session.subscription (ID de la suscripción Stripe).
    - Busca al usuario en tu base de datos (quizás usando el client_reference_id que puedes pasar al crear la sesión de checkout, o el email si lo asociaste).
    - Actualiza el estado del usuario en tu base de datos: marca la suscripción como activa, guarda el customer_id y subscription_id de Stripe, establece la fecha de fin del periodo actual (current_period_end de la suscripción, que puedes obtener haciendo un fetch a la API de Stripe con el subscription_id). Concede acceso a las funciones premium del plan comprado.
  - Si event.type === 'invoice.paid':
    - Obtén el objeto invoice de event.data.object.
    - Actualiza la fecha de fin del periodo actual (current_period_end) en tu base de datos para el usuario asociado a invoice.customer y invoice.subscription. Asegura que el acceso continúe.
  - Si event.type === 'invoice.payment_failed':
    - Notifica al usuario. Puedes empezar un periodo de gracia o restringir el acceso según tu política.
  - Si event.type === 'customer.subscription.deleted':
    - Obtén el objeto subscription de event.data.object.
    - Busca al usuario asociado a subscription.customer.
    - Marca la suscripción como cancelada en tu base de datos y revoca el acceso a las funciones premium (quizás al final del periodo ya pagado).
- Responder a Stripe: ¡IMPORTANTE! Debes devolver una respuesta 200 OK a Stripe lo antes posible para confirmar que recibiste el evento. Si no lo haces, Stripe reintentará enviar el evento varias veces Realiza las operaciones que consuman tiempo (como llamadas a otras APIs o tareas pesadas) de forma asíncrona (ej: en una cola de trabajos) después de enviar la respuesta 200.
Ejemplo (Node.js con Express, verificación básica):

Fase 5: Prueba del Webhook Localmente

Antes de desplegar, prueba tu endpoint de webhook localmente.

1 Usando la Stripe CLI:

Instala la Stripe CLI: Sigue las instrucciones en https://stripe.com/docs/stripe-cli.
Inicia sesión: Abre tu terminal y ejecuta stripe login. Sigue las instrucciones en el navegador.
Reenvía eventos: Ejecuta tu servidor local. Luego, en la terminal, ejecuta:
La CLI te dará un nuevo secreto de firma de webhook temporal (diferente al del Dashboard) para usar solo durante esta sesión de listen. Asegúrate de configurar tu variable de entorno STRIPE_WEBHOOK_SECRET con este valor temporal mientras pruebas.
Ahora, realiza acciones en tu aplicación (como completar un checkout en modo prueba). Verás los eventos llegar a tu terminal y ser reenviados a tu servidor local. Depura tu lógica de manejo de webhooks.
También puedes disparar eventos manualmente con la CLI: stripe trigger checkout.session.completed

2 Usando Herramientas como Ngrok (Alternativa):

Instala ngrok (https://ngrok.com/).
Ejecuta tu servidor local.
En la terminal, ejecuta ngrok http 3000 (reemplaza 3000 por tu puerto).
Ngrok te dará una URL pública (ej: https://abcd-1234.ngrok.io).
Ve al Dashboard de Stripe -> Desarrolladores -> Webhooks. Edita tu endpoint de prueba y pega la URL de ngrok seguida de tu ruta (ej: https://abcd-1234.ngrok.io/stripe-webhook). Usa el secreto de firma del Dashboard.
Realiza acciones en tu app; los eventos llegarán a tu servidor local a través de ngrok.

Fase 6: Configuración del Portal del Cliente (Customer Portal)

El Portal del Cliente de Stripe permite a tus usuarios gestionar sus suscripciones (actualizar método de pago, cancelar suscripción, ver historial de facturas) sin que tengas que construir esa interfaz tú mismo.

1 Configurar el Portal en el Dashboard:

Ve a "Configuración" (Settings) -> "Billing" -> "Portal del cliente" (Customer portal).
Personalización: Ajusta los colores y logo para que coincidan con tu marca.
Funcionalidades: Elige qué pueden hacer los usuarios:
- Actualizar métodos de pago (Recomendado).
- Cancelar suscripciones (Decide si permitir cancelación inmediata o al final del periodo. Añade un flujo de retención si quieres).
- Ver historial de facturas (Recomendado).
- Actualizar datos de facturación.
- Cambiar de plan (Pausar/Reanudar suscripciones - opcional).
Políticas: Enlaza a tus términos de servicio y política de privacidad.
Guarda la configuración.

2 Integrar el Acceso al Portal en tu Aplicación:

Necesitas un endpoint en tu backend para crear una sesión del Portal del Cliente.
Ejemplo (Node.js con Express):
En tu frontend (ej: en la página de configuración de cuenta del usuario):
- Añade un botón o enlace "Gestionar Suscripción" / "Administrar Facturación".
- Al hacer clic, haz una petición a tu endpoint /create-portal-session (asegúrate de enviar el customerId de Stripe correcto).
- Recibe la url de la sesión del portal.
- Redirige al usuario a esa URL: window.location.href = portalSessionUrl;

Fase 7: Pruebas End-to-End (Modo Prueba)

Ahora, junta todo y prueba el flujo completo en Modo de Prueba:

1 Asegúrate: Estás usando las claves API de Prueba (pk_test_..., sk_test_...) y el secreto de firma de Webhook de Prueba (whsec_... del Dashboard o el temporal de la CLI). 2 Flujo de Registro y Pago:

Registra un usuario de prueba en tu aplicación.
Navega a la página de precios/suscripción.
Selecciona un plan.
Haz clic en "Suscribirse". Deberías ser redirigido a la página de Stripe Checkout.
Usa una tarjeta de prueba de Stripe (encuéntralas en la documentación de Stripe, ej: 4242 4242 4242 4242, cualquier fecha futura, CVC 123).
Completa el pago.
Deberías ser redirigido a tu success_url. 3 Verificación del Webhook:
Comprueba los logs de tu servidor (o la salida de stripe listen) para asegurarte de que el evento checkout.session.completed fue recibido y procesado correctamente.
Verifica en tu base de datos que el estado del usuario se actualizó (suscripción activa, IDs de Stripe guardados, acceso concedido). 4 Prueba del Portal del Cliente:
Navega a la sección de tu app donde está el enlace "Gestionar Suscripción".
Haz clic. Deberías ser redirigido al Portal del Cliente de Stripe.
Prueba a realizar acciones permitidas (ej: ver factura, si configuras la cancelación, pruébala).
Verifica que la return_url te devuelve correctamente a tu aplicación. 5 Prueba de Cancelación (vía Portal o Lógica Propia):
Si permites la cancelación desde el portal, úsala.
Verifica que recibes el webhook customer.subscription.deleted.
Comprueba que tu lógica de cancelación se ejecuta (el acceso se revoca al final del periodo actual). 6 Prueba de Fallo de Pago (Opcional pero Recomendado):
Usa tarjetas de prueba de Stripe diseñadas para fallar.
Verifica que recibes el webhook invoice.payment_failed y que tu lógica (notificación, etc.) se activa. 7 Prueba de Renovación (Avanzado):
Puedes usar la funcionalidad "Test Clocks" de Stripe para simular el paso del tiempo y probar renovaciones, periodos de prueba, etc., sin esperar días o meses reales.

Fase 8: Pasar a Producción (Live Mode)

Una vez que todo funcione correctamente en Modo Prueba:

1 Completa la Activación de la Cuenta: Asegúrate de que tu cuenta Stripe está completamente activada y verificada. 2 Cambia a Claves de Producción:

En tu backend, reemplaza la Clave Secreta de Prueba (sk_test_...) por la Clave Secreta de Producción (sk_live_...). ¡Guárdala de forma segura!
En tu frontend, reemplaza la Clave Publicable de Prueba (pk_test_...) por la Clave Publicable de Producción (pk_live_...). 3 Crea Productos y Precios en Modo Producción: Los productos y precios creados en Modo Prueba no existen en Modo Producción. Debes recrearlos manualmente en el Dashboard (cambiando el interruptor a "Ver datos de producción"). Asegúrate de que los Price ID coincidan o actualiza tu código con los nuevos IDs de producción. 4 Configura el Webhook de Producción:
En el Dashboard (Modo Producción), ve a "Desarrolladores" -> "Webhooks".
Añade un nuevo endpoint apuntando a la URL de tu servidor en producción (ej: https://tu-saas-real.com/stripe-webhook).
Selecciona los mismos eventos que en prueba.
Obtén el Secreto de Firma de Producción (whsec_...) y configúralo en tu variable de entorno de producción STRIPE_WEBHOOK_SECRET. 5 Configura el Portal del Cliente en Modo Producción: Ve a "Configuración" -> "Portal del cliente" en Modo Producción y asegúrate de que esté configurado como deseas. 6 Despliega tu Aplicación: Sube los cambios con las claves y configuraciones de producción a tu servidor real. 7 Realiza una Transacción Real (Pequeña): Haz una compra real con una tarjeta válida (puede ser tuya o de un amigo/beta tester) en el plan más barato. Verifica que todo el flujo funciona: pago, redirección, recepción del webhook, actualización de la base de datos, concesión de acceso y acceso al portal del cliente. 8 Monitoriza: Vigila el Dashboard de Stripe y los logs de tu aplicación durante los primeros días/semanas para detectar cualquier problema inesperado.

¡Felicidades! Si has seguido todos estos pasos, deberías tener una integración funcional y robusta de Stripe en tu template SaaS, lista para aceptar pagos de tus clientes.

Recuerda siempre priorizar la seguridad (especialmente con las claves secretas y la verificación de webhooks) y probar exhaustivamente antes de pasar a producción.