--- id: "BA-008-PAYMENTS" title: "BA-008: Modulo de Payments" type: "Module Definition" epic: "BA-008" status: "Draft" project: "betting-analytics" version: "1.0.0" created_date: "2026-01-04" updated_date: "2026-01-04" --- # BA-008: Modulo de Payments **Version:** 1.0.0 **Fecha:** 2026-01-04 **Estado:** Definicion **Prioridad:** Alta --- ## Descripcion General El modulo de Payments proporciona la integracion con Stripe para gestionar suscripciones, pagos y facturacion del sistema SaaS de Betting Analytics. --- ## Objetivos 1. Integrar Stripe como pasarela de pagos 2. Gestionar planes de suscripcion (Free, Pro, Enterprise) 3. Implementar checkout flow con Stripe Elements 4. Automatizar facturacion y cobros recurrentes 5. Gestionar creditos de prediccion por tenant --- ## Planes de Suscripcion ```yaml Planes: free: nombre: "Free" precio: $0/mes limites: predicciones_mes: 50 modelos_max: 1 historico_dias: 30 usuarios_max: 1 features: - Predicciones basicas - 1 modelo standard - Soporte comunidad pro: nombre: "Pro" precio: $39/mes stripe_price_id: ba_pro_monthly limites: predicciones_mes: 500 modelos_max: 3 historico_dias: 365 usuarios_max: 5 features: - Todo de Free - Modelos avanzados - API access - Soporte email enterprise: nombre: "Enterprise" precio: $149/mes stripe_price_id: ba_enterprise_monthly limites: predicciones_mes: unlimited modelos_max: unlimited historico_dias: unlimited usuarios_max: unlimited features: - Todo de Pro - Modelos custom - SLA garantizado - Soporte dedicado ``` --- ## Productos Stripe ```yaml Productos: ba_pro_monthly: type: subscription nombre: "Betting Analytics Pro" precio: $39/mes billing_interval: monthly metadata: plan_code: pro predictions: 500 ba_enterprise_monthly: type: subscription nombre: "Betting Analytics Enterprise" precio: $149/mes billing_interval: monthly metadata: plan_code: enterprise predictions: unlimited ba_predictions_100: type: one_time nombre: "Pack 100 Predicciones" precio: $9 metadata: product_type: credits credits_amount: 100 ``` --- ## Entidades del Dominio ### Subscription ```yaml Entidad: Subscription Descripcion: Suscripcion activa de un tenant Atributos: - id: UUID (PK) - tenant_id: UUID (FK) - plan_id: UUID (FK) - stripe_subscription_id: string - stripe_customer_id: string - status: enum [active, past_due, canceled, incomplete, trialing] - current_period_start: timestamp - current_period_end: timestamp - cancel_at_period_end: boolean - created_at: timestamp - updated_at: timestamp Relaciones: - N:1 con Tenant - N:1 con Plan - 1:N con Invoice ``` ### Invoice ```yaml Entidad: Invoice Descripcion: Factura de Stripe Atributos: - id: UUID (PK) - tenant_id: UUID (FK) - subscription_id: UUID (FK) - stripe_invoice_id: string - amount_due: decimal - amount_paid: decimal - currency: string - status: enum [draft, open, paid, void, uncollectible] - invoice_pdf_url: string - paid_at: timestamp - created_at: timestamp ``` ### PredictionCredit ```yaml Entidad: PredictionCredit Descripcion: Balance de creditos por tenant Atributos: - id: UUID (PK) - tenant_id: UUID (FK, unico) - credits_included: integer - credits_remaining: integer - credits_used: integer - credits_extra: integer - resets_at: timestamp - created_at: timestamp - updated_at: timestamp Notas: - credits_remaining se resetea cada periodo - credits_extra no expiran ``` --- ## Webhooks Stripe ```yaml Eventos: - customer.subscription.created: accion: Crear Subscription en BD - customer.subscription.updated: accion: Actualizar status/periodo - customer.subscription.deleted: accion: Marcar como canceled - invoice.payment_succeeded: accion: Registrar pago, resetear creditos - invoice.payment_failed: accion: Marcar past_due, notificar - checkout.session.completed: accion: Activar plan o creditos ``` --- ## Funcionalidades ### F-008.1: Gestion de Suscripciones | ID | Funcionalidad | Descripcion | Prioridad | |----|---------------|-------------|-----------| | F-008.1.1 | Ver planes | Listar planes disponibles | Alta | | F-008.1.2 | Suscribirse | Checkout con Stripe | Alta | | F-008.1.3 | Cambiar plan | Upgrade/downgrade | Media | | F-008.1.4 | Cancelar | Cancelar al final del periodo | Media | ### F-008.2: Facturacion | ID | Funcionalidad | Descripcion | Prioridad | |----|---------------|-------------|-----------| | F-008.2.1 | Ver facturas | Historial de facturas | Alta | | F-008.2.2 | Descargar PDF | Obtener factura PDF | Media | | F-008.2.3 | Portal billing | Redirect a Stripe portal | Alta | ### F-008.3: Creditos | ID | Funcionalidad | Descripcion | Prioridad | |----|---------------|-------------|-----------| | F-008.3.1 | Ver balance | Creditos restantes | Alta | | F-008.3.2 | Comprar extra | Pack de creditos | Media | | F-008.3.3 | Consumir | Decrementar al predecir | Alta | --- ## API Endpoints ```yaml Base: /api/v1/billing Endpoints: GET /billing/plans: Descripcion: Listar planes disponibles Response: 200 OK POST /billing/checkout: Descripcion: Crear sesion de checkout Body: { plan_code, success_url, cancel_url } Response: 200 { checkout_url } GET /billing/subscription: Descripcion: Suscripcion actual del tenant Response: 200 OK POST /billing/subscription/cancel: Descripcion: Cancelar al final del periodo Response: 200 OK GET /billing/invoices: Descripcion: Historial de facturas Response: 200 OK (paginado) GET /billing/credits: Descripcion: Balance de creditos Response: 200 OK POST /billing/credits/purchase: Descripcion: Comprar creditos extra Body: { pack_id } Response: 200 { checkout_url } POST /billing/webhook: Descripcion: Webhook de Stripe Headers: { stripe-signature } Response: 200 OK ``` --- ## Dependencias ```yaml Dependencias: - BA-007 (tenants): Multi-tenancy - BA-001 (auth): Autenticacion Servicios Externos: - Stripe API - Stripe Webhooks Catalogos: - shared/catalog/payments/ ``` --- ## Criterios de Aceptacion - [ ] Usuario puede ver planes y precios - [ ] Checkout redirect a Stripe funciona - [ ] Webhooks actualizan estado correctamente - [ ] Creditos se resetean cada periodo - [ ] Portal de billing funciona - [ ] Facturas se pueden descargar --- **Documento generado por:** NEXUS Orchestration **Fecha:** 2026-01-04