Cómo añadir suscripciones con Stripe: planes, pruebas, webhooks y pagos fallidos

Para añadir suscripciones con Stripe, crea un producto con un precio recurrente en el panel de Stripe, envía a los clientes desde tu servidor a Stripe Checkout en modo suscripción y deja que un webhook avise a tu app cuando cada pago se completa, falla, cambia o termina. Guarda el estado de la suscripción asociado al usuario y concede el acceso a partir de ese estado, no a partir de la página de éxito. Añade un botón de Gestionar facturación que abra el portal de cliente alojado por Stripe, para que las personas puedan cambiar la tarjeta, cambiar de plan y cancelar sin que tú tengas que construir esas pantallas.

Esta guía se apoya en cómo añadir pagos a tu app, que cubre el Checkout de pago único, el modo de prueba y la puesta en producción. Aquí nos centramos en lo que cambia con el cobro recurrente. Los detalles de Stripe proceden de su documentación a fecha de septiembre de 2026.

Por qué las suscripciones son más difíciles que los pagos únicos

Un pago único ocurre mientras el cliente está en tu app. Una suscripción sigue cobrándose cuando el cliente ya se ha ido: renovaciones cada mes, tarjetas que caducan, mejoras a mitad de ciclo, cancelaciones que surten efecto al final del periodo. Tu app solo se entera de todo esto mediante webhooks. La mayoría de los errores con suscripciones vienen de tratar el primer pago como si fuera toda la historia.

Tus opciones

Para la mayoría de apps, Checkout más el portal es el equilibrio adecuado. Compara proveedores en Stripe frente a Paddle frente a Lemon Squeezy si la gestión fiscal te preocupa.

Planifica primero tus precios en Stripe

En Stripe, un producto es lo que vendes («Plan Pro») y un precio es cómo lo cobras («20 $ al mes», «200 $ al año»). Un mismo producto puede tener varios precios. Decide:

• Qué niveles ofreces y qué desbloquea cada uno en tu app
• Mensual, anual o ambos
• Si ofreces una prueba, y si necesita tarjeta por adelantado

Crea los productos y los precios en modo de prueba y guarda sus ID de precio; tu app los referencia. Si aún no has cerrado los precios, lee cómo fijar el precio de un producto SaaS y freemium frente a prueba gratuita.

El ciclo de vida de la suscripción que debes gestionar

La visión general de suscripciones de Stripe enumera los estados que puede tener una suscripción. Los que más importan para el acceso:

Guarda el estado en el registro de tu usuario o cuenta y basa el acceso en él. Actualízalo cada vez que llegue un webhook relevante.

Los eventos de webhook que hay que gestionar

Las reglas para los gestores de webhooks de la documentación de Stripe siguen valiendo: verifica la firma con el cuerpo sin procesar, devuelve un 2xx rápidamente, gestiona eventos duplicados y fuera de orden, y espera reintentos. La guía qué es un webhook explica la idea, y la guía de pagos enumera las reglas en detalle.

Paso a paso

1. Crea los productos y los precios en el modo de prueba de Stripe.
2. Añade los secretos: la clave secreta, los ID de precio y, más adelante, el secreto de firma del webhook. Nunca los pongas en el código del frontend.
3. Página de precios: el botón de cada plan llama a tu servidor, que crea una sesión de Checkout en modo suscripción para el usuario que ha iniciado sesión. Pasa el ID de tu usuario para que el webhook pueda vincular el pago a la cuenta.
4. Endpoint de webhook: verifica las firmas y gestiona los eventos anteriores, actualizando un único registro de suscripción por usuario.
5. Restringe las funciones según el estado y el plan guardados, comprobados en el servidor en cada acción protegida, no solo con botones ocultos.
6. Portal de cliente: configúralo en el panel de Stripe (a qué planes pueden cambiar las personas, si pueden cancelar) y añade un botón de Gestionar facturación que cree una sesión del portal en el servidor y redirija a ella.
7. Pagos fallidos: en los ajustes de facturación de Stripe, elige el comportamiento de reintentos y qué pasa tras el último. Muestra un aviso dentro de la app mientras esté en past_due.
8. Prueba todo el ciclo de vida, y después publica y registra el webhook de producción.

Prompts para tu creador con IA

Añade facturación por suscripción con Stripe. Planes: Starter (ID de precio en STRIPE_PRICE_STARTER) y Pro (STRIPE_PRICE_PRO). La página de precios crea en el servidor una sesión de Checkout en modo suscripción usando STRIPE_SECRET_KEY, con el ID del usuario que ha iniciado sesión adjunto. Guarda en el usuario el ID de cliente de Stripe, el ID de suscripción, el plan y el estado. Nunca expongas la clave secreta al navegador.

Añade POST /api/stripe/webhook. Verifica la firma con STRIPE_WEBHOOK_SECRET usando el cuerpo de la petición sin procesar. Gestiona checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted y customer.subscription.trial_will_end. Registra los ID de eventos procesados para ignorar los duplicados. Actualiza el estado del usuario a partir del objeto de suscripción, no a partir del orden en que lleguen los eventos.

Restringe las funciones Pro en el servidor: permítelas solo cuando el estado sea active o trialing y el plan sea Pro. Muestra un aviso de «pago fallido, actualiza tu tarjeta» cuando el estado sea past_due. Añade un botón de Gestionar facturación que abra el portal de cliente de Stripe para este usuario.

Mejoras, bajadas de plan y prorrateo

Cuando un cliente cambia de plan, la documentación de Stripe indica que el cambio suele generar un prorrateo: el nuevo precio se aplica al resto del periodo de facturación actual. Puedes previsualizar los prorrateos o desactivarlos. Si los planes tienen el mismo intervalo, las fechas de cobro se mantienen; pasar de mensual a anual mueve la fecha de cobro al día del cambio. Dejar que los clientes cambien de plan en el portal te ahorra escribir esta lógica, pero decide en los ajustes del portal qué cambios están permitidos.

Lista de comprobación de pruebas

Usa el modo de prueba de Stripe y las tarjetas de prueba, y recorre cada estado:

• Una nueva suscripción concede el plan correcto al usuario correcto
• Cerrar la pestaña justo después de pagar sigue concediendo el acceso (esto demuestra que el webhook funciona)
• Una tarjeta rechazada al registrarse no concede nada
• Una renovación fallida pone la cuenta en past_due y muestra el aviso
• Actualizar la tarjeta en el portal restaura el estado active
• Mejorar y bajar de plan cambia las funciones correctamente
• Cancelar al final del periodo mantiene el acceso hasta la fecha de fin, y después lo retira
• Los usuarios en prueba tienen acceso, reciben el recordatorio, y se convierten o pierden el acceso correctamente
• Enviar dos veces el mismo evento de webhook no cambia nada

Los relojes de prueba de Stripe te permiten simular el paso del tiempo, así que puedes probar renovaciones sin esperar un mes. Consulta la documentación de pruebas actual de Stripe para saber cómo usarlos.

Errores habituales

• Conceder el acceso en la página de éxito. Los clientes pueden pagar y no llegar nunca a ella. Usa el webhook.
• Gestionar solo el primer pago. Las renovaciones, los fallos y las cancelaciones llegan más tarde, como eventos.
• Comprobar el estado del plan solo en el frontend. Cualquiera puede llamar directamente a tu API.
• Un usuario con varias suscripciones por accidente. Comprueba si ya existe una suscripción antes de crear una nueva sesión de Checkout, o envía a los clientes existentes al portal.
• Revocar el acceso en la primera renovación fallida. Las tarjetas fallan por motivos banales. Un periodo de gracia corto con un aviso claro retiene a los clientes.
• Olvidarse del webhook de producción. Los endpoints de prueba y de producción tienen secretos de firma distintos.
• Ignorar impuestos y devoluciones. Define tu política de devoluciones y revisa tus obligaciones fiscales con un asesor antes del lanzamiento.

Suscripciones en Mythex

Las apps que construyes en Mythex usan tu propia cuenta y tus propias claves de Stripe; no hay una conexión de Stripe de un solo clic para tu app. Añade tus claves de prueba y tus ID de precio como secretos del proyecto, usa prompts como los de arriba y prueba con las tarjetas de prueba de Stripe en la vista previa. Los webhooks necesitan la URL pública de tu app, así que publica antes de registrar el endpoint en Stripe, y vuelve a publicar tras cambiar a las claves de producción para que la app en vivo las recoja. Consulta Aceptar pagos con Stripe y Gestionar webhooks en tu backend. Para el producto en su conjunto, cómo crear un MVP de SaaS explica qué construir alrededor de la facturación.

Preguntas