# Cómo usar webhooks con suscripciones

Aprende a usar webhooks para recibir notificaciones de actividad en las suscripciones.

Recibes notificaciones de Stripe en tu aplicación a través de eventos de webhook. Procesa estos eventos en un punto de conexión de webhook u otros destinos como Amazon EventBridge o Azure Event Grid mediante la creación de un [destino de evento](https://docs.stripe.com/events/set-up-events.md). Una integración de *suscripciones* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) requiere un destino que gestione eventos de webhook, ya que la mayor parte de la actividad de las suscripciones ocurre de forma asíncrona.

Para usar webhooks con tus suscripciones:

1. Crea un punto de conexión de webhook en tu aplicación.
2. Registra tu [punto de conexión de webhook](https://docs.stripe.com/webhooks.md) en Workbench.
3. Agrega lógica para gestionar eventos de Stripe. En el caso de las suscripciones, esto incluye los pagos fallidos y los cambios en los estados de las suscripciones (como pasar del estado `trial` a `active`). Puedes usar el [webhook de inicio rápido](https://docs.stripe.com/webhooks/quickstart.md) para crear un punto de conexión mínimo de webhook. Asegúrate de [verificar que los eventos entrantes provengan de Stripe](https://docs.stripe.com/webhooks.md#verify-events).
4. Prueba el punto de conexión del webhook para confirmar que funciona según lo previsto.

Si tu solicitud se ejecuta en AWS, puedes [configurar Stripe para enviar eventos directamente a AWS EventBridge en tu cuenta de AWS](https://docs.stripe.com/event-destinations/eventbridge.md). Si tu solicitud se ejecuta en Azure, puedes [configurar Stripe para enviar eventos de manera directa a Azure Event Grid en tu suscripción a Azure](https://docs.stripe.com/event-destinations/eventgrid.md).

## Eventos de suscripción

Stripe activa los [eventos](https://docs.stripe.com/api.md#event_types) cada vez que se crea o modifica una suscripción. Cuando se crea una suscripción, algunos eventos se envían de inmediato, mientras que otros se repiten en períodos de facturación regulares.

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.

En la siguiente tabla se describen los eventos más comunes relacionados con las suscripciones y, si corresponde, se sugieren acciones para controlar los eventos.

> La API Accounts v2 está en GA para los usuarios de Connect y en versión preliminar pública para otros usuarios de Stripe.
> 
> Independientemente de si usas objetos de [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) o [Customer](https://docs.stripe.com/api/customers.md) para representar a tus clientes, usa los eventos `customer.subscription` para realizar el seguimiento de los eventos de suscripción.

| Evento | Descripción |
| --- | --- |
| `v2.core.account.created` | Se envía cuando se crea correctamente una [Account v2](https://docs.stripe.com/api/v2/core/accounts/object.md). |
| `customer.created` | Se envía cuando se crea correctamente un objeto [Customer](https://docs.stripe.com/api/customers/object.md). |
| `customer.subscription.created` | Se envía cuando se crea la suscripción. El `status` de la suscripción puede ser `incomplete` si se necesita la autenticación del cliente para completar el pago o si se establece `payment_behavior` en [default_incomplete](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). |
| `customer.subscription.deleted` | Se envía cuando se termina la suscripción de un cliente. |
| `customer.subscription.paused` | Se envía cuando el valor de `status` de una suscripción cambia a `paused`; por ejemplo, si [configuras](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) una suscripción en pausa cuando finaliza una [prueba sin cargo sin un método de pago](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment). La facturación no se producirá hasta que se [reanude](https://docs.stripe.com/api/subscriptions/resume.md) la suscripción. No enviamos este evento si [suspendes el cobro de pagos](https://docs.stripe.com/billing/subscriptions/pause-payment.md) porque se siguen creando facturas durante ese período. |
| `customer.subscription.resumed` | Se envía cuando reanudas una suscripción en estado `suspendido`. Esto no se aplica cuando [despausas el cobro de pagos](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing). |
| `customer.subscription.trial_will_end` | Se envía tres días antes de que [finalice el período de prueba](https://docs.stripe.com/billing/subscriptions/trials.md). Si la prueba es de menos de tres días, se activa este evento. |
| `customer.subscription.updated` | Se envía cuando se inicia o [cambia](https://docs.stripe.com/billing/subscriptions/change.md) una suscripción. Por ejemplo, este evento se activa cuando se renueva una suscripción, se agrega un cupón, se aplica un descuento, se agrega una partida de factura o se cambia de plan. |
| `entitlements.active_entitlement_summary.updated` | Se 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](https://docs.stripe.com/billing/entitlements.md). |
| `invoice.created` | Se envía cuando se crea una factura para una suscripción renovada o una nueva. Si Stripe no recibe una respuesta correcta al evento `invoice.created`, la finalización de todas las facturas con [cobro automático](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) se retrasará hasta 72 horas. Obtén más información sobre [cómo finalizar facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized).
- Para responder a la notificación, envía una solicitud a la API [Finalize an invoice](https://docs.stripe.com/api/invoices/finalize.md). |
| `invoice.finalized` | Se envía cuando una factura se finaliza correctamente y está lista para pagarse.
- Puedes enviar la factura al cliente. Consulta la [finalización de la factura](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) para obtener más información.
- Según tu configuración, cobramos automáticamente al método de pago predeterminado o intentamos el cobro. Consulta los [correos electrónicos posteriores a la finalización](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails) para obtener más información. |
| `invoice.finalization_failed` | No se pudo finalizar la factura. Obtén más información sobre [cómo gestionar los errores en la finalización de facturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures) y la [finalización de facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized).
- Inspecciona el [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) de la factura para determinar la causa del error.
- Si usas Stripe Tax, marca el campo [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) del objeto `Factura`.
- Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y cobra la [ubicación del cliente](https://docs.stripe.com/tax/customer-locations.md) requerida.
- Si `automatic_tax[status]=failed`, reintenta la solicitud más tarde. |
| `invoice.paid` | Se 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_required` | Se envía cuando la factura requiere la autenticación del cliente. Aprende a gestionar la suscripción cuando la factura [requiere intervención](https://docs.stripe.com/billing/subscriptions/overview.md#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` *only* en la primera factura de la suscripción. Si falla un pago, puedes tomar varias medidas:

- Notifica al cliente.
- Realiza la [configuración de la suscripción](https://dashboard.stripe.com/settings/billing/automatic) en el Dashboard para habilitar [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) y otras funcionalidades de recuperación de ingresos.
- Si estás usando PaymentIntents, recopila la nueva información de pago y [confirma el PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md).
- Actualiza el [método de pago predeterminado](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) en la suscripción. |
| `invoice.upcoming` | Se envía unos días antes de la renovación de la suscripción. La cantidad de días se basa en el número establecido en **Próximos eventos de renovación** en el [Dashboard](https://dashboard.stripe.com/settings/billing/automatic). Para las suscripciones existentes, el cambio del número de días entrará en vigencia en el siguiente período de facturación. De ser necesario, aún puedes agregar [más partidas de factura](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). |
| `invoice.updated` | Se envía tanto cuando un pago falla como cuando se efectúa correctamente. Si sucede esto último, el atributo `paid` se establecerá en `true` y el valor de `status` será `paid`. Si el pago falla, el valor de `paid` será `false` y el de `status` seguirá siendo `open`. Los errores en los pagos también activan un `invoice.payment_failed`. |
| `payment_intent.created` | Se envía cuando se crea una [PaymentIntent](https://docs.stripe.com/api/payment_intents.md). |
| `payment_intent.succeeded` | Se envía cuando un PaymentIntent ha completado correctamente un pago. |
| `subscription_schedule.aborted` | Se envía cuando se cancela un calendario de suscripciones porque el retraso en el pago canceló la suscripción relacionada. |
| `subscription_schedule.canceled` | Se envía cuando se cancela un calendario de suscripciones, lo que también cancela las suscripciones asociadas activas. |
| `subscription_schedule.completed` | Se envía cuando se completan todas las [fases](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-phases) de un calendario de suscripciones. |
| `subscription_schedule.created` | Se envía cuando se crea un nuevo calendario de suscripciones. |
| `subscription_schedule.expiring` | Se envía siete días antes de que expire el calendario de suscripción. |
| `subscription_schedule.released` | Se envía cuando se [lanza](https://docs.stripe.com/api/subscription_schedules/release.md) un calendario de suscripción, o cuando se pausa y desvincula dicho calendario de la suscripción. La suscripción permanece. |
| `subscription_schedule.updated` | Se envía cuando se actualiza un calendario de suscripciones. |

## Gestionar eventos de riesgo y de datos de clientes

Los eventos del ciclo de vida de la suscripción anteriores notifican a tu integración respecto de los cambios en la facturación y los derechos. Si tu integración de producción acepta pagos, también gestiona los eventos de reembolsos, disputas y alertas de fraude. De lo contrario, tu integración no recibirá notificaciones cuando alguien dispute un cargo o lo marque como posible fraude.

Si tu integración almacena datos del cliente de manera local, también considera gestionar `customer.updated`.

| Evento | Por qué es importante para las suscripciones |
| --- | --- |
| `charge.dispute.created` | Un cliente o su banco disputó un cargo. Usa este evento para decidir si enviar evidencia, restringir el acceso a la cuenta o realizar otra acción. Consulta [Cómo gestionar los eventos de reembolso, disputa y alerta preventiva de fraude](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events) para resolver la suscripción asociada. |
| `charge.refunded` | Un cargo asociado a una factura de suscripción recibió un reembolso total o parcial. Consulta [Cómo gestionar los eventos de reembolso, disputa y alerta preventiva de fraude](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events) para resolver la suscripción asociada. |
| `radar.early_fraud_warning.created` | Un emisor de tarjeta o una red identificó un cargo como posiblemente fraudulento, por lo general antes de una disputa formal. Consulta [Cómo gestionar los eventos de reembolso, disputa y alerta preventiva de fraude](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events) para resolver la suscripción asociada. |
| `customer.updated` | Stripe envía este evento cuando cambia cualquier propiedad de un [Cliente](https://docs.stripe.com/api/customers/object.md). Los flujos del [Portal de clientes](https://docs.stripe.com/customer-management.md) pueden actualizar detalles a nivel del cliente, como la información de facturación o el método de pago predeterminado. Escucha este evento si almacenas datos del cliente a nivel local o dependes de los cambios en el campo del cliente. En su lugar, si usas [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) para representar a los clientes, escucha `v2.core.account[configuration.customer].updated` para los cambios en la configuración del cliente y `v2.core.account[identity].updated` para los cambios de identidad. |

Suscríbete solo a los eventos que requiera tu integración. Si omites los eventos de riesgo, tu aplicación no se enterará de las disputas o alertas de fraude hasta que revises el Dashboard.

## Gestionar pagos fallidos

Los eventos le proporcionan a Stripe una forma confiable de notificar los errores de pago en las facturas de suscripciones. Algunos errores en el pago son temporales; por ejemplo, el emisor de una tarjeta puede rechazar el cargo inicial, pero permitir un reintento automático. Otros errores en el pago son definitivos y requieren acción, como no tener un método de pago utilizable para el cliente.

| Evento | Descripción |
| --- | --- |
| `invoice.payment_failed` | Falló el pago de una factura. El estado del PaymentIntent cambia a `requires_payment_method`. El estado de la suscripción cambia a `incomplete`. Si se produce un error en un pago, hay varias medidas que se pueden tomar:

- Notifica al cliente.
- Si estás usando PaymentIntents, recopila la nueva información de pago y [confirma el PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md).
- Actualiza el [default payment method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) en la suscripción.
- Considera habilitar [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md). |

## Gestionar pagos que requieren una acción adicional

Es posible que algunos métodos de pago deban cumplir con pasos adicionales, como la autenticación del cliente. Si recibes estos eventos, tu aplicación tendrá que solicitarle al cliente que lleve a cabo la acción requerida. Para obtener detalles sobre cómo [gestionar eventos que requieren acciones adicionales](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action), lee la guía resumida sobre suscripciones.

| Evento | Descripción |
| --- | --- |
| `invoice.finalization_failed` | No se pudo finalizar la factura. Lee la guía y aprende a [gestionar los fallos de finalización de facturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures). En la guía resumida sobre facturas, encontrarás más información la [finalización de facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized).
- Inspecciona el [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) del objeto Invoice para determinar la causa del error.
- Si usas Stripe Tax, revisa el campo [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-automatic_tax) del objeto Factura.
- Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la [ubicación del cliente](https://docs.stripe.com/tax/customer-locations.md). requerida.
- Si `automatic_tax[status]=failed`, vuelve a intentar la solicitud más tarde. |
| `invoice.payment_failed` | Falló el pago de una factura. El estado de PaymentIntent cambia a `requires_action`. El estado de la suscripción cambia a `incomplete`. Si se produce un error en un pago, hay varias medidas que se pueden tomar:

- Notifica al cliente.
- Si estás usando PaymentIntents, recopila la nueva información de pago y [confirma el PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md).
- Actualiza el [default payment method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) en la suscripción.
- Considera habilitar [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md). |
| `invoice.payment_action_required` | Se envía cuando la factura requiere la autenticación del cliente. Aprende a gestionar la suscripción cuando la factura [requiere intervención](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). |

## Cómo gestionar eventos de reembolso, disputa y alerta preventiva de fraude

Cuando un cargo asociado a una suscripción se reembolsa, se disputa o se marca como fraude, Stripe envía uno de los siguientes eventos:

- `charge.refunded`: contiene [Charge](https://docs.stripe.com/api/charges/object.md) actualizado.
- `charge.dispute.created`: contiene [Dispute](https://docs.stripe.com/api/disputes/object.md), que expone [charge](https://docs.stripe.com/api/disputes/object.md#dispute_object-charge) y [payment_intent](https://docs.stripe.com/api/disputes/object.md#dispute_object-payment_intent), que admite valores nulos.
- `radar.early_fraud_warning.created`: contiene [EarlyFraudWarning](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md), que expone [charge](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md#early_fraud_warning_object-charge) y [payment_intent](https://docs.stripe.com/api/radar/early_fraud_warnings/object.md#early_fraud_warning_object-payment_intent), que admite valores nulos.

Algunos cargos y PaymentIntents no están asociados a una factura o suscripción. La forma de identificar la suscripción depende de tu versión de la API.

### Versión de la API 2025-03-31.basil o posterior

1. Obtén el ID de [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md). Para `charge.refunded`, usa el campo [payment_intent](https://docs.stripe.com/api/charges/object.md#charge_object-payment_intent) en Charge. Para `charge.dispute.created` o `radar.early_fraud_warning.created`, usa el campo `payment_intent` en el objeto Dispute o EarlyFraudWarning. Si `payment_intent` es nulo, [recupera Charge](https://docs.stripe.com/api/charges/retrieve.md) y usa el campo [payment_intent](https://docs.stripe.com/api/charges/object.md#charge_object-payment_intent). Si Charge tampoco tiene una `payment_intent` (por ejemplo, un cargo directo heredado), no se aplica este procedimiento.
2. Usa el punto de conexión [Enumerar todos los pagos de una factura](https://docs.stripe.com/api/invoice-payment/list.md) con [payment.type](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-payment-type) establecido en `payment_intent`, [payment.payment_intent](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-payment-payment_intent) establecido en el ID de PaymentIntent, y [status](https://docs.stripe.com/api/invoice-payment/list.md#list_invoice_payments-status) establecido en `paid`. Si la lista está vacía, este procedimiento no puede resolver una factura asociada.
3. PaymentIntent puede estar asociada a varias facturas, por lo que este punto de conexión puede devolver más de un `InvoicePayment`. Pagina todos los resultados mientras `has_more` sea true; cada `InvoicePayment` contiene un campo [invoice](https://docs.stripe.com/api/invoice-payment/object.md#invoice_payment_object-invoice) con el ID de factura asociado.
4. Para cada ID de factura, recupera la factura y verifica que [parent.type](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-type) sea `subscription_details`. Luego, usa [parent.subscription_details.subscription](https://docs.stripe.com/api/invoices/object.md#invoice_object-parent-subscription_details-subscription) para obtener [Subscription](https://docs.stripe.com/api/subscriptions/object.md).

### Versiones de la API anteriores a 2025-03-31.basil

En las versiones anteriores de la API, el objeto Charge incluye un campo [invoice](https://docs.stripe.com/api/charges/object.md?api-version=2025-02-24.acacia#charge_object-invoice).

1. Obtén Charge. Para `charge.refunded`, usa Charge del evento. Para `charge.dispute.created` o `radar.early_fraud_warning.created`, el campo `charge` en Dispute o EarlyFraudWarning es un ID. [Recupera Charge](https://docs.stripe.com/api/charges/retrieve.md) mediante ese ID.
2. Si el campo `invoice` de Charge es nulo, este procedimiento no puede resolver una factura asociada. De lo contrario, recupera la factura y usa el campo [Subscription](https://docs.stripe.com/api/invoices/object.md?api-version=2025-02-24.acacia#invoice_object-subscription) para obtener la suscripción.

## Hacer el seguimiento de suscripciones activas

Las suscripciones necesitan que exista coordinación entre tu sitio y Stripe. El acceso del cliente a tu producto o servicio depende de si se concretan o no los pagos recurrentes.

En las integraciones típicas, almacenas las credenciales de los clientes y un valor de marca de tiempo asignado que representa la fecha de vencimiento del acceso de ese cliente en tu sitio cuando se suscribe. Cuando el cliente inicia sesión, compruebas si la marca de tiempo aún está con fecha futura. De ser así, la cuenta está activa y el cliente aún debería tener acceso al servicio.

Cuando se [renueva](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle) la suscripción, Stripe factura al cliente e intenta cobrar el pago mediante [el cobro automático](https://docs.stripe.com/invoicing/automatic-charging.md) del método de pago registrado o [enviando la factura](https://docs.stripe.com/invoicing/integration.md#accept-invoice-payment) por correo electrónico a los clientes. Stripe notifica a tu sitio el estado de la factura mediante el envío de un evento de webhook:

1. Tu sitio recibe un evento `invoice.paid`.

   - Cuando se cobra automáticamente un método de pago, tu sitio recibe primero un evento `invoice.upcoming` en tu [punto de conexión de webhook](https://docs.stripe.com/webhooks.md) configurado unos días antes de la renovación. Puedes escuchar este evento para [agregar elementos de factura adicionales](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items) a la próxima factura. Si `collection_method=send_invoice`, Stripe no envía un evento `invoice.upcoming`.

2. La aplicación encuentra el cliente para el que se realizó el pago.

3. Después de recibir `invoice.paid`, recupera la suscripción asociada y confirma que su estado es `active` antes de extender la fecha de vencimiento del acceso del cliente. Una factura pagada no necesariamente cambia la suscripción a `active` cuando la resolución del estado usa todas las facturas.

## Captar los cambios de estado de las suscripciones

Asegúrate de que tu integración gestione y controle de forma correcta las transiciones entre los estados de suscripción descritos en la tabla a continuación.

Algunos cambios de estado necesitan atención especial:

- Unos días antes de que finalice una prueba y la suscripción pase de `trialing` a `active`, recibirás un evento `customer.subscription.trial_will_end`. Cuando recibas este evento, verifica que tienes un método de pago del cliente para poder facturarle. Opcionalmente, notifica al cliente que se le cobrará.

- Cuando una suscripción pasa a `past_due`, notifica directamente al cliente y solicítale que actualice sus datos de pago. Stripe ofrece varias funcionalidades que ayudan a automatizar este proceso. Obtén más información sobre la [recuperación de ingresos](https://docs.stripe.com/billing/revenue-recovery.md).

- Cuando una suscripción cambia a `canceled` o `unpaid`, revoca el acceso a tu producto.

| 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á al día. Tu [configuración de suscripciones](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments) determina qué facturas se deben liquidar para que una suscripción `past_due` pase a ser `active`. Cuando la resolución del estado usa la factura más reciente, Stripe usa la factura más reciente no anulada para determinar el estado de la suscripción. Pagar esa factura o marcarla de forma manual como incobrable hace que la suscripción pase a ser `active`. Cuando la resolución del estado usa todas las facturas, liquida todas las facturas pendientes correspondientes para que la suscripción pase a ser `active`.

`active` no necesariamente indica que se hayan pagado todas las facturas pendientes asociadas a la suscripción. Cuando la resolución del estado usa la factura más reciente, puedes dejar otras facturas pendientes abiertas para su pago, marcarlas como incobrables o anularlas según consideres oportuno. |
| `incomplete` | El cliente debe realizar un pago exitoso en un plazo de 23 horas para activar la suscripción. O bien, el pago [requiere una acción](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action), como la autenticación del cliente. Las suscripciones también pueden estar `incomplete` si hay un pago pendiente y el estado del 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` | Se produjo un error en el pago de la última factura finalizada o no se intentó. Cuando la resolución del estado usa todas las facturas, `past_due` también puede indicar que una factura correspondiente anterior sigue pendiente. La suscripción sigue creando facturas. Stripe podría volver a intentar el pago mientras la suscripción esté `past_due`, pero este estado no garantiza otro intento de pago. La [configuración de suscripciones](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments) de tu Dashboard determina el próximo estado de la suscripción. Si una factura sigue sin pagarse después de todos los [reintentos de pago](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md), puedes configurar la suscripción para que pase a ser `canceled` o `unpaid`, o bien para que siga siendo `past_due`.

Para reactivar la suscripción, paga la factura más reciente no anulada o márcala de forma manual como incobrable cuando la resolución del estado utilice la factura más reciente, o liquida las facturas pendientes correspondientes cuando la resolución del estado utilice todas las facturas. La suscripción pasará a ser `active` independientemente de si liquidas las facturas requeridas antes o después de su fecha de vencimiento. |
| `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` | Stripe establece el estado de una suscripción en `unpaid` solo cuando la [configuración de suscripciones](https://dashboard.stripe.com/settings/billing/subscriptions#manage-failed-payments) de tu Dashboard selecciona este resultado. La factura o las facturas que rigen el estado de la suscripción no se liquidaron, pero la suscripción se mantiene. La suscripción sigue generando facturas, pero no intenta realizar el pago. Revoca el acceso a tu producto cuando la suscripción esté en `unpaid` porque Stripe ya intentó y reintentó el pago mientras la suscripción estaba en `past_due`. Para cambiar la suscripción a `active`, paga la factura más reciente no anulada o márcala de forma manual como incobrable cuando la resolución del estado utilice la factura más reciente, o liquida las facturas pendientes correspondientes cuando la resolución del estado utilice todas las facturas. |
| `paused` | La suscripción ha finalizado su período de prueba sin un método de pago predeterminado y el [trial_settings.end_behavior.missing_payment_method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment) está establecido en `pausa`. Ya no se crean facturas para la suscripción. Después de adjuntar un método de pago predeterminado al cliente, puedes [reanudar la suscripción](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#resume-a-paused-subscription). |

## Puntos de conexión de webhook y facturas

Registra un punto de conexión de webhooks para hacer un seguimiento de los estados de las facturas. La integración de tu suscripción depende de finalizar correctamente las facturas y gestionar adecuadamente los errores de finalización de facturas.

Cuando habilitas el [cobro automático](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md), Stripe finaliza automáticamente y da inicio al cobro automático de la [factura](https://docs.stripe.com/billing/invoices/subscription.md)…

- Si Stripe no recibe una respuesta correcta al evento `invoice.created`, retrasaremos la finalización de todas las facturas con [cobro automático](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) hasta 72 horas, salvo aquellas en las que hayas [establecido una hora de finalización programada personalizada](https://docs.stripe.com/invoicing/scheduled-finalization.md).
- Una respuesta adecuada al evento `invoice.created` incluye la gestión de todos los puntos de conexión de webhooks configurados para tu cuenta y para cualquier plataforma con la que te hayas conectado. Estas no incluyen ningún punto de conexión de webhook configurado en una [organización](https://docs.stripe.com/get-started/account/orgs.md). Si bien puedes recibir notificaciones de eventos `invoice.created` en la organización, una respuesta correcta no afecta la finalización de la factura cuando se usa el cobro automático.
- Si se actualiza una suscripción de forma que se intenta el pago de manera sincrónica (en la factura inicial y en algunos tipos de actualizaciones), no se da esta espera.
- La falla en la finalización de la factura evita el cobro del pago de la factura. Asegúrate de recibir notificaciones de eventos `invoice.finalization_failed` en tu punto de conexión de webhooks.

### Eventos de webhook relacionados con la finalización de facturas

Consulta una lista completa de los [tipos de eventos de factura](https://docs.stripe.com/api/events/types.md#event_types-invoice.created).

| Evento | Descripción |
| --- | --- |
| `invoice.created` | La factura se creó correctamente y está lista para finalizarse. Lee la documentación para aprender más sobre [cómo finalizar facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized).
- Para responder a la notificación, envía una solicitud a la API [Finalize an invoice](https://docs.stripe.com/api/invoices/finalize.md). |
| `invoice.finalized` | La factura se finalizó correctamente y está lista para pagarse.
- Puedes enviar la factura al cliente. Obtén más información sobre la [finalización de facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized).
- Según tu configuración, Stripe cobra automáticamente al método de pago predeterminado o intenta el cobro. Obtén más información sobre los [correos electrónicos posteriores a la finalización](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails). |
| `invoice.finalization_failed` | No se pudo finalizar la factura. Lee la guía y aprende a [gestionar los fallos de finalización de facturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures). Obtén más información sobre la [finalización de facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) en la guía resumida sobre facturas.
- Inspecciona el [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) del objeto Invoice para determinar la causa del error.
- Si usas Stripe Tax, revisa el campo [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) del objeto Invoice.
- Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y recopila la [ubicación del cliente](https://docs.stripe.com/tax/customer-locations.md) requerida.
- Si `automatic_tax[status]=failed`, reintenta la solicitud más tarde. |

### Finalización correcta de una factura

Stripe espera una hora después de recibir una respuesta correcta al evento `invoice.created` antes de intentar el pago. Si no recibimos ninguna respuesta correcta en el término de 72 horas, intentaremos finalizar la factura y enviarla.

Si quieres procesar las facturas puntuales de manera distinta a las facturas de suscripciones, revisa la propiedad `subscription` en el cuerpo del webhook. Esto indica si la factura fue creada para una suscripción.

En modo activo, si el punto de conexión de webhooks no responde adecuadamente, Stripe sigue reintentando la notificación de webhooks hasta por 3 días con un retroceso exponencial. En un entorno de prueba, reintentamos tres veces en el transcurso de unas horas. Durante ese período, no intentaremos cobrarle al cliente a menos que recibamos una respuesta correcta. También te notificaremos por correo electrónico que el webhook está devolviendo un error.

Este comportamiento se aplica a todos los puntos de conexión de webhooks definidos en tu cuenta, incluidos aquellos casos en que una [aplicación de Connect](https://stripe.com/works-with) u otro servicio de terceros tenga problemas para gestionar webhooks entrantes.

### Fallo en la finalización de una factura

Si Stripe no puede finalizar una factura, se envía un [evento](https://docs.stripe.com/api/events/types.md#event_types-invoice.finalization_failed) `invoice.finalization_failed` a tu punto de conexión de webhooks. Si las facturas no se pueden finalizar, las suscripciones permanecen activas, por lo que es posible que los usuarios sigan teniendo acceso a tu producto, pero tú no puedas cobrar los pagos. Asegúrate de tomar medidas sobre las facturas que devuelven un error en la finalización. No puedes cobrar los pagos de una factura que no esté finalizada.

Para determinar por qué falló la finalización de la factura, revisa el [campo](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) `last_finalization_error` del objeto Invoice. Este campo proporciona más información sobre el error y cómo proceder.

Si usas Stripe Tax, comprueba si el campo [automatic_tax.status](https://docs.stripe.com/api/invoices/object.md#invoice_object-automatic_tax-status) es `requires_location_inputs`, lo que indica que los datos de la dirección no son válidos o no son suficientes. Si Stripe Tax no puede encontrar una ubicación de cliente reconocida, no podemos finalizar la factura. Aprende a [gestionar los errores en la finalización de facturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures).

## Pruebas

Para probar tu punto de conexión de webhook o [destino de eventos](https://docs.stripe.com/events/how-events-work.md), elige una de las dos opciones siguientes:

1. Realiza acciones en un entorno de prueba que activen eventos legítimos en tu destino de eventos. Por ejemplo, para activar el evento [charge.succeeded](https://docs.stripe.com/api.md#event_types-charge.succeeded), puedes usar una [tarjeta de prueba que produzca un cargo exitoso](https://docs.stripe.com/testing.md#cards).
2. [Activa eventos con la CLI de Stripe](https://docs.stripe.com/webhooks.md#test-webhook) o con [Stripe para Visual Studio Code](https://docs.stripe.com/stripe-vscode.md#webhooks).

## See also

- [Ciclo de vida de la suscripción](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle)
- [Cómo probar suscripciones](https://docs.stripe.com/billing/testing.md)