Actualizaciones pendientes

Aprende a gestionar pagos fallidos cuando se actualizan suscripciones.

Actualizar una suscripción genera una nueva factura cuando:

Debe abonarse la suscripción por primera vez, por ejemplo, porque ha finalizado un período de prueba.
Cambia el período de facturación.
Un cambio hecho en la suscripción da lugar a un prorrateo y proration_behavior=always_invoice.

De forma predeterminada, Stripe aplica actualizaciones independientemente de si el pago de la nueva factura se realiza correctamente. Si el pago falla, la reversión de las actualizaciones es un proceso manual. Debes crear una nueva factura, prorratear los ítems de la factura y luego reiniciar el pago. Sin embargo, con la función de actualizaciones pendientes, solo puedes realizar cambios en las suscripciones si el pago de la nueva factura se efectúa con éxito.

Antes de comenzar

Puedes usar actualizaciones pendientes si el collection_method de la suscripción es charge_automatically o si el método de pago de la suscripción es una tarjeta o Link.

Actualizar la suscripción
Lado del servidor

Puedes usar actualizaciones pendientes con las llamadas para actualizar la suscripción, crear el elemento de suscripción y actualizar el elemento de suscripción. Cuando hagas la actualización, debes definir payment_behavior=pending_if_incomplete. En el siguiente ejemplo, se agrega un nuevo precio a la suscripción. Debido a que proration_behavior=always_invoice, se crea una factura y se intenta el pago al hacer la actualización.

Si el pago es correcto, la suscripción se actualiza. Si el pago falla, el objeto Subscription recibido contiene un hash pending_update con los cambios:

{
  "id": "sub_49ty4767H20z6a",
  "object": "subscription",
  "application_fee_percent": null,
  "pending_update": {
    "expires_at": 1571194285,
    "subscription_items": [
      {
        "id": "si_09IkI4u3ZypJUk5onGUZpe8O",
        "price": "price_CBb6IXqvTLXp3f"
      }
    ]
  },
}

Gestiona pagos fallidos
Lado del cliente

Después de hacer la actualización, verifica el hash pending_update en la suscripción o escucha el evento customer.subscription.updated en tu webhook. Un hash pending_update completado automáticamente significa que el pago falló y que no se aplicó la actualización de tu suscripción.

Crea una lógica para gestionar los pagos fallidos que se deben a rechazos de tarjetas y solicitudes de autenticación de clientes:

En caso de rechazos de tarjetas, adjunta un nuevo método de pago al cliente. A continuación, usa el punto de conexión de pagos para abonar la factura generada por la actualización.
Para la autenticación de clientes, sigue el flujo que requiere acción.

Un pago efectuado correctamente aplica de inmediato los cambios en el hash pending_update y actualiza la factura a paid.

Si el pago vuelve a fallar, queda el hash pending_update en la suscripción con la fecha de vencimiento original y no se aplica ningún cambio.

OpcionalCancelar o modificar actualizaciones pendientes
Lado del servidor

Atributos admitidos para actualizaciones pendientes

Las actualizaciones pendientes solo admiten atributos que controlan el comportamiento de prorrateo o generan nuevas facturas.

El punto de conexión de actualización de suscripción admite los siguientes atributos:

expand
payment_behavior
proration_behavior
proration_date
billing_cycle_anchor
items
- price
- quantity
trial_end
trial_from_plan
add_invoice_items

Los puntos de conexión para crear un elemento de suscripción y actualizar un elemento de suscripción admiten los siguientes atributos:

expand
payment_behavior
proration_behavior
proration_date
price
quantity

Actualizaciones vencidas

Si no realizas ninguna acción después de que falle una actualización, Stripe anulará la factura y descartará la actualización después de que venza.

El tiempo expired_at de una actualización pendiente coincide con la primera aparición del final del período de prueba o el final del período items.current más próximo. Esto se aplica si cualquiera de las dos horas es dentro de las 23 horas posteriores a la solicitud de actualización. De lo contrario, el vencimiento es de 23 horas a partir de la solicitud de actualización.

Stripe también anula automáticamente la factura y elimina la actualización pendiente si se produce cualquiera de los siguientes eventos:

La suscripción alcanza un umbral de facturación.
El calendario de suscripciones vinculado a la suscripción pasa a una nueva fase.

Eventos de actualizaciones pendientes

Usa webhooks para escuchar los siguientes eventos relacionados con actualizaciones pendientes:

Evento	Propósito
`customer.subscription.updated`	Recibe notificaciones sobre suscripciones, verifica el hash `pending_updates` y resuelve los errores de pago si es necesario.
`customer.subscription.pending_update_applied`	Recibe notificaciones cuando se apliquen actualizaciones pendientes para que puedas tomar medidas adicionales, como actualizar o degradar servicios, aprovisionarlos o desaprovisionarlos.
`customer.subscription.pending_update_expired`	Recibe notificaciones cuando las actualizaciones pendientes caduquen o se anulen automáticamente y, si es necesario, vuelve a intentar la solicitud de actualización.

Actualizaciones y calendarios de suscripciones pendientes

Puedes usar tanto actualizaciones pendientes como calendarios de suscripciones para administrar suscripciones. Un cambio de fase de programación descarta una actualización pendiente y anula la factura asociada. Vuelve a intentar la solicitud de actualización después de la transición de fase, si es necesario.

Ítems de consumo medido

Si una suscripción incluye ítems de consumo medido, Stripe factura cualquier consumo pendiente en la factura de actualización pendiente. Sin embargo, si la actualización pendiente vence antes del pago, Stripe descarta este consumo, lo que impide que las facturas posteriores puedan facturarlos.

Si la actualización pendiente elimina un precio por consumo medido, Stripe no tiene en cuenta el consumo informado entre la creación de la actualización pendiente y el pago de la factura resultante. No puedes facturar por ese consumo. Sin embargo, si la suscripción contiene billing_mode=flexible, Stripe factura por el consumo al quitar un precio por consumo medido.