Ir a contenido
Crea una cuenta
o
Inicia sesión
Logotipo de Stripe Docs
/
Pregúntale a la IA
Crear una cuenta
Iniciar sesión
Empieza ahora
Pagos
Automatización contable
Plataformas y marketplaces
Gestión del dinero
Herramientas para desarrolladores
Empieza ahora
Pagos
Automatización contable
Empieza ahora
Pagos
Automatización contable
Plataformas y marketplaces
Gestión del dinero
Resumen
Billing
    Resumen
    Acerca de las API de facturación
    Suscripciones
      Resumen
      Inicio rápido
      Casos de uso
      Desarrolla tu integración
      Funcionalidades de la suscripción
      Análisis
    Invoicing
    Cobro por consumo
    Connect y Billing
    Tax y Billing
    Presupuestos
    Recuperación de ingresos
    Automatizaciones
    Scripts
    Reconocimiento de ingresos
    Gestión de clientes
    Derechos
    Prueba tu integración
Impuesto
Elaboración de informes
Datos
Constitución de una startup
InicioAutomatización contableBillingSubscriptions

Cómo funcionan las suscripciones

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

Copiar página

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.

Objetos de las suscripciones

Usa los siguientes recursos API para crear y gestionar suscripciones:

RecursoDefinición
CustomerRepresenta a un cliente que compra una suscripción. Usa el objeto Customer asociado a una suscripción para realizar y hacer seguimiento de los cargos recurrentes y para administrar los productos a los que se suscriben.
DerechoRepresenta el acceso de un cliente a una funcionalidad incluida en un producto de servicio al que está suscrito. Cuando creas una suscripción para la compra recurrente de un producto por parte de un cliente, se crea automáticamente un derecho activo para cada funcionalidad asociada a ese producto. Cuando un cliente accede a tus servicios, utiliza sus derechos activos para habilitar las funcionalidades incluidas en su suscripción.
FuncionalidadRepresenta una funcionalidad o capacidad a la que tus clientes pueden acceder cuando se suscriben a un producto de servicio. Puedes incluir funciones en un producto creando ProductFeatures.
FacturaUna declaración de importes que un cliente adeuda y que rastrea los estados de pago desde el borrador hasta su pago o su finalización. Las suscripciones generan facturas automáticamente.
PaymentIntentUna forma de crear flujos de pago dinámicos. Un PaymentIntent hace un seguimiento del ciclo de vida del flujo del proceso compra del cliente y activa pasos adicionales de autenticación, si así lo exigen las disposiciones normativas, las reglas antifraude personalizadas de Radar o los métodos de pago con redireccionamiento. Las facturas crean PaymentIntents de forma automática.
PaymentMethodLos instrumentos de pago de un cliente que usa para pagar tus productos. Por ejemplo, puedes almacenar una tarjeta de crédito en un objeto Customer y usarla para realizar pagos recurrentes para ese cliente. Normalmente se usa con las API Payment Intents o Setup Intents.
PrecioDefine el precio por unidad, la moneda y el ciclo de facturación para un producto.
ProductoUn bien o servicio que vende tu empresa. Un producto de servicio puede incluir una o más funciones.
ProductFeatureRepresenta la inclusión de una sola funcionalidades en un solo producto. Cada producto está asociado a una ProductFeature para cada funcionalidad que incluye, y cada funcionalidad está asociada a una ProductFeature para cada producto que la incluye.
SuscripciónRepresenta la compra recurrente programada de un producto por parte de un cliente. Usa una suscripción para cobrar pagos y proporcionar entrega repetida o acceso continuo a un producto.

Veamos un ejemplo de cómo funcionan juntos los productos, las funcionalidades y los derechos. Imagina que quieres configurar un servicio de suscripción que ofrezca dos niveles: un producto estándar con funcionalidad básica y un producto avanzado que agregue funcionalidad extendida.

  1. Creas dos funcionalidades: basic_features y extended_features.
  2. Creas dos productos: standard_product y advanced_product.
  3. Para el producto estándar, creas una ProductFeature que asocia basic_features con standard_product.
  4. Para el producto avanzado, creas dos ProductFeatures: una que asocia basic_features con advanced_product y otra que asocia extended_features con advanced_product.

Un cliente, first_customer, se suscribe al producto estándar. Cuando creas la suscripción, Stripe crea automáticamente un derecho que asocia first_customer con basic_features.

Otro cliente, second_customer, se suscribe al producto avanzado. Al crear la suscripción, Stripe crea automáticamente dos derechos: uno que asocia second_customer con basic_features y otro que asocia second_customer con extended_features.

You can determine which features to provision for a customer by retrieving their active entitlements or listening to the Active Entitlement Summary event. You don’t have to retrieve their subscriptions, products, and features.

Cómo funcionan los objetos de Stripe durante el ciclo de vida de una suscripción.

Modelo de integración

En esta sección se describe nuestra integración de ejemplo en GitHub, que ilustra cómo crear una integración de suscripciones. Si estás listo para crear tu propia integración, consulta la guía de inicio rápido de Billing o la guía de integración.

Página de inicio

En el front-end, la página de inicio primero recopila la dirección de correo electrónico. Es posible que tu aplicación requiera que obtengas otros datos específicos del cliente, como un nombre de usuario o un domicilio. Al hacer click en el botón para crear una cuenta, los datos recopilados en la página de inicio se envían al back-end. Este proceso crea un nuevo cliente y abre la página de tarifas en el front-end.

Página de tarifas

La página de precios muestra tus opciones de suscripción en función de los productos y precios que creaste cuando configuraste tu integración por primera vez, lo que significa que no necesitas crear otras nuevas cada vez que los clientes se registren. Tu página de precios muestra los precios que creaste y tus clientes eligen la opción que desean. El ejemplo en GitHub muestra un formulario de pago cuando un cliente selecciona una opción. Obtén más información sobre los productos y los precios.

Pago

El formulario de pago recopila los datos de la tarjeta y un nombre. Si usas Checkout, este formulario está alojado en Stripe y es una de las funcionalidades clave que te permiten cobrar pagos y cumplir siempre con la normativa PCI. Al hacer click en Suscribirse:

  1. Crea una nueva suscripción con los ID de precio y de cliente.
  2. Genera una factura para el ciclo inicial de suscripción.
  3. Recopila los datos de la tarjeta y paga la factura.
  4. Establece el método de pago como predeterminado para la suscripción, lo cual es necesario para los próximos pagos.

Asegúrate de confirmar el pago antes de proporcionar acceso a tu cliente.

Para implementar esto:

  • Acepta pagos sin necesidad de escribir ni una línea de código: Si no quieres escribir ningún código, aprende a crear un enlace de pago y compártelo con tus clientes.
  • Crea una página de confirmación de compra: usa la API Checkout Sessions para aceptar pagos a través de una página alojada, un formulario integrado en tu sitio o una página de confirmación de compra personalizada creada con componentes integrados.
  • Integración avanzada: usa Stripe Elements para recopilar los datos de pago y activar la suscripción con el Payment Element.

Cómo hacer el suministro

Usa Derechos para determinar cuándo puedes conceder o revocar el acceso a las funcionalidades del producto para tus clientes. Alternativamente, después de un pago exitoso, puedes aprovisionar el producto de manera segura para el cliente. Por lo general, esto significa:

  1. Verificar que el estado de la suscripción sea active.
  2. Otorgarle al cliente acceso a los productos y las funcionalidades a los que se suscribió.

Aprende a usar destinos de eventos para hacer lo siguiente:

  • Hacer el seguimiento de suscripciones activas
  • Gestionar errores de pago
  • Comprobar objetos de evento

Cómo funcionan los pagos con las suscripciones

Para simplificar la gestión de pagos fallidos y crear suscripciones antes de intentar el pago:

  1. Especifica payment_behavior=default_incomplete al crear una suscripción. Si esta requiere un pago, se crea con el estado incomplete; de lo contrario, la suscripción inmediatamente pasa al estado active.

  2. Activa una suscripción incompleta pagando la primera factura.

  3. Especifica el identificador del Payment Intent de la factura en tu interfaz de usuario para recopilar información de pago y confirmar el Payment Intent. Puedes usar Elements, el SDK para Android o el SDK para iOS.

Nota

Las suscripciones creadas en el Dashboard se establecen de forma predeterminada en payment_behavior=error_if_incomplete si no usas los métodos de pago Oxxo, Konbini o Boleto. Si el pago inicial falla debido a la autenticación con 3D Secure, puedes crear la suscripción con payment_behavior=default_incomplete en su lugar.

Estado del pago

El proceso de pago varía según los métodos de pago y la ubicación geográfica. Al principio, los pagos pueden fallar (por ejemplo, si el cliente introduce un número de tarjeta incorrecto o no tiene fondos suficientes), por lo que es posible que haya diferentes resultados de los pagos.

El PaymentIntent hace el seguimiento del ciclo de vida de cada pago. Cada vez que vence el pago de una suscripción, Stripe genera una factura y un PaymentIntent. La ID del PaymentIntent se adjunta a la factura y puedes acceder a ella desde los objetos Invoice y Subscription. El estado del PaymentIntent repercute en el estado de la factura y de la suscripción. A continuación, se detallan las correspondencias entre los diferentes resultados de un pago y los distintos estados:

Resultado del pagoEstado del PaymentIntentEstado de la facturaEstado de la suscripción
Se efectúa con éxitosucceededpaidactive
Falla debido a un error de la tarjetarequires_payment_methodopenincomplete
Falla debido a la autenticaciónrequires_actionopenincomplete

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

Pago efectuado con éxito

Cuando tu pago se efectúa correctamente, el estado del PaymentIntent es succeeded, y la suscripción pasa a ser active. En el caso de los métodos de pago con períodos de procesamiento más largos, las suscripciones se activan de inmediato. En estos casos, el estado del PaymentIntent de una suscripción active puede ser processing hasta que se complete el pago.

Ahora que la suscripción está activa, brinda acceso a tu producto. Lee la guía para obtener más información sobre el ciclo de vida de las suscripciones y las mejores prácticas para el suministro.

RespuestaSuscripciónPaymentIntent
{ "id": "sub_1ELI8bClCIKljWvsvK36TXlC", "object": "subscription", "status": "active", ... "latest_invoice": { "id": "in_EmGqfJMYy3Nt9M", "status": "paid", "payments": { "data": [ { "payment": { "type": "payment_intent", "payment_intent": { "status": "succeeded", ... } } ... } ], ... } }
activesucceeded
Flujo de la red de pago de la suscripción.

Requiere un método de pago

Si el pago falla debido a un error de la tarjeta, por ejemplo, porque es rechazada, el estado del PaymentIntent será requires_payment_method y la suscripción estará incomplete.

RespuestaSuscripciónPaymentIntent
{ "id": "sub_1ELI8bClCIKljWvsvK36TXlC", "object": "subscription", "status": "incomplete", ... "latest_invoice": { "id": "in_EmGqfJMYy3Nt9M", "status": "open", "payments": { "data": [ { "payment": { "type": "payment_intent", "payment_intent": { "status": "requires_payment_method", ... } } ... } ], ... } } }
incompleterequires_payment_method

Para resolver estos escenarios:

  • Notifica al cliente.
  • Recopila nueva información de pago y confirma el Payment Intent.
  • Actualiza el default payment method en la suscripción.

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

Cómo gestionar fallas en los pagos de suscripciones.

Requiere intervención

Algunos métodos de pago requieren la autenticación del cliente con 3D Secure (3DS) para completar el proceso de pago. Si usas el API Payment Intents, el valor status del PaymentIntent es requires_action cuando un cliente tiene que autenticar un pago. Puedes obtener el PaymentIntent en el recurso Pago de facturas expandiendo latest_invoice.payments.data.payment.payment_intent o especificando el parámetro de la factura con Lista de pago de facturas. 3D Secure completa el proceso de autenticación. Un método de pago requerirá autenticación en función de tus reglas de Radar y del banco emisor de la tarjeta.

Las normativas europeas suelen exigir 3D Secure. Consulta la guía sobre la autenticación reforzada de clientes para determinar si la gestión de este estado es importante para tu empresa. Si ya tienes una integración de Stripe Billing y quieres agregar soporte para este flujo, también puedes revisar nuestra guía de migración a la SCA para Billing.

RespuestaSuscripciónPaymentIntent
{ "id": "sub_1ELI8bClCIKljWvsvK36TXlC", "object": "subscription", "status": "incomplete", ... "latest_invoice": { "id": "in_EmGqfJMYy3Nt9M", "status": "open", ... "payments": { "data": [ { "payment": { "type": "payment_intent", "payment_intent": { "status": "requires_action", "client_secret": "pi_91_secret_W9", "next_action": { "type": "use_stripe_sdk", ... }, ... } } ... } ], } } }
incompleterequires_action

Para gestionar estos escenarios:

  • Supervisa la notificación de eventos invoice.payment_action_required con puntos de conexión de webhooks. Esto indica que se requiere autenticación.
  • Notifica a tu cliente que debe realizar una autenticación.
  • Recupera el secreto del cliente para el intento de pago y especifícalo en una llamada a stripe.ConfirmCardPayment. En este punto, se abre un cuadro de diálogo para que los clientes completen la autenticación, se intenta el pago, luego se cierra el cuadro de diálogo y tu aplicación recibe información de contexto.
  • Controla el evento invoice.paid en el destino del evento para verificar que el pago se haya realizado correctamente. Los usuarios pueden abandonar la aplicación antes de que confirmCardPayment() termine. Verificar si el pago se efectuó en forma correcta te permitirá prestar el servicio como corresponde.
Cómo gestionar los pagos de suscripción que requieren una acción adicional del cliente.

Cargos recurrentes

Stripe gestiona los cargos recurrentes automáticamente. Esto implica lo siguiente:

  • La facturación automática a los clientes y el intento de pagos cada vez que comienza un nuevo ciclo de cobro.
  • Cuando se produce un error de pago, Stripe lo reintenta usando la funcionalidad Smart Retries o tu calendario de reintentos personalizado. De esta manera, el pago se reintenta automáticamente cuando se rechaza una tarjeta, según la configuración del Dashboard. Si un error devuelve un código de rechazo permanente, los reintentos programados continúan, pero el pago se ejecuta solo si obtienes un nuevo método de pago.

También puedes enviar correos electrónicos de reclamación de pagos para los pagos vencidos, con el fin de aumentar las probabilidades de recuperación. Para los pagos que requieren la autenticación mediante 3D Secure, puedes configurar tus opciones de cobro de forma que se envíe un enlace alojado a los clientes para que puedan completar el flujo.

Gestiona los fallos en los cargos recurrentes

Si no quieres usar las herramientas de Stripe para gestionar los fallos, puedes crear tu propia herramienta. Si un pago falla o requiere la autenticación del cliente, el status de la suscripción pasa a past_due, y el estado del PaymentIntent será requires_payment_method o requires_action.

Objetos involucrados cuando se gestionan pagos de suscripciones que fallaron o que requieren una acción.

Para administrar estos escenarios, configura un punto de conexión de webhook y escucha el evento customer.subscription.updated de modo que se te notifique cuando las suscripciones entren en el estado past_due:

{ "id": "sub_E8uXk63MAbZbto", "object": "subscription", ... "status": "past_due", "latest_invoice": "in_1EMLu1ClCIKljWvsfTjRFAxa" }

Para estas suscripciones, es necesario que tus clientes vuelvan a tu aplicación a especificar otro método de pago para que puedan completar el pago. Puedes hacerlo por correo electrónico o mediante una notificación push en el teléfono móvil. Para estos casos, Stripe cuenta con la opción integrada de enviar recordatorios por correo electrónico. Puedes habilitarlos en la configuración de facturación.

Cuando tu cliente vuelve a tu aplicación, reutiliza el flujo del pago fallido o el flujo de acción del cliente, según el estado del PaymentIntent asociado. Una vez que el pago se completa correctamente, el estado de la suscripción pasa a active y la factura, a paid.

Gestionar facturas que no exigen pago

Las suscripciones que incluyen pruebas gratuitas, cobro por consumo, facturas con cupones o saldos de crédito del cliente aplicados suelen generar facturas que no exigen pago. Es decir, no le cobras a tu cliente inmediatamente después de crear la suscripción.

Aun cuando no hagas cargos a los clientes en la primera factura, suele convenir autenticar y autorizar su tarjeta, ya que aumenta la probabilidad de que el primer pago que deba efectuarse se complete correctamente. Los pagos efectuados de esta manera se conocen como pagos fuera de la sesión. Para gestionar estos escenarios, Stripe creó SetupIntents.

Usa SetupIntents

Puedes usar SetupIntents para lo siguiente:

  • Recopila datos de pago.
  • Autenticar la tarjeta de tu cliente para después pedir exenciones
  • Autoriza la tarjeta de tu cliente sin efectuar un cargo.

La autenticación de los pagos permite que tu cliente otorgue permisos para hacer cargos a su tarjeta. La autenticación reforzada de clientes lo requiere, y es habitual que se complete mediante 3D Secure. La recopilación de información de los métodos de pago y su autorización garantiza que puedas efectuar correctamente el cargo en el método de pago.

En los escenarios fuera de la sesión, los SetupIntents te permiten cobrarles a los clientes su primer pago no en cero sin que deban volver a tu sitio web o a la aplicación para autenticarse. Esto reduce las fricciones para el cliente.

El campo pending_setup_intent de una suscripción no se cancela automáticamente cuando esta finaliza. Escucha los eventos customer.subscription.deleted y de forma manual cancela una suscripción SetupIntent si es necesario.

Stripe crea automáticamente los SetupIntents para las suscripciones que no exigen un pago inicial. Si es necesario, en este punto también se completa el proceso de autenticación y autorización. Si se ejecuta correctamente o si no es necesario, no tienes que hacer nada. En este caso, el campo subscription.pending_setup_intent es null. Si se produce un error en alguno de los pasos, Stripe te recomienda usar el SetupIntent en tu front-end para resolver el problema mientras tu cliente está en la sesión. Las dos secciones siguientes explican en detalle cómo gestionar los escenarios en los que se produce un error en la autenticación o la autorización.

Gestiona los errores de autenticación Client-side

La autenticación falla cuando Stripe no puede autenticar a tu cliente ante el emisor de tarjeta. Cuando esto ocurre, el status del SetupIntent es requires_action.

Cómo gestionar las fallas en la autenticación de pagos de suscripciones.

Para resolver estos casos, debes llamar a confirmCardSetup en tu front-end para que tu cliente pueda completar el flujo de autenticación manualmente. Ten en cuenta que el código de ejemplo a continuación expande el pending_setup_intent para completar el flujo.

const {pending_setup_intent} = subscription; if (pending_setup_intent) { const {client_secret, status} = subscription.pending_setup_intent; if (status === "requires_action") { const {setupIntent, error} = await stripe.confirmCardSetup(client_secret); if (error) { // Display error.message in your UI. } else { // The setup has succeeded. Display a success message. } } }

Después de haber completado el flujo, se ejecuta la autorización si es necesaria. Si se ejecuta correctamente o no es necesaria, pending_setup_intent se actualiza a null una vez finalizado.

Gestiona los errores de autorización Client-side

La autorización del pago falla cuando Stripe no puede verificar si se puede hacer el cargo en la tarjeta. Cuando esto ocurre, el status del SetupIntent es requires_payment_method. Esto suele implicar que fallarán los cargos sucesivos que se efectúen con la misma tarjeta.

Cómo gestionar las fallas en la autorización de pagos de suscripciones.

Para solucionar estos casos, recopila un nuevo método de pago y luego actualiza el método de pago predeterminado para el cliente o la suscripción. El código de ejemplo que aparece a continuación expande el pending_setup_intent para completar el flujo.

const {pending_setup_intent, latest_invoice} = subscription; if (pending_setup_intent) { const {client_secret, status} = subscription.pending_setup_intent; if (status === "requires_action") { const {setupIntent, error} = await stripe.confirmCardSetup(client_secret); if (error) { // Display error.message in your UI. } else { // The setup has succeeded. Display a success message. } } else if (status === "requires_payment_method") { // Collect new payment method } }

El ciclo de vida de la suscripción

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

Comportamiento del pago

Si estableces payment_behavior en default_incomplete, el status de la suscripción es incomplete. Obtén más información sobre por qué recomendamos usar este tipo de comportamiento de pago para las suscripciones.

  1. Tú creas la suscripción. El status de la suscripción es incomplete (si sigues el flujo recomendado: si creas una suscripción sin especificar el payment_behavior, el status predeterminado es active).

  2. Se crea una factura para la suscripción. El status de la factura es open.

  3. El cliente paga la primera factura.

  4. Cuando el pago se efectúa correctamente:

    • El status de la suscripción pasa a active
    • El status de la factura se establece en paid
    • Stripe envía un evento invoice.paid a los puntos de conexión de webhook configurados.
  5. Brindas acceso a tu producto. Tienes varias formas de confirmar si la factura se ha pagado:

    • Configurar un punto de conexión de webhook u otro tipo de destino de evento y escuchar el evento invoice.paid.
    • Verificar manualmente el objeto Suscription y buscar subscription.status=active. El status se vuelve active cuando se paga la factura, ya sea mediante un cargo automático o de forma manual.

El status también puede convertirse en trialing si ofreces pruebas que no requieren pagos. Cuando finaliza la prueba, la suscripción pasa a active y se comienza a cobrar al cliente suscrito.

Flujo de trabajo de creación y vencimiento de la suscripción

Comportamiento del pago de la suscripción

Para simplificar la gestión de pagos fallidos, crea suscripciones con payment_behavior establecido como default_incomplete. Esto crea suscripciones con estado incomplete, lo que te permite recopilar y confirmar la información de pago en una sola interfaz de usuario. Al usar allow_incomplete o error_if_incomplete, Stripe intenta pagar la factura de inmediato. Si se produce un error en el pago, el estado de la suscripción cambiará a incomplete o no se creará la suscripción.

Nota

Asynchronous payment methods, such as ACH Direct Debit, handle subscription status transitions differently than immediate payment methods. When you use asynchronous methods, subscriptions transition directly to an active state upon creation, bypassing the incomplete state typically associated with other payment types. If an asynchronous payment fails later, it voids the associated invoice; however, the subscription remains in the active state. This behavior contrasts with immediate payment methods, where failed payments often lead to incomplete or past_due states. Be aware of this distinction and implement appropriate logic to manage subscription status, access control, and payment retry mechanisms.

Pagos exitosos

Cuando tu cliente paga correctamente la factura, la suscripción se actualiza a active y la factura, a paid. En este momento puedes brindar acceso a tu producto.

Período de pago

Los clientes tienen aproximadamente 23 horas para efectuar el pago correctamente. Durante este período, la suscripción permanece en estado incomplete y la factura está open. Si el cliente paga la factura, la suscripción se actualiza a active y la factura, a paid. Si no efectúa ningún pago, la suscripción se actualiza a incomplete_expired y la factura, a void.

Este intervalo existe porque el cliente en general hace el primer pago de una suscripción durante la sesión. Si el cliente vuelve a tu aplicación después de transcurridas 23 horas, crea una nueva suscripción.

Pagos fallidos

Mientras los pagos automáticos se efectúen correctamente, el estado de la suscripción sigue siendo active. Si estos fallan, la suscripción se actualiza a past_due y Stripe intenta recuperar el pago según tus reglas de reintentos. Si la recuperación del pago falla, puedes cambiar el estado de la suscripción a canceled o unpaid, o puedes dejarlo como past_due.

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 ciclo de facturación, que permanecen en el estado draft. Para reactivar la suscripción:

  1. Recopila nueva información de pago si es necesario.

  2. Habilita el cobro automático configurando el anticipo automático en true en los borradores de facturas.

  3. 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 se tratan como paid cuando se determina el estado de la suscripción, aunque su propiedad pagada siga siendo false. Stripe ignora las facturas anuladas al determinar el estado de la suscripción; en su lugar, se utiliza la factura no anulada más reciente.

El status de una suscripción impaga se basa en la configuración de pagos fallidos del Dashboard.

Cancela suscripciones

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

Cómo invalidar una factura generada por una suscripción

Si anulas la primera factura de una suscripción, se aplica la siguiente lógica según el estado de la suscripción:

  • Si la suscripción está incomplete, el estado de la suscripción será incomplete_expired.
  • Si la suscripción está past_due, el estado de la suscripción será active.
  • Si la suscripción está active, el estado de la suscripción no cambiará.

Si anulas la factura más reciente de una suscripción activa que no es la primera, Stripe aplicará la siguiente lógica a cada factura, comenzando por la más reciente a la más antigua, hasta que cumpla con una de las siguientes condiciones:

  • Si el estado de la factura es paid o uncollectible, el estado de la suscripción será active.
  • Si el collection_method de la factura está establecido en charge_automatically, y Stripe dejó de reclamar el pago de la factura debido a un límite de reintentos, el estado de la suscripción será canceled, unpaid o past_due según tu configuración de cobros automáticos.
  • Si el collection_method se establece en send_invoice, y la factura está vencida, el estado de la suscripción será past_due.
  • Si la factura no está en ninguno de estos estados, se siguen los mismos pasos para la siguiente factura en orden más reciente.

Si ninguna factura cumple con los criterios anteriores, el estado de la suscripción será active.

Sesiones de Checkout

Para las integraciones de Stripe Checkout, no puedes actualizar la suscripción o su factura si la suscripción de la sesión está incomplete. Puedes escuchar el evento checkout.session.completed para realizar la actualización una vez finalizada la sesión.

También puedes dejar vencer la sesión si quieres cancelar la suscripción de la sesión, anular la factura de la suscripción o marcar la factura como incobrable.

Obtén información sobre las recomendaciones

Puedes usar Stripe Apps para afiliaciones y recomendaciones para configurar y administrar programas de recomendaciones y afiliaciones con Stripe, obtener información de clientes y automatizar los ajustes de comisiones desde el Dashboard de Stripe.

Estados de las suscripciones

EstadoDescripción
trialingThe subscription is currently in a trial period and you can safely provision your product for your customer. The subscription transitions automatically to active when a customer makes the first payment.
activeThe subscription is in good standing. For past_due subscriptions, paying the latest associated invoice or marking it uncollectible transitions the subscription to active. Note that active doesn’t indicate that all outstanding invoices associated with the subscription have been paid. You can leave other outstanding invoices open for payment, mark them as uncollectible, or void them as you see fit.
incompleteThe customer must make a successful payment within 23 hours to activate the subscription. Or the payment requires action, such as customer authentication. Subscriptions can also be incomplete if there’s a pending payment and the PaymentIntent status is processing.
incomplete_expiredThe initial payment on the subscription failed and the customer didn’t make a successful payment within 23 hours of subscription creation. These subscriptions don’t bill customers. This status exists so you can track customers that failed to activate their subscriptions.
past_duePayment on the latest finalized invoice either failed or wasn’t attempted. The subscription continues to create invoices. Your subscription settings determine the subscription’s next state. If the invoice is still unpaid after all attempted smart retries, you can configure the subscription to move to canceled, unpaid, or leave it as past_due. To move the subscription to active, pay the most recent invoice before its due date.
canceledThe subscription was canceled. During cancellation, automatic collection for all unpaid invoices is disabled (auto_advance=false). This is a terminal state that can’t be updated.
unpaidThe latest invoice hasn’t been paid but the subscription remains in place. The latest invoice remains open and invoices continue to generate, but payments aren’t attempted. Revoke access to your product when the subscription is unpaid because payments were already attempted and retried while past_due. To move the subscription to active, pay the most recent invoice before its due date.
pausedThe subscription has ended its trial period without a default payment method and the trial_settings.end_behavior.missing_payment_method is set to pause. Invoices are no longer created for the subscription. After attaching a default payment method to the customer, you can resume the subscription.

Eventos de suscripción

Los eventos se activan cada vez que se crea o cambia una suscripción. Algunos eventos se envían inmediatamente cuando se crea una suscripción, mientras que otros se repiten en intervalos de facturación regulares. Te recomendamos que escuches los eventos con puntos de conexión de webhook.

Asegúrate de que tu integración gestione los eventos de forma correcta. Por ejemplo, recomendamos enviarle un correo electrónico a un cliente si falla un pago o anular el acceso cuando se cancela una suscripción.

La siguiente tabla describe los eventos más comunes relacionados con las suscripciones y, donde sea relevante, sugiere qué medidas tomar para gestionar los eventos.

customer.createdSent when a Customer is successfully created.
customer.subscription.createdSent when the subscription is created. The subscription status might be incomplete if customer authentication is required to complete the payment or if you set payment_behavior to default_incomplete. View subscription payment behavior to learn more.
customer.subscription.deletedSe envía cuando se termina la suscripción de un cliente.
customer.subscription.pausedSent when a subscription’s status changes to paused. For example, this is sent when a subscription is configured to pause when a free trial ends without a payment method. Invoicing won’t occur until the subscription is resumed. We don’t send this event if payment collection is paused because invoices continue to be created during that time period.
customer.subscription.resumedSent when a subscription previously in a paused status is resumed. This doesn’t apply when payment collection is unpaused.
customer.subscription.trial_will_endSent three days before the trial period ends. If the trial is less than three days, this event is triggered.
customer.subscription.updatedSent when a subscription starts or changes. For example, renewing a subscription, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event.
entitlements.active_entitlement_summary.updatedSe envía cuando se actualizan los derechos activos de un cliente. Cuando recibas este evento, puedes proporcionar o anular el acceso a las funciones de tu producto. Lee más sobre integración con derechos.
invoice.createdSent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to invoice.created, then finalizing all invoices with automatic collection is delayed for up to 72 hours. Read more about finalizing invoices.
  • Respond to the notification by sending a request to the Finalize an invoice API.
invoice.finalizedSe envía cuando una factura se finaliza correctamente y está lista para pagarse.
  • You can send the invoice to the customer. View invoice finalization to learn more.
  • Depending on your settings, we automatically charge the default payment method or attempt collection. View emails after finalization to learn more.
invoice.finalization_failedThe invoice couldn’t be finalized. Learn how to handle invoice finalization failures by reading the guide. Learn more about invoice finalization in the invoices overview guide.
  • Inspect the Invoice’s last_finalization_error to determine the cause of the error.
  • If you’re using Stripe Tax, check the Invoice object’s automatic_tax field.
  • If automatic_tax[status]=requires_location_inputs, the invoice can’t be finalized and payments can’t be collected. Notify your customer and collect the required customer location.
  • Si automatic_tax[status]=failed, reintenta la solicitud más tarde.
invoice.paidSe envía cuando la factura se paga correctamente. Puedes brindar acceso a tu producto cuando recibas este evento y el status de la suscripción sea active.
invoice.payment_action_requiredSent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice requires action.

invoice.payment_failed

Falló el pago de una factura. El estado del PaymentIntent cambia a requires_action, mientras que el de la suscripción sigue siendo incomplete solo en la primera factura. Si falla un pago, puedes tomar varias medidas:

  • Notify the customer. Read about how you can configure subscription settings to enable Smart Retries and other revenue recovery features.
  • If you’re using PaymentIntents, collect new payment information and confirm the PaymentIntent.
  • Update the default payment method on the subscription.
invoice.upcomingSent a few days prior to the renewal of the subscription. The number of days is based on the number set for Upcoming renewal events in the Dashboard. For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add extra invoice items, if needed.
invoice.updatedSe envía tanto cuando un pago falla como cuando se efectúa correctamente. Si sucede esto último, el atributo paid se establece en true y el status será paid. Si el pago falla, paid se establece en false y el status permanecerá open. Los pagos fallidos también activan el evento invoice.payment_failed.
payment_intent.createdSent when a PaymentIntent is created.
payment_intent.succeededSent when a PaymentIntent has successfully completed payment.
subscription_schedule.abortedSe envía cuando se cancela un calendario de suscripciones porque el retraso en el pago canceló la suscripción relacionada.
subscription_schedule.canceledSe envía cuando se cancela un calendario de suscripciones, lo que también cancela las suscripciones asociadas activas.
subscription_schedule.completedSent when all phases of a subscription schedule complete.
subscription_schedule.createdSe envía cuando se crea un nuevo calendario de suscripciones.
subscription_schedule.expiringSe envía siete días antes de que expire el calendario de suscripción.
subscription_schedule.releasedSent when a subscription schedule is released, or stopped and disassociated from the subscription, which remains.
subscription_schedule.updatedSe envía cuando se actualiza un calendario de suscripciones.

Ciclo de vida de la factura

El resumen de las facturas brinda un panorama más claro de cómo funcionan las facturas, pero el ciclo de vida básico de las facturas generadas para suscripciones se ve así:

  1. La suscripción genera una factura nueva en estado draft.

  2. Aproximadamente una hora después de su creación, la factura se cierra y ya no puedes realizar cambios.

  3. El estado se establece en open, y Stripe automáticamente intentará pagarla usando el método de pago predeterminado.

  4. Si el pago se efectúa correctamente, el estado se actualiza a paid.

  5. Si el pago falla, la factura permanece open y la suscripción pasa a past_due.

En este flujo, Stripe no notifica a tu cliente sobre la factura. El pago de la factura se intenta automáticamente poco después de generarla. Sin embargo, si está habilitado el envío de correos electrónicos para clientes, enviamos el recibo por correo electrónico.

Configuración y recuperación de suscripciones

Tu configuración de suscripciones determina cómo Stripe responderá cuando falle un pago o cuando venza una suscripción.

Smart Retries

Después de crear la suscripción, el evento posible más importante es el error en el pago. El pago puede fallar por varios motivos:

  • Falta un método de pago del lado del cliente.
  • Venció el método de pago.
  • Se rechazó el pago.

Puedes configurar Stripe para reintentar los pagos fallidos. Smart Retries usa el modelo de machine learning de Stripe para elegir el momento óptimo y realizar el reintento, en un período que puede configurarse en hasta dos meses después del fallo del pago inicial.

También puedes modificar el calendario de reintentos mediante reglas personalizadas. Puedes definir hasta tres intentos, cada uno con un determinado intervalo de días entre intento e intento.

Puedes usar el evento invoice.payment_failed para controlar los eventos de errores en el pago de suscripciones y reintentar las actualizaciones. Después de un intento de pago en una factura, el valor next_payment_attempt se establece según la configuración de suscripción vigente en tu Dashboard.

Si falla la recuperación, la suscripción se comportará conforme a tu configuración. Estas son las opciones:

ConfiguraciónDescripción
Cancelar la suscripciónCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a canceled.
Marcar la suscripción como impagaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a unpaid. Las facturas se siguen generando y permanecen en borrador.
Dejar la suscripción como vencidaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción sigue siendo past_due. Las facturas se siguen generando y se le cobran al cliente según la configuración de los reintentos.

Después del último intento de pago, no hacemos más intentos. El cambio de la configuración de suscripciones solo afectará los reintentos futuros.

Correos electrónicos

Stripe tiene la opción de enviar distintos correos electrónicos a los clientes usando las direcciones de correo electrónico asociadas a cada objeto Customer:

  • Un recordatorio sobre una futura renovación al mismo tiempo que enviamos el evento invoice.upcoming.
  • Una notificación de pago fallido para solicitarle al cliente que actualice su información de pago. Obtén información sobre cómo activar las notificaciones de pagos fallidos.
  • Una notificación de tarjeta por vencer cuando la tarjeta default_source de un cliente esté a punto de vencer.

Puedes personalizar los logotipos y colores que tus clientes ven en los correos electrónicos y en nuestra página de pago de facturas alojadas cambiando la configuración de imagen de marca en el Dashboard.

Pago manual

Puedes configurar la fecha de vencimiento de las facturas que utilizan el método de cobro send_invoice para recibir pagos manuales. También puedes configurar hasta tres recordatorios, que inicien 10 días antes de la fecha de vencimiento y terminen 60 días después.

También puedes optar por tomar medidas adicionales sobre la suscripción 30, 60 o 90 días después del vencimiento de la factura. Estas son las opciones:

ConfiguraciónDescripción
Cancelar la suscripciónCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a canceled.
Marcar la suscripción como impagaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a unpaid. Las facturas se siguen generando y permanecen en el estado draft o pasan a un estado especificado en la configuración de la factura.
Dejar la suscripción como vencidaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción sigue siendo past_due. Las facturas se siguen generando en estado open.

Más información sobre estado de suscripciones.

Pagos que exigen 3D Secure

En caso de pagos que exigen 3D Secure, Stripe puede enviar un correo electrónico de confirmación a tu cliente al mismo tiempo que enviamos la invoice.payment_action_required. También puedes configurar el envío de hasta tres recordatorios, de uno a siete días después del inicio del pago.

Si sigue sin completarse el pago después de la cantidad de días especificada, puedes optar por lo siguiente:

ConfiguraciónDescripción
Cancelar la suscripciónCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a canceled.
Marcar la suscripción como impagaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción cambia a unpaid. Las facturas se siguen generando y permanecen en borrador.
Dejar la suscripción como vencidaCuando se alcanza el número máximo de días definido en el calendario de reintentos, el estado de la suscripción sigue siendo past_due. Las facturas se siguen generando y se le cobran al cliente según la configuración de los reintentos.

Períodos de prueba

Las redes de tarjeta exigen que les informes a tus clientes sobre sus períodos de prueba. Stripe puede encargarse de estas comunicaciones. En el Dashboard de Stripe, puedes configurar la URL de cancelación que se incluirá tanto en los correos electrónicos de recordatorio como en el recibo de la primera factura después de la finalización de la prueba. También puedes configurar cuál será la descripción del cargo en el extracto bancario para el primer cargo después de la finalización de la prueba. Obtén más información sobre estos requisitos y su configuración en la página de pruebas.

Modifica suscripciones

Stripe admite modificar suscripciones existentes sin tener que cancelarlas y volver a crearlas. Algunos de los cambios más importantes que puedes hacer son actualizar o rebajar el precio de la suscripción, o cancelar o pausar el cobro de una suscripción activa. Obtén más información sobre cómo modificar las suscripciones existentes.

¿Te fue útil esta página?
SíNo
¿Necesitas ayuda? Ponte en contacto con soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Contacto.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc
Productos utilizados
Billing