betting-analytics/docs/02-definicion-modulos/BA-008-PAYMENTS.md

---
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