workspace-v1/shared/modules/payments/README.md

# Payments - Core Module

**Modulo:** shared/modules/payments/
**Version:** 0.1.0
**Fecha:** 2026-01-03
**Owner:** Backend-Agent
**Estado:** desarrollo

---

## Descripcion

Modulo de pagos compartido que abstrae integraciones con proveedores de pago (Stripe, PayPal, MercadoPago). Provee interfaces unificadas para procesamiento de pagos, suscripciones y webhooks.

---

## Instalacion

### Prerequisitos

```bash
npm install stripe
# Opcional:
npm install @paypal/checkout-server-sdk
npm install mercadopago
```

### Configuracion de Paths

```json
{
  "compilerOptions": {
    "paths": {
      "@shared/modules/*": ["../../shared/modules/*"]
    }
  }
}
```

---

## API Publica (Planificada)

### Servicios

| Servicio | Descripcion | Proveedor |
|----------|-------------|-----------|
| `PaymentService` | Servicio unificado | Multi-provider |
| `StripeService` | Integracion Stripe | Stripe |
| `SubscriptionService` | Gestion suscripciones | Stripe |
| `WebhookService` | Procesamiento webhooks | Multi-provider |

### Tipos

```typescript
interface PaymentIntent {
  id: string;
  amount: number;
  currency: string;
  status: 'pending' | 'processing' | 'succeeded' | 'failed';
  provider: 'stripe' | 'paypal' | 'mercadopago';
  customerId?: string;
  metadata?: Record<string, any>;
}

interface Subscription {
  id: string;
  customerId: string;
  planId: string;
  status: 'active' | 'canceled' | 'past_due' | 'trialing';
  currentPeriodStart: Date;
  currentPeriodEnd: Date;
  cancelAtPeriodEnd: boolean;
}

interface CheckoutSession {
  id: string;
  url: string;
  expiresAt: Date;
  lineItems: LineItem[];
  successUrl: string;
  cancelUrl: string;
}
```

---

## Ejemplos de Uso

### Ejemplo 1: Crear Checkout Session

```typescript
import { PaymentService } from '@shared/modules/payments';

@Injectable()
export class CheckoutService {
  constructor(private payments: PaymentService) {}

  async createCheckout(items: CartItem[], userId: string) {
    const session = await this.payments.createCheckoutSession({
      customerId: userId,
      lineItems: items.map(item => ({
        name: item.name,
        amount: item.price,
        quantity: item.quantity,
      })),
      successUrl: '/checkout/success',
      cancelUrl: '/checkout/cancel',
    });

    return { checkoutUrl: session.url };
  }
}
```

### Ejemplo 2: Procesar Webhook

```typescript
import { WebhookService } from '@shared/modules/payments';

@Controller('webhooks')
export class WebhookController {
  constructor(private webhooks: WebhookService) {}

  @Post('stripe')
  async handleStripeWebhook(
    @Headers('stripe-signature') signature: string,
    @Body() rawBody: Buffer,
  ) {
    const event = await this.webhooks.verifyStripeEvent(rawBody, signature);

    switch (event.type) {
      case 'payment_intent.succeeded':
        await this.handlePaymentSuccess(event.data);
        break;
      case 'customer.subscription.updated':
        await this.handleSubscriptionUpdate(event.data);
        break;
    }

    return { received: true };
  }
}
```

---

## Dependencias

### Internas

| Modulo | Uso |
|--------|-----|
| `@shared/modules/utils` | Formateo moneda |

### Externas (npm)

| Paquete | Version | Uso |
|---------|---------|-----|
| `stripe` | `^14.0` | API Stripe |

---

## Relacion con Catalogo

| Aspecto | modules/payments | catalog/payments |
|---------|-----------------|------------------|
| Contenido | Servicios listos | Documentacion + DDL |
| Uso | Importar | Copiar y adaptar |
| DDL tablas | No | Si |
| Webhooks docs | Basico | Completo |

---

## Estado Actual

```markdown
- [ ] PaymentService base
- [ ] StripeService integracion
- [ ] SubscriptionService
- [ ] WebhookService
- [ ] Checkout sessions
- [ ] Customer management
- [ ] Refunds
- [ ] Tests unitarios
```

---

## Changelog

### v0.1.0 (2026-01-03)
- Estructura inicial
- README con planificacion

---

**Modulo:** shared/modules/payments/ | **Owner:** Backend-Agent