Creación de facturación de suscripción recurrente con 4Geeks Payments¶

Descripción general¶

4Geeks Payments proporciona herramientas sólidas para administrar pagos y suscripciones recurrentes, lo que le permite automatizar los ciclos de facturación, manejar actualizaciones/bajas de categoría y administrar el ciclo de vida completo de la suscripción, todo mientras maneja el cumplimiento tributario y la prevención del fraude como su comerciante registrado.

En este tutorial, podrás:

Crear planes de suscripción
Suscribir clientes a planes.
Manejar actualizaciones, degradaciones y cancelaciones.
Gestionar el Portal de Autoservicio del Cliente
Manejar pagos fallidos y reclamaciones.

Requisitos previos¶

Una cuenta de pagos 4Geeks activada
Claves API (clave secreta)
Conocimiento básico de los modelos de negocio de suscripción.

Paso 1: crear planes de suscripción¶

A través de API¶

const axios = require('axios');

const response = await axios.post('https://api.4geeks.io/v1/plans', {
  name: 'Pro Plan',
  amount: 4900,           // $49.00 in cents
  currency: 'USD',
  interval: 'month',       // 'week', 'month', 'year'
  interval_count: 1,       // Every 1 month
  trial_period_days: 14,   // 14-day free trial
  metadata: {
    features: 'Unlimited projects, Priority support, API access',
    tier: 'pro'
  }
}, {
  headers: {
    'Authorization': `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json'
  }
});

console.log('Plan created:', response.data);
// plan_xxxxxxxxxxxxx

Propiedades del plan¶

Propiedad	Descripción	Ejemplo
`nombre`	Nombre para mostrar del plan	“Plan profesional”
`cantidad`	Precio en centavos	4900 ($49,00)
`moneda`	Código de moneda	“USD”, “EUR”, “CRC”
`intervalo`	Frecuencia de facturación	“semana”, “mes”, “año”
`recuento_intervalo`	Multiplicador de frecuencia	1 (mensual), 3 (trimestral)
`días_periodo_prueba`	Duración de la prueba gratuita	14
`metadatos`	Pares clave-valor personalizados	`{ nivel: "pro" }`

Paso 2: suscribir a un cliente¶

Crear cliente primero¶

const customer = await axios.post('https://api.4geeks.io/v1/customers', {
  email: 'customer@example.com',
  name: 'Jane Smith',
  metadata: {
    company: 'Acme Corp',
    signup_source: 'website'
  }
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

const customerId = customer.data.id; // cus_xxxxxxxxxxxxx

Crear suscripción¶

const subscription = await axios.post('https://api.4geeks.io/v1/subscriptions', {
  customer_id: customerId,
  plan_id: 'plan_xxxxxxxxxxxxx',
  payment_method_id: 'pm_xxxxxxxxxxxxx',  // From checkout form
  billing_cycle_anchor: 'now',             // or specific date
  metadata: {
    sales_rep: 'john@example.com'
  }
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

console.log('Subscription created:', subscription.data);
// sub_xxxxxxxxxxxxx

Paso 3: Manejar los cambios del plan¶

Actualizar una suscripción¶

const upgrade = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/update', {
  plan_id: 'plan_enterprise_xxx',  // New plan ID
  prorate: true,                    // Prorate the remaining period
  billing_cycle_anchor: 'unchanged' // Keep existing cycle
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Bajar de categoría una suscripción¶

const downgrade = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/update', {
  plan_id: 'plan_basic_xxx',
  prorate: false,                   // Apply at next billing cycle
  billing_cycle_anchor: 'next_cycle'
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Cancelar una suscripción¶

const cancel = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/cancel', {
  cancel_at_period_end: true  // Access continues until period ends
  // Or set to false for immediate cancellation
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Reactivar una suscripción cancelada¶

const reactivate = await axios.post('https://api.4geeks.io/v1/subscriptions/sub_xxx/reactivate', {}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

Paso 4: configurar el portal del cliente¶

El Portal de autoservicio del cliente permite a los suscriptores administrar sus propias suscripciones.

Habilitar el portal¶

Vaya a Pagos → Configuración → Portal del cliente
Habilite el portal
Configurar acciones permitidas:
Actualizar método de pago
Ver historial de facturación
Plan de actualización/baja de categoría
Cancelar suscripción
Descargar facturas

Incrustar el portal¶

<!-- Redirect to hosted portal -->
<a href="https://pay.4geeks.io/portal/{{ customer.portal_token }}">
  Manage Subscription
</a>

<!-- Or embed as iframe -->
<iframe 
  src="https://pay.4geeks.io/portal/{{ customer.portal_token }}"
  width="100%" 
  height="800"
  frameborder="0"
></iframe>

Generar token de portal¶

const portal = await axios.post('https://api.4geeks.io/v1/customer-portal', {
  customer_id: customerId,
  return_url: 'https://yoursite.com/account/billing'
}, {
  headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
});

console.log('Portal URL:', portal.data.url);

Paso 5: Manejar pagos fallidos (reclamación)¶

Lógica de reintento automático¶

4Geeks Payments reintenta automáticamente los pagos fallidos:

Intento	Tiempo
1er reintento	3 días después del fracaso
2do reintento	7 días después del fracaso
3er intento	15 días después del fracaso

Eventos de webhook para pagos fallidos¶

// In your webhook handler
switch (event.type) {
  case 'invoice.payment_failed':
    // Notify customer about failed payment
    sendEmail(customer.email, 'Payment Failed', {
      amount: event.data.amount,
      retry_date: event.data.next_retry_date
    });
    break;

  case 'invoice.payment_succeeded':
    // Confirm successful payment
    sendEmail(customer.email, 'Payment Confirmed', {
      amount: event.data.amount,
      period: event.data.period
    });
    break;

  case 'subscription.past_due':
    // Subscription is past due after all retries failed
    notifyAdmin('Subscription past due', {
      customer: event.data.customer,
      amount: event.data.amount
    });
    break;

  case 'subscription.canceled':
    // Subscription canceled after failed payments
    notifyAdmin('Subscription canceled', {
      customer: event.data.customer
    });
    break;
}

Correos electrónicos de reclamación personalizados¶

Configure correos electrónicos de reclamación automatizados en la consola:

Vaya a Pagos → Configuración → Reclamaciones
Personalice plantillas de correo electrónico para:
Notificación de pago fallido
Notificación de reintento
Aviso final antes de la cancelación.
Notificación de suscripción cancelada
Establece el tiempo para cada correo electrónico

Paso 6: Supervisar las métricas de suscripción¶

Métricas clave para realizar un seguimiento¶

Métrica	Descripción
MRR	Ingresos mensuales recurrentes
ARR	Ingresos anuales recurrentes
Tasa de abandono	% de suscriptores que cancelan por mes
MRR de expansión	Ingresos por actualizaciones
Contracción MRR	Ingresos perdidos por rebajas de calificación
Retención de ingresos netos	(MRR inicial + Expansión - Contracción - Rotación) / MRR inicial

Informes de acceso¶

Vaya a Pagos → Análisis → Suscripciones
Vea paneles en tiempo real para todas las métricas de suscripción
Exportar informes como CSV para su posterior análisis.

Mejores prácticas¶

Estrategia de precios¶

Oferta facturación anual con un descuento (por ejemplo, 20 % de descuento) para mejorar el flujo de caja
Utilice períodos de prueba para reducir la fricción con nuevos clientes
Implementar precios protegidos para los primeros usuarios
Considere modelos de precios basados en el uso o escalonados

Reducir la deserción¶

Envíe informes de uso para mostrar el valor entregado
Implementar campañas de recuperación para suscriptores cancelados
Ofrecer la opción de pausa en lugar de cancelación
Proporcionar soporte proactivo antes de las fechas de renovación

Cumplimiento¶

Como comerciante registrado, 4Geeks maneja el cumplimiento fiscal automáticamente
El cumplimiento de PCI DSS está integrado: los datos de la tarjeta nunca tocan sus servidores
Cumplimiento del GDPR para clientes de la UE
Regulaciones de pago locales manejadas por jurisdicción

¿Qué sigue?¶

Obtenga más información sobre 3D Secure para la prevención del fraude
Explorar Pago multidivisa

¿Necesitas ayuda?¶

Documentación: docs.4geeks.io/es/pagos
Referencia de API: docs.4geeks.io/en/api
Soporte: disponible a través del panel de la consola

Aún con dudas? Pregunta en Discord o explore tutoriales