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 a Stripe Checkout en modo suscripción desde tu servidor, y deja que un webhook le diga a tu app cuándo 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 eso, 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 cambien la tarjeta, cambien de plan y cancelen 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 es distinto del cobro recurrente. Los detalles de Stripe proceden de su documentación a 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 ocurriendo después de que se vaya: 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 esto a través de los webhooks. La mayoría de los errores con suscripciones vienen de tratar el primer pago como si fuera toda la historia.
Tus opciones
| Enfoque | Qué construyes | Ideal para |
|---|---|---|
| Payment Link con un precio recurrente | Nada más que un enlace | Probar la demanda; gestionar el acceso a mano |
| Checkout (modo suscripción) + portal de cliente | Una ruta de servidor, un webhook, un botón de facturación | La mayoría de apps SaaS y membresías |
| API de suscripciones con tu propio formulario de pago | Mucho más: interfaz de pago, autenticación, reintentos | Apps con flujos de facturación poco habituales |
| Proveedor de comerciante de registro | Parecido a Checkout | Vendedores que quieren que el proveedor gestione el impuesto sobre ventas |
Para la mayoría de apps, Checkout más el portal es el compromiso adecuado. Compara proveedores en Stripe frente a Paddle frente a Lemon Squeezy si la gestión de impuestos te preocupa.
Planifica tus precios en Stripe primero
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 producto puede tener varios precios. Decide:
- Qué niveles ofreces y qué desbloquea cada uno en tu app
- Mensual, anual o ambos
- Si ofreces prueba, y si necesita tarjeta por adelantado
Crea los productos y precios en modo de prueba, y guarda sus ID de precio; tu app los usa. 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:
| Estado | Qué significa | ¿Dar acceso? |
|---|---|---|
trialing | En periodo de prueba | Sí |
active | Al día | Sí |
incomplete | El primer pago aún no se ha completado; Stripe da al cliente 23 horas | No |
incomplete_expired | El primer pago nunca se completó | No |
past_due | El último pago falló o no se intentó; pueden seguir reintentos | Tu decisión; muchas apps permiten un breve periodo de gracia |
unpaid | Los reintentos han terminado, las facturas siguen abiertas, sin más intentos | No; la documentación de Stripe indica revocar el acceso |
canceled | Terminada; no se puede reiniciar | No |
paused | Una prueba terminó sin método de pago y se configuró para pausarse | No |
Guarda el estado en el registro del usuario o de la cuenta y basa el acceso en él. Actualízalo cada vez que llegue un webhook relevante.
Los eventos de webhook que debes gestionar
| Evento | Qué hace tu app |
|---|---|
checkout.session.completed | Vincula los ID de cliente y de suscripción de Stripe al usuario |
invoice.paid | Marca la suscripción como activa y registra el nuevo fin de periodo |
invoice.payment_failed | Avisa al usuario de que su tarjeta ha fallado y enlaza al portal |
invoice.payment_action_required | Pide al usuario que complete la autenticación de la tarjeta |
customer.subscription.updated | Actualiza el plan, el estado y cualquier cancelación programada |
customer.subscription.deleted | Quita el acceso de pago |
customer.subscription.trial_will_end | Recuerda al usuario antes de que termine la prueba; Stripe lo envía tres días antes |
Las reglas para los manejadores de la documentación de webhooks de Stripe siguen aplicando: verifica la firma con el cuerpo original, devuelve un 2xx rápidamente, gestiona los duplicados y los eventos 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
- Crea los productos y precios en el modo de prueba de Stripe.
- 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.
- Página de precios: el botón de cada plan llama a tu servidor, que crea una Checkout Session en modo suscripción para el usuario con sesión iniciada. Pasa tu ID de usuario para que el webhook pueda asociar el pago a la cuenta.
- Endpoint de webhook: verifica las firmas y gestiona los eventos anteriores, actualizando un registro de suscripción por usuario.
- Controla las funciones según el estado y el plan guardados, comprobados en el servidor en cada acción protegida, no solo con botones ocultos.
- Portal de cliente: configúralo en el panel de Stripe (a qué planes pueden cambiar las personas, si pueden cancelar) y luego añade un botón de Gestionar facturación que crea una sesión del portal en el servidor y redirige a ella.
- Pagos fallidos: en la configuración de facturación de Stripe, elige el comportamiento de reintentos y qué pasa tras el último. Muestra un aviso en la app mientras esté en
past_due. - Prueba todo el ciclo de vida, luego publica y registra el webhook en modo real.
Prompts para tu constructor de 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 Checkout Session en modo suscripción usando STRIPE_SECRET_KEY, con el ID del usuario con sesión iniciada 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 original de la petición. 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 evento procesados para ignorar los duplicados. Actualiza el estado del usuario a partir del objeto de suscripción, no del orden en que lleguen los eventos.
Controla las funciones Pro en el servidor: permite el acceso solo cuando el estado sea active o trialing y el plan sea Pro. Muestra el aviso «el pago ha fallado, 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, rebajas y prorrateo
Cuando un cliente cambia de plan, la documentación de Stripe indica que el cambio a menudo genera 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 no cambian; 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 la configuración 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 suscripción nueva concede el plan correcto al usuario correcto
- Cerrar la pestaña justo después de pagar sigue concediendo el acceso (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
- Subir y bajar de plan cambia las funciones correctamente
- Cancelar al final del periodo mantiene el acceso hasta la fecha de fin, y luego lo quita
- 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 las renovaciones sin esperar un mes. Consulta la documentación de pruebas actual de Stripe para ver cómo usarlos.
Errores habituales
- Conceder el acceso en la página de éxito. Los clientes pueden pagar y nunca llegar a ella. Usa el webhook.
- Gestionar solo el primer pago. Las renovaciones, los fallos y las cancelaciones llegan después, como eventos.
- Comprobar el estado del plan solo en el frontend. Cualquiera puede llamar a tu API directamente.
- Un usuario, muchas suscripciones por accidente. Comprueba si ya existe una suscripción antes de crear una nueva Checkout Session, o envía a los clientes existentes al portal.
- Revocar el acceso al primer intento de renovación fallido. Las tarjetas fallan por motivos triviales. Un breve periodo de gracia con un aviso claro mantiene a los clientes.
- Olvidar el webhook de modo real. Los endpoints de prueba y de producción tienen secretos de firma distintos.
- Ignorar impuestos y reembolsos. Decide tu política de reembolsos y consulta tus obligaciones fiscales con un contable antes del lanzamiento.
Suscripciones en Mythex
Las apps que construyes en Mythex usan tu propia cuenta y tus claves de Stripe; no hay una conexión de Stripe con un 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 después de cambiar a las claves reales para que la app en producción las cargue. Consulta Aceptar pagos con Stripe y Gestionar webhooks en tu backend. Para el producto en general, cómo crear un MVP de SaaS explica qué construir alrededor de la facturación.
Preguntas
¿Cuál es la forma más simple de añadir suscripciones con Stripe?
Crea un producto con un precio recurrente en el panel de Stripe, envía a los clientes a Stripe Checkout en modo suscripción, gestiona los eventos de suscripción con un webhook y enlaza un botón de Gestionar facturación al portal de cliente alojado por Stripe. Así no tienes que construir formularios de tarjeta ni pantallas de cambio de plan.
¿Qué eventos de webhook de Stripe necesito para las suscripciones?
Como mínimo, checkout.session.completed para vincular la nueva suscripción a tu usuario, invoice.paid para confirmar cada pago correcto, invoice.payment_failed para avisar de las renovaciones fallidas, y customer.subscription.updated y customer.subscription.deleted para seguir los cambios de plan y las cancelaciones.
¿Qué pasa cuando falla un pago de suscripción?
Según la documentación de Stripe a septiembre de 2026, la suscripción normalmente pasa a past_due y Stripe puede reintentar el pago según tu configuración. Tras el último reintento, los ajustes de tu panel deciden si se cancela, se marca como impagada o se deja en past_due.
¿Puedo ofrecer una prueba gratuita sin pedir tarjeta?
Sí. Stripe admite periodos de prueba gratuitos, y su documentación describe un estado pausado para las pruebas que terminan sin método de pago cuando está configurado así. Pedir la tarjeta por adelantado suele significar menos registros pero más clientes de pago; prueba qué encaja con tu producto.