Cobrar suscripciones

Cómo funciona

1. Llamas a landapay.subscriptions.create con el plan, que puede ser un id o definirse en la misma llamada, y opcionalmente el cliente.
2. Envías al cliente a checkoutUrl, donde registra su tarjeta, Nequi o cuenta Bancolombia.
3. Se crea la suscripción y te llega el webhook subscription.created.
4. Landa Pay cobra cada periodo y te avisa de cada cambio con webhooks.

Con el plan en la llamada

No necesitas crear el plan antes. Pasa sus datos en plan y la librería lo crea por ti, ideal cuando el precio depende de cada cliente, como una licencia por número de usuarios.

1import { landapay } from "landapay";2 3const { checkoutUrl, plan, customer } = await landapay.subscriptions.create({4  plan: {5    name: "Licencia Pro - 5 usuarios",6    interval: "monthly",7    amount: 4_990_000, // $49.900 COP al mes8    metadata: { seats: 5 },9  },10  customer: { name: "María Gómez", email: "[email protected]" },11  externalId: "license_8812",12  metadata: { workspace: "acme" },13  redirectUrl: "https://tuapp.com/suscripcion",14});15 16res.redirect(checkoutUrl);

El resultado trae checkoutUrl, el checkout completo, el plan que se creó y el id del customer. Si no envías name, el plan se llama según su frecuencia, por ejemplo “Suscripción mensual”.

Con un plan existente

Si vendes los mismos planes a todos tus clientes, créalos una vez con landapay.plans.create o en el panel, y usa su id:

1const { checkoutUrl } = await landapay.subscriptions.create({2  plan: "plan_PLANCODE23456789",3  customer: "cus_ABCDEFGHJKLMNPQR",4  externalId: "user_42",5});

Prueba gratis y precios por etapas

Con amount y trialDays defines un precio simple con prueba gratis. Con phases defines precios por etapas: cada fase lleva su duration salvo la última, que se repite hasta el final. Usa termCycleCount para terminar la suscripción tras un número de cobros.

1// 14 días gratis y luego $49.900 al mes2await landapay.subscriptions.create({3  plan: { interval: "monthly", amount: 4_990_000, trialDays: 14 },4  customer: "cus_ABCDEFGHJKLMNPQR",5});6 7// 3 meses a $19.900, luego $49.900, durante 12 cobros en total8await landapay.subscriptions.create({9  plan: {10    name: "Promo lanzamiento",11    interval: "monthly",12    termCycleCount: 12,13    phases: [14      { type: "priced", amount: 1_990_000, duration: { unit: "month", count: 3 } },15      { type: "priced", amount: 4_990_000 },16    ],17  },18  customer: "cus_ABCDEFGHJKLMNPQR",19});

El cliente

• Con un id (cus_...) se usa ese cliente.
• Con sus datos se crea el cliente, o se reutiliza el que ya tenga ese email o externalId.
• Sin cliente, el checkout le pide sus datos.

Con un cliente, su email queda fijo en el checkout y solo se piden los datos que le falten.

Después del checkout

La suscripción se crea solo cuando el cliente completa el checkout, con el primer cobro o con el periodo de prueba del plan, y hereda el externalId y la metadata. El checkout vence en 24 horas, o en el expiresAt que envíes (máximo 7 días).

Con redirectUrl el cliente vuelve a tu URL con subscription_id y checkout_id; sin ella ve la página de resultado de Landa Pay.

1app.get("/suscripcion", async (req, res) => {2  const checkout = await landapay.subscriptions.retrieveCheckout(String(req.query.checkout_id));3 4  if (checkout.status === "completed" && checkout.subscription) {5    const subscription = await landapay.subscriptions.retrieve(checkout.subscription);6    return res.render("suscripcion-lista", { status: subscription.status });7  }8  res.render("suscripcion-pendiente");9});

Cada cobro de la suscripción es un pago con el campo subscription, y te llega con los eventos payment.*.

Activar el acceso

1const event = landapay.webhooks.constructEvent(req.body, req.get("Landa-Signature"));2 3switch (event.type) {4  case "subscription.created":5  case "subscription.activated":6  case "subscription.past_due":7  case "subscription.canceled":8  case "subscription.completed": {9    const subscription = event.data.object;10    const allowed = subscription.status === "active" || subscription.status === "trialing";11    if (allowed) await grantAccess(subscription.externalId, subscription.id);12    else await revokeAccess(subscription.externalId);13    break;14  }15}

No existe subscription.unpaid. Al fallar un cobro llega subscription.past_due y ahí quitas el acceso. unpaid significa que se agotaron los reintentos; el acceso ya debía estar quitado. No lo devuelvas hasta subscription.activated.

Aprende a configurar el endpoint y verificar la firma en Recibir webhooks.

Actualizar el método de pago

Si un cobro falla porque la tarjeta cambió o no tiene saldo, no pidas los datos en tu app. Crea una sesión y redirige al cliente a Landa Pay para ver, agregar o eliminar sus métodos. El enlace es de un solo uso, caduca en 15 minutos y la API key no sale de tu servidor.

1const session = await landapay.subscriptions.createPaymentMethodSession(2  "sub_SUBSCRIPTION2345",3  { returnUrl: "https://tuapp.com/facturacion" },4);5 6res.redirect(session.url);

returnUrl es opcional. Si no lo envías, un cobro aprobado vuelve al redirectUrl del checkout de esa suscripción. La vuelta trae subscription_id y payment_id. Confirma con payments.retrieve o con el webhook; volver no activa el acceso.

• Si la suscripción está past_due o unpaid, guardar un método nuevo o elegir uno anula los periodos impagos y cobra de inmediato un ciclo nuevo desde ese momento. Si aprueba, llega payment.approved y subscription.activated, y ahí devuelves el acceso.
• Si está al día, solo se guarda el método. Los próximos cobros salen de ahí y no se cobra nada en ese momento.
• Si el cobro se rechaza, el cliente se queda en la página y puede probar otra tarjeta.

Estados

Los periodos que no se cobraron no se recuperan. Cuando el cliente guarda un método de pago, se abre un ciclo desde ese momento. Si ese cobro se aprueba, llega subscription.activated.

Cancelar y reanudar

Por defecto la suscripción sigue activa hasta el final del periodo pagado (subscription.cancel_scheduled) y puedes deshacerlo con resume. Con atPeriodEnd: false termina de inmediato (subscription.canceled). En ambos casos el cliente recibe un correo.

1// Al final del periodo pagado; se puede deshacer2await landapay.subscriptions.cancel("sub_SUBSCRIPTION2345", { reason: "Cambio de plan" });3await landapay.subscriptions.resume("sub_SUBSCRIPTION2345");4 5// De inmediato6await landapay.subscriptions.cancel("sub_SUBSCRIPTION2345", { atPeriodEnd: false });

Cambiar de plan

Una suscripción active o trialing puede subir o bajar de plan. Es una subida si el plan nuevo cuesta más por día que el actual, así que se pueden comparar planes de distinta frecuencia, y un empate cuenta como subida. Antes de confirmar, muestra a tu cliente lo que pasará con previewPlanChange; no cambia nada.

1const preview = await landapay.subscriptions.previewPlanChange("sub_SUBSCRIPTION2345", {2  plan: "plan_PRO2345ABCDEFGH",3});4 5preview.direction; // "upgrade" o "downgrade"6preview.behavior; // el que se usará: el del panel o el que envíes7preview.charge; // lo que se cobra hoy, en centavos8preview.balanceDelta; // lo que queda a favor del cliente (positivo) o se suma al próximo cobro9preview.effectiveAt; // cuándo entra en vigor10preview.nextBillingAt; // próximo cobro con el plan nuevo11preview.nextAmount; // y su monto, ya con el saldo aplicado

Comportamientos

Ejemplo: el cliente paga $50.000 al mes por Básico, ya usó el 20 % del periodo y sube a Pro de $100.000. Le quedan $40.000 sin usar del plan actual ($50.000 × 0,8).

• Si el plan nuevo tiene otra frecuencia, prorate se aplica como reset porque los periodos no coinciden.
• En prueba gratis no hay nada cobrado: el cambio se aplica sin cobro y la prueba termina en la misma fecha, salvo con period_end, que espera al final de la prueba.
• El plan nuevo empieza en su primera fase con precio; su prueba gratis no se repite.
• Pedir otro cambio reemplaza al que estaba programado.

Cobro y saldo a favor

Si hay algo que cobrar, se cobra en el momento al método de pago de la suscripción y el cambio solo se aplica si el cobro se aprueba. Si se rechaza, recibes un InvalidRequestError con código payment_declined y la suscripción sigue en su plan. Con Nequi o Bancolombia el cobro puede quedar pendiente: pendingPlanChange.status es pending_payment hasta que te llegue subscription.plan_changed o subscription.plan_change_failed.

El cambio genera su propia factura con kind: "plan_change". Lo no usado del plan anterior aparece como descuento en creditApplied.

Cuando el resultado favorece al cliente, por ejemplo al bajar de Pro a Básico con prorate ($40.000 − $80.000), la diferencia queda como saldo a favor en subscription.balance y se descuenta de los próximos cobros: el siguiente de Básico sería de $10.000. Un cobro menor a $2.000 COP no se hace en el momento: el cambio se aplica y el monto se suma al próximo cobro. El saldo negativo es esa deuda pendiente.

1import { InvalidRequestError, landapay } from "landapay";2 3try {4  const subscription = await landapay.subscriptions.changePlan("sub_SUBSCRIPTION2345", {5    plan: "plan_PRO2345ABCDEFGH",6    behavior: "prorate", // opcional; sin él se usa lo configurado en el panel7  });8 9  if (subscription.pendingPlanChange?.status === "pending_payment") {10    // Nequi o Bancolombia: el cambio se aplica cuando se apruebe el cobro11  }12} catch (error) {13  if (error instanceof InvalidRequestError && error.code === "payment_declined") {14    // El cliente sigue en su plan15  }16}17 18// Plan definido en la misma llamada, como en create19await landapay.subscriptions.changePlan("sub_SUBSCRIPTION2345", {20  plan: { name: "Licencia Pro - 10 usuarios", interval: "monthly", amount: 8_990_000 },21});22 23// Deshacer un cambio programado con period_end24await landapay.subscriptions.cancelPlanChange("sub_SUBSCRIPTION2345");

Configuración del proyecto

En el panel, en Configuración › Facturación › Cambios de plan, defines el comportamiento por defecto para subidas (prorate) y bajadas (period_end), si se permite bajar de plan y si se permite cambiar a un plan con otra frecuencia. El behavior que envíes en la llamada tiene prioridad sobre el del panel.

Webhooks

Usa subscription.plan_changed para ajustar los límites o el acceso de tu cliente; el evento trae la suscripción con su plan nuevo. El cliente también recibe un correo con el cambio.

1switch (event.type) {2  case "subscription.plan_changed": {3    const subscription = event.data.object;4    const plan = await landapay.plans.retrieve(subscription.plan);5    await updateLimits(subscription.externalId, plan.metadata);6    break;7  }8  case "subscription.plan_change_failed":9    await notifyUser(event.data.object.externalId, "No pudimos cobrar el cambio de plan");10    break;11}

Facturas de la suscripción

Cada ciclo tiene su factura, igual que en el tab Cobros del panel. Lístalas con landapay.subscriptions.listInvoices: llegan de 15 en 15 (máximo 50 con limit), la más reciente primero, con totalPages y hasMore para tu paginación. Cada factura trae su number y la url pública para mostrarla a tu cliente.

Los cobros de cambio de plan tienen su propia factura con kind: "plan_change" y cycle: null. Usa amountDue para mostrar lo cobrado: amount es el precio antes de descontar el saldo (creditApplied).

1// Página de 15 facturas, la más reciente primero2const page = await landapay.subscriptions.listInvoices("sub_SUBSCRIPTION2345", {3  page: Number(searchParams.get("pagina") ?? 1),4});5 6const rows = page.data.map((invoice) => ({7  number: invoice.number, // FAC-000128  url: invoice.url, // ábrelo con target="_blank"9  amount: invoice.amount,10  status: invoice.chargeStatus,11}));12 13console.log(`Página ${page.page} de ${page.totalPages}`);14 15// O recórrelas todas sin manejar páginas16for await (const invoice of landapay.subscriptions.listInvoices("sub_SUBSCRIPTION2345")) {17  console.log(invoice.number, invoice.paidAt);18}