Cómo funcionan las suscripciones

Gestiona los pagos recurrentes y los ciclos de vida de las suscripciones.

Con Subscriptions, los clientes acceden a un producto por el que hacen pagos recurrentes. Las suscripciones requieren que retengas más datos sobre los clientes que en las compras únicas, porque tienes que poder cobrarles en el futuro.

Stripe ofrece muchas funcionalidades que te ayudan a gestionar la facturación de suscripciones:

El ciclo de vida de la suscripción

El proceso de crear y gestionar suscripciones depende de los principales recursos API de Stripe, incluidos clientes, facturas y PaymentIntents. Consulta las definiciones de objetos de API para obtener la lista completa de recursos relacionados con suscripciones.

Así se ve el flujo recomendado de suscripción:

Crear la suscripción

Puedes crear una suscripción nueva en el Dashboard o con la API. Cada vez que creas una suscripción, esto activa un evento. Escucha estos eventos con puntos de conexión webhook y asegúrate de que tu integración los gestione correctamente.

Como alternativa, puedes crear una prueba que no requiera pagos por la suscripción. En ese caso, el estado (status) es de prueba (trialing). Cuando la prueba termina, la suscripción pasa a estado activo (active) y se le cobra al cliente suscrito.

Comportamiento del pago

Recomendamos que establezcas el comportamiento del pago (payment_behavior) de una suscripción en default_incomplete para ayudar a gestionar pagos fallidos y flujos de pago complejos como 3DS. Esto crea suscripciones con estado incompleto (incomplete) si se requiere pago, lo que te permite cobrar y confirmar posteriormente la información de pago a fin de activar la suscripción.

Si estableces el comportamiento del pago (payment_behavior) en permitir incompleto (allow_incomplete), Stripe inmediatamente intenta cobrar el pago de la factura. Si el pago falla, el estado de la suscripción cambia a incompleto (incomplete). Si estableces el comportamiento del pago (pago_behavior) en error si es incompleto (error_if_incomplete), la creación de la suscripción falla cuando el pago falla.

Las suscripciones que creas en el Dashboard tienen el correcto comportamiento de pago predeterminado según el método de pago.

Cómo gestionar la factura

Cuando creas una suscripción, Stripe genera automáticamente una factura con el estado abierto (open). El cliente tiene alrededor de 23 horas para realizar el pago de forma correcta. Durante este tiempo, el estado de la suscripción es incompleto (incomplete) y el de la factura permanece como abierto (open). El período de 23 horas existe porque el cliente suele realizar el primer pago de una suscripción durante la sesión. Si el cliente vuelve a la aplicación pasadas las 23 horas, crea una nueva suscripción para él.

El cliente paga

Si tu cliente paga la factura, la suscripción pasa a estado activo (active) y la factura a pagado (paid). Si no se realiza el pago, la suscripción pasa a estado incompleto y vencido (incomplete_expired) y la factura queda en estado anulado (void).

Para confirmar si la factura se pagó, realiza lo siguiente:

Configura un punto de conexión de webhook u otro tipo de destino de evento y escucha el evento de factura pagada (invoice.paid).
Marca manualmente el objeto de suscripción y busca subscription.status=active. El estado (status) pasa a activo (active) cuando se paga la factura, ya sea por cobro automático o por pago manual del cliente.

Para obtener más información, consulta Estados de suscripciones y Estados de pagos.

Cómo brindar acceso a tu producto

Cuando creas una suscripción para un cliente, se crea un derecho activo para cada funcionalidad asociada a ese producto. Cuando un cliente accede a tus servicios, usa sus derechos activos para otorgarle acceso a las funcionalidades incluidas en su suscripción.

Como alternativa, puedes utilizar la opción de realizar el seguimiento de suscripciones activas con eventos webhook y proporcionar el producto al cliente en función de esa actividad.

Actualizar la suscripción

Puedes modificar las suscripciones existentes según sea necesario sin tener que cancelarlas y recrearlas. Algunos de los cambios más importantes que puedes hacer son subir o bajar el precio de la suscripción o suspender el cobro de una suscripción activa.

Puedes escuchar los eventos de suscripción con puntos de conexión webhook para ver si se modifica la suscripción; por ejemplo, mediante el envío de un correo electrónico al cliente si falla un pago o la revocación del acceso del cliente cuando este cancela su suscripción.

En el caso de las integraciones de Stripe Checkout, no puedes actualizar la suscripción ni su factura si la suscripción de la sesión está en estado incompleto (incomplete). Puedes escuchar el evento checkout.session.completed para hacer la actualización después de que se haya completado la sesión. También puedes hacer que se venza la sesión si, en cambio, quieres cancelar la suscripción, anular la factura de suscripción o marcar la factura como incobrable.

Gestionar suscripciones impagas

En el caso de las suscripciones con facturas impagas, las facturas impagas permanecen abiertas, pero se suspenden los intentos de pago. La suscripción continúa generando facturas en cada período de facturación, que permanecen en el estado borrador. Para reactivar la suscripción:

Recopila nueva información de pago si es necesario.
Para habilitar el cobro automático, configura la propiedad auto_advance como verdadera (true) en los borradores de facturas.
Cierra y paga las facturas abiertas. Al pagar la factura no anulada más reciente antes de su fecha de vencimiento, el estado de la suscripción se actualiza a active.

Las facturas marcadas como incobrables mantienen activa (active) la suscripción subyacente. Stripe ignora las facturas anuladas al momento de determinar el estado de la suscripción y, en su lugar, utiliza la factura no anulada más reciente.

El estado (status) de la suscripción impaga depende de la configuración de pagos fallidos que figure en el Dashboard.

Cancelación de la suscripción

Puedes cancelar una suscripción en cualquier momento, incluso al final de un ciclo de facturación o después de un número determinado de ciclos de facturación.

Si cancelas una suscripción, se deshabilitará la creación de nuevas facturas y se interrumpirá el cobro automático de todas las facturas pendientes en esa suscripción. También se eliminará la suscripción y ya no podrás actualizar ni la suscripción ni sus metadatos. Si el cliente quiere volver a suscribirse, tendrás que recopilar nuevos datos de pago y crear una suscripción nueva.

Estados de las suscripciones

Las suscripciones pueden tener los siguientes estados. Las acciones que puedes realizar en una suscripción dependen de su estado.

Estado	Descripción
`trialing`	La suscripción actualmente está dentro de un período de prueba y puedes suministrar el producto a tu cliente de forma segura. La suscripción pasará automáticamente a `active` cuando un cliente efectúe el primer pago.
`active`	La suscripción está en regla. En el caso de las suscripciones `past_due`, pagar la última factura asociada o marcarla como incobrable hace que la suscripción pase a `active`. Ten en cuenta que `active` no indica que se hayan pagado todas las facturas pendientes asociadas con la suscripción. Puedes dejar otras facturas pendientes abiertas para su pago, marcarlas como incobrables o anularlas como mejor te parezca.
`incomplete`	El cliente debe realizar un pago correctamente en el transcurso de 23 horas para activar la suscripción. O bien, el pago requiere acción, como la autenticación del cliente. Las suscripciones también pueden mostrarse como `incomplete` si hay un pago pendiente y el estado de PaymentIntent es `processing`.
`incomplete_expired`	Se produjo un error en el pago inicial de la suscripción y el cliente no efectuó ningún pago correctamente procesado en el transcurso de 23 horas de creada la suscripción. Estas suscripciones no se cobran a los clientes. Este estado existe para que puedas hacer el seguimiento de los clientes que no pudieron activar sus suscripciones.
`past_due`	El pago de la última factura finalizada falló o no se intentó. La suscripción continúa creando facturas. La configuración de la suscripción del Dashboard determina el siguiente estado de la suscripción. Si la factura sigue impaga después de todos los intentos de Smart Retries, puedes configurar la suscripción para que pase al estado cancelado (`canceled`), impago (`unpaid`) o dejarla como estado vencido (`past_due`). Para reactivar la suscripción, el cliente debe pagar la factura más reciente. El estado de la suscripción pasa a activo (`active`) independientemente de si el pago se realiza antes o después de la fecha de vencimiento de la última factura.
`canceled`	Se canceló la suscripción. Mientras esté cancelada, se deshabilita el cobro automático de todas las facturas no pagadas (`auto_advance=false`). Este estado es final y no puede actualizarse.
`unpaid`	No se abonó la última factura, pero la suscripción sigue vigente. La última factura permanece abierta y las facturas se siguen generando, pero no se intenta hacer pagos. Revoca el acceso a tu producto cuando la suscripción tenga el estado `unpaid` porque los pagos ya se intentaron y reintentaron mientras la suscripción estaba en estado `past_due`. Para que la suscripción pase a `active`, paga la factura más reciente antes de la fecha de vencimiento.
`paused`	La suscripción finalizó su período de prueba sin un método de pago predeterminado y el trial_settings.end_behavior.missing_payment_method está configurado en `pause`. Ya no se crean facturas para la suscripción. Después de asociar un método de pago predeterminado al cliente, puedes reanudar la suscripción.

Estados del pago

Un PaymentIntent realiza el seguimiento del ciclo de vida de cada pago. Cada vez que vence un pago de una suscripción, Stripe genera una factura y un PaymentIntent. El PaymentIntent ID se adjunta a la factura, y puedes acceder a él desde los objetos de la factura y la suscripción.

El estado del PaymentIntent afecta el estado de la factura y de la suscripción. Los diferentes resultados de un pago se asignan a los diferentes estados de la siguiente forma:

Resultado del pago	Estado del PaymentIntent	Estado de la factura	Estado de la suscripción
Se efectúa con éxito	`succeeded`	`paid`	`active`
Falla debido a un error de la tarjeta	`requires_payment_method`	`open`	`incomplete`
Falla debido a la autenticación	`requires_action`	`open`	`incomplete`

Nota

Con los métodos de pago asincrónicos, como ACH Direct Debit, se gestionan las transiciones del estado de la suscripción de manera diferente a los métodos de pago inmediatos. Cuando usas métodos asincrónicos, las suscripciones pasan directamente a un estado activo (active) después de su creación, lo que omite el estado incompleto (incomplete) asociado, en general, con otros tipos de pago. Si un pago asincrónico falla posteriormente, se anula la factura asociada, pero la suscripción permanece en estado activo (active). Este comportamiento contrasta con el de los métodos de pago inmediatos, en los que los pagos fallidos suelen llevar a estados incompletos (incomplete) o vencidos (past_due). Ten en cuenta esta distinción e implementa la lógica adecuada al momento de gestionar el estado de la suscripción, el control de acceso y los mecanismos de reintento de pago.

En las siguientes secciones, se explican estos estados y las medidas que puedes tomar para cada uno.

Pago efectuado con éxito

Cuando el pago del cliente se efectúe correctamente, realiza lo siguiente:

El estado (status) del PaymentIntent pasa a correcto (succeeded).
El estado (status) de la suscripción es activo (active).
El estado (status) de la factura es pagado (paid).
Stripe envía un evento invoice.paid a los puntos de conexión de webhook configurados.

En el caso de métodos de pago con períodos de procesamiento más largos, las suscripciones se activan inmediatamente. En estos casos, el estado del PaymentIntent puede ser en procesamiento (processing) de una suscripción activa (active) hasta que el pago se efectúe de forma correcta.

Ahora que la suscripción está activa, brinda acceso a tu producto.

Requiere un método de pago

Si el pago falla debido a un error de tarjeta, como un pago rechazado, ocurre lo siguiente:

El estado status del PaymentIntent es requiere método de pago (requires_payment_method).
El estado (status) de la suscripción es incompleto (incomplete).
El estado (status) de la factura es abierto (open).

Para gestionar estos escenarios:

Notifica al cliente.
Recopila datos de pagos nuevos y confirmar el PaymentIntent.
Actualiza el default payment method en la suscripción.
Stripe vuelve a hacer el intento de pago con Smart Retries o en función de tus reglas de reintentos personalizadas.
Usa el evento invoice.payment_failed para controlar los eventos de pago fallido de suscripciones y reintentar la realización de actualizaciones. Después de intentar el pago de una factura, el valor de next_payment_attempt se establece a partir de la configuración actual de suscripciones en el Dashboard.

Obtén información sobre cómo gestionar los errores de pago en las suscripciones.

Requiere intervención

Algunos métodos de pago exigen que se realice la autenticación del cliente con 3D Secure (3DS) para completar el proceso de pago. 3DS completa el proceso de autenticación. El hecho de que un método de pago requiera autenticación depende de las reglas de Radar y del banco emisor de la tarjeta.

Si el pago falla porque el cliente necesita autenticar un pago, ocurre lo siguiente:

El estado (status) del PaymentIntent es requiere acción (requires_action).
El estado (status) de la suscripción es incompleto (incomplete).
El estado (status) de la factura es abierto (open).