💳 Subscriptions Checkout

🛒 Checkout de Suscripciones

Proceso de Checkout

Este endpoint permite crear una sesión de checkout de Stripe para que los usuarios puedan suscribirse a un plan Premium. Se encarga de validar datos, sincronizar clientes y crear la sesión de pago.

🛡️ Uso del Endpoint

Para iniciar el proceso de checkout, se debe hacer una petición POST al endpoint /create-checkout-subscription con los parámetros necesarios. Este endpoint es parte del controlador de checkout de Strapi y está diseñado para integrarse con Stripe. Es necesario antes de realizar esta petición, tener configurado un Product en Strapi con sus precios de suscripción (subscriptionPrices) y su respectivo stripeID.

Y además habilitar el uso del endpoint para public en la configuración de roles de Strapi.

Ruta

Método: POST Path: /create-checkout-subscription

📋 Parámetros de entrada

Campo	Tipo	Requerido	Descripción
customer_email	string	✅	Email del cliente para la suscripción
payment_method_types	array	✅	Métodos de pago permitidos (card, paypal)
priceID	string	✅	ID del precio de Stripe del producto
productStripeID	string	✅	ID del producto de Stripe
vertical	string	✅	Vertical del producto (Alebat, Inspiria)
origin	string	✅	Origen de la transacción (Alebat, Inspiria)
success_url	string	✅	URL de redirección tras pago exitoso
cancel_url	string	✅	URL de redirección si se cancela

📝 Ejemplo de request

{
  "payment_method_types": ["card", "paypal"],
  "customer_email": "yiyi.rodrigo@hotmail.com",
  "priceID": "price_1S8lJDIi92H5oiSFYXZqSCZ5",
  "productStripeID": "prod_T4v90U7jGs2PmQ",
  "vertical": "Inspiria",
  "origin": "Inspiria",
  "success_url": "https://tusitio.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://tusitio.com/cancel"
}

🔄 Flujo del Controller

1. Validación

// Valida estructura y campos requeridos
validateKeys(ctx.request.body, SUBSCRIPTION_CHECKOUT_VALIDATION_KEYS, FIELD_ROOT);
validateRequiredFields(ctx.request.body, SUBSCRIPTION_CHECKOUT_VALIDATION_KEYS);

2. Búsqueda del producto

// Busca el Product por stripeID
const { productStripeID, priceID } = ctx.request.body;
const productStrapi = await findOne(
  PRODUCT,
  null,
  { stripeID: productStripeID },
  COMPONENTS_SUBSCRIPTION_PRODUCT,
  undefined,
  { enableLocaleFallback: true }
);

if (productStrapi === NOT_FOUND ||
    !productStrapi.subscriptionPrices ||
    productStrapi.subscriptionPrices.length === 0) {
  throw new Error(ERROR_PRODUCT_NOT_FOUND);
}

3. Validación del precio

// Verifica que el priceID existe en subscriptionPrices
const matchedSubscription = productStrapi.subscriptionPrices.find(
  (subsPrice) => subsPrice && subsPrice.stripePriceID === priceID
);

if (!matchedSubscription) {
  throw new Error(ERROR_PRODUCT_NOT_FOUND);
}

4. Sincronización cliente

// Sincroniza/crea cliente en Stripe según el origin
const stripe = await selectStripeCrm(ctx.request.body.origin);
const customer = await syncCustomerWithStripe(
  stripe,
  ctx.request.body.customer_email,
  ctx.request.body.origin
);

Sincroniza el cliente con Stripe basándose en el origin especificado.

5. Crear sesión checkout

// Crea sesión de checkout en Stripe
const checkoutSession = await strapi
  .service(CHECKOUT_STRIPE_SERVICES)
  .createSubscriptionCheckoutSession(
    customer,
    ctx.request.body.origin,
    ctx.request.body.payment_method_types,
    priceID,
    ctx.request.body.success_url,
    ctx.request.body.cancel_url
  );

🛠️ Servicio Stripe

El servicio ahora se llama createSubscriptionCheckoutSession y está ubicado en CHECKOUT_STRIPE_SERVICES. Este método crea una sesión de checkout de Stripe con las siguientes características:

🔧 Características del servicio

• Modo suscripción: Configura el checkout específicamente para suscripciones - Metadatos personalizados: Incluye origin y originEvent para tracking - Campos personalizados: Captura DNI durante el checkout - Facturación automática: Calcula impuestos y dirección automáticamente - Códigos promocionales: Permite aplicar descuentos

🔧 Parámetros del servicio

async createSubscriptionCheckoutSession(
  customer: Stripe.Customer,           // Cliente sincronizado de Stripe
  origin: StripeCrmName,              // Origen (Alebat/Inspiria)
  payment_method_types: Array,        // Métodos de pago permitidos
  priceID: string,                    // ID del precio de Stripe
  success_url: string,                // URL de éxito
  cancel_url: string                  // URL de cancelación
)

⚙️ Configuración de la sesión

return await stripe.checkout.sessions.create({
  customer: customer.id,
  mode: "subscription",
  payment_method_types,
  line_items: [{ price: priceID, quantity: 1 }],
  success_url,
  cancel_url,
  subscription_data: {
    metadata: {
      origin,
      originEvent: "subscription_checkout",
    },
  },
  metadata: {
    origin,
    originEvent: "subscription_checkout",
  },
  custom_fields: [
    {
      key: "dni",
      label: { custom: "DNI", type: "custom" },
      type: "text",
    },
  ],
  automatic_tax: { enabled: true },
  billing_address_collection: "required",
  allow_promotion_codes: true,
  customer_update: { name: "auto", address: "auto" },
});

🔄 Proceso completo

1. Request

Cliente envía datos de checkout al endpoint

2. Validación

Sistema valida estructura y campos requeridos

3. Product Lookup

Busca Product por productStripeID y valida priceID

4. Price Validation

Verifica que el precio existe en subscriptionPrices

5. Customer Sync

Sincroniza cliente con Stripe según origin

6. Checkout Session

Crea sesión de checkout en Stripe

7. Response

Retorna URL de checkout al cliente

📊 Respuesta exitosa

{
  "id": "cs_test_1234567890",
  "object": "checkout.session",
  "url": "https://checkout.stripe.com/pay/cs_test_1234567890",
  "payment_status": "unpaid",
  "status": "open",
  "customer": "cus_1234567890",
  "metadata": {
    "origin": "Alebat",
    "originEvent": "subscription_checkout"
  }
}

⚠️ Posibles errores

ERROR_PRODUCT_NOT_FOUND

Causas: - El productStripeID no corresponde a ningún Product en Strapi

• El Product no tiene configurados subscriptionPrices - El priceID no existe en los subscriptionPrices del producto Solución: Verificar que el productStripeID y priceID sean válidos y estén correctamente configurados

Validación de campos

Causa: Faltan campos requeridos o estructura incorrecta Solución: Revisar que todos los campos obligatorios estén presentes (customer_email, payment_method_types, priceID, productStripeID, vertical, origin, success_url, cancel_url)

Error de Origin/CRM

Causa: El origin especificado no corresponde a un CRM válido Solución: Verificar que el origin sea ‘Alebat’ o ‘Inspiria’

Error de Stripe

Causa: Problemas con la API de Stripe (cliente, precio, etc.) Solución: Verificar configuración de Stripe y validez de los datos

🎯 Características especiales

Multi-CRM por Origin

Selección automática de cuenta Stripe basada en el campo origin

Validación de Precios

Verifica que el priceID existe en subscriptionPrices del producto

Códigos promocionales

Permite uso de códigos de descuento en el checkout

Múltiples métodos de pago

Soporte para tarjetas y PayPal

Facturación automática

Cálculo automático de impuestos y dirección de facturación

Campos personalizados

Captura de DNI durante el proceso de checkout

Metadatos de tracking

Incluye origin y originEvent para seguimiento de transacciones

Actualización automática

Actualiza automáticamente nombre y dirección del cliente

🔗 Flujo posterior

Después del checkout

Una vez completado el pago en Stripe, se ejecuta un webhook que: 1. Recibe la confirmación de pago de Stripe 2. Identifica el origin y la vertical desde los metadatos 3. Crea el registro de Subscription en Strapi 4. Relaciona la suscripción con el usuario correspondiente 5. Actualiza el estado de la suscripción según el vertical

Documentación relacionada

Para entender cómo se procesan los webhooks y se crean las suscripciones finales, consulta: Subscriptions

Cambios importantes

• Nuevo endpoint: /create-checkout-subscription (anteriormente /subscription/create-subscription)
• Nuevos parámetros: productStripeID, vertical, origin
• Nueva validación: Verifica precios en subscriptionPrices del Product
• Controlador unificado: Todo el flujo ahora está en el controlador de checkout

---