# Actualizaciones pendientes Aprende a gestionar pagos fallidos cuando se actualizan suscripciones. Actualizar una *suscripción* (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) genera una nueva *factura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) 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`. Varias actualizaciones de suscripciones no generan nuevas facturas ni provocan actualizaciones pendientes, como por ejemplo: - Cambios en la configuración (métodos de pago, configuración fiscal, ajustes de reintentos) - Actualizaciones de metadatos en suscripciones o partidas de suscripción - Cómo agregar o actualizar cupones o códigos de promoción que se apliquen a facturas futuras - Ajustes del umbral de facturación - Establecer `cancel_at_period_end` en `true` - Agregar cargos puntuales con `add_invoice_items` Estas actualizaciones se aplican de inmediato sin afectar los pagos. Para ver la lista completa, consulta [Qué no genera prorrateos](https://docs.stripe.com/billing/subscriptions/prorations.md#no-prorations). 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. ## Before you begin Puedes usar actualizaciones pendientes si el [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) de la suscripción es `charge_automatically` y el método de pago es uno de los siguientes: - [Tarjeta](https://docs.stripe.com/payments/cards.md) - [Link](https://docs.stripe.com/payments/link.md) - [Alipay](https://docs.stripe.com/payments/alipay.md) - [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md) - [Afterpay/Clearpay](https://docs.stripe.com/payments/afterpay-clearpay.md) - [Apple Pay](https://docs.stripe.com/apple-pay.md) - [Amazon Pay](https://docs.stripe.com/payments/cash-app-pay.md) - [EPS](https://docs.stripe.com/payments/eps.md) - [GoPay](https://docs.stripe.com/payments/gopay.md) - [Google Pay](https://docs.stripe.com/google-pay.md) - [Kakao Pay](https://docs.stripe.com/payments/kakao-pay/accept-a-payment.md) - [Klarna](https://docs.stripe.com/payments/klarna.md) - [Tarjeta KR](https://docs.stripe.com/payments/kr-card/accept-a-payment.md) - [Naver Pay](https://docs.stripe.com/payments/naver-pay/accept-a-payment.md) - [Tarjeta NG](https://docs.stripe.com/payments/ng-card/accept-a-payment.md) - [PayPal](https://docs.stripe.com/payments/paypal.md) - [PayTo](https://docs.stripe.com/payments/payto.md) - [Pix](https://docs.stripe.com/payments/pix.md) - [PromptPay](https://docs.stripe.com/payments/promptpay.md) - [Revolut Pay](https://docs.stripe.com/payments/revolut-pay.md) - [Satispay](https://docs.stripe.com/payments/satispay.md) - [Criptomonedas y stablecoins](https://docs.stripe.com/payments/stablecoin-payments.md) - [Swish](https://docs.stripe.com/payments/swish.md) - [TWINT](https://docs.stripe.com/payments/twint.md) - [UPI](https://docs.stripe.com/payments/upi.md) - [WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) ## Actualizar la suscripción [Lado del servidor] Puedes usar actualizaciones pendientes con las llamadas para [actualizar la suscripción](https://docs.stripe.com/api/subscriptions/update.md), [crear el elemento de suscripción](https://docs.stripe.com/api/subscription_items/create.md) y [actualizar el elemento de suscripción](https://docs.stripe.com/api/subscription_items/update.md). 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. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` 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: ```json { "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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method) al cliente. A continuación, usa el punto de conexión de [pagos](https://docs.stripe.com/api/invoices/pay.md) para abonar la factura generada por la actualización. - Para la autenticación de clientes, sigue el flujo que [requiere acción](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). 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](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) original y no se aplica ningún cambio. ## Optional: Cancelar o modificar actualizaciones pendientes [Lado del servidor] Para cancelar una actualización pendiente, tienes que invalidar la factura creada por la actualización. Revisa el atributo [latest invoice](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-latest_invoice) de la suscripción para encontrar la ID de la factura. Luego, utiliza esta ID para [anular](https://docs.stripe.com/api/invoices/void.md) la factura. Puedes [actualizar un suscripción](https://docs.stripe.com/billing/subscriptions/pending-updates.md#update-subscription) con nuevos valores para una actualización pendiente. Esto actualiza los valores en el`pending_update` hash, anula la factura asociado con la actualización pendiente anterior y crea una nueva factura para reflejar los valores actualizados. El pago exitoso de esta nueva factura aplica las actualizaciones más recientes a la suscripción. La falla de pago genera una nueva actualización pendiente con una nueva [fecha de caducidad](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) para reemplazar el existente. ## 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](https://docs.stripe.com/api/subscriptions/update.md) 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](https://docs.stripe.com/api/subscription_items/create.md) y [actualizar un elemento de suscripción](https://docs.stripe.com/api/subscription_items/update.md) 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_end) o el [final del período items.current](https://docs.stripe.com/api/subscriptions/object.md##subscription_object-items-data-current_period_end) 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](https://docs.stripe.com/webhooks.md) para escuchar los siguientes eventos relacionados con las actualizaciones pendientes. Los eventos son los mismos tanto si usas objetos `Customer` como objetos `Account` configurados por el cliente. | Evento | Propósito | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.updated` | Recibe notificaciones sobre suscripciones, verifica el hash `pending_updates` y [resuelve los errores de pago](https://docs.stripe.com/billing/subscriptions/pending-updates.md#handling-failed-payments) 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](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) 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.