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

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

Configuracion de Paths

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

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

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

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

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