feat: add MercadoPago payments, subscription service, and webhooks

- MercadoPago PreApproval integration for recurring subscriptions
- Subscription service with caching, manual payment, payment history
- Webhook handler with HMAC-SHA256 signature verification
- Admin endpoints for subscription management and payment links
- Email notifications on payment success/failure/cancellation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/src/controllers/subscription.controller.ts

@@ -0,0 +1,51 @@
+import type { Request, Response, NextFunction } from 'express';
+import * as subscriptionService from '../services/payment/subscription.service.js';
+
+export async function getSubscription(req: Request, res: Response, next: NextFunction) {
+  try {
+    const tenantId = String(req.params.tenantId);
+    const subscription = await subscriptionService.getActiveSubscription(tenantId);
+    if (!subscription) {
+      return res.status(404).json({ message: 'No se encontró suscripción' });
+    }
+    res.json(subscription);
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function generatePaymentLink(req: Request, res: Response, next: NextFunction) {
+  try {
+    const tenantId = String(req.params.tenantId);
+    const result = await subscriptionService.generatePaymentLink(tenantId);
+    res.json(result);
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function markAsPaid(req: Request, res: Response, next: NextFunction) {
+  try {
+    const tenantId = String(req.params.tenantId);
+    const { amount } = req.body;
+
+    if (!amount || amount <= 0) {
+      return res.status(400).json({ message: 'Monto inválido' });
+    }
+
+    const payment = await subscriptionService.markAsPaidManually(tenantId, amount);
+    res.json(payment);
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function getPayments(req: Request, res: Response, next: NextFunction) {
+  try {
+    const tenantId = String(req.params.tenantId);
+    const payments = await subscriptionService.getPaymentHistory(tenantId);
+    res.json(payments);
+  } catch (error) {
+    next(error);
+  }
+}

apps/api/src/controllers/webhook.controller.ts

@@ -0,0 +1,95 @@
+import type { Request, Response, NextFunction } from 'express';
+import * as mpService from '../services/payment/mercadopago.service.js';
+import * as subscriptionService from '../services/payment/subscription.service.js';
+import { prisma } from '../config/database.js';
+
+export async function handleMercadoPagoWebhook(req: Request, res: Response, next: NextFunction) {
+  try {
+    const { type, data } = req.body;
+    const xSignature = req.headers['x-signature'] as string;
+    const xRequestId = req.headers['x-request-id'] as string;
+
+    // Verify webhook signature
+    if (xSignature && xRequestId && data?.id) {
+      const isValid = mpService.verifyWebhookSignature(xSignature, xRequestId, String(data.id));
+      if (!isValid) {
+        console.warn('[WEBHOOK] Invalid MercadoPago signature');
+        return res.status(401).json({ message: 'Invalid signature' });
+      }
+    }
+
+    if (type === 'payment') {
+      await handlePaymentNotification(String(data.id));
+    } else if (type === 'subscription_preapproval') {
+      await handlePreapprovalNotification(String(data.id));
+    }
+
+    // Always respond 200 to acknowledge receipt
+    res.status(200).json({ received: true });
+  } catch (error) {
+    console.error('[WEBHOOK] Error processing MercadoPago webhook:', error);
+    // Still respond 200 to prevent retries for processing errors
+    res.status(200).json({ received: true, error: 'processing_error' });
+  }
+}
+
+async function handlePaymentNotification(paymentId: string) {
+  const payment = await mpService.getPaymentDetails(paymentId);
+
+  if (!payment.externalReference) {
+    console.warn('[WEBHOOK] Payment without external_reference:', paymentId);
+    return;
+  }
+
+  const tenantId = payment.externalReference;
+
+  // Find the subscription for this tenant
+  const subscription = await prisma.subscription.findFirst({
+    where: { tenantId },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  if (!subscription) {
+    console.warn('[WEBHOOK] No subscription found for tenant:', tenantId);
+    return;
+  }
+
+  await subscriptionService.recordPayment({
+    tenantId,
+    subscriptionId: subscription.id,
+    mpPaymentId: paymentId,
+    amount: payment.transactionAmount || 0,
+    status: payment.status || 'unknown',
+    paymentMethod: payment.paymentMethodId || 'unknown',
+  });
+
+  // If payment approved, ensure subscription is active
+  if (payment.status === 'approved') {
+    await prisma.subscription.update({
+      where: { id: subscription.id },
+      data: { status: 'authorized' },
+    });
+    subscriptionService.invalidateSubscriptionCache(tenantId);
+  }
+
+  // Broadcast cache invalidation to PM2 cluster workers
+  if (typeof process.send === 'function') {
+    process.send({ type: 'invalidate-tenant-cache', tenantId });
+  }
+}
+
+async function handlePreapprovalNotification(preapprovalId: string) {
+  const preapproval = await mpService.getPreapproval(preapprovalId);
+
+  if (preapproval.status) {
+    await subscriptionService.updateSubscriptionStatus(preapprovalId, preapproval.status);
+  }
+
+  // Broadcast cache invalidation
+  const subscription = await prisma.subscription.findFirst({
+    where: { mpPreapprovalId: preapprovalId },
+  });
+  if (subscription && typeof process.send === 'function') {
+    process.send({ type: 'invalidate-tenant-cache', tenantId: subscription.tenantId });
+  }
+}