Renovaciones con Pago Móvil

Para cualquier producto con suscripciones pagas. Con Pago Móvil no hay domiciliación: Billete no puede cobrarle solo al cliente, así que cada renovación es un Cobro que el cliente paga desde su página. Esta receta explica ese ciclo y lo poco que tu aplicación tiene que hacer.

El modeloCopiar enlace

• Billete cobra; tu aplicación muestra. Billete emite el Cobro, se lo recuerda al cliente y extiende la suscripción cuando paga. Tu aplicación solo enseña el estado y un botón para pagar, y ajusta el acceso con los eventos.
• Pagar antes no regala ni quita días. El periodo nuevo empieza donde terminó el anterior, aunque pague 3 días antes o durante la gracia.
• La gracia es del plan. gracePeriodDays (0, 1, 3 o 7) vale para todos sus suscriptores, también los que ya están. Sin gracia, la suscripción termina el mismo día que vence.
• Qué pasa al final también es del plan. Con fallbackPlanId vuelve a un plan gratuito (planes personales); con suspensionDays se suspende hasta que pague (planes de equipo); sin ninguno, expira.

1. Configura la gracia y el finalCopiar enlace

await billete.plans.update(PLANS.plus, {
  gracePeriodDays: 3,
  fallbackPlanId: PLANS.hobby,
});

Un plan tiene respaldo o suspensión, nunca ambos (suspension_with_fallback). Mira renovación y suspensión.

2. Muestra «Pagar renovación»Copiar enlace

Todo lo que necesitas está en renewal de la suscripción:

const { renewal } = await billete.subscriptions.retrieve(user.subscriptionId);

if (renewal?.invoiceUrl && renewal.status !== "upcoming") {
  showBanner({
    // due: «Tu plan vence en 2 días»; overdue: «Venció: te quedan 2 días de gracia».
    status: renewal.status,
    daysRemaining: renewal.daysRemaining,
    amount: renewal.amount,
    currency: renewal.currency,
    payUrl: renewal.invoiceUrl,
  });
}

daysRemaining cuenta hasta el vencimiento, el fin de la gracia o el de la suspensión, según el estado. amount ya incluye un cambio programado, el cupón y el IVA. renewal es null si la suscripción terminó o se cancela al final del periodo. Desde el navegador, client.customer.subscriptions() con una sesión de cliente trae el mismo bloque.

El Cobro está en la moneda del plan. Si es en dólares, quien paga con Pago Móvil ve el monto en bolívares a la tasa del momento: muestra amount como referencia y deja que la página del Cobro diga cuánto transferir. Mira precios en dólares.

3. Deja los recordatorios a BilleteCopiar enlace

Desde que se abre el Cobro, Billete le escribe al cliente cada día, a la hora que el negocio eligió en el dashboard (Hora de envío), hasta que pague o termine la gracia; si el plan suspende, también al suspenderse, cada semana y a diario los últimos 3 días. Tu aplicación no necesita enviar esos correos; si quieres, añade un aviso propio dentro de la aplicación con los eventos. El cliente también encuentra el Cobro en el portal.

Durante los 3 días del Cobro y la gracia no se aceptan cambios inmediatos (subscription_renewal_open): ofrece pagar la renovación o programar el cambio para ella.

4. Escucha los eventosCopiar enlace

Las entregas pueden repetirse y llegar en otro orden: en cada evento consulta la suscripción y guarda lo que dice, como en planes personales.

5. Cobro automáticoCopiar enlace

autoCharge de la suscripción dice si sus renovaciones se cobran solas. Solo es posible cuando el método del primer pago permite domiciliar: entonces Billete guarda ese permiso y cobra cada renovación una vez, al abrirse su Cobro; si el cobro falla, el Cobro sigue abierto con sus recordatorios para pagarlo a mano, y el cliente puede desactivarlo desde el portal. Pago Móvil no lo permite, así que con él autoCharge es null y todo lo anterior aplica.

Referencia de suscripciones · Cobros · Portal del cliente