Suscripciones

Requisito: una tarjeta tokenizada

Primero guarda la tarjeta con save_card: true en un pago normal (el primer cobro del plan, por ejemplo). Con el saved_card.key ya puedes crear la suscripción.

Crea la suscripción

const sub = await wpay.createSubscription({
  card_key: 'C8F0D2A1B3E4F5A6B7C8D9E0',
  plan_name: 'Plan Pro',
  amount: 99.9,
  currency: 'BOB',              // default BOB
  frequency: 'MONTHLY',         // DAILY | WEEKLY | MONTHLY | YEARLY (default MONTHLY)
  external_subscriber_id: 'user_42',   // tu id del suscriptor (opcional)
})

{
  "reference": "sub_a1b2c3d4e5f6a7b8c9d0",
  "status": "ACTIVE",
  "next_charge_at": "2026-08-16 12:00:00",
  "id": 17
}

Guarda reference (formato sub_<hex>): identifica la suscripción en todas las operaciones.

La renovación es automática

En cada next_charge_at, WizPay cobra la tarjeta (merchant-initiated). Según el resultado:

• ✅ Aprobado → nueva fecha next_charge_at según la frecuencia + webhook subscription.charge.success.
• ❌ Fallido → failed_attempts + 1 + webhook subscription.charge.failed; se reintenta. Al agotar los reintentos pasa a EXPIRED + webhook subscription.expired.

Consulta el estado

const st = await wpay.getSubscriptionStatus('sub_a1b2c3d4e5f6a7b8c9d0')
// { ...suscripción, charges: [últimos 10 intentos de cobro] }

Lista las suscripciones del sistema

const page = await wpay.listSubscriptions({ page: 1, limit: 20, status: 'ACTIVE' })
// { data: [...], total, page, limit, totalPages }

Cancela

Desde tu backend:

await wpay.cancelSubscription({ reference: 'sub_a1b2c3d4e5f6a7b8c9d0' })
// { msg: 'SUBSCRIPTION_CANCELLED', reference }

O dale al cliente un enlace de cancelación firmado (HMAC, expira a los 7 días) que WizPay sirve como página pública — útil para el pie de tus correos:

GET https://api.wizpay.app/subscriptions/cancel/<token>

El token se genera desde tu panel/sistema (requiere key_cancel configurada en el sistema).