Integración de Stripe

Fuente

Esta guía está basada en la documentación oficial de Open SaaS — Stripe, traducida y adaptada al español para TalentBricksAI.

¿Por qué Stripe?

• Cobertura global con soporte para 135+ monedas
• APIs bien documentadas con excelente DX
• Facturación automática, gestión de impuestos y prevención de fraude
• Herramientas de prueba robustas (Stripe CLI)

Requisitos previos

• Cuenta de Stripe en stripe.com
• TalentBricksAI configurado localmente → Setup local

Paso 1: Obtener claves API

1. Inicia sesión en Dashboard de Stripe
2. Activa Modo de Prueba (toggle superior derecho)
3. Ve a Developers → API keys
4. Copia:
   • Secret key (sk_test_...) → va al backend
   • Publishable key (pk_test_...) → va al frontend (si aplica)

Seguridad

Nunca expongas la clave secreta en el frontend ni la incluyas en el repositorio.

Paso 2: Configurar variables de entorno

Solo estas dos son obligatorias:

app/.env.server

STRIPE_API_KEY=sk_test_51...
STRIPE_WEBHOOK_SECRET=whsec_...   # Lo obtienes en el Paso 4

Los Price IDs de los planes ya no son variables de entorno requeridas — se gestionan desde el Admin Panel en /admin/pricing. Si los tienes del setup anterior, el seed los migra automáticamente.

# Opcionales — solo para migración inicial desde .env a la DB
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID=price_xxx
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID=price_xxx
PAYMENTS_CREDITS_10_PLAN_ID=price_xxx

Paso 3: Crear productos en Stripe

Crea un producto por cada plan en Product catalog → Products. Copia el price_xxx de cada uno.

Planes personales

Producto	Tipo	Monto	Intervalo
Monthly Subscription	Recurring	$19.00	month
Annual Subscription	Recurring	$190.00	year
10 Credits	One time	$10.00	—

Planes de equipos (crear cuando vayas a activarlos)

Producto	Tipo	Monto	Intervalo
Team 10	Recurring	$99.00	month
Team 50	Recurring	$399.00	month
Team 100	Recurring	$699.00	month
Team 10 Annual	Recurring	$950.40	year
Team 50 Annual	Recurring	$3820.80	year
Team 100 Annual	Recurring	$6700.80	year

Opción CLI (más rápido)

# Instalar Stripe CLI
brew install stripe/stripe-cli/stripe
stripe login

# Suscripción mensual
stripe products create --name="Monthly Subscription" --description="Acceso mensual a todos los cursos"
stripe prices create --product=prod_XXX --unit-amount=1900 --currency=usd --recurring[interval]=month

# Suscripción anual
stripe products create --name="Annual Subscription" --description="Acceso anual a todos los cursos"
stripe prices create --product=prod_YYY --unit-amount=19000 --currency=usd --recurring[interval]=year

# Pack de créditos (pago único)
stripe products create --name="10 Credits" --description="Pack de 10 créditos"
stripe prices create --product=prod_ZZZ --unit-amount=1000 --currency=usd

# Team 10 mensual
stripe products create --name="Team 10" --description="Hasta 10 usuarios"
stripe prices create --product=prod_AAA --unit-amount=9900 --currency=usd --recurring[interval]=month

Paso 4: Configurar webhooks

Desarrollo local

# En una terminal separada, mientras desarrollas
stripe listen --forward-to localhost:3001/payments/stripe-webhook
# Copia el whsec_... que imprime → STRIPE_WEBHOOK_SECRET en .env.server

Producción

1. Stripe Dashboard → Developers → Webhooks → Add endpoint
2. URL: https://tu-dominio.com/payments/stripe-webhook
3. Eventos requeridos:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. Copia el Signing secret (whsec_...) → variable de entorno de producción

Importante

Los secrets de webhook son distintos entre desarrollo y producción. No los mezcles.

Paso 5: Vincular Price IDs al Admin Panel

Una vez creados los productos en Stripe, tienes tres opciones para vincularlos:

Opción A — Botón “Sync con Stripe” (recomendado)

1. Ve a /admin/pricing
2. Clic en Editar en un plan (p.ej. monthly-subscription)
3. Clic en Sync con Stripe
4. El sistema crea el producto + precio en Stripe automáticamente y guarda el ID

Idempotente

Puedes hacer clic en Sync varias veces sin problema — el sistema verifica si el Price ya existe en Stripe antes de crear uno nuevo.

Opción B — Pegar el Price ID manualmente

1. Ve a /admin/pricing → Editar el plan
2. Pega el price_xxx en el campo Stripe Price ID
3. Guarda

Opción C — Seed automático desde env vars

1. Agrega los Price IDs en .env.server
2. Ejecuta wasp db seed seedPricingPlans
3. El seed migra los IDs del env a la base de datos

Paso 6: Activar Stripe en el código

Abre app/src/payment/paymentProcessor.ts y asegúrate de que Stripe esté activo:

// Stripe activo (por defecto en TalentBricksAI)
export { stripePaymentProcessor as paymentProcessor } from "./stripe/paymentProcessor";

// Alternativas (comentadas por defecto)
// export { lemonSqueezyPaymentProcessor as paymentProcessor } from './lemonSqueezy/paymentProcessor';
// export { polarPaymentProcessor as paymentProcessor } from './polar/paymentProcessor';

Paso 7: Probar la integración

Tarjetas de prueba

Escenario	Número de tarjeta
Pago exitoso	4242 4242 4242 4242
Pago rechazado	4000 0000 0000 0002
Requiere 3D Secure	4000 0025 0000 3155
Fondos insuficientes	4000 0000 0000 9995

Fecha: cualquier fecha futura · CVC: cualquier 3 dígitos · ZIP: cualquier 5 dígitos

Más tarjetas: stripe.com/docs/testing

Flujo de prueba completo

1. wasp db start (terminal 1)
2. wasp start (terminal 2)
3. stripe listen --forward-to localhost:3001/payments/stripe-webhook (terminal 3)
4. Ir a http://localhost:3000/pricing
5. Comprar un plan con tarjeta de prueba 4242 4242 4242 4242
6. Verificar en terminal 3 que el webhook checkout.session.completed se activó
7. Verificar en /admin/users que el usuario tiene suscripción activa

Verificar estado de la integración

En /admin/pricing, la columna Stripe muestra:

• ✅ price_xxx en verde → plan listo para checkout
• ⚠️ “No configurado” en amarillo → falta el Price ID, el checkout fallará

Funciones avanzadas

Impuestos automáticos (Stripe Tax)

Ya está habilitado en el checkout (app/src/payment/stripe/checkoutUtils.ts):

automatic_tax: {
  enabled: true;
}

Actívalo en tu cuenta: Stripe Dashboard → Settings → Tax.

Códigos de promoción

También habilitados por defecto:

allow_promotion_codes: true;

Para crear códigos: Stripe Dashboard → Product catalog → Coupons → Promotion codes.

Portal del cliente

Permite a los usuarios gestionar su suscripción (cancelar, actualizar pago, ver facturas). Actívalo en: Stripe Dashboard → Settings → Billing → Customer portal.

El enlace ya está integrado en la página /account.

Período de prueba

Configúralo al crear el precio en Stripe Dashboard o con CLI:

stripe prices create \
  --product=prod_XXX \
  --unit-amount=1900 \
  --currency=usd \
  --recurring[interval]=month \
  --recurring[trial_period_days]=14

Solución de problemas

Los webhooks no se reciben

1. Verifica que stripe listen esté corriendo en una terminal
2. Confirma que STRIPE_WEBHOOK_SECRET en .env.server sea el whsec_... que imprimió el CLI
3. Revisa los logs del servidor: wasp start muestra los webhooks recibidos

El checkout falla con error 500 o 404

1. Ve a /admin/pricing y verifica que el plan tiene stripePriceId configurado (columna Stripe verde)
2. Si está en amarillo → usa el botón Sync o pega el Price ID manualmente

Error: “No API key provided”

• Verifica que STRIPE_API_KEY esté en .env.server
• Reinicia wasp start después de agregar la variable

Error de webhook inválido

• El STRIPE_WEBHOOK_SECRET debe coincidir con el secret mostrado por stripe listen
• Reinicia la app después de actualizar el secret

Modo producción

1. Activa tu cuenta de Stripe — completa información del negocio y verificación de identidad
2. Cambia a claves en vivo — Stripe Dashboard → Live Mode → Developers → API keys
   • Actualiza STRIPE_API_KEY=sk_live_... en producción
3. Recrea los productos en Live Mode — los productos de test no existen en Live
4. Actualiza los Price IDs — desde el Admin Panel en producción (/admin/pricing)
5. Configura webhook de producción — apuntando a tu dominio real
6. Prueba con una tarjeta real — haz un pago pequeño, verifica y reembolsa

Recursos

• Documentación oficial de Stripe
• Stripe API Reference
• Stripe CLI Documentation
• Stripe Webhook Events
• Open SaaS Stripe Guide
• Configurar pagos en TalentBricksAI