Implementar Suscripciones y Facturación en el Backend

Concepto clave

Implementar suscripciones y facturación en el backend es como gestionar un gimnasio: necesitas registrar miembros, cobrar cuotas mensuales, emitir recibos y manejar cambios (como upgrades o cancelaciones). Stripe actúa como tu cajero y administrador de pagos automatizado.

El núcleo de este sistema son tres componentes: Customers (clientes), Subscriptions (suscripciones) y Invoices (facturas). Los customers representan a tus usuarios, las subscriptions definen planes recurrentes, y las invoices generan registros de cobro. Los webhooks son notificaciones que Stripe envía a tu backend cuando ocurren eventos importantes, como un pago exitoso o una suscripción cancelada, permitiéndote sincronizar tu base de datos en tiempo real.

Cómo funciona en la práctica

Imagina que estás construyendo una plataforma SaaS con planes básico ($10/mes) y premium ($30/mes). El flujo típico es:

1. Un usuario se registra en tu app y selecciona un plan.
2. Tu backend crea un customer en Stripe asociado al usuario.
3. Creas una subscription para ese customer con el plan elegido.
4. Stripe genera automáticamente invoices mensuales y procesa los pagos.
5. Cuando ocurre un evento (ej., invoice.paid), Stripe envía un webhook a tu endpoint.
6. Tu backend procesa el webhook y actualiza el estado del usuario en tu base de datos.

Este proceso asegura que la facturación sea automática y confiable, sin intervención manual.

Código en acción

Aquí un ejemplo básico usando Node.js y la librería stripe. Primero, configuración inicial:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

// Crear un customer
async function createCustomer(email, name) {
  const customer = await stripe.customers.create({
    email: email,
    name: name,
  });
  return customer.id; // Guarda este ID en tu base de datos
}

Ahora, crea una suscripción para ese customer. Supongamos que ya tienes predefinidos los precios en Stripe (price_basico y price_premium):

async function createSubscription(customerId, priceId) {
  const subscription = await stripe.subscriptions.create({
    customer: customerId,
    items: [
      { price: priceId },
    ],
    payment_behavior: 'default_incomplete',
    expand: ['latest_invoice.payment_intent'],
  });
  
  // Retorna info para el frontend (ej., clientSecret para confirmar pago)
  return {
    subscriptionId: subscription.id,
    clientSecret: subscription.latest_invoice.payment_intent.client_secret,
  };
}

Antes, podrías haber manejado pagos de forma manual; después, con este código, automatizas todo el ciclo de facturación.

Errores comunes

• No validar webhooks: Siempre verifica la firma de los webhooks para evitar ataques. Usa stripe.webhooks.constructEvent en lugar de confiar en el body crudo.
• Ignorar estados de invoices: No asumas que una invoice está pagada solo porque se creó. Revisa el estado (paid, open, void) antes de activar servicios.
• No manejar fallos de pago: Configura retries y notificaciones para invoices con payment_failed, o los usuarios perderán acceso sin saber por qué.
• Duplicar customers: Evita crear un nuevo customer cada vez que un usuario vuelve; en su lugar, busca por email o guarda el ID de Stripe en tu base de datos.
• Olvidar cancelaciones: Cuando un usuario cancela, actualiza tu base de datos inmediatamente via webhook (evento customer.subscription.deleted) para evitar cobros incorrectos.

Checklist de dominio

• Puedo crear y gestionar customers en Stripe desde mi backend.
• Sé configurar precios y planes recurrentes en el dashboard de Stripe.
• Implemento suscripciones con manejo de pagos iniciales y recurrentes.
• Proceso webhooks para eventos clave como invoice.paid o subscription.updated.
• Genero y descargo facturas automáticas para cumplir con regulaciones.
• Manejo errores de pago y notifico a los usuarios apropiadamente.
• Pruebo mi integración en modo test antes de pasar a producción.

Implementa un endpoint de webhooks para actualizar suscripciones

En este ejercicio, crearás un endpoint en tu backend que procese webhooks de Stripe para mantener sincronizada la base de datos de usuarios. Sigue estos pasos:

1. Configura un endpoint público (ej., /webhooks/stripe) en tu servidor Node.js/Express.
2. Usa la librería stripe para validar la firma del webhook con tu STRIPE_WEBHOOK_SECRET.
3. Implementa el manejo para dos eventos: invoice.paid y customer.subscription.updated.
4. Para invoice.paid, actualiza el campo subscriptionStatus del usuario a 'active' en tu base de datos.
5. Para customer.subscription.updated, actualiza el plan del usuario basado en el item de la suscripción en Stripe.
6. Prueba tu endpoint usando la CLI de Stripe o el dashboard de test.

Entrega el código del endpoint y una explicación de cómo lo probaste.

• Recuerda usar raw body en Express para validar webhooks, no body-parser.
• Puedes simular eventos con stripe listen y stripe trigger en desarrollo.
• Guarda los IDs de Stripe en tu base de datos para buscar usuarios rápidamente.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.