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 manera predeterminada, se aplican actualizaciones al margen de si se hace el pago de la nueva factura. Si el pago falla, la reversión de la actualización es un proceso manual. Debes crear una nueva factura, prorratear los ítems de la factura y luego reiniciar el pago. No obstante, con la función de actualizaciones pendientes, solo puedes hacer cambios en las suscripciones si el pago de la nueva factura se efectúa con éxito.

Precaución

Las actualizaciones pendientes no se admiten cuando el collection_method de la suscripción es send_invoice o cuando se utilizan débitos bancarios como método de pago para la suscripción.

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"
      }
    ]
  },
}

Cómo gestionar pagos fallidos
Lado del cliente

Después de hacer la actualización, verifica el hash pending_update en la suscripción. Si quieres recibir una notificación automática, puedes crear un webhook para escuchar el evento customer.subscription.updated. Si se rellena el hash pending_update, el pago ha fallado y la suscripción seguirá el mismo ciclo como si no se hubiera hecho una solicitud de actualización.

Los errores de pago suelen deberse a que se rechazó el método de pago o a que se exige la autenticación del cliente. Debes crear una lógica para gestionar estos dos escenarios.

Utiliza las instrucciones sobre pagos fallidos para gestionar los rechazos de tarjetas. Debes adjuntar un nuevo método de pago al cliente y luego utilizar el punto de conexión de pagos para abonar la factura generada por la actualización.

Utiliza las instrucciones relacionadas con acciones del cliente para gestionar la autenticación del cliente. De esta manera, se guía al usuario a través del proceso de autenticación y luego se efectúa el pago de la factura.

Un pago efectuado con éxito:

Aplica inmediatamente los cambios en el hash pending_update.
Actualiza el estado de 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.

OpcionalCómo cancelar o modificar actualizaciones pendientes
Lado del servidor

Consulta también

Detalles del ciclo de vida, de los webhooks y atributos aceptados cuando se usan actualizaciones pendientes:

Referencia sobre actualizaciones pendientes