Facturación de suscripciones con Stripe

Lee esto primero

Si aún no ha configurado el webhook de Stripe, empiece con Configurar webhook de Stripe. Esta página explica todo el flujo de facturación de la suscripción Stripe después de que su webhook esté conectado.

facturación de Stripe en Booknetic SaaS depende de dos partes que trabajan juntas:

• Stripe recoge el pago con tarjeta, almacena la tarjeta, crea la suscripción, renueva facturas, intenta los pagos fallidos y envía los recibos de pago.
• Booknetic SaaS envía a los inquilinos a Stripe Checkout, almacena el resultado de la suscripción, actualice el plan y la fecha de caducidad del inquilino, y escucha eventos de Stripe de webhook.

En palabras sencillas: Stripe es el propietario del pago; Booknetic SaaS refleja el estado de suscripción que su inquilino necesita dentro de la plataforma SaaS.

Antes de empezar

Antes de aceptar suscripciones de Stripe de pago, asegúrate de tener:

1. Stripe habilitado en Booknetic SaaS → Settings → Payment methods.
2. Su Stripe Publishable key y Secret key guardados en Booknetic SaaS.
3. Un endpoint de Stripe web hook funcional conectado a su sitio.
4. Los eventos de webhook requeridos seleccionedos en Stripe:

invoice.paid
customer.subscription.deleted

El webhook no es opcional para la facturación por suscripción. El primer pago puede parecer exitoso porque el inquilino regresa de Stripe Checkout, pero las renovaciones y actualizaciones de cancelación dependen del webhook.

Para los pasos de configuración del webhook, utiliza la guía complementaria: Configuración webhook de Stripe.

El modelo de facturación Stripe en un solo flujo

Una suscripción Stripe en Booknetic SaaS sigue este camino:

Inquilino chooses plan
→ Stripe Checkout opens
→ Inquilino enters card
→ Stripe creates the subscription and first invoice
→ Stripe sends invoice.paid webhook
→ Booknetic SaaS activates or extends the inquilino plan
→ Stripe repeats the invoice cycle on the next renewal date

El detalle importante es que Stripe y Booknetic SaaS no almacenan lo mismo.

Stripe guarda

Booknetic SaaS guarda

Tarjeta de cliente y método de pago

Plan de inquilinos y fecha de caducidad

Stripe Cliente

Cuenta de inquilino

Stripe Suscripción

Referencia de suscripción activa

Stripe Factura

Referencia Billing/historial de pagos

Calendario de renovación y lógica de reintentos

Si el inquilino debería tener acceso SaaS

Esta separación es normal. Significa que la gestión de la tarjeta, los recibos, las reintentos de pago no cumplidos y los reembolsos ocurren en Stripe, mientras que el acceso al plan y la expiración del inquilino ocurren en Booknetic SaaS.

Inscripción de inquilinos y primer pago

Cuando un inquilino elija un plan de pago y seleccione el pago con tarjeta, Booknetic SaaS lo envía a Stripe Checkout.

El flujo de inquilinos es así:

1. El inquilino abra Billing en su panel de inquilinos.
2. El inquilino elija un plan y un ciclo de facturación, como mensual o anual.
3. El inquilino elija el pago con tarjeta.
4. Stripe Checkout se abra en el navegador.
5. El inquilino introduce los datos de su tarjeta en la página segura de Stripe.
6. Stripe captura el primer pago y crea la suscripción.
7. Stripe redirige al inquilino de vuelta a Booknetic SaaS.
8. Booknetic SaaS marca la fila de facturación como pagada, guarda la referencia de suscripción activa y actualiza la fecha de caducidad del inquilino.

Booknetic SaaS no almacena el número completo de la tarjeta del inquilino. Los datos de la tarjeta se introducen y almacenan en el lado de Stripe.

Flujo de renovación recurrente

Después del primer pago, Stripe continúa la suscripción automáticamente.

En cada fecha de renovación:

1. Stripe crea la siguiente factura de suscripción.
2. Stripe carga la tarjeta guardada.
3. Si la carga tiene éxito, Stripe envía el invoice.paid webhook a su sitio Booknetic SaaS.
4. Booknetic SaaS registra la renovación pagada y amplía la fecha de caducidad del inquilino.

Si el webhook falta, está equivocado o es rechazado, Stripe puede mostrar la factura como pagada mientras Booknetic SaaS no extiende el vencimiento del inquilino. En ese caso, corrija primero el webhook y luego revise el inquilino afectado.

Flujo de cancelación

La cancelación es donde es especialmente importante entender qué sistema posee qué.

Cancelación de Booknetic SaaS

Cuando una suscripción se cancela del flujo de facturación Booknetic SaaS, Booknetic SaaS envía una solicitud de cancelación a Stripe para la suscripción activa.

Después de que Stripe borra/cancela la suscripción, Stripe envía este evento webhook de vuelta a Booknetic SaaS:

customer.subscription.deleted

Booknetic SaaS entonces borra la referencia activa de suscripción y marca el inquilino como dado de baja/cancelado en el estado de facturación SaaS.

Una cancelación no es lo mismo que eliminar al inquilino. La cuenta del inquilino y los datos del inquilino permanecen a menos que elimines al inquilino por separado. Para la orden de cancelación y eliminación segura, véase Cómo cancelar o eliminar un inquilino en Booknetic SaaS.

Cancelación iniciada por inquilinos y actualizaciones de tarjeta

Booknetic SaaS no actualmente ofrece un botón de Stripe Customer Portal para los inquilinos.

Eso significa que los inquilinos no pueden autoatender estas Stripe acciones desde un portal alojado en Stripe dentro de Booknetic SaaS:

• actualizar la tarjeta archivada;
• ver o descargar todas las facturas Stripe de un portal;
• cambiar la dirección de facturación desde un portal de Stripe;
• Pausa una suscripción desde un portal de Stripe.

Si un inquilino quiere usar una tarjeta diferente, utiliza una de estas opciones:

1. Pide al inquilino que cancele la suscripción actual y que vuelva a suscribirse al mismo plan. La nueva sesión de Stripe Checkout les permite introducir una nueva carta.
2. Ayude al inquilino desde su Stripe Dashboard si gestionas la facturación manualmente para ellos.

No digas a los inquilinos que busquen un enlace de Stripe Customer Portal en Booknetic SaaS, porque ese portal de autoservicio no está actualmente cableado.

¿Qué significan Stripe estados de suscripción

Stripe puede mostrar un estado de suscripción que no se parezca exactamente al estado inquilino que ves en Booknetic SaaS. Utiliza esta tabla para comparar ambos.

Stripe estado

Lo que significa en Stripe

Qué esperar en Booknetic SaaS

incomplete

La suscripción se creó, pero la primera factura aún no se ha pagado correctamente.

Booknetic SaaS no debe considerar el plan como totalmente pagado hasta que el pago tenga éxito. El inquilino puede permanecer en su estado anterior, de prueba, de expiración o no suscrito.

active

La suscripción está pagando según lo previsto.

El inquilino debe tener un plan activo y una fecha de caducidad basada en el último pago confirmado.

past_due

La última factura falló y Stripe está intentando de nuevo según la configuración de su Stripe.

Booknetic SaaS no ejecuta el calendario de reintentos de Stripe. El inquilino puede mantener el acceso hasta que finalice su periodo pagado actual, pero la expiración no se extenderá hasta que se reciba un webhook invoice.paid.

unpaid

Stripe ha dejado de intentarlo de nuevo o considera la factura no cobrable según la configuración de su Stripe.

Booknetic SaaS no extiende el periodo de inquilino sin una factura pagada. Si la fecha de caducidad del inquilino pasa, su acceso sigue la configuración de su plan caducado.

canceled

La suscripción fue cancelada o eliminada en Stripe.

Después de que se acepta el webhook customer.subscription.deleted, Booknetic SaaS borra la referencia activa de suscripción y trata al inquilino como dado de baja/cancelado.

La regla clave es sencilla: los pagos exitosos extienden el acceso; Los pagos fallidos no. Stripe pueden volver a intentar pagos fallidos, pero Booknetic SaaS extiende el acceso al inquilino solo cuando recibe un evento de pago exitoso.

Pagos fallidos y proceso de reclamación de pagos

proceso de reclamación de pagos significa el proceso de recuperación de pagos fallidos: reintentos, correos electrónicos de pagos fallidos, recordatorios y reglas finales de cobro.

Para suscripciones de Stripe, el proceso de reclamación de pagos lo gestiona Stripe, no Booknetic SaaS.

Booknetic SaaS no envía correos internos de "su pago fallido" a los inquilinos por Stripe fallos de suscripción. Si quiere que los inquilinos reciban recordatorios de pagos fallidos, configúralo en su Stripe Dashboard usando la configuración de facturación y correo electrónico de Stripe.

Booknetic SaaS escucha las facturas pagadas exitosas y la cancelación de suscripción. No sustituye las propias herramientas de recuperación de pagos impagados de Stripe.

Para conocer los conceptos de suscripción y el comportamiento de reintentos de Stripe, consulte la visión general de Stripe: https://docs.stripe.com/billing/subscriptions/overview

Stripe Sincronización de productos para planes

Cuando creas o editas planes de pago en Booknetic SaaS, Booknetic puede sincronizar el plan para Stripe como un Producto/Precio Stripe para que la compra pueda cobrar el plan correcto y el ciclo.

En el uso normal, no es necesario crear Stripe productos a mano para cada Booknetic SaaS plan. Configura sus planes en Booknetic SaaS y luego deja que el flujo de Stripe de compra utilice los datos de producto/precio que Booknetic cree.

Para detalles sobre la configuración de planos, incluyendo capacidades, límites, planes predeterminados y planes ocultos, consulte Plans y capacidades de plan en Booknetic SaaS.

Nota: Si cambias el nombre de un plan, el nombre del producto en Stripe puede actualizarse en adelante, pero las facturas de Stripe históricas no se reescribirán. Trata las facturas antiguas como registros contables que conservan los detalles desde la fecha en que se crearon.

Modo de prueba y modo en producción

Stripe modo de prueba y modo en producción son entornos separados.

Si su cuenta de Stripe está en modo de prueba pero su sitio Booknetic SaaS está activa, los inquilinos reales no serán cobrados con éxito. Asegúrese de que su sitio SaaS en producción use claves Stripe en producción:

• pk_live_... para el Publishable key;
• sk_live_... para el Secret key;
• El secreto de firma de webhook en producción para el endpoint de webhook en producción.

Si cambias del modo de prueba al modo en producción, actualice las claves en Booknetic SaaS y crea/compruebe el endpoint de webhook en producción correspondiente en Stripe. Los secretos de webhook en modo de prueba y los secretos de webhook en modo vivo no son intercambiables.

Nota de la versión de la API

La integración actual de Booknetic SaaS Stripe utiliza una versión Stripe API compatible con:

2025-07-30.basil

La mayoría de los clientes no necesitan cambiar nada por esto. Si eventos de Stripe webhook se entregan correctamente pero las renovaciones siguen sin actualizarse en Booknetic SaaS, contacte con el soporte con el ID de evento de Stripe y el inquilino afectado para que la carga útil pueda ser revisada.

Preguntas comunes

¿Cómo le devolvo el dinero a un inquilino?

Tramita el reembolso en su Stripe Dashboard.

Booknetic SaaS no ajusta automáticamente la fecha de caducidad del inquilino, el periodo del plan o el acceso a la facturación tras un reembolso Stripe. Si le devolves el dinero a un inquilino, revise si también necesita ajustar manualmente a ese inquilino en Booknetic SaaS.

Por ejemplo: si reembolsa una renovación pero quiere que el inquilino mantenga el acceso hasta una fecha concreta, revise el plan del inquilino y el estado de caducidad tras el reembolso.

¿Puede un inquilino pausar su suscripción?

No hay un flujo de pausa nativo en Booknetic SaaS para suscripciones de Stripe.

Las opciones prácticas son:

• cancelar la suscripción y permitir que el inquilino se suscriba de nuevo más tarde;
• gestionar manualmente una pausa excepcional en Stripe y ajustar el estado del inquilino manualmente si es necesario.

No describas esto como una función de pausa incorporada a menos que la versión de su producto añada una más adelante.

¿Y si Stripe dice past_due pero el inquilino sigue pareciendo activo en Booknetic SaaS?

Eso puede pasar.

past_due significa que Stripe está intentando de nuevo la factura fallida. Booknetic SaaS aún pueden mostrar al inquilino como activo porque el inquilino ya pagó el periodo actual. Si Stripe más adelante tiene éxito, el webhook invoice.paid prorroga el plazo de expiración. Si Stripe nunca tiene éxito, el inquilino no recibirá la siguiente prórroga.

Revise ambos sitios:

1. Stripe estado de suscripción/factura.
2. Fecha de caducidad del inquilino en Booknetic SaaS.

¿Por qué un pago de renovación no amplió la fecha de caducidad del inquilino?

Las renovaciones Booknetic SaaS llegan a través del invoice.paid webhook.

Comprobar:

• la URL del webhook es correcta;
• el punto final está suscrito a invoice.paid;
• el secreto de firma de webhooks en Booknetic SaaS está actualizado;
• Stripe muestra una entrega 2xx exitosa para el evento de factura.

Si todo eso parece correcto, contacte con el soporte con el ID del evento Stripe y el inquilino afectado.

¿Por qué mi inquilino no recibe un correo electrónico después del primer pago?

Los recibos de pago y muchos correos electrónicos de facturación se controlan mediante Stripe configuraciones.

Las notificaciones de workflow de Booknetic SaaS son independientes. Si quiere un correo de inquilino de Booknetic después de los eventos de suscripción, revise su Booknetic SaaS flujo de trabajo y la configuración de notificaciones. Si quiere correos de Stripe de recibo o de pago fallido, configúrelos en Stripe.

¿Puedo crear manualmente una factura en Stripe y que Booknetic SaaS prorroge el inquilino?

No, no automáticamente.

Las facturas de Stripe creadas manualmente no son el camino normal para renovar la suscripción en Booknetic SaaS. Si facturas manualmente a un inquilino en Stripe, actualice o revise el estado del inquilino manualmente en Booknetic SaaS también.

¿Pueden los inquilinos actualizar su tarjeta sin cancelar?

Ahora mismo no a través de Booknetic SaaS, porque Stripe Customer Portal no está cableado en el panel de inquilino.

Utiliza el flujo de cancelación y resuscripción, o ayude al inquilino desde la Stripe Dashboard si gestionas directamente su facturación.

Lista de comprobación de solución de problemas

El primer pago tuvo éxito en Stripe, pero el inquilino no se activó

Comprobar:

• el inquilino regresó de Stripe Checkout con éxito;
• el webhook Stripe está configurado;
• el secreto del webhook se guarda en Booknetic SaaS;
• la entrega del evento Stripe devolvió 200;
• el inquilino seleccionó el plan y el ciclo de facturación previstos.

Si la primera factura nunca se pagó, la suscripción Stripe puede seguir siendo incomplete. En ese caso, Booknetic SaaS no debería activar el plan de pago todavía.

La renovación se paga en Stripe, pero Booknetic SaaS sigue mostrando la fecha de vencimiento antigua

Esto suele ser un problema de webhook.

Corrija primero el webhook y luego revise el inquilino afectado. La guía de webhook complementaria cubre la configuración: Configuración webhook de Stripe.

El inquilino dice que cambió su correo de facturación, pero recibos de Stripe siguen yendo al correo antiguo

Stripe recibe el correo electrónico del inquilino cuando se crea la sesión de pago. Si el inquilino luego cambia su correo dentro de Booknetic SaaS, eso no actualice automáticamente el correo ya almacenado en la suscripción o cliente de Stripe.

Actualice el correo de facturación en Stripe si el inquilino necesita que los recibos de Stripe futuros se envíen a otro sitio.

El inquilino canceló, pero le cobraron de nuevo

Consulte la Stripe cronología de la suscripción.

Causas comunes:

• la factura final se emitió antes de la cancelación;
• la cancelación no llegó a Stripe;
• el customer.subscription.deleted webhook no alcanzó Booknetic SaaS;
• El inquilino fue eliminado antes de que se verificara la cancelación del proveedor.

Utiliza la guía de cancelación antes de eliminar inquilinos: Cómo cancelar o eliminar un inquilino en Booknetic SaaS.

Utiliza entre 3 y 5 capturas de pantalla de Booknetic cara al preparar la página publicada.

Capturas recomendadas:

1. Booknetic SaaS → Settings → Payment methods → Stripe sección mostrando los campos Publishable key, Secret key y Webhook secret, con todos los valores sensibles difuminados.
2. Booknetic SaaS → Plans → editor de planes mostrando precios mensuales/anuales pagados o el contexto de sincronización de planes relacionados con Stripe si es visible en la interfaz.
3. Panel de inquilinos → Billing mostrando tarjetas de plan y opción de pago tarjeta/Stripe antes de la compra.
4. Panel de inquilinos → Billing → estado actual del plan/suscripción que muestra el plan activo y la expiración tras un pago exitoso.
5. Botón de → Billing → Cancel subscription panel de inquilino que muestra dónde empieza la cancelación.

No capturar:

• Stripe Dashboard listas de suscriptores;
• Stripe Dashboard detalles de la factura;
• Stripe pantallas de entrega de webhooks;
• Stripe Checkout páginas;
• cualquier página que exponga datos de tarjeta, cliente, clave secreta, secreto de webhook o facturación en producción.

Para la interfaz de usuario propiedad de Stripe, enlaza a la documentación propia de Stripe en su lugar: https://docs.stripe.com/billing/subscriptions/overview

Revision 2026-05-30: TASK-3211 link prefix correction; draft-side only, no Marketing API call.