Concepto clave

El SDK de Stripe es la herramienta principal que conecta tu backend con los servicios de pago de Stripe. Piensa en él como el traductor oficial entre tu código y la compleja infraestructura de pagos: convierte tus solicitudes en llamadas API seguras y procesa las respuestas de Stripe de manera confiable. Sin este SDK, tendrías que manejar manualmente autenticación, serialización de datos y manejo de errores, lo que sería como construir tu propio puente en lugar de usar uno ya probado.

En el contexto de suscripciones y facturación, el SDK no solo procesa pagos, sino que gestiona todo el ciclo de vida: creación de clientes, configuración de productos, manejo de suscripciones y procesamiento de webhooks. Es el orquestador central que coordina todas las operaciones de facturación recurrente, asegurando que cada componente (cliente, producto, suscripción, factura) esté correctamente sincronizado.

Cómo funciona en la práctica

La implementación sigue un flujo estructurado: primero instalas el paquete, luego configuras las credenciales, después inicializas el cliente y finalmente comienzas a usar las diferentes funcionalidades. Veamos el proceso paso a paso:

Instalación del paquete mediante tu gestor de dependencias
Configuración de las claves API (pública y secreta) en variables de entorno
Inicialización del cliente Stripe en tu aplicación
Implementación de tus primeros endpoints para crear clientes y productos
Configuración del manejo básico de webhooks

Este enfoque asegura que tu integración sea segura (las claves sensibles nunca están en el código), mantenible (configuración centralizada) y escalable (listo para añadir más funcionalidades).

Código en acción

Aquí tienes la configuración básica en Node.js con Express:

// 1. Instalación (ya realizada via npm/yarn)
// npm install stripe

// 2. Configuración inicial
const express = require('express');
const Stripe = require('stripe');
require('dotenv').config();

const app = express();
app.use(express.json());

// Inicialización del cliente Stripe
const stripe = Stripe(process.env.STRIPE_SECRET_KEY);

// 3. Endpoint para crear un cliente
app.post('/api/create-customer', async (req, res) => {
  try {
    const { email, name } = req.body;
    
    const customer = await stripe.customers.create({
      email,
      name,
      metadata: {
        userId: '12345', // ID de tu sistema
        plan: 'premium'
      }
    });
    
    res.json({ success: true, customerId: customer.id });
  } catch (error) {
    console.error('Error creando cliente:', error);
    res.status(500).json({ error: error.message });
  }
});

// 4. Endpoint para crear un producto con precio recurrente
app.post('/api/create-product', async (req, res) => {
  try {
    const { name, description, amount, interval } = req.body;
    
    // Primero creamos el producto
    const product = await stripe.products.create({
      name,
      description,
      metadata: {
        internalCode: 'PROD_001'
      }
    });
    
    // Luego el precio asociado
    const price = await stripe.prices.create({
      product: product.id,
      unit_amount: amount, // en centavos
      currency: 'usd',
      recurring: {
        interval: interval || 'month'
      }
    });
    
    res.json({ 
      success: true, 
      productId: product.id, 
      priceId: price.id 
    });
  } catch (error) {
    console.error('Error creando producto:', error);
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Servidor ejecutándose en puerto 3000');
});

Y aquí cómo mejorar la configuración para producción:

// Configuración mejorada para producción
const stripe = Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2023-10-16', // Versión específica para consistencia
  maxNetworkRetries: 3, // Reintentos automáticos
  timeout: 10000, // Timeout de 10 segundos
  telemetry: false // Desactiva telemetría en producción
});

// Middleware para verificar webhooks
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

app.post('/webhook', express.raw({type: 'application/json'}), 
  async (req, res) => {
    const sig = req.headers['stripe-signature'];
    
    let event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body, sig, endpointSecret
      );
    } catch (err) {
      console.error('Webhook signature verification failed:', err.message);
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }
    
    // Manejo del evento
    switch (event.type) {
      case 'customer.subscription.created':
        await handleSubscriptionCreated(event.data.object);
        break;
      case 'invoice.payment_succeeded':
        await handlePaymentSucceeded(event.data.object);
        break;
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }
    
    res.json({received: true});
  }
);

Errores comunes

Exponer la clave secreta en el frontend: La clave secreta (STRIPE_SECRET_KEY) solo debe usarse en el backend. En el frontend usa la clave pública (STRIPE_PUBLISHABLE_KEY).
No validar webhooks: Siempre verifica la firma de los webhooks usando stripe.webhooks.constructEvent(). Sin esto, cualquiera podría enviarte eventos falsos.
Manejo inadecuado de errores: Stripe devuelve errores específicos (card_declined, insufficient_funds). Captúralos y proporcióna mensajes claros al usuario.
No versionar la API: Especifica una versión de API en la configuración para evitar cambios rotos cuando Stripe actualice su API.
Olvidar el manejo de idempotencia: Para operaciones críticas como crear suscripciones, usa claves de idempotencia para evitar cobros duplicados.

Checklist de dominio

SDK instalado correctamente y funcionando en tu entorno de desarrollo
Claves API configuradas como variables de entorno (nunca en el código)
Cliente Stripe inicializado con configuración apropiada para tu entorno
Endpoints básicos implementados (crear cliente, producto, precio)
Manejo de errores implementado para todas las operaciones de Stripe
Webhooks configurados y validando firmas correctamente
Logs implementados para rastrear todas las interacciones con Stripe

Configura un entorno de integración completo con Stripe

Implementa un backend básico que integre Stripe siguiendo estas instrucciones:

Crea un nuevo proyecto Node.js con Express
Instala las dependencias necesarias: stripe, express, dotenv
Configura un archivo .env con tus claves de Stripe (usa claves de test)
Implementa los siguientes endpoints:
- POST /api/customers - Crea un nuevo cliente en Stripe
- POST /api/products - Crea un producto con precio recurrente mensual
- POST /api/subscriptions - Crea una suscripción para un cliente existente
- POST /webhook - Endpoint para recibir y validar webhooks
Asegúrate de que cada endpoint:
- Valide los datos de entrada
- Maneje errores específicos de Stripe
- Registre las operaciones en consola
Prueba tu implementación usando el dashboard de Stripe Test

Pistas

Usa el método stripe.customers.create() para crear clientes, incluyendo metadata relevante
Para webhooks, recuerda usar express.raw() middleware y validar la firma con stripe.webhooks.constructEvent()
Configura diferentes precios (monthly, yearly) para el mismo producto usando stripe.prices.create()

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Instalar y Configurar el SDK de Stripe en tu Backend