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/package.json

@@ -28,6 +28,7 @@
     "fast-xml-parser": "^5.3.3",
     "helmet": "^8.0.0",
     "jsonwebtoken": "^9.0.2",
+    "mercadopago": "^2.12.0",
     "node-cron": "^4.2.1",
     "node-forge": "^1.3.3",
     "nodemailer": "^8.0.2",

apps/api/src/app.ts

@@ -15,6 +15,8 @@ import { usuariosRoutes } from './routes/usuarios.routes.js';
 import { tenantsRoutes } from './routes/tenants.routes.js';
 import fielRoutes from './routes/fiel.routes.js';
 import satRoutes from './routes/sat.routes.js';
+import { webhookRoutes } from './routes/webhook.routes.js';
+import { subscriptionRoutes } from './routes/subscription.routes.js';
 
 const app: Express = express();
 
@@ -47,6 +49,8 @@ app.use('/api/usuarios', usuariosRoutes);
 app.use('/api/tenants', tenantsRoutes);
 app.use('/api/fiel', fielRoutes);
 app.use('/api/sat', satRoutes);
+app.use('/api/webhooks', webhookRoutes);
+app.use('/api/subscriptions', subscriptionRoutes);
 
 // Error handling
 app.use(errorMiddleware);

apps/api/src/config/env.ts

@@ -14,6 +14,9 @@ const envSchema = z.object({
   JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
   CORS_ORIGIN: z.string().default('http://localhost:3000'),
 
+  // Frontend URL (for MercadoPago back_url, emails, etc.)
+  FRONTEND_URL: z.string().default('https://horux360.consultoria-as.com'),
+
   // FIEL encryption (separate from JWT to allow independent rotation)
   FIEL_ENCRYPTION_KEY: z.string().min(32).default('dev-fiel-encryption-key-min-32-chars!!'),
   FIEL_STORAGE_PATH: z.string().default('/var/horux/fiel'),

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 });
+  }
+}

apps/api/src/routes/subscription.routes.ts

@@ -0,0 +1,16 @@
+import { Router, type IRouter } from 'express';
+import { authenticate } from '../middlewares/auth.middleware.js';
+import * as subscriptionController from '../controllers/subscription.controller.js';
+
+const router: IRouter = Router();
+
+// All endpoints require authentication
+router.use(authenticate);
+
+// Admin subscription management
+router.get('/:tenantId', subscriptionController.getSubscription);
+router.post('/:tenantId/generate-link', subscriptionController.generatePaymentLink);
+router.post('/:tenantId/mark-paid', subscriptionController.markAsPaid);
+router.get('/:tenantId/payments', subscriptionController.getPayments);
+
+export { router as subscriptionRoutes };

apps/api/src/routes/webhook.routes.ts

@@ -0,0 +1,9 @@
+import { Router, type IRouter } from 'express';
+import { handleMercadoPagoWebhook } from '../controllers/webhook.controller.js';
+
+const router: IRouter = Router();
+
+// Public endpoint — no auth middleware
+router.post('/mercadopago', handleMercadoPagoWebhook);
+
+export { router as webhookRoutes };

apps/api/src/services/payment/mercadopago.service.ts

@@ -0,0 +1,103 @@
+import { MercadoPagoConfig, PreApproval, Payment as MPPayment } from 'mercadopago';
+import { env } from '../../config/env.js';
+import { createHmac } from 'crypto';
+
+const config = new MercadoPagoConfig({
+  accessToken: env.MP_ACCESS_TOKEN || '',
+});
+
+const preApprovalClient = new PreApproval(config);
+const paymentClient = new MPPayment(config);
+
+/**
+ * Creates a recurring subscription (preapproval) in MercadoPago
+ */
+export async function createPreapproval(params: {
+  tenantId: string;
+  reason: string;
+  amount: number;
+  payerEmail: string;
+}) {
+  const response = await preApprovalClient.create({
+    body: {
+      reason: params.reason,
+      external_reference: params.tenantId,
+      payer_email: params.payerEmail,
+      auto_recurring: {
+        frequency: 1,
+        frequency_type: 'months',
+        transaction_amount: params.amount,
+        currency_id: 'MXN',
+      },
+      back_url: `${env.FRONTEND_URL}/configuracion/suscripcion`,
+    },
+  });
+
+  return {
+    preapprovalId: response.id!,
+    initPoint: response.init_point!,
+    status: response.status!,
+  };
+}
+
+/**
+ * Gets subscription (preapproval) status from MercadoPago
+ */
+export async function getPreapproval(preapprovalId: string) {
+  const response = await preApprovalClient.get({ id: preapprovalId });
+  return {
+    id: response.id,
+    status: response.status,
+    payerEmail: response.payer_email,
+    nextPaymentDate: response.next_payment_date,
+    autoRecurring: response.auto_recurring,
+  };
+}
+
+/**
+ * Gets payment details from MercadoPago
+ */
+export async function getPaymentDetails(paymentId: string) {
+  const response = await paymentClient.get({ id: paymentId });
+  return {
+    id: response.id,
+    status: response.status,
+    statusDetail: response.status_detail,
+    transactionAmount: response.transaction_amount,
+    currencyId: response.currency_id,
+    payerEmail: response.payer?.email,
+    dateApproved: response.date_approved,
+    paymentMethodId: response.payment_method_id,
+    externalReference: response.external_reference,
+  };
+}
+
+/**
+ * Verifies MercadoPago webhook signature (HMAC-SHA256)
+ */
+export function verifyWebhookSignature(
+  xSignature: string,
+  xRequestId: string,
+  dataId: string
+): boolean {
+  if (!env.MP_WEBHOOK_SECRET) return true; // Skip in dev
+
+  // Parse x-signature header: "ts=...,v1=..."
+  const parts: Record<string, string> = {};
+  for (const part of xSignature.split(',')) {
+    const [key, value] = part.split('=');
+    parts[key.trim()] = value.trim();
+  }
+
+  const ts = parts['ts'];
+  const v1 = parts['v1'];
+  if (!ts || !v1) return false;
+
+  // Build the manifest string
+  const manifest = `id:${dataId};request-id:${xRequestId};ts:${ts};`;
+  const hmac = createHmac('sha256', env.MP_WEBHOOK_SECRET)
+    .update(manifest)
+    .digest('hex');
+
+  return hmac === v1;
+}

apps/api/src/services/payment/subscription.service.ts

@@ -0,0 +1,232 @@
+import { prisma } from '../../config/database.js';
+import * as mpService from './mercadopago.service.js';
+import { emailService } from '../email/email.service.js';
+
+// Simple in-memory cache with TTL
+const subscriptionCache = new Map<string, { data: any; expires: number }>();
+
+export function invalidateSubscriptionCache(tenantId: string) {
+  subscriptionCache.delete(`sub:${tenantId}`);
+}
+
+/**
+ * Creates a subscription record in DB and a MercadoPago preapproval
+ */
+export async function createSubscription(params: {
+  tenantId: string;
+  plan: string;
+  amount: number;
+  payerEmail: string;
+}) {
+  const tenant = await prisma.tenant.findUnique({
+    where: { id: params.tenantId },
+  });
+  if (!tenant) throw new Error('Tenant no encontrado');
+
+  // Create MercadoPago preapproval
+  const mp = await mpService.createPreapproval({
+    tenantId: params.tenantId,
+    reason: `Horux360 - Plan ${params.plan} - ${tenant.nombre}`,
+    amount: params.amount,
+    payerEmail: params.payerEmail,
+  });
+
+  // Create DB record
+  const subscription = await prisma.subscription.create({
+    data: {
+      tenantId: params.tenantId,
+      plan: params.plan as any,
+      status: mp.status || 'pending',
+      amount: params.amount,
+      frequency: 'monthly',
+      mpPreapprovalId: mp.preapprovalId,
+    },
+  });
+
+  invalidateSubscriptionCache(params.tenantId);
+
+  return {
+    subscription,
+    paymentUrl: mp.initPoint,
+  };
+}
+
+/**
+ * Gets active subscription for a tenant (cached 5 min)
+ */
+export async function getActiveSubscription(tenantId: string) {
+  const cached = subscriptionCache.get(`sub:${tenantId}`);
+  if (cached && cached.expires > Date.now()) return cached.data;
+
+  const subscription = await prisma.subscription.findFirst({
+    where: { tenantId },
+    orderBy: { createdAt: 'desc' },
+  });
+
+  subscriptionCache.set(`sub:${tenantId}`, {
+    data: subscription,
+    expires: Date.now() + 5 * 60 * 1000,
+  });
+
+  return subscription;
+}
+
+/**
+ * Updates subscription status from webhook notification
+ */
+export async function updateSubscriptionStatus(mpPreapprovalId: string, status: string) {
+  const subscription = await prisma.subscription.findFirst({
+    where: { mpPreapprovalId },
+  });
+  if (!subscription) return null;
+
+  const updated = await prisma.subscription.update({
+    where: { id: subscription.id },
+    data: { status },
+  });
+
+  invalidateSubscriptionCache(subscription.tenantId);
+
+  // Handle cancellation
+  if (status === 'cancelled') {
+    const tenant = await prisma.tenant.findUnique({
+      where: { id: subscription.tenantId },
+      include: { users: { where: { role: 'admin' }, take: 1 } },
+    });
+    if (tenant && tenant.users[0]) {
+      emailService.sendSubscriptionCancelled(tenant.users[0].email, {
+        nombre: tenant.nombre,
+        plan: subscription.plan,
+      }).catch(err => console.error('[EMAIL] Subscription cancelled notification failed:', err));
+    }
+  }
+
+  return updated;
+}
+
+/**
+ * Records a payment from MercadoPago webhook
+ */
+export async function recordPayment(params: {
+  tenantId: string;
+  subscriptionId: string;
+  mpPaymentId: string;
+  amount: number;
+  status: string;
+  paymentMethod: string;
+}) {
+  const payment = await prisma.payment.create({
+    data: {
+      tenantId: params.tenantId,
+      subscriptionId: params.subscriptionId,
+      mpPaymentId: params.mpPaymentId,
+      amount: params.amount,
+      status: params.status,
+      paymentMethod: params.paymentMethod,
+    },
+  });
+
+  // Send email notifications based on payment status
+  const tenant = await prisma.tenant.findUnique({
+    where: { id: params.tenantId },
+    include: { users: { where: { role: 'admin' }, take: 1 } },
+  });
+
+  if (tenant && tenant.users[0]) {
+    const subscription = await prisma.subscription.findUnique({
+      where: { id: params.subscriptionId },
+    });
+
+    if (params.status === 'approved') {
+      emailService.sendPaymentConfirmed(tenant.users[0].email, {
+        nombre: tenant.nombre,
+        amount: params.amount,
+        plan: subscription?.plan || 'N/A',
+        date: new Date().toLocaleDateString('es-MX'),
+      }).catch(err => console.error('[EMAIL] Payment confirmed notification failed:', err));
+    } else if (params.status === 'rejected') {
+      emailService.sendPaymentFailed(tenant.users[0].email, {
+        nombre: tenant.nombre,
+        amount: params.amount,
+        plan: subscription?.plan || 'N/A',
+      }).catch(err => console.error('[EMAIL] Payment failed notification failed:', err));
+    }
+  }
+
+  return payment;
+}
+
+/**
+ * Manually marks a subscription as paid (for bank transfers)
+ */
+export async function markAsPaidManually(tenantId: string, amount: number) {
+  const subscription = await getActiveSubscription(tenantId);
+  if (!subscription) throw new Error('No hay suscripción activa');
+
+  // Update subscription status
+  await prisma.subscription.update({
+    where: { id: subscription.id },
+    data: { status: 'authorized' },
+  });
+
+  // Record the manual payment
+  const payment = await prisma.payment.create({
+    data: {
+      tenantId,
+      subscriptionId: subscription.id,
+      mpPaymentId: `manual-${Date.now()}`,
+      amount,
+      status: 'approved',
+      paymentMethod: 'bank_transfer',
+    },
+  });
+
+  invalidateSubscriptionCache(tenantId);
+  return payment;
+}
+
+/**
+ * Generates a payment link for a tenant
+ */
+export async function generatePaymentLink(tenantId: string) {
+  const tenant = await prisma.tenant.findUnique({
+    where: { id: tenantId },
+    include: { users: { where: { role: 'admin' }, take: 1 } },
+  });
+  if (!tenant) throw new Error('Tenant no encontrado');
+  if (!tenant.users[0]) throw new Error('No admin user found');
+
+  const subscription = await getActiveSubscription(tenantId);
+  const plan = subscription?.plan || tenant.plan;
+  const amount = subscription?.amount || 0;
+
+  if (!amount) throw new Error('No se encontró monto de suscripción');
+
+  const mp = await mpService.createPreapproval({
+    tenantId,
+    reason: `Horux360 - Plan ${plan} - ${tenant.nombre}`,
+    amount,
+    payerEmail: tenant.users[0].email,
+  });
+
+  // Update subscription with new MP preapproval ID
+  if (subscription) {
+    await prisma.subscription.update({
+      where: { id: subscription.id },
+      data: { mpPreapprovalId: mp.preapprovalId },
+    });
+  }
+
+  return { paymentUrl: mp.initPoint };
+}
+
+/**
+ * Gets payment history for a tenant
+ */
+export async function getPaymentHistory(tenantId: string) {
+  return prisma.payment.findMany({
+    where: { tenantId },
+    orderBy: { createdAt: 'desc' },
+    take: 50,
+  });
+}