Integraciones de Pago

TalentBricksAI usa Stripe

TalentBricksAI está configurado para usar Stripe como procesador de pagos. Si necesitas configurar Stripe, ve directamente a Configurar Pagos o consulta la Guía de Integración de Stripe.

Otros procesadores disponibles

Open SaaS (la plantilla base de TalentBricksAI) soporta también Lemon Squeezy y Polar. Si necesitas cambiar de procesador, consulta la documentación oficial de Open SaaS.

TalentBricksAI está construido sobre la plantilla Open SaaS, que incluye soporte integrado para Stripe como procesador de pagos principal.

Por qué Stripe

Stripe es el procesador de pagos elegido para TalentBricksAI por las siguientes razones:

Ventajas:

• Más maduro y ampliamente utilizado a nivel global
• Mejor documentación y soporte para desarrolladores
• Excelentes opciones de personalización
• Soporta facturación compleja y precios dinámicos
• Excelentes herramientas para desarrolladores (Stripe CLI, webhooks, etc.)
• Funciona en casi todos los países
• Amplio ecosistema de integraciones

Consideraciones:

• Requiere configuración inicial (pero esta guía te ayuda con eso)
• Necesitas manejar el cumplimiento fiscal tú mismo (o usar Stripe Tax)
• Las tarifas pueden variar según el país

Tarifas típicas: 2.9% + $0.30 por transacción (varía según el país)

Aprende más: Guía de Integración de Stripe

configuración Rápida

Para comenzar con cualquier procesador de pago, sigue estos pasos generales:

1. Regístrate en el procesador de pago que elijas
2. Obtén tus claves API del dashboard del procesador
3. Configura las variables de entorno en tu aplicación
4. Crea productos/precios en el dashboard del procesador
5. Configura webhooks para recibir actualizaciones de eventos
6. Prueba tu integración en modo de prueba

Estructura del Código

TalentBricksAI organiza el código de pagos de la siguiente manera:

app/src/payment/
├── operations.ts              # Operaciones de pago (queries y actions)
├── plans.ts                   # Definición de planes de pago
├── paymentProcessor.ts        # Interfaz común de procesador de pago
├── webhook.ts                 # Manejador principal de webhooks
└── stripe/
    ├── checkoutUtils.ts      # Utilidades de checkout de Stripe
    ├── paymentProcessor.ts   # Implementación del procesador de Stripe
    ├── stripeClient.ts       # Cliente configurado de Stripe
    └── webhook.ts            # Manejador de webhooks de Stripe

Nota sobre Open SaaS

Open SaaS también incluye implementaciones para lemonSqueezy/ y polar/, pero TalentBricksAI solo usa Stripe. Si necesitas cambiar de procesador, la arquitectura de Open SaaS lo hace sencillo gracias a la interfaz común paymentProcessor.ts.

Variables de Entorno

Stripe requiere las siguientes variables de entorno:

app/.env.server

STRIPE_API_KEY=sk_test_...              # Clave secreta de Stripe
STRIPE_WEBHOOK_SECRET=whsec_...         # Secret del webhook

# IDs de planes (obtenidos del Dashboard de Stripe)
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID=price_...
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID=price_...
PAYMENTS_CREDITS_10_PLAN_ID=price_...

Desarrollo vs Producción

• Desarrollo: Usa claves que empiezan con sk_test_ y pk_test_
• Producción: Usa claves que empiezan con sk_live_ y pk_live_

Consulta la Guía de Integración de Stripe para más detalles.

Planes de Pago

Los planes de pago se definen en app/src/payment/plans.ts:

export enum PaymentPlanId {
  Hobby = "hobby",
  Pro = "pro",
  Credits10 = "credits10",
  MonthlySubscription = "monthly-subscription",
  AnnualSubscription = "annual-subscription",
}

Cada plan requiere un ID del procesador de pago correspondiente:

app/.env.server

PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_ID=price_...
PAYMENTS_PRO_SUBSCRIPTION_PLAN_ID=price_...
PAYMENTS_CREDITS_10_PLAN_ID=price_...
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID=price_test_monthly
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID=price_test_annual

Webhooks

Los webhooks son esenciales para que tu aplicación reciba actualizaciones sobre eventos de pago (pagos completados, suscripciones canceladas, etc.).

URL del webhook de Stripe:

https://tu-dominio.com/payments/stripe-webhook

Para configurar webhooks en Stripe:

1. Ve al Dashboard de Stripe → Developers → Webhooks
2. Agrega la URL del webhook
3. Selecciona los eventos que necesitas escuchar
4. Copia el Signing secret y agrégalo a STRIPE_WEBHOOK_SECRET

Eventos importantes que TalentBricksAI escucha:

• checkout.session.completed - Pago completado
• invoice.paid - Factura pagada (suscripciones)
• customer.subscription.updated - Suscripción actualizada
• customer.subscription.deleted - Suscripción cancelada

Modo de Prueba vs Producción

Stripe ofrece dos ambientes separados:

Ambiente	Claves API	Uso
Test	sk_test_... / pk_test_...	Desarrollo local y testing
Live	sk_live_... / pk_live_...	Producción

Importante

Nunca uses claves de producción en desarrollo. Siempre usa las claves de prueba (sk_test_) hasta que estés listo para lanzar. Stripe proporciona tarjetas de prueba para simular pagos sin cargos reales.

Próximos Pasos

Para configurar Stripe en TalentBricksAI, consulta estas guías:

1. Guía de Integración de Stripe - Tutorial completo paso a paso
2. Configurar Pagos - Guía rápida de configuración

Cambiar de Procesador de Pago (Avanzado)

Nota

TalentBricksAI está configurado para Stripe, pero si necesitas cambiar a otro procesador, Open SaaS lo facilita gracias a su arquitectura modular.

Si necesitas cambiar a Lemon Squeezy o Polar:

1. Consulta la documentación de Open SaaS sobre Payment Integrations
2. Modifica app/src/payment/paymentProcessor.ts para usar el procesador deseado
3. Actualiza las variables de entorno correspondientes
4. Crea productos/precios en el nuevo procesador
5. Actualiza los IDs de plan en .env.server

El resto de tu código de aplicación permanece sin cambios gracias a la interfaz común de procesador de pago.

Recursos Adicionales

• Documentación de Open SaaS sobre Pagos
• Documentación oficial de Stripe
• Stripe Dashboard