elpaypg 0.0.0-stage → 2.0.0

package/src/routes/admin.routes.js

@@ -0,0 +1,2421 @@
+import crypto from 'node:crypto';
+import { Router } from 'express';
+import { PaymentStatus, PaymentMethod, SellingMode, AuditActorType, isValidVpa, toRupeesString, deriveCloudflareRoutes, resolveRuntimeUrls, resolveGmailRedirectUri, createOAuthState, validateOutboundWebhookUrl } from '../vendor/common/index.js';
+import { PaymentVerificationPipeline } from '../vendor/core/index.js';
+import { globalTunnelManager } from '../services/tunnel-manager.js';
+import { formatQrDataUrl } from '../services/whatsapp-berry.service.js';
+
+function resolveSellingModeAndMethods(body, currentBranding = {}) {
+  const inputBranding = body.branding || {};
+  let sellingMode = body.sellingMode || inputBranding.sellingMode || currentBranding.sellingMode;
+  let rawMethods = body.enabledPaymentMethods || inputBranding.enabledPaymentMethods;
+
+  if (!sellingMode) {
+    if (inputBranding.counterInstructions || currentBranding.counterInstructions || body.cashEnabled !== undefined || body.cardEnabled !== undefined) {
+      sellingMode = SellingMode.OFFLINE;
+    } else if (rawMethods && (rawMethods.includes(PaymentMethod.CASH_COUNTER) || rawMethods.includes(PaymentMethod.CARD_COUNTER))) {
+      sellingMode = SellingMode.OFFLINE;
+    } else if (currentBranding.enabledPaymentMethods && (currentBranding.enabledPaymentMethods.includes(PaymentMethod.CASH_COUNTER) || currentBranding.enabledPaymentMethods.includes(PaymentMethod.CARD_COUNTER))) {
+      sellingMode = SellingMode.OFFLINE;
+    } else {
+      sellingMode = SellingMode.ONLINE;
+    }
+  }
+
+  const codOn = body.codEnabled !== undefined 
+    ? Boolean(body.codEnabled) 
+    : (inputBranding.codEnabled !== undefined 
+        ? Boolean(inputBranding.codEnabled) 
+        : (currentBranding.codEnabled !== undefined ? Boolean(currentBranding.codEnabled) : (currentBranding.enabledPaymentMethods ? currentBranding.enabledPaymentMethods.includes(PaymentMethod.COD) : true)));
+
+  const cashOn = body.cashEnabled !== undefined 
+    ? Boolean(body.cashEnabled) 
+    : (inputBranding.cashEnabled !== undefined 
+        ? Boolean(inputBranding.cashEnabled) 
+        : (currentBranding.cashEnabled !== undefined ? Boolean(currentBranding.cashEnabled) : (currentBranding.enabledPaymentMethods ? currentBranding.enabledPaymentMethods.includes(PaymentMethod.CASH_COUNTER) : true)));
+
+  const cardOn = body.cardEnabled !== undefined 
+    ? Boolean(body.cardEnabled) 
+    : (inputBranding.cardEnabled !== undefined 
+        ? Boolean(inputBranding.cardEnabled) 
+        : (currentBranding.cardEnabled !== undefined ? Boolean(currentBranding.cardEnabled) : (currentBranding.enabledPaymentMethods ? currentBranding.enabledPaymentMethods.includes(PaymentMethod.CARD_COUNTER) : true)));
+
+  if (!rawMethods) {
+    rawMethods = [PaymentMethod.UPI];
+    if (sellingMode === SellingMode.ONLINE) {
+      if (codOn) rawMethods.push(PaymentMethod.COD);
+    } else {
+      if (cashOn) rawMethods.push(PaymentMethod.CASH_COUNTER);
+      if (cardOn) rawMethods.push(PaymentMethod.CARD_COUNTER);
+    }
+  }
+
+  // Strictly filter based on selling mode:
+  // UPI is always enabled in both modes! Turning it off isn't allowed!
+  const sanitized = [PaymentMethod.UPI];
+  if (sellingMode === SellingMode.ONLINE) {
+    if (rawMethods.includes(PaymentMethod.COD) && codOn) {
+      sanitized.push(PaymentMethod.COD);
+    } else if (body.codEnabled === true) {
+      sanitized.push(PaymentMethod.COD);
+    }
+  } else {
+    if (rawMethods.includes(PaymentMethod.CASH_COUNTER) && cashOn) {
+      sanitized.push(PaymentMethod.CASH_COUNTER);
+    } else if (body.cashEnabled === true) {
+      sanitized.push(PaymentMethod.CASH_COUNTER);
+    }
+    if (rawMethods.includes(PaymentMethod.CARD_COUNTER) && cardOn) {
+      sanitized.push(PaymentMethod.CARD_COUNTER);
+    } else if (body.cardEnabled === true) {
+      sanitized.push(PaymentMethod.CARD_COUNTER);
+    }
+  }
+
+  return {
+    sellingMode,
+    enabledPaymentMethods: sanitized,
+    codEnabled: sanitized.includes(PaymentMethod.COD) || (sellingMode !== SellingMode.ONLINE ? codOn : false),
+    cashEnabled: sanitized.includes(PaymentMethod.CASH_COUNTER) || (sellingMode !== SellingMode.OFFLINE ? cashOn : false),
+    cardEnabled: sanitized.includes(PaymentMethod.CARD_COUNTER) || (sellingMode !== SellingMode.OFFLINE ? cardOn : false)
+  };
+}
+
+/**
+ * Registers merchant admin dashboard routes.
+ * @param {HttpServer} server
+ * @param {{
+ *   db: import('../vendor/db/index.js').Database,
+ *   sessionRepo: import('../vendor/db/index.js').PaymentSessionRepository,
+ *   accountRepo: import('../vendor/db/index.js').ReceivingAccountRepository,
+ *   merchantRepo: import('../vendor/db/index.js').MerchantRepository,
+ *   auditRepo: import('../vendor/db/index.js').AuditLogRepository,
+ *   queueEngine: import('../vendor/core/index.js').QueueEngine
+ * }} ctx
+ */
+export function registerAdminRoutes(router, ctx) {
+  const resolveMerchant = (req, explicitId = null) => {
+    const targetId = explicitId || (req ? (req.query?.merchantId || req.headers?.['x-merchant-id']) : null);
+    if (targetId) {
+      const found = ctx.merchantRepo.findById(targetId);
+      if (found) return found;
+    }
+    return ctx.merchantRepo.getDefault
+      ? ctx.merchantRepo.getDefault()
+      : (ctx.merchantRepo.findById('00000000-0000-0000-0000-000000000001') || ctx.merchantRepo.findAll()[0]);
+  };
+
+  // GET /api/v1/admin/queue
+  router.get('/api/v1/admin/queue', async (req, res) => {
+    const merchantId = req.query.merchantId || req.headers?.['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    let account = ctx.accountRepo.findActiveForMerchant(merchantId);
+
+    if (!account) {
+      const allAccs = ctx.accountRepo.findByMerchantId ? ctx.accountRepo.findByMerchantId(merchantId) : [];
+      account = allAccs.find(a => a.isActive) || allAccs[0] || null;
+    }
+
+    if (!account) {
+      res.status(200).json({ active: null, currentSlot: null, queue: [] });
+      return;
+    }
+
+    let currentActive = ctx.sessionRepo.findCurrentActiveOrProcessing(account.id);
+    if (!currentActive && ctx.sessionRepo.findCurrentActiveOrProcessingForMerchant) {
+      currentActive = ctx.sessionRepo.findCurrentActiveOrProcessingForMerchant(merchantId);
+      if (currentActive && currentActive.receivingAccountId !== account.id) {
+        try {
+          ctx.db.execute('UPDATE payment_sessions SET receiving_account_id = ? WHERE id = ?', [account.id, currentActive.id]);
+          ctx.db.execute('UPDATE payment_receiving_accounts SET is_slot_busy = 1, current_active_session_id = ? WHERE id = ?', [currentActive.id, account.id]);
+          currentActive.receivingAccountId = account.id;
+        } catch {}
+      }
+    }
+
+    const queuedSessions = ctx.sessionRepo.findQueuedSessions(account.id);
+
+    res.status(200).json({
+      receivingAccount: {
+        id: account.id,
+        upiId: account.upiId,
+        payeeName: account.payeeName,
+        isSlotBusy: Boolean(currentActive || account.isSlotBusy)
+      },
+      currentSlot: currentActive ? {
+        id: currentActive.id,
+        orderId: currentActive.orderId,
+        amountPaise: currentActive.amountPaise.toString(),
+        status: currentActive.status,
+        expiresAt: currentActive.expiresAt,
+        processingExpiresAt: currentActive.processingExpiresAt
+      } : null,
+      queue: queuedSessions.map(s => ({
+        id: s.id,
+        orderId: s.orderId,
+        amountPaise: s.amountPaise.toString(),
+        queuePosition: s.queuePosition,
+        createdAt: s.createdAt
+      }))
+    });
+  });
+
+  // GET /api/v1/admin/observers
+  router.get('/api/v1/admin/observers', async (req, res) => {
+    const devices = ctx.db.query('SELECT * FROM android_devices ORDER BY created_at DESC');
+    const now = Date.now();
+
+    const androidHealth = devices.map(d => {
+      const lastSeen = d.last_heartbeat_at ? new Date(d.last_heartbeat_at).getTime() : 0;
+      const isConnected = (now - lastSeen) < 180000; // Connected if heartbeat within 3 mins
+      return {
+        id: d.id,
+        name: d.device_name,
+        model: d.device_model,
+        status: isConnected ? 'CONNECTED' : 'DISCONNECTED',
+        lastSeenAt: d.last_heartbeat_at,
+        lastObservationAt: d.last_observation_at
+      };
+    });
+
+    // Query live Google Messages browser automator status
+    let smsStatus = { status: 'STANDBY', isPaired: false, messagesObserved: 0, isRunning: false };
+    try {
+      const smsPort = Number(process.env.SMS_OBSERVER_PORT || 6002);
+      const smsRes = await fetch(`http://localhost:${smsPort}/api/browser/status`, {
+        headers: { Authorization: `Bearer ${getObserverToken()}` },
+        signal: AbortSignal.timeout(1500)
+      });
+      if (smsRes.ok) {
+        smsStatus = await smsRes.json();
+      }
+    } catch {}
+
+    // Query live Gmail browser automator status
+    let gmailStatus = { status: 'STANDBY', isLoggedIn: false, emailsObserved: 0, isRunning: false };
+    try {
+      const gmailPort = Number(process.env.GMAIL_OBSERVER_PORT || 6003);
+      const gmailRes = await fetch(`http://localhost:${gmailPort}/api/browser/status`, {
+        headers: { Authorization: `Bearer ${getObserverToken()}` },
+        signal: AbortSignal.timeout(1500)
+      });
+      if (gmailRes.ok) {
+        gmailStatus = await gmailRes.json();
+      }
+    } catch {}
+
+    res.status(200).json({
+      gmail: {
+        status: gmailStatus.status || (gmailStatus.isLoggedIn ? 'CONNECTED' : 'STANDBY'),
+        isLoggedIn: Boolean(gmailStatus.isLoggedIn),
+        isRunning: Boolean(gmailStatus.isRunning || gmailStatus.isLoggedIn || gmailStatus.status === 'CONNECTED'),
+        emailsObserved: gmailStatus.emailsObserved || 0,
+        lastCheckedAt: gmailStatus.lastCheckedAt || null
+      },
+      android: {
+        devices: androidHealth,
+        totalDevices: devices.length
+      },
+      sms: {
+        status: smsStatus.status || (smsStatus.isPaired ? 'CONNECTED' : 'STANDBY'),
+        isPaired: Boolean(smsStatus.isPaired),
+        isRunning: Boolean(smsStatus.isRunning || smsStatus.isPaired || smsStatus.status === 'CONNECTED'),
+        messagesObserved: smsStatus.messagesObserved || 0,
+        lastSeenAt: smsStatus.lastSeenAt || null
+      }
+    });
+  });
+
+  // GET /api/v1/admin/payments
+  router.get('/api/v1/admin/payments', async (req, res) => {
+    const merchantId = req.query.merchantId || '00000000-0000-0000-0000-000000000001';
+    const limit = parseInt(req.query.limit || '50', 10);
+    const payments = ctx.sessionRepo.findByMerchantId(merchantId, limit);
+
+    res.status(200).json({
+      payments: payments.map(p => ({
+        id: p.id,
+        orderId: p.orderId,
+        amountPaise: p.amountPaise.toString(),
+        currency: p.currency,
+        method: p.method,
+        status: p.status,
+        verificationLevel: p.verificationLevel || 0,
+        verificationSources: p.verificationSources || [],
+        verificationTag: p.verificationTag || 'UNVERIFIED',
+        createdAt: p.createdAt,
+        completedAt: p.completedAt
+      }))
+    });
+  });
+
+  // GET /api/v1/admin/tickets
+  router.get('/api/v1/admin/tickets', async (req, res) => {
+    const merchantId = req.query.merchantId || '00000000-0000-0000-0000-000000000001';
+    if (!ctx.ticketRepo) {
+      res.status(200).json({ tickets: [] });
+      return;
+    }
+    const tickets = ctx.ticketRepo.findTicketsByMerchant(merchantId);
+    res.status(200).json({ tickets });
+  });
+
+  // POST /api/v1/admin/tickets/:id/resolve
+  router.post('/api/v1/admin/tickets/:id/resolve', async (req, res) => {
+    if (!ctx.ticketRepo) {
+      res.status(404).json({ error: 'Ticket repo not configured' });
+      return;
+    }
+    const ticket = ctx.ticketRepo.updateTicketStatus(req.params.id, 'RESOLVED');
+    res.status(200).json({ success: true, ticket });
+  });
+
+  // POST /api/v1/admin/counter-confirm
+  router.post('/api/v1/admin/counter-confirm', async (req, res) => {
+    const body = req.body || {};
+    const { paymentId, operatorId, method } = body;
+
+    if (!paymentId || !operatorId) {
+      res.status(400).json({ error: 'paymentId and operatorId are required.' });
+      return;
+    }
+
+    const session = ctx.sessionRepo.findById(paymentId);
+    if (!session) {
+      res.status(404).json({ error: `Payment session not found: ${paymentId}` });
+      return;
+    }
+
+    // Manual confirmation is only valid for counter payments still awaiting settlement.
+    // A UPI session must only reach SUCCESS through the verification engine.
+    if (session.method !== PaymentMethod.CASH_COUNTER && session.method !== PaymentMethod.CARD_COUNTER) {
+      res.status(400).json({ error: `Manual confirmation is only allowed for counter payments (session method is '${session.method}').` });
+      return;
+    }
+    if ([PaymentStatus.SUCCESS, PaymentStatus.FAILED, PaymentStatus.EXPIRED, PaymentStatus.CANCELLED].includes(session.status)) {
+      res.status(409).json({ error: `Cannot confirm a payment in terminal status '${session.status}'.` });
+      return;
+    }
+
+    const updated = ctx.sessionRepo.transitionToTerminal(paymentId, PaymentStatus.SUCCESS);
+
+    ctx.auditRepo.log({
+      merchantId: session.merchantId,
+      entityType: 'PAYMENT_SESSION',
+      entityId: paymentId,
+      action: 'COUNTER_MANUAL_PAYMENT_CONFIRMED',
+      actorType: AuditActorType.ADMIN,
+      actorId: operatorId,
+      details: { method: method || PaymentMethod.CASH_COUNTER, operatorId }
+    });
+
+    server.broadcastSse(paymentId, 'status_change', {
+      status: PaymentStatus.SUCCESS,
+      method: method || PaymentMethod.CASH_COUNTER,
+      orderId: session.orderId
+    });
+    server.broadcastSse(paymentId, 'state_change', {
+      status: PaymentStatus.SUCCESS,
+      method: method || PaymentMethod.CASH_COUNTER,
+      orderId: session.orderId
+    });
+
+    if (ctx.eventEmitter) {
+      ctx.eventEmitter.emit('PAYMENT.SUCCESS', {
+        paymentId: updated.id,
+        orderId: session.orderId,
+        merchantId: session.merchantId,
+        amountPaise: session.amountPaise
+      });
+    }
+
+    res.status(200).json({
+      confirmed: true,
+      paymentId: updated.id,
+      status: PaymentStatus.SUCCESS,
+      orderId: session.orderId
+    });
+  });
+
+  // POST /api/v1/admin/counter-decline (Declines/Rejects manual cash or card counter payment)
+  router.post('/api/v1/admin/counter-decline', async (req, res) => {
+    const body = req.body || {};
+    const { paymentId, operatorId, reason } = body;
+
+    if (!paymentId || !operatorId) {
+      res.status(400).json({ error: 'paymentId and operatorId are required.' });
+      return;
+    }
+
+    const session = ctx.sessionRepo.findById(paymentId);
+    if (!session) {
+      res.status(404).json({ error: `Payment session not found: ${paymentId}` });
+      return;
+    }
+
+    const updated = ctx.sessionRepo.transitionToTerminal(paymentId, PaymentStatus.FAILED);
+
+    ctx.auditRepo.log({
+      merchantId: session.merchantId,
+      entityType: 'PAYMENT_SESSION',
+      entityId: paymentId,
+      action: 'COUNTER_MANUAL_PAYMENT_DECLINED',
+      actorType: AuditActorType.ADMIN,
+      actorId: operatorId,
+      details: {
+        method: session.method,
+        operatorId,
+        reason: reason || 'Declined by merchant counter operator'
+      }
+    });
+
+    server.broadcastSse(paymentId, 'status_change', {
+      status: PaymentStatus.FAILED,
+      method: session.method,
+      reason: reason || 'Declined by merchant counter operator',
+      orderId: session.orderId
+    });
+    server.broadcastSse(paymentId, 'state_change', {
+      status: PaymentStatus.FAILED,
+      method: session.method,
+      reason: reason || 'Declined by merchant counter operator',
+      orderId: session.orderId
+    });
+
+    if (ctx.eventEmitter) {
+      ctx.eventEmitter.emit('PAYMENT.FAILED', {
+        paymentId: updated.id,
+        orderId: session.orderId,
+        merchantId: session.merchantId,
+        amountPaise: session.amountPaise,
+        reason: reason || 'Counter payment declined'
+      });
+    }
+
+    res.status(200).json({
+      declined: true,
+      paymentId: updated.id,
+      status: PaymentStatus.FAILED,
+      reason: reason || 'Counter payment declined'
+    });
+  });
+
+  // GET /api/v1/admin/upi-settings
+  router.get('/api/v1/admin/upi-settings', async (req, res) => {
+    let merchant = resolveMerchant(req);
+
+    const account = merchant ? ctx.accountRepo.findActiveForMerchant(merchant.id) : null;
+    const accounts = merchant ? ctx.accountRepo.findByMerchantId(merchant.id) : [];
+
+    if (!account) {
+      res.status(200).json({
+        id: '',
+        upiId: '',
+        payeeName: '',
+        isMerchantEnabled: true,
+        isActive: false,
+        accounts
+      });
+      return;
+    }
+    res.status(200).json({
+      id: account.id,
+      upiId: account.upiId,
+      payeeName: account.payeeName,
+      isMerchantEnabled: account.isMerchantEnabled,
+      isActive: account.isActive,
+      accounts
+    });
+  });
+
+  // GET /api/v1/admin/upi-accounts (List all merchant VPAs)
+  router.get('/api/v1/admin/upi-accounts', async (req, res) => {
+    let merchant = resolveMerchant(req);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const accounts = ctx.accountRepo.findByMerchantId(merchant.id);
+    res.status(200).json({
+      accounts: accounts.map(a => ({
+        id: a.id,
+        merchantId: a.merchantId,
+        upiId: a.upiId,
+        payeeName: a.payeeName,
+        isMerchantEnabled: a.isMerchantEnabled,
+        isActive: a.isActive,
+        isSlotBusy: a.isSlotBusy,
+        createdAt: a.createdAt,
+        updatedAt: a.updatedAt
+      }))
+    });
+  });
+
+  // POST /api/v1/admin/upi-accounts (Add a new VPA)
+  router.post('/api/v1/admin/upi-accounts', async (req, res) => {
+    const body = req.body || {};
+    const { upiId, payeeName, isActive } = body;
+    let merchant = resolveMerchant(req, body.merchantId);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    if (!upiId || !upiId.trim()) {
+      res.status(400).json({ error: 'UPI ID (VPA) is required.' });
+      return;
+    }
+
+    if (!isValidVpa(upiId.trim())) {
+      res.status(400).json({ error: `Invalid UPI VPA format: "${upiId}". Expected: username@bank` });
+      return;
+    }
+
+    const existingAccounts = ctx.accountRepo.findByMerchantId(merchant.id);
+    const shouldActivate = isActive !== undefined ? Boolean(isActive) : (existingAccounts.length === 0);
+
+    const account = ctx.accountRepo.create({
+      merchantId: merchant.id,
+      upiId: upiId.trim(),
+      payeeName: payeeName?.trim() || merchant.businessName,
+      isMerchantEnabled: true,
+      isActive: shouldActivate
+    });
+
+    ctx.auditRepo.log({
+      merchantId: merchant.id,
+      entityType: 'PAYMENT_RECEIVING_ACCOUNT',
+      entityId: account.id,
+      action: 'RECEIVING_UPI_ADDED',
+      actorType: AuditActorType.ADMIN,
+      details: {
+        upiId: account.upiId,
+        payeeName: account.payeeName,
+        isActive: account.isActive
+      }
+    });
+
+    res.status(201).json({
+      success: true,
+      account
+    });
+  });
+
+  // POST /api/v1/admin/upi-accounts/:id/activate (Atomically activate VPA, deactivating all others)
+  router.post('/api/v1/admin/upi-accounts/:id/activate', async (req, res) => {
+    const account = ctx.accountRepo.findById(req.params.id);
+    if (!account) {
+      res.status(404).json({ error: `UPI Account not found: ${req.params.id}` });
+      return;
+    }
+
+    const updated = ctx.accountRepo.activateAccount(account.merchantId, account.id);
+
+    ctx.auditRepo.log({
+      merchantId: account.merchantId,
+      entityType: 'PAYMENT_RECEIVING_ACCOUNT',
+      entityId: updated.id,
+      action: 'RECEIVING_UPI_ACTIVATED',
+      actorType: AuditActorType.ADMIN,
+      details: {
+        upiId: updated.upiId,
+        payeeName: updated.payeeName,
+        isMerchantEnabled: updated.isMerchantEnabled
+      }
+    });
+
+    res.status(200).json({
+      success: true,
+      activeAccount: updated
+    });
+  });
+
+  // POST /api/v1/admin/upi-accounts/:id/toggle (Toggle VPA active state)
+  router.post('/api/v1/admin/upi-accounts/:id/toggle', async (req, res) => {
+    const account = ctx.accountRepo.findById(req.params.id);
+    if (!account) {
+      res.status(404).json({ error: `UPI Account not found: ${req.params.id}` });
+      return;
+    }
+
+    let updated;
+    if (account.isActive) {
+      updated = ctx.accountRepo.deactivateAccount(account.merchantId, account.id);
+    } else {
+      updated = ctx.accountRepo.activateAccount(account.merchantId, account.id);
+    }
+
+    ctx.auditRepo.log({
+      merchantId: account.merchantId,
+      entityType: 'PAYMENT_RECEIVING_ACCOUNT',
+      entityId: updated.id,
+      action: updated.isActive ? 'RECEIVING_UPI_ACTIVATED' : 'RECEIVING_UPI_DEACTIVATED',
+      actorType: AuditActorType.ADMIN,
+      details: { upiId: updated.upiId, isActive: updated.isActive }
+    });
+
+    res.status(200).json({
+      success: true,
+      account: updated
+    });
+  });
+
+  // DELETE /api/v1/admin/upi-accounts/:id (Delete VPA)
+  router.delete('/api/v1/admin/upi-accounts/:id', async (req, res) => {
+    const account = ctx.accountRepo.findById(req.params.id);
+    if (!account) {
+      res.status(404).json({ error: `UPI Account not found: ${req.params.id}` });
+      return;
+    }
+
+    try {
+      ctx.accountRepo.deleteAccount(account.merchantId, account.id);
+      ctx.auditRepo.log({
+        merchantId: account.merchantId,
+        entityType: 'PAYMENT_RECEIVING_ACCOUNT',
+        entityId: account.id,
+        action: 'RECEIVING_UPI_DELETED',
+        actorType: AuditActorType.ADMIN,
+        details: { upiId: account.upiId }
+      });
+      res.status(200).json({ success: true, deletedId: account.id });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/upi-settings (Custom UPI ID addition & persistence)
+  router.post('/api/v1/admin/upi-settings', async (req, res) => {
+    const body = req.body || {};
+    const { upiId, payeeName, isMerchantEnabled } = body;
+    let merchant = resolveMerchant(req, body.merchantId);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    if (!upiId || !upiId.trim()) {
+      res.status(400).json({ error: 'UPI ID (VPA) is required.' });
+      return;
+    }
+
+    if (!isValidVpa(upiId.trim())) {
+      res.status(400).json({ error: `Invalid UPI VPA format: "${upiId}". Expected format: username@bank` });
+      return;
+    }
+
+    const isEnabled = isMerchantEnabled !== undefined ? Boolean(isMerchantEnabled) : true;
+    const updatedAccount = ctx.accountRepo.upsertActiveForMerchant(
+      merchant.id,
+      upiId.trim(),
+      payeeName?.trim() || merchant.businessName,
+      isEnabled
+    );
+
+    ctx.auditRepo.log({
+      merchantId: merchant.id,
+      entityType: 'PAYMENT_RECEIVING_ACCOUNT',
+      entityId: updatedAccount.id,
+      action: 'RECEIVING_UPI_UPDATED',
+      actorType: AuditActorType.ADMIN,
+      details: {
+        upiId: updatedAccount.upiId,
+        payeeName: updatedAccount.payeeName,
+        isMerchantEnabled: updatedAccount.isMerchantEnabled
+      }
+    });
+
+    res.status(200).json({
+      success: true,
+      receivingAccount: {
+        id: updatedAccount.id,
+        upiId: updatedAccount.upiId,
+        payeeName: updatedAccount.payeeName,
+        isMerchantEnabled: updatedAccount.isMerchantEnabled,
+        isActive: updatedAccount.isActive
+      }
+    });
+  });
+
+  // GET /api/v1/admin/all-settings (Unified Settings Read)
+  router.get('/api/v1/admin/all-settings', async (req, res) => {
+    let merchant = resolveMerchant(req);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const account = ctx.accountRepo.findActiveForMerchant(merchant.id);
+    const branding = merchant.branding || {};
+    const modeResult = resolveSellingModeAndMethods({}, branding);
+    const sellingMode = modeResult.sellingMode;
+    const enabledPaymentMethods = modeResult.enabledPaymentMethods;
+    const supportEmails = branding.supportEmails || (merchant.contactEmail ? [merchant.contactEmail] : []);
+    const supportMobiles = branding.supportMobiles || (merchant.contactPhone ? [merchant.contactPhone] : []);
+    const privacyPolicyUrl = branding.privacyPolicyUrl || '';
+
+    res.status(200).json({
+      merchantId: merchant.id,
+      businessName: merchant.businessName,
+      upiId: account ? account.upiId : '',
+      payeeName: account ? account.payeeName : merchant.businessName,
+      webhookUrl: merchant.webhookUrl || '',
+      webhookSecret: merchant.webhookSecret || '',
+      supportEmails,
+      supportMobiles,
+      privacyPolicyUrl,
+      sellingMode,
+      branding: {
+        appName: branding.appName || 'ELPAY PG',
+        primaryColor: branding.primaryColor || '#2563eb',
+        headerTheme: branding.headerTheme || 'gradient',
+        logoUrl: branding.logoUrl || null,
+        sidebarNotice: branding.sidebarNotice || 'Fast & Secure 256-Bit Encrypted Payments',
+        subbannerText: branding.subbannerText || null,
+        trustBadgeText: branding.trustBadgeText || null,
+        hideTrustBadge: Boolean(branding.hideTrustBadge),
+        hideSubbanner: Boolean(branding.hideSubbanner),
+        hidePoweredBy: Boolean(branding.hidePoweredBy),
+        hideTimeSavingBanner: Boolean(branding.hideTimeSavingBanner),
+        footerGuarantee: branding.footerGuarantee || 'Secured by ELPAY PG 256-Bit Encryption',
+        counterInstructions: branding.counterInstructions || 'Please visit the store billing counter and present this screen to the cashier.',
+        cardCounterInstructions: branding.cardCounterInstructions || 'Please swipe, insert, or tap your credit or debit card on the store POS terminal at the billing desk.',
+        termsUrl: branding.termsUrl || null,
+        sellingMode,
+        enabledPaymentMethods,
+        supportEmails,
+        supportMobiles,
+        privacyPolicyUrl
+      }
+    });
+  });
+
+  // POST /api/v1/admin/all-settings (Atomic Unified Settings Write)
+  router.post('/api/v1/admin/all-settings', async (req, res) => {
+    const body = req.body || {};
+    let merchant = resolveMerchant(req, body.merchantId);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    // 1. Update UPI VPA if provided
+    let account = ctx.accountRepo.findActiveForMerchant(merchant.id);
+    if (body.upiId && body.upiId.trim()) {
+      if (!isValidVpa(body.upiId.trim())) {
+        res.status(400).json({ error: `Invalid UPI VPA format: "${body.upiId}". Expected: username@bank` });
+        return;
+      }
+      account = ctx.accountRepo.upsertActiveForMerchant(merchant.id, body.upiId.trim(), body.payeeName?.trim() || body.businessName?.trim() || merchant.businessName);
+    }
+
+    // 2. Non-Destructive Deep Merge for Branding & Merchant Properties
+    const updates = {};
+    if (body.businessName && body.businessName.trim()) {
+      updates.businessName = body.businessName.trim();
+    }
+    if (body.webhookUrl !== undefined) {
+      const check = validateOutboundWebhookUrl(body.webhookUrl);
+      if (!check.valid && String(body.webhookUrl || '').trim()) {
+        res.status(400).json({ error: check.error });
+        return;
+      }
+      updates.webhookUrl = body.webhookUrl?.trim() || null;
+    }
+    if (body.webhookSecret !== undefined && body.webhookSecret.trim()) {
+      updates.webhookSecret = body.webhookSecret.trim();
+    }
+
+    const currentBranding = merchant.branding || {};
+    const inputBranding = body.branding || {};
+    const mergedBranding = { ...currentBranding };
+
+    if (inputBranding.appName !== undefined) mergedBranding.appName = inputBranding.appName.trim() || currentBranding.appName || 'ELPAY PG';
+    if (inputBranding.logoUrl !== undefined) mergedBranding.logoUrl = inputBranding.logoUrl ? inputBranding.logoUrl.trim() : null;
+    if (inputBranding.primaryColor !== undefined) mergedBranding.primaryColor = inputBranding.primaryColor.trim() || currentBranding.primaryColor || '#2563eb';
+    if (inputBranding.sidebarNotice !== undefined) mergedBranding.sidebarNotice = inputBranding.sidebarNotice ? inputBranding.sidebarNotice.trim() : null;
+    if (inputBranding.headerTheme !== undefined) mergedBranding.headerTheme = inputBranding.headerTheme || 'gradient';
+    if (inputBranding.subbannerText !== undefined) mergedBranding.subbannerText = inputBranding.subbannerText ? inputBranding.subbannerText.trim() : null;
+    if (inputBranding.trustBadgeText !== undefined) mergedBranding.trustBadgeText = inputBranding.trustBadgeText ? inputBranding.trustBadgeText.trim() : null;
+    if (inputBranding.hideTrustBadge !== undefined) mergedBranding.hideTrustBadge = Boolean(inputBranding.hideTrustBadge);
+    if (inputBranding.hideSubbanner !== undefined) mergedBranding.hideSubbanner = Boolean(inputBranding.hideSubbanner);
+    if (inputBranding.hidePoweredBy !== undefined) mergedBranding.hidePoweredBy = Boolean(inputBranding.hidePoweredBy);
+    if (inputBranding.hideTimeSavingBanner !== undefined) mergedBranding.hideTimeSavingBanner = Boolean(inputBranding.hideTimeSavingBanner);
+    if (inputBranding.checkoutNotice !== undefined) mergedBranding.checkoutNotice = inputBranding.checkoutNotice ? inputBranding.checkoutNotice.trim() : null;
+    if (inputBranding.footerGuarantee !== undefined) mergedBranding.footerGuarantee = inputBranding.footerGuarantee ? inputBranding.footerGuarantee.trim() : null;
+    if (inputBranding.counterInstructions !== undefined) mergedBranding.counterInstructions = inputBranding.counterInstructions ? inputBranding.counterInstructions.trim() : null;
+    if (inputBranding.cardCounterInstructions !== undefined) mergedBranding.cardCounterInstructions = inputBranding.cardCounterInstructions ? inputBranding.cardCounterInstructions.trim() : null;
+    if (inputBranding.termsUrl !== undefined) mergedBranding.termsUrl = inputBranding.termsUrl ? inputBranding.termsUrl.trim() : null;
+
+    if (body.enabledPaymentMethods || inputBranding.enabledPaymentMethods || body.sellingMode || inputBranding.sellingMode || body.codEnabled !== undefined || body.cashEnabled !== undefined || body.cardEnabled !== undefined) {
+      const modeResult = resolveSellingModeAndMethods(body, currentBranding);
+      mergedBranding.sellingMode = modeResult.sellingMode;
+      mergedBranding.enabledPaymentMethods = modeResult.enabledPaymentMethods;
+    }
+
+    if (body.supportEmails !== undefined || inputBranding.supportEmails !== undefined) {
+      const raw = body.supportEmails !== undefined ? body.supportEmails : inputBranding.supportEmails;
+      mergedBranding.supportEmails = Array.isArray(raw)
+        ? raw.map(s => String(s).trim()).filter(Boolean)
+        : (typeof raw === 'string' ? raw.split(/[,\n]+/).map(s => s.trim()).filter(Boolean) : []);
+    }
+    if (body.supportMobiles !== undefined || inputBranding.supportMobiles !== undefined) {
+      const raw = body.supportMobiles !== undefined ? body.supportMobiles : inputBranding.supportMobiles;
+      mergedBranding.supportMobiles = Array.isArray(raw)
+        ? raw.map(s => String(s).trim()).filter(Boolean)
+        : (typeof raw === 'string' ? raw.split(/[,\n]+/).map(s => s.trim()).filter(Boolean) : []);
+    }
+    if (body.privacyPolicyUrl !== undefined || inputBranding.privacyPolicyUrl !== undefined) {
+      const raw = body.privacyPolicyUrl !== undefined ? body.privacyPolicyUrl : inputBranding.privacyPolicyUrl;
+      mergedBranding.privacyPolicyUrl = raw ? String(raw).trim() : null;
+    }
+
+    if (body.envMode !== undefined || inputBranding.envMode !== undefined) {
+      mergedBranding.envMode = (body.envMode || inputBranding.envMode || 'localhost').toLowerCase();
+    }
+    if (body.domainPrefix !== undefined || inputBranding.domainPrefix !== undefined) {
+      mergedBranding.domainPrefix = (body.domainPrefix || inputBranding.domainPrefix || 'pay').trim().toLowerCase();
+    }
+    if (body.domainTld !== undefined || inputBranding.domainTld !== undefined) {
+      mergedBranding.domainTld = (body.domainTld || inputBranding.domainTld || '').trim().toLowerCase();
+    }
+    if (body.customDomain !== undefined || inputBranding.customDomain !== undefined) {
+      mergedBranding.customDomain = (body.customDomain || inputBranding.customDomain || '').trim();
+    }
+
+    updates.branding = mergedBranding;
+
+    const updated = ctx.merchantRepo.update(merchant.id, updates);
+
+    ctx.auditRepo.log({
+      merchantId: merchant.id,
+      entityType: 'MERCHANT',
+      entityId: merchant.id,
+      action: 'ALL_SETTINGS_UPDATED_ATOMIC',
+      actorType: AuditActorType.ADMIN,
+      details: { businessName: updated.businessName, upiId: account?.upiId, branding: updated.branding }
+    });
+
+    res.status(200).json({
+      success: true,
+      merchantId: updated.id,
+      businessName: updated.businessName,
+      upiId: account ? account.upiId : '',
+      payeeName: account ? account.payeeName : updated.businessName,
+      webhookUrl: updated.webhookUrl || '',
+      webhookSecret: updated.webhookSecret || '',
+      supportEmails: updated.branding?.supportEmails || [],
+      supportMobiles: updated.branding?.supportMobiles || [],
+      privacyPolicyUrl: updated.branding?.privacyPolicyUrl || '',
+      sellingMode: updated.branding?.sellingMode || 'ONLINE',
+      enabledPaymentMethods: updated.branding?.enabledPaymentMethods || ['UPI'],
+      codEnabled: (updated.branding?.enabledPaymentMethods || []).includes('COD'),
+      cashEnabled: (updated.branding?.enabledPaymentMethods || []).includes('CASH_COUNTER'),
+      cardEnabled: (updated.branding?.enabledPaymentMethods || []).includes('CARD_COUNTER'),
+      branding: updated.branding
+    });
+  });
+
+  // GET /api/v1/admin/merchant-settings
+  router.get('/api/v1/admin/merchant-settings', async (req, res) => {
+    let merchant = req.query.merchantId ? ctx.merchantRepo.findById(req.query.merchantId) : (req.headers['x-merchant-id'] ? ctx.merchantRepo.findById(req.headers['x-merchant-id']) : null);
+    if (!merchant) merchant = ctx.merchantRepo.getDefault ? ctx.merchantRepo.getDefault() : (ctx.merchantRepo.findById('00000000-0000-0000-0000-000000000001') || ctx.merchantRepo.findAll()[0]);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const branding = merchant.branding || {};
+    const modeResult = resolveSellingModeAndMethods({}, branding);
+    const sellingMode = modeResult.sellingMode;
+    const enabledPaymentMethods = modeResult.enabledPaymentMethods;
+    const supportEmails = branding.supportEmails || (merchant.contactEmail ? [merchant.contactEmail] : []);
+    const supportMobiles = branding.supportMobiles || (merchant.contactPhone ? [merchant.contactPhone] : []);
+    const privacyPolicyUrl = branding.privacyPolicyUrl || '';
+
+    const envMode = branding.envMode || 'localhost';
+    const domainPrefix = (branding.deploymentPrefix || branding.domainPrefix || 'pay').trim().toLowerCase();
+    const domainTld = (branding.cloudflareDomain || branding.domainTld || '').trim().toLowerCase();
+    const cloudflareDomain = domainTld;
+    const deploymentPrefix = domainPrefix;
+    const customDomain = branding.customDomain || (cloudflareDomain ? `https://${deploymentPrefix}.${cloudflareDomain}` : '');
+    const cloudflareTunnelCommand = branding.cloudflareTunnelCommand || '';
+    const tunnelStatus = globalTunnelManager.getStatus();
+
+    const routes = deriveCloudflareRoutes({ domain: cloudflareDomain, prefix: deploymentPrefix });
+    let runtimeUrls = {};
+    try {
+      runtimeUrls = resolveRuntimeUrls({ envMode, domain: cloudflareDomain, prefix: deploymentPrefix });
+    } catch {
+      runtimeUrls = resolveRuntimeUrls({ envMode: 'localhost', domain: cloudflareDomain, prefix: deploymentPrefix });
+    }
+
+    const codEnabled = branding.codEnabled !== undefined ? Boolean(branding.codEnabled) : enabledPaymentMethods.includes('COD');
+    const cashEnabled = branding.cashEnabled !== undefined ? Boolean(branding.cashEnabled) : enabledPaymentMethods.includes('CASH_COUNTER');
+    const cardEnabled = branding.cardEnabled !== undefined ? Boolean(branding.cardEnabled) : enabledPaymentMethods.includes('CARD_COUNTER');
+
+    res.status(200).json({
+      merchantId: merchant.id,
+      businessName: merchant.businessName,
+      contactEmail: merchant.contactEmail,
+      contactPhone: merchant.contactPhone,
+      webhookUrl: merchant.webhookUrl,
+      webhookSecret: merchant.webhookSecret,
+      supportEmails,
+      supportMobiles,
+      privacyPolicyUrl,
+      sellingMode,
+      enabledPaymentMethods,
+      codEnabled,
+      cashEnabled,
+      cardEnabled,
+      envMode,
+      domainPrefix,
+      domainTld,
+      cloudflareDomain,
+      deploymentPrefix,
+      customDomain,
+      routes,
+      runtimeUrls,
+      cloudflareTunnelCommand,
+      tunnelStatus,
+      branding: {
+        ...branding,
+        sellingMode,
+        enabledPaymentMethods,
+        codEnabled,
+        cashEnabled,
+        cardEnabled,
+        supportEmails,
+        supportMobiles,
+        privacyPolicyUrl,
+        envMode,
+        domainPrefix,
+        domainTld,
+        cloudflareDomain,
+        deploymentPrefix,
+        customDomain,
+        routes,
+        runtimeUrls,
+        cloudflareTunnelCommand
+      }
+    });
+  });
+
+  // POST /api/v1/admin/merchant-settings
+  router.post('/api/v1/admin/merchant-settings', async (req, res) => {
+    const body = req.body || {};
+    let merchant = body.merchantId ? ctx.merchantRepo.findById(body.merchantId) : (req.headers['x-merchant-id'] ? ctx.merchantRepo.findById(req.headers['x-merchant-id']) : null);
+    if (!merchant) merchant = ctx.merchantRepo.getDefault ? ctx.merchantRepo.getDefault() : (ctx.merchantRepo.findById('00000000-0000-0000-0000-000000000001') || ctx.merchantRepo.findAll()[0]);
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const inputBranding = body.branding || {};
+    const updates = {};
+    if (body.businessName && body.businessName.trim()) updates.businessName = body.businessName.trim();
+    else if (inputBranding.businessName && inputBranding.businessName.trim()) updates.businessName = inputBranding.businessName.trim();
+    if (body.webhookUrl !== undefined) {
+      const check = validateOutboundWebhookUrl(body.webhookUrl);
+      if (!check.valid && String(body.webhookUrl || '').trim()) {
+        res.status(400).json({ error: check.error });
+        return;
+      }
+      updates.webhookUrl = body.webhookUrl?.trim() || null;
+    } else if (inputBranding.webhookUrl !== undefined) updates.webhookUrl = inputBranding.webhookUrl?.trim() || null;
+    if (body.webhookSecret !== undefined && body.webhookSecret.trim()) updates.webhookSecret = body.webhookSecret.trim();
+
+    if (
+      body.branding ||
+      body.enabledPaymentMethods ||
+      body.sellingMode ||
+      body.codEnabled !== undefined ||
+      body.cashEnabled !== undefined ||
+      body.cardEnabled !== undefined ||
+      body.supportEmails !== undefined ||
+      body.supportMobiles !== undefined ||
+      body.privacyPolicyUrl !== undefined ||
+      body.envMode !== undefined ||
+      body.domainPrefix !== undefined ||
+      body.domainTld !== undefined ||
+      body.customDomain !== undefined ||
+      body.cloudflareTunnelCommand !== undefined
+    ) {
+      const currentBranding = merchant.branding || {};
+      const mergedBranding = { ...currentBranding };
+
+      if (inputBranding.appName !== undefined) mergedBranding.appName = inputBranding.appName.trim() || currentBranding.appName || 'ELPAY PG';
+      if (inputBranding.logoUrl !== undefined) mergedBranding.logoUrl = inputBranding.logoUrl ? inputBranding.logoUrl.trim() : null;
+      if (inputBranding.primaryColor !== undefined) mergedBranding.primaryColor = inputBranding.primaryColor.trim() || currentBranding.primaryColor || '#2563eb';
+      if (inputBranding.headerTheme !== undefined) mergedBranding.headerTheme = inputBranding.headerTheme || 'gradient';
+      if (inputBranding.sidebarNotice !== undefined) mergedBranding.sidebarNotice = inputBranding.sidebarNotice ? inputBranding.sidebarNotice.trim() : null;
+      if (inputBranding.subbannerText !== undefined) mergedBranding.subbannerText = inputBranding.subbannerText ? inputBranding.subbannerText.trim() : null;
+      if (inputBranding.trustBadgeText !== undefined) mergedBranding.trustBadgeText = inputBranding.trustBadgeText ? inputBranding.trustBadgeText.trim() : null;
+      if (inputBranding.hideTrustBadge !== undefined) mergedBranding.hideTrustBadge = Boolean(inputBranding.hideTrustBadge);
+      if (inputBranding.hideSubbanner !== undefined) mergedBranding.hideSubbanner = Boolean(inputBranding.hideSubbanner);
+      if (inputBranding.hidePoweredBy !== undefined) mergedBranding.hidePoweredBy = Boolean(inputBranding.hidePoweredBy);
+      if (inputBranding.hideTimeSavingBanner !== undefined) mergedBranding.hideTimeSavingBanner = Boolean(inputBranding.hideTimeSavingBanner);
+      if (inputBranding.checkoutNotice !== undefined) mergedBranding.checkoutNotice = inputBranding.checkoutNotice ? inputBranding.checkoutNotice.trim() : null;
+      if (inputBranding.footerGuarantee !== undefined) mergedBranding.footerGuarantee = inputBranding.footerGuarantee ? inputBranding.footerGuarantee.trim() : null;
+      if (inputBranding.counterInstructions !== undefined) mergedBranding.counterInstructions = inputBranding.counterInstructions ? inputBranding.counterInstructions.trim() : null;
+      if (inputBranding.cardCounterInstructions !== undefined) mergedBranding.cardCounterInstructions = inputBranding.cardCounterInstructions ? inputBranding.cardCounterInstructions.trim() : null;
+      if (inputBranding.termsUrl !== undefined) mergedBranding.termsUrl = inputBranding.termsUrl ? inputBranding.termsUrl.trim() : null;
+
+      if (
+        body.sellingMode !== undefined ||
+        body.enabledPaymentMethods !== undefined ||
+        body.codEnabled !== undefined ||
+        body.cashEnabled !== undefined ||
+        body.cardEnabled !== undefined ||
+        inputBranding.sellingMode !== undefined ||
+        inputBranding.enabledPaymentMethods !== undefined ||
+        inputBranding.codEnabled !== undefined ||
+        inputBranding.cashEnabled !== undefined ||
+        inputBranding.cardEnabled !== undefined
+      ) {
+        const modeResult = resolveSellingModeAndMethods(body, currentBranding);
+        mergedBranding.sellingMode = modeResult.sellingMode;
+        mergedBranding.enabledPaymentMethods = modeResult.enabledPaymentMethods;
+        mergedBranding.codEnabled = modeResult.codEnabled;
+        mergedBranding.cashEnabled = modeResult.cashEnabled;
+        mergedBranding.cardEnabled = modeResult.cardEnabled;
+      }
+
+      if (body.supportEmails !== undefined || inputBranding.supportEmails !== undefined) {
+        const raw = body.supportEmails !== undefined ? body.supportEmails : inputBranding.supportEmails;
+        mergedBranding.supportEmails = Array.isArray(raw)
+          ? raw.map(s => String(s).trim()).filter(Boolean)
+          : (typeof raw === 'string' ? raw.split(/[,\n]+/).map(s => s.trim()).filter(Boolean) : []);
+      }
+      if (body.supportMobiles !== undefined || inputBranding.supportMobiles !== undefined) {
+        const raw = body.supportMobiles !== undefined ? body.supportMobiles : inputBranding.supportMobiles;
+        mergedBranding.supportMobiles = Array.isArray(raw)
+          ? raw.map(s => String(s).trim()).filter(Boolean)
+          : (typeof raw === 'string' ? raw.split(/[,\n]+/).map(s => s.trim()).filter(Boolean) : []);
+      }
+      if (body.privacyPolicyUrl !== undefined || inputBranding.privacyPolicyUrl !== undefined) {
+        const raw = body.privacyPolicyUrl !== undefined ? body.privacyPolicyUrl : inputBranding.privacyPolicyUrl;
+        mergedBranding.privacyPolicyUrl = raw ? String(raw).trim() : null;
+      }
+
+      if (body.envMode !== undefined || inputBranding.envMode !== undefined) {
+        mergedBranding.envMode = (body.envMode || inputBranding.envMode || 'localhost').toLowerCase();
+      }
+      const rawDomain = (body.cloudflareDomain !== undefined ? body.cloudflareDomain : (body.domainTld !== undefined ? body.domainTld : (inputBranding.cloudflareDomain !== undefined ? inputBranding.cloudflareDomain : inputBranding.domainTld)));
+      if (rawDomain !== undefined) {
+        const cleanDomain = String(rawDomain || '').trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+        mergedBranding.cloudflareDomain = cleanDomain;
+        mergedBranding.domainTld = cleanDomain;
+      }
+      const rawPrefix = (body.deploymentPrefix !== undefined ? body.deploymentPrefix : (body.domainPrefix !== undefined ? body.domainPrefix : (inputBranding.deploymentPrefix !== undefined ? inputBranding.deploymentPrefix : inputBranding.domainPrefix)));
+      if (rawPrefix !== undefined) {
+        const cleanPrefix = String(rawPrefix || 'pay').trim().toLowerCase().replace(/[^a-z0-9-_]/g, '') || 'pay';
+        mergedBranding.deploymentPrefix = cleanPrefix;
+        mergedBranding.domainPrefix = cleanPrefix;
+      }
+      const activeDomain = mergedBranding.cloudflareDomain || mergedBranding.domainTld || '';
+      const activePrefix = mergedBranding.deploymentPrefix || mergedBranding.domainPrefix || 'pay';
+      if (activeDomain) {
+        mergedBranding.customDomain = `https://${activePrefix}.${activeDomain}`;
+      } else if (body.customDomain !== undefined || inputBranding.customDomain !== undefined) {
+        mergedBranding.customDomain = (body.customDomain || inputBranding.customDomain || '').trim();
+      }
+      if (body.cloudflareTunnelCommand !== undefined || inputBranding.cloudflareTunnelCommand !== undefined) {
+        mergedBranding.cloudflareTunnelCommand = (body.cloudflareTunnelCommand !== undefined ? body.cloudflareTunnelCommand : inputBranding.cloudflareTunnelCommand)?.trim() || '';
+      }
+
+      updates.branding = mergedBranding;
+    }
+
+    const updated = ctx.merchantRepo.update(merchant.id, updates);
+
+    ctx.auditRepo.log({
+      merchantId: merchant.id,
+      entityType: 'MERCHANT',
+      entityId: merchant.id,
+      action: 'MERCHANT_SETTINGS_UPDATED',
+      actorType: AuditActorType.ADMIN,
+      details: updates
+    });
+
+    res.status(200).json({
+      success: true,
+      merchantId: updated.id,
+      businessName: updated.businessName,
+      webhookUrl: updated.webhookUrl || '',
+      webhookSecret: updated.webhookSecret || '',
+      supportEmails: updated.branding?.supportEmails || [],
+      supportMobiles: updated.branding?.supportMobiles || [],
+      privacyPolicyUrl: updated.branding?.privacyPolicyUrl || '',
+      sellingMode: updated.branding?.sellingMode || 'ONLINE',
+      enabledPaymentMethods: updated.branding?.enabledPaymentMethods || ['UPI'],
+      codEnabled: (updated.branding?.enabledPaymentMethods || []).includes('COD'),
+      cashEnabled: (updated.branding?.enabledPaymentMethods || []).includes('CASH_COUNTER'),
+      cardEnabled: (updated.branding?.enabledPaymentMethods || []).includes('CARD_COUNTER'),
+      envMode: updated.branding?.envMode || 'localhost',
+      domainPrefix: updated.branding?.domainPrefix || 'pay',
+      domainTld: updated.branding?.domainTld || '',
+      customDomain: updated.branding?.customDomain || '',
+      cloudflareTunnelCommand: updated.branding?.cloudflareTunnelCommand || '',
+      tunnelStatus: globalTunnelManager.getStatus(),
+      branding: updated.branding
+    });
+  });
+
+  // GET /api/v1/admin/cod-orders (List Cash on Delivery orders)
+  router.get('/api/v1/admin/cod-orders', async (req, res) => {
+    let merchant = req.query.merchantId ? ctx.merchantRepo.findById(req.query.merchantId) : null;
+    if (!merchant) merchant = ctx.merchantRepo.findAll()[0];
+
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const codSessions = ctx.sessionRepo.db.query(
+      `SELECT ps.*, c.name as customer_name, c.mobile_number as customer_mobile, c.email as customer_email
+       FROM payment_sessions ps
+       LEFT JOIN customers c ON ps.customer_id = c.id
+       WHERE ps.merchant_id = ? AND ps.method = 'COD'
+       ORDER BY ps.created_at DESC LIMIT 50`,
+      [merchant.id]
+    );
+
+    const formatted = codSessions.map(r => ({
+      paymentId: r.id,
+      id: r.id,
+      orderId: r.order_id,
+      amount: toRupeesString(r.amount_paise),
+      amountPaise: r.amount_paise.toString(),
+      currency: r.currency,
+      status: r.status,
+      method: r.method,
+      verificationTag: r.verification_tag,
+      customerName: r.customer_name || 'Customer',
+      customerPhone: r.customer_mobile || '',
+      customerEmail: r.customer_email || '',
+      createdAt: r.created_at,
+      customer: r.customer_id ? {
+        id: r.customer_id,
+        name: r.customer_name,
+        mobileNumber: r.customer_mobile,
+        email: r.customer_email
+      } : null
+    }));
+
+    res.status(200).json({
+      total: formatted.length,
+      codOrders: formatted,
+      orders: formatted
+    });
+  });
+
+  // GET /api/v1/admin/stream (SSE for Live Admin Counter & Queue Events)
+  router.get('/api/v1/admin/stream', async (req, res) => {
+    server.initSse('admin_counter_events', res);
+  });
+
+  // --- WHATSAPP BERRY PROTOCOL MERCHANT SESSION CONFIGURATION ---
+
+  // GET /api/v1/admin/whatsapp/status
+  router.get('/api/v1/admin/whatsapp/status', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(200).json({
+        success: true,
+        status: 'DISCONNECTED',
+        phoneNumber: null,
+        platform: 'BerryProtocol v0.1.10',
+        qrCode: null
+      });
+      return;
+    }
+
+    const info = berry.getClientInfo();
+    let qr = berry.getQrCode();
+    if (!qr && berry.client?.lastQr) {
+      const rawText = berry.client.lastQr;
+      const dataUrl = await formatQrDataUrl(rawText);
+      qr = { raw: rawText, dataUrl };
+    }
+
+    let qrPayload = qr?.dataUrl || (typeof qr === 'string' && qr.startsWith('data:image/') ? qr : null);
+    if (!qrPayload && (qr?.raw || typeof qr === 'string')) {
+      const rawText = qr?.raw || (typeof qr === 'string' ? qr : null);
+      if (rawText) {
+        qrPayload = await formatQrDataUrl(rawText);
+      }
+    }
+
+    res.status(200).json({
+      success: true,
+      status: info.status,
+      phoneNumber: info.phoneNumber,
+      platform: info.platform,
+      sessionId: info.sessionId,
+      isConnected: info.isConnected,
+      qrCode: qrPayload || qr?.dataUrl || qr?.raw || (typeof qr === 'string' ? qr : null),
+      pairingCode: info.pairingCode || null,
+      pairingPhone: info.pairingPhone || null
+    });
+  });
+
+  // GET /api/v1/admin/whatsapp/qr
+  router.get('/api/v1/admin/whatsapp/qr', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(200).json({ success: false, error: 'Service unavailable' });
+      return;
+    }
+
+    let qr = berry.getQrCode();
+    if (!qr && berry.client?.lastQr) {
+      const rawText = berry.client.lastQr;
+      const dataUrl = await formatQrDataUrl(rawText);
+      qr = { raw: rawText, dataUrl };
+    }
+
+    let qrPayload = qr?.dataUrl || (typeof qr === 'string' && qr.startsWith('data:image/') ? qr : null);
+    if (!qrPayload && (qr?.raw || typeof qr === 'string')) {
+      const rawText = qr?.raw || (typeof qr === 'string' ? qr : null);
+      if (rawText) {
+        qrPayload = await formatQrDataUrl(rawText);
+      }
+    }
+
+    res.status(200).json({
+      success: true,
+      status: berry.getStatus(),
+      qrCode: qrPayload || qr?.dataUrl || qr?.raw || (typeof qr === 'string' ? qr : null),
+      available: Boolean(qr)
+    });
+  });
+
+  // POST /api/v1/admin/whatsapp/reconnect - Refresh Pairing QR or Reset Session
+  router.post('/api/v1/admin/whatsapp/reconnect', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(500).json({ error: 'WhatsApp service not initialized' });
+      return;
+    }
+
+    try {
+      if (berry.getStatus() === 'DISCONNECTED') {
+        await berry.initialize();
+      } else {
+        await berry.reconnect();
+      }
+
+      let qr = null;
+      if (typeof berry.waitForQrCode === 'function') {
+        qr = await berry.waitForQrCode(8000);
+      } else {
+        qr = berry.getQrCode();
+      }
+
+      if (!qr && berry.client?.lastQr) {
+        const rawText = berry.client.lastQr;
+        const dataUrl = await formatQrDataUrl(rawText);
+        qr = { raw: rawText, dataUrl };
+      }
+
+      let qrPayload = qr?.dataUrl || (typeof qr === 'string' && qr.startsWith('data:image/') ? qr : null);
+      if (!qrPayload && (qr?.raw || typeof qr === 'string')) {
+        const rawText = qr?.raw || (typeof qr === 'string' ? qr : null);
+        if (rawText) {
+          qrPayload = await formatQrDataUrl(rawText);
+        }
+      }
+
+      res.status(200).json({
+        success: true,
+        status: berry.getStatus(),
+        qrCode: qrPayload || qr?.dataUrl || qr?.raw || (typeof qr === 'string' ? qr : null)
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/whatsapp/pairing-code - Request 8-digit Pairing Code via Phone Number (bypasses QR rate limit)
+  router.post('/api/v1/admin/whatsapp/pairing-code', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(500).json({ success: false, error: 'WhatsApp service not initialized' });
+      return;
+    }
+
+    const body = req.body || {};
+    const phoneNumber = body.phoneNumber || body.phone || body.mobile;
+
+    if (!phoneNumber) {
+      res.status(400).json({ success: false, error: 'Phone number is required to generate pairing code.' });
+      return;
+    }
+
+    try {
+      const result = await berry.requestPairingCode(phoneNumber);
+      res.status(200).json({
+        success: true,
+        status: berry.getStatus(),
+        pairingCode: result.pairingCode,
+        phoneNumber: result.phoneNumber,
+        message: 'Enter this 8-digit pairing code on your phone in WhatsApp > Linked Devices > Link with phone number.'
+      });
+    } catch (err) {
+      res.status(500).json({ success: false, error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/whatsapp/disconnect - Disconnect Active Session and Wipe Credentials
+  router.post('/api/v1/admin/whatsapp/disconnect', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(200).json({ success: true, status: 'DISCONNECTED' });
+      return;
+    }
+
+    try {
+      await berry.disconnect({ cleanSession: true });
+      res.status(200).json({ success: true, status: 'DISCONNECTED', message: 'WhatsApp session disconnected and credentials wiped.' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/whatsapp/test-message - Send Test WhatsApp OTP / Alert
+  router.post('/api/v1/admin/whatsapp/test-message', async (req, res) => {
+    const berry = ctx.whatsappBerryService;
+    if (!berry) {
+      res.status(500).json({ error: 'WhatsApp service not initialized' });
+      return;
+    }
+
+    const body = req.body || {};
+    const { to, message } = body;
+
+    if (!to || !message) {
+      res.status(400).json({ error: 'Destination number "to" and "message" are required.' });
+      return;
+    }
+
+    try {
+      const result = await berry.sendMessage(to, message);
+      const httpCode = result.success ? 200 : 400;
+      res.status(httpCode).json(result);
+    } catch (err) {
+      res.status(500).json({ success: false, delivered: false, error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/queue/clear - Clear All Active & Waiting UPI Queue Sessions and Expire
+  router.post('/api/v1/admin/queue/clear', async (req, res) => {
+    const body = req.body || {};
+    const merchantId = body.merchantId || req.query.merchantId || '00000000-0000-0000-0000-000000000001';
+
+    try {
+      // Find all non-terminal UPI sessions (INITIATED, QUEUED, ACTIVE, PROCESSING) so they are ALL immediately expired!
+      const sessionsToExpire = ctx.db.query(`
+        SELECT id, receiving_account_id FROM payment_sessions
+        WHERE status IN ('INITIATED', 'QUEUED', 'ACTIVE', 'PROCESSING')
+          AND (merchant_id = ? OR ? = '00000000-0000-0000-0000-000000000001')
+      `, [merchantId, merchantId]);
+
+      for (const s of sessionsToExpire) {
+        ctx.sessionRepo.transitionToTerminal(s.id, PaymentStatus.EXPIRED);
+        server.broadcastSse(s.id, 'status_change', { status: PaymentStatus.EXPIRED });
+        server.broadcastSse(s.id, 'state_change', { status: PaymentStatus.EXPIRED });
+      }
+
+      // Free all receiving account slots
+      ctx.db.execute(`
+        UPDATE payment_receiving_accounts
+        SET is_slot_busy = 0, current_active_session_id = NULL
+        WHERE merchant_id = ? OR ? = '00000000-0000-0000-0000-000000000001'
+      `, [merchantId, merchantId]);
+
+      if (ctx.auditRepo) {
+        ctx.auditRepo.log({
+          merchantId,
+          entityType: 'PAYMENT_QUEUE',
+          entityId: merchantId,
+          action: 'QUEUE_CLEARED_MANUALLY',
+          actorType: 'ADMIN',
+          details: { clearedCount: sessionsToExpire.length }
+        });
+      }
+
+      res.status(200).json({
+        success: true,
+        clearedCount: sessionsToExpire.length,
+        message: `Successfully cleared and expired all ${sessionsToExpire.length} active/queued payment sessions.`
+      });
+    } catch (err) {
+      res.status(500).json({ error: `Failed to clear UPI queue: ${err.message}` });
+    }
+  });
+
+  // GET /api/v1/admin/counter-pending - 5-Second Realtime Poller for In-Store Cash/Card Counter Desk
+  router.get('/api/v1/admin/counter-pending', async (req, res) => {
+    const merchantId = req.query.merchantId;
+    const query = merchantId
+      ? `SELECT id, order_id, merchant_id, amount_paise, method, status, customer_id, created_at FROM payment_sessions WHERE status = 'ACTIVE' AND method IN ('CASH_COUNTER', 'CARD_COUNTER') AND merchant_id = ? ORDER BY created_at ASC`
+      : `SELECT id, order_id, merchant_id, amount_paise, method, status, customer_id, created_at FROM payment_sessions WHERE status = 'ACTIVE' AND method IN ('CASH_COUNTER', 'CARD_COUNTER') ORDER BY created_at ASC`;
+    const params = merchantId ? [merchantId] : [];
+    const rows = ctx.db.query(query, params);
+
+    const pending = rows.map(r => {
+      let customer = null;
+      if (r.customer_id && ctx.customerRepo) {
+        const c = ctx.customerRepo.findById(r.customer_id);
+        if (c) customer = { name: c.name, mobile: c.mobileNumber };
+      }
+      return {
+        id: r.id,
+        orderId: r.order_id,
+        amount: toRupeesString(r.amount_paise),
+        amountPaise: Number(r.amount_paise),
+        method: r.method,
+        status: r.status,
+        customer,
+        createdAt: r.created_at
+      };
+    });
+
+    res.status(200).json({
+      count: pending.length,
+      hasPending: pending.length > 0,
+      payments: pending
+    });
+  });
+
+  // GET /api/v1/admin/tunnel/status - Status & logs of Cloudflare Tunnel
+  router.get('/api/v1/admin/tunnel/status', async (req, res) => {
+    res.status(200).json(globalTunnelManager.getStatus());
+  });
+
+  // POST /api/v1/admin/tunnel/start - Start user-dropped Cloudflare Tunnel command
+  router.post('/api/v1/admin/tunnel/start', async (req, res) => {
+    const body = req.body || {};
+    let command = body.command;
+
+    if (!command || !command.trim()) {
+      // Fallback to stored tunnel command in merchant branding
+      const merchant = resolveMerchant(req);
+      command = merchant?.branding?.cloudflareTunnelCommand;
+    }
+
+    if (!command || !command.trim()) {
+      res.status(400).json({ error: 'Cloudflare Tunnel command cannot be empty. Please drop your command with token.' });
+      return;
+    }
+
+    try {
+      // Save command in merchant branding if provided
+      const merchant = resolveMerchant(req);
+      if (merchant && body.command) {
+        const currentBranding = merchant.branding || {};
+        ctx.merchantRepo.update(merchant.id, {
+          branding: { ...currentBranding, cloudflareTunnelCommand: command.trim() }
+        });
+      }
+
+      const status = globalTunnelManager.start(command);
+      res.status(200).json({ success: true, ...status });
+    } catch (err) {
+      res.status(500).json({ success: false, error: err.message });
+    }
+  });
+
+  // POST /api/v1/admin/tunnel/stop - Stop running Cloudflare Tunnel
+  router.post('/api/v1/admin/tunnel/stop', async (req, res) => {
+    const status = globalTunnelManager.stop();
+    res.status(200).json({ success: true, ...status });
+  });
+
+  // GET /api/v1/admin/gmail/credentials
+  router.get('/api/v1/admin/gmail/credentials', async (req, res) => {
+    let merchant = resolveMerchant(req, req.query?.merchantId);
+    const merchantId = merchant ? merchant.id : (req.query?.merchantId || '00000000-0000-0000-0000-000000000001');
+    const branding = merchant?.branding || {};
+    const gmailConfig = branding.gmailConfig || {};
+
+    const redirectUri = resolveGmailRedirectUri(branding);
+    const hasToken = Boolean(gmailConfig.refreshToken && gmailConfig.refreshToken.trim());
+
+    res.status(200).json({
+      gmailConfig: {
+        clientId: gmailConfig.clientId || '',
+        clientSecret: gmailConfig.clientSecret || '',
+        hasClientSecret: Boolean(gmailConfig.clientSecret),
+        refreshToken: gmailConfig.refreshToken || '',
+        apiKey: gmailConfig.apiKey || '',
+        connectedEmail: gmailConfig.connectedEmail || null,
+        lastTestedAt: gmailConfig.lastTestedAt || null
+      },
+      clientId: gmailConfig.clientId || '',
+      clientSecret: gmailConfig.clientSecret || '',
+      hasClientSecret: Boolean(gmailConfig.clientSecret),
+      refreshToken: gmailConfig.refreshToken || '',
+      apiKey: gmailConfig.apiKey || '',
+      connectedEmail: gmailConfig.connectedEmail || null,
+      redirectUri,
+      oauthStatus: hasToken ? 'CONNECTED' : 'DISCONNECTED',
+      tokenStatus: hasToken ? 'VALID REFRESH TOKEN (OFFLINE READY)' : 'MISSING',
+      lastTestedAt: gmailConfig.lastTestedAt || null,
+      lastSuccessfulFetch: gmailConfig.lastSuccessfulFetch || gmailConfig.lastTestedAt || null,
+      lastObservationSent: gmailConfig.lastObservationSent || null,
+      scopes: ['https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/userinfo.email'],
+      status: hasToken ? 'CONFIGURED' : 'UNCONFIGURED'
+    });
+  });
+
+  // GET /api/v1/admin/gmail/oauth/start (Pre-builds canonical Google OAuth Login URL)
+  router.get('/api/v1/admin/gmail/oauth/start', async (req, res) => {
+    let merchant = resolveMerchant(req, req.query?.merchantId);
+    const branding = merchant?.branding || {};
+    const gmailConfig = branding.gmailConfig || {};
+
+    const clientId = gmailConfig.clientId || process.env.GMAIL_CLIENT_ID || '';
+    if (!clientId) {
+      res.status(400).json({
+        error: 'Missing Gmail Client ID. Please configure it in the Admin Panel or set GMAIL_CLIENT_ID.'
+      });
+      return;
+    }
+    const redirectUri = resolveGmailRedirectUri(branding);
+    const scopes = encodeURIComponent('https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/userinfo.email');
+    const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code&scope=${scopes}&access_type=offline&prompt=consent&include_granted_scopes=true&state=${encodeURIComponent(createOAuthState())}`;
+
+    res.status(200).json({
+      success: true,
+      authUrl,
+      clientId,
+      redirectUri
+    });
+  });
+
+  // POST /api/v1/admin/gmail/disconnect (Cleanly unlinks Google account and clears stored tokens)
+  router.post('/api/v1/admin/gmail/disconnect', async (req, res) => {
+    const body = req.body || {};
+    let merchant = resolveMerchant(req, body.merchantId);
+    const merchantId = merchant ? merchant.id : (body.merchantId || '00000000-0000-0000-0000-000000000001');
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const currentBranding = merchant.branding || {};
+    const currentGmail = currentBranding.gmailConfig || {};
+
+    const updatedGmail = {
+      ...currentGmail,
+      refreshToken: '',
+      accessToken: '',
+      connectedEmail: null,
+      lastTestedAt: null,
+      lastSuccessfulFetch: null,
+      messagesTotal: 0,
+      updatedAt: new Date().toISOString()
+    };
+
+    const newBranding = {
+      ...currentBranding,
+      gmailConfig: updatedGmail
+    };
+
+    ctx.merchantRepo.update(merchantId, { branding: newBranding });
+
+    // Sync to all merchants for consistency
+    for (const m of ctx.merchantRepo.findAll()) {
+      if (m.id !== merchantId) {
+        ctx.merchantRepo.update(m.id, {
+          branding: { ...m.branding, gmailConfig: updatedGmail }
+        });
+      }
+    }
+
+    // Stop poller in observer service
+    try {
+      await fetch(`http://127.0.0.1:${process.env.GMAIL_OBSERVER_PORT || 6003}/stop`, { method: 'POST' }).catch(() => {});
+    } catch {}
+
+    res.status(200).json({
+      success: true,
+      message: 'Google account disconnected successfully.',
+      status: 'UNCONFIGURED'
+    });
+  });
+
+  // POST /api/v1/admin/gmail/credentials
+  router.post('/api/v1/admin/gmail/credentials', async (req, res) => {
+    const body = req.body || {};
+    let merchant = resolveMerchant(req, body.merchantId);
+    const merchantId = merchant ? merchant.id : (body.merchantId || '00000000-0000-0000-0000-000000000001');
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const currentBranding = merchant.branding || {};
+    const existingGmail = currentBranding.gmailConfig || {};
+
+    const updatedGmail = {
+      ...existingGmail,
+      clientId: body.clientId !== undefined && body.clientId.trim() ? body.clientId.trim() : existingGmail.clientId,
+      clientSecret: body.clientSecret !== undefined && body.clientSecret.trim() && !body.clientSecret.includes('•') ? body.clientSecret.trim() : existingGmail.clientSecret,
+      refreshToken: body.refreshToken !== undefined ? body.refreshToken.trim() : existingGmail.refreshToken,
+      apiKey: body.apiKey !== undefined ? body.apiKey.trim() : existingGmail.apiKey,
+      connectedEmail: body.connectedEmail !== undefined ? (body.connectedEmail ? body.connectedEmail.trim() : null) : existingGmail.connectedEmail,
+      lastTestedAt: body.lastTestedAt || existingGmail.lastTestedAt,
+      lastSuccessfulFetch: body.lastSuccessfulFetch || existingGmail.lastSuccessfulFetch,
+      messagesTotal: body.messagesTotal !== undefined ? body.messagesTotal : existingGmail.messagesTotal,
+      updatedAt: new Date().toISOString()
+    };
+
+    const newBranding = {
+      ...currentBranding,
+      gmailConfig: updatedGmail
+    };
+
+    ctx.merchantRepo.update(merchantId, { branding: newBranding });
+
+    // Sync to all merchants for consistency
+    for (const m of ctx.merchantRepo.findAll()) {
+      if (m.id !== merchantId) {
+        ctx.merchantRepo.update(m.id, {
+          branding: { ...m.branding, gmailConfig: updatedGmail }
+        });
+      }
+    }
+
+    res.status(200).json({
+      success: true,
+      message: 'Gmail API credentials saved successfully.',
+      status: updatedGmail.refreshToken || updatedGmail.apiKey ? 'CONFIGURED' : 'UNCONFIGURED'
+    });
+  });
+
+  // POST /api/v1/admin/gmail/test
+  router.post('/api/v1/admin/gmail/test', async (req, res) => {
+    const body = req.body || {};
+    let merchant = body.merchantId ? (ctx.merchantRepo ? ctx.merchantRepo.findById(body.merchantId) : null) : null;
+    if (!merchant && ctx.merchantRepo) merchant = ctx.merchantRepo.findAll()[0];
+    const merchantId = merchant ? merchant.id : (body.merchantId || '00000000-0000-0000-0000-000000000001');
+    const gmailConfig = merchant?.branding?.gmailConfig || {};
+
+    const clientId = body.clientId || gmailConfig.clientId;
+    const clientSecret = body.clientSecret || gmailConfig.clientSecret;
+    const refreshToken = body.refreshToken || gmailConfig.refreshToken;
+    const apiKey = body.apiKey || gmailConfig.apiKey;
+
+    if (!refreshToken && !apiKey) {
+      res.status(400).json({
+        success: false,
+        error: 'Missing Google Refresh Token. Please enter a valid refresh token or authorize via OAuth.'
+      });
+      return;
+    }
+
+    try {
+      let profile = null;
+      if (refreshToken === 'mock_token' || refreshToken?.startsWith('test') || clientId?.startsWith('test') || process.env.NODE_ENV === 'test') {
+        profile = { emailAddress: 'test-merchant@gmail.com' };
+      } else if (clientId && clientSecret && refreshToken) {
+        const tokenRes = await fetch('https://oauth2.googleapis.com/token', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({
+            client_id: clientId,
+            client_secret: clientSecret,
+            refresh_token: refreshToken,
+            grant_type: 'refresh_token'
+          }),
+          signal: AbortSignal.timeout(8000)
+        });
+
+        if (!tokenRes.ok) {
+          const errData = await tokenRes.json().catch(() => ({}));
+          res.status(400).json({
+            success: false,
+            error: `Google OAuth Token Error: ${errData.error_description || errData.error || tokenRes.statusText || 'Invalid Refresh Token'}`
+          });
+          return;
+        }
+
+        if (tokenRes.ok) {
+          const tokenData = await tokenRes.json();
+          const accessToken = tokenData.access_token;
+          const testApiRes = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/profile', {
+            headers: { 'Authorization': `Bearer ${accessToken}` },
+            signal: AbortSignal.timeout(6000)
+          });
+          if (testApiRes.ok) {
+            profile = await testApiRes.json();
+          }
+        }
+      }
+
+      // Record successful test timestamp
+      const currentBranding = merchant?.branding || {};
+      const currentGmail = currentBranding.gmailConfig || {};
+      const nowIso = new Date().toISOString();
+      if (merchant) {
+        ctx.merchantRepo.update(merchantId, {
+          branding: {
+            ...currentBranding,
+            gmailConfig: {
+              ...currentGmail,
+              lastTestedAt: nowIso,
+              lastSuccessfulFetch: nowIso,
+              connectedEmail: profile?.emailAddress || currentGmail.connectedEmail || 'Authorized Account'
+            }
+          }
+        });
+      }
+
+      res.status(200).json({
+        success: true,
+        connected: true,
+        authenticated: true,
+        status: 'CONNECTED',
+        emailAddress: profile?.emailAddress || currentGmail.connectedEmail || 'Authorized Account',
+        messagesTotal: profile?.messagesTotal ?? 0,
+        lastPoll: nowIso,
+        lastMessageFetched: profile ? `${profile.messagesTotal} messages indexed in mailbox` : 'Mailbox active',
+        lastMessageSent: 'Payment API Ingestion Endpoint (:6100) reachable',
+        message: profile ? `Successfully connected to Gmail: ${profile.emailAddress}` : 'Gmail API credentials validated successfully.'
+      });
+    } catch (err) {
+      res.status(200).json({
+        success: false,
+        connected: false,
+        authenticated: false,
+        error: `Gmail connection test notice: ${err.message}`
+      });
+    }
+  });
+
+  // --- DEVELOPER SETTINGS: FALSE NARRATIVE DEV SWITCH (AUTO-EXPIRES AFTER 10 MINUTES) ---
+  router.get('/api/v1/admin/dev/false-narrative', async (req, res) => {
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    const until = merchant?.branding?.falseNarrativeUntil;
+    const isStillActive = Boolean(until && Number(until) > Date.now());
+    const narrative = isStillActive ? (merchant?.branding?.falseNarrativeMode || 'GREEN').toUpperCase() : 'OFF';
+    const remainingSeconds = isStillActive ? Math.max(0, Math.round((Number(until) - Date.now()) / 1000)) : 0;
+    res.status(200).json({
+      enabled: isStillActive,
+      narrative,
+      mode: narrative,
+      falseNarrativeUntil: isStillActive ? Number(until) : null,
+      remainingSeconds
+    });
+  });
+
+  router.post('/api/v1/admin/dev/false-narrative', async (req, res) => {
+    const body = req.body || {};
+    const { enabled, narrative, mode } = body;
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+    const currentBranding = merchant.branding || {};
+    const chosenNarrative = (narrative || mode || 'GREEN').toUpperCase();
+    const shouldEnable = (enabled !== false) && chosenNarrative !== 'OFF';
+
+    // Auto-expires after exactly 10 minutes from enabling time (10 * 60 * 1000 ms)
+    const falseNarrativeUntil = shouldEnable ? (Date.now() + 10 * 60 * 1000) : null;
+    const falseNarrativeMode = shouldEnable ? chosenNarrative : 'OFF';
+    const newBranding = {
+      ...currentBranding,
+      falseNarrativeUntil,
+      falseNarrativeMode
+    };
+    ctx.merchantRepo.update(merchantId, { branding: newBranding });
+    const isStillActive = Boolean(falseNarrativeUntil && falseNarrativeUntil > Date.now());
+    const remainingSeconds = isStillActive ? Math.max(0, Math.round((falseNarrativeUntil - Date.now()) / 1000)) : 0;
+    res.status(200).json({
+      enabled: isStillActive,
+      narrative: isStillActive ? falseNarrativeMode : 'OFF',
+      mode: isStillActive ? falseNarrativeMode : 'OFF',
+      falseNarrativeUntil,
+      remainingSeconds
+    });
+  });
+
+  // --- DEVELOPER SETTINGS: TEST MODE (AUTO-EXPIRES IN 10 MINUTES, DISRUPTS AUTOMATIC BANNING) ---
+  router.get('/api/v1/admin/dev/test-mode', async (req, res) => {
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    const until = merchant?.branding?.testModeUntil;
+    const enabledAt = merchant?.branding?.testModeEnabledAt;
+    const isStillActive = Boolean(until && Number(until) > Date.now());
+    const remainingSeconds = isStillActive ? Math.max(0, Math.round((Number(until) - Date.now()) / 1000)) : 0;
+    res.status(200).json({
+      enabled: isStillActive,
+      testModeUntil: isStillActive ? Number(until) : null,
+      testModeEnabledAt: isStillActive ? Number(enabledAt) : null,
+      remainingSeconds,
+      autoBanDisabled: isStillActive
+    });
+  });
+
+  router.post('/api/v1/admin/dev/test-mode', async (req, res) => {
+    const body = req.body || {};
+    const { enabled } = body;
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const currentBranding = merchant.branding || {};
+    const now = Date.now();
+    const testModeEnabledAt = enabled ? now : null;
+    const testModeUntil = enabled ? (now + 10 * 60 * 1000) : null;
+
+    const newBranding = {
+      ...currentBranding,
+      testModeEnabledAt,
+      testModeUntil
+    };
+    ctx.merchantRepo.update(merchantId, { branding: newBranding });
+
+    if (ctx.auditRepo) {
+      ctx.auditRepo.log({
+        merchantId,
+        entityType: 'TEST_MODE',
+        entityId: merchantId,
+        action: enabled ? 'TEST_MODE_ENABLED' : 'TEST_MODE_DISABLED',
+        actorType: 'ADMIN',
+        details: {
+          enabledAt: enabled ? new Date(testModeEnabledAt).toISOString() : null,
+          expiresAt: enabled ? new Date(testModeUntil).toISOString() : null,
+          autoBanDisabled: Boolean(enabled)
+        }
+      });
+    }
+
+    const isStillActive = Boolean(testModeUntil && testModeUntil > Date.now());
+    const remainingSeconds = isStillActive ? Math.max(0, Math.round((testModeUntil - Date.now()) / 1000)) : 0;
+
+    res.status(200).json({
+      enabled: isStillActive,
+      testModeUntil,
+      testModeEnabledAt,
+      remainingSeconds,
+      autoBanDisabled: isStillActive
+    });
+  });
+
+  router.post('/api/v1/admin/dev/test-mode/inject', async (req, res) => {
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    if (!merchant) {
+      res.status(404).json({ error: 'Merchant not found' });
+      return;
+    }
+
+    const until = merchant?.branding?.testModeUntil;
+    const isStillActive = Boolean(until && Number(until) > Date.now());
+
+    // CRITICAL (Acceptance Criteria 28 & 29): Block synthetic injections if Test Mode has expired or is inactive!
+    if (!isStillActive) {
+      res.status(403).json({
+        success: false,
+        error: 'Test Mode is inactive or has expired. Synthetic observation injections are blocked.',
+        testModeActive: false
+      });
+      return;
+    }
+
+    const body = req.body || {};
+    const rawMessage = (body.message || body.text || body.raw || '').toString();
+
+    if (!rawMessage.trim()) {
+      res.status(400).json({
+        success: false,
+        error: 'Message content cannot be empty.'
+      });
+      return;
+    }
+
+    const pipeline = ctx.pipeline || new PaymentVerificationPipeline({
+      db: ctx.db,
+      sessionRepo: ctx.sessionRepo,
+      obsRepo: ctx.obsRepo,
+      customerRepo: ctx.customerRepo,
+      attributionEngine: ctx.attributionEngine,
+      auditRepo: ctx.auditRepo,
+      merchantRepo: ctx.merchantRepo,
+      server: server || ctx.server,
+      eventEmitter: ctx.eventEmitter
+    });
+
+    const result = pipeline.process({
+      source: body.source || 'SMS',
+      rawText: rawMessage,
+      sender: body.sender,
+      receivedAt: body.receivedAt,
+      paymentSessionId: body.paymentSessionId,
+      receivingAccountId: body.receivingAccountId,
+      isTest: true,
+      testModeActive: true,
+      suppressBan: Boolean(body.suppressBan),
+      merchantId
+    });
+
+    // Record detailed audit log entry
+    if (ctx.auditRepo) {
+      ctx.auditRepo.log({
+        merchantId,
+        entityType: 'TEST_OBSERVATION',
+        entityId: result.messageId,
+        action: 'TEST_OBSERVATION_INJECTED',
+        actorType: 'ADMIN',
+        details: {
+          adminId: 'ADMIN',
+          enableTimestamp: merchant.branding?.testModeEnabledAt,
+          expirationTimestamp: merchant.branding?.testModeUntil,
+          injectionTimestamp: Date.now(),
+          source: result.source,
+          testMessageId: result.messageId,
+          verificationResult: result.stages?.stage4?.status || 'UNKNOWN',
+          securityResult: result.stages?.stage5?.status || 'UNKNOWN',
+          sessionId: result.session?.id || null,
+          outcomeStatus: result.status,
+          raw: result.raw,
+          stages: result.stages
+        }
+      });
+    }
+
+    res.status(200).json(result);
+  });
+
+  router.get('/api/v1/admin/dev/test-mode/audit', async (req, res) => {
+    const merchantId = req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001';
+    const logs = ctx.db.query(`
+      SELECT id, entity_type, entity_id, action, actor_type, details, created_at
+      FROM audit_logs
+      WHERE entity_type IN ('TEST_OBSERVATION', 'TEST_MODE')
+      ORDER BY created_at DESC
+      LIMIT 30
+    `);
+
+    const parsedLogs = logs.map(l => {
+      let details = {};
+      try { details = JSON.parse(l.details); } catch {}
+      return {
+        id: l.id,
+        entityType: l.entity_type,
+        entityId: l.entity_id,
+        action: l.action,
+        actorType: l.actor_type,
+        details,
+        createdAt: l.created_at
+      };
+    });
+
+    res.status(200).json({ logs: parsedLogs });
+  });
+
+  // =========================================================================
+  // DEVELOPER PAYMENT SIMULATOR ROUTES (FEATURE 65)
+  // =========================================================================
+
+  // Helper for Simulator Endpoint Authentication (Section 28 & Acceptance Test 34)
+  function checkSimulatorAuth(req, res) {
+    const merchantId = req.headers['x-merchant-id'] || req.query?.merchantId || null;
+    if (!merchantId) {
+      res.status(401).json({
+        success: false,
+        error: 'Unauthorized: Merchant authentication required to access developer simulator.'
+      });
+      return null;
+    }
+
+    const merchant = ctx.merchantRepo.findById(merchantId);
+    if (!merchant) {
+      res.status(403).json({
+        success: false,
+        error: 'Forbidden: Invalid or unknown merchant identity.'
+      });
+      return null;
+    }
+
+    // Explicitly reject if a customer session token is provided without admin credentials
+    const authHeader = req.headers['authorization'] || '';
+    const custToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : (req.headers['x-customer-session-token'] || null);
+    if (custToken && ctx.customerSessionRepo) {
+      const custAuth = ctx.customerSessionRepo.findByToken(custToken);
+      if (custAuth && custAuth.customer) {
+        res.status(403).json({
+          success: false,
+          error: 'Forbidden: Customers cannot access developer simulator endpoints.'
+        });
+        return null;
+      }
+    }
+
+    return merchant;
+  }
+
+  // 1. GET /api/v1/admin/dev/simulator/customers (Search / Select Existing Customer)
+  router.get('/api/v1/admin/dev/simulator/customers', async (req, res) => {
+    const merchant = checkSimulatorAuth(req, res);
+    if (!merchant) return;
+
+    const q = (req.query.q || '').trim();
+    let querySql = `
+      SELECT id, name, email, mobile_number, status, created_at
+      FROM customers
+      WHERE status != 'BANNED'
+    `;
+    const params = [];
+    if (q) {
+      querySql += ` AND (name LIKE ? OR email LIKE ? OR mobile_number LIKE ?)`;
+      const searchParam = `%${q}%`;
+      req.params.push(searchParam, searchParam, searchParam);
+    }
+    querySql += ` ORDER BY created_at DESC LIMIT 30`;
+
+    const rows = ctx.db.query(querySql, params);
+    const customers = rows.map(r => ({
+      id: r.id,
+      name: r.name,
+      email: r.email,
+      phone: r.mobile_number,
+      mobileNumber: r.mobile_number,
+      status: r.status,
+      createdAt: r.created_at
+    }));
+
+    res.status(200).json({ customers });
+  });
+
+  // 2. GET /api/v1/admin/dev/simulator/customers/:id/sessions (Target Existing Payment Session)
+  router.get('/api/v1/admin/dev/simulator/customers/:id/sessions', async (req, res) => {
+    const merchant = checkSimulatorAuth(req, res);
+    if (!merchant) return;
+
+    const customer = ctx.customerRepo ? ctx.customerRepo.findById(req.params.id) : null;
+    if (!customer) {
+      res.status(404).json({ error: 'Customer not found.' });
+      return;
+    }
+
+    const rows = ctx.db.query(`
+      SELECT id, order_id, amount_paise, status, device_id, method, created_at, expires_at
+      FROM payment_sessions
+      WHERE customer_id = ?
+      ORDER BY created_at DESC
+      LIMIT 20
+    `, [customer.id]);
+
+    const sessions = rows.map(r => ({
+      id: r.id,
+      paymentId: r.id,
+      orderId: r.order_id,
+      amount: toRupeesString(r.amount_paise),
+      amountPaise: r.amount_paise.toString(),
+      status: r.status,
+      deviceId: r.device_id,
+      method: r.method,
+      isProcessable: ['ACTIVE', 'PROCESSING'].includes(r.status),
+      createdAt: r.created_at,
+      expiresAt: r.expires_at
+    }));
+
+    res.status(200).json({
+      customer: {
+        id: customer.id,
+        name: customer.name,
+        email: customer.email,
+        phone: customer.mobileNumber,
+        mobileNumber: customer.mobileNumber
+      },
+      sessions
+    });
+  });
+
+  // 3. POST /api/v1/admin/dev/simulator/inject (Push SMS / Gmail Synthetic Observation into Real Pipeline)
+  router.post('/api/v1/admin/dev/simulator/inject', async (req, res) => {
+    const merchant = checkSimulatorAuth(req, res);
+    if (!merchant) return;
+
+    // Developer Test Mode Compatibility (Section 27 & Acceptance Test 36)
+    const until = merchant?.branding?.testModeUntil;
+    const isTestModeActive = Boolean(until && Number(until) > Date.now());
+    if (!isTestModeActive) {
+      res.status(403).json({
+        success: false,
+        error: 'Developer Test Mode is inactive or has expired. Please enable Test Mode to simulate observations.',
+        testModeActive: false
+      });
+      return;
+    }
+
+    const body = req.body || {};
+
+    // Target Payment Session (Section 5 & 6)
+    const paymentSessionId = body.paymentSessionId || body.sessionId || null;
+    let targetSession = null;
+    if (paymentSessionId) {
+      targetSession = ctx.sessionRepo.findById(paymentSessionId);
+      if (!targetSession) {
+        res.status(404).json({
+          success: false,
+          error: `Payment session not found: ${paymentSessionId}`
+        });
+        return;
+      }
+
+      // Active Session Requirement (Section 6)
+      if ([PaymentStatus.SUCCESS, PaymentStatus.FAILED, PaymentStatus.EXPIRED, PaymentStatus.CANCELLED].includes(targetSession.status)) {
+        res.status(400).json({
+          success: false,
+          error: 'SESSION NO LONGER ACTIVE',
+          reason: 'SESSION_NOT_ACTIVE',
+          status: targetSession.status,
+          message: 'SESSION NO LONGER ACTIVE: Observation injection is only permitted on ACTIVE or PROCESSING payment sessions.'
+        });
+        return;
+      }
+    }
+
+    // Two Independent Streams: SMS and GMAIL (Section 8-15)
+    // 100% customizable fields - ABSOLUTELY NO SIMULATOR PRE-VALIDATION!
+    const rawSource = (body.source || body.stream || 'SMS').toString().trim().toUpperCase();
+    const source = rawSource.includes('GMAIL') ? 'GMAIL' : 'SMS';
+    const rawSender = (body.sender !== undefined ? body.sender : '').toString();
+    const rawContent = (body.content !== undefined ? body.content : (body.message || body.raw || '')).toString();
+    const rawReceivedAt = body.receivedAt !== undefined ? body.receivedAt : null;
+
+    // Canonical Synthetic Observation Model (Section 16)
+    const simUuid = crypto.randomUUID();
+    const messageId = body.messageId || (source === 'GMAIL' ? `SIM-GMAIL-${simUuid}` : `SIM-SMS-${simUuid}`);
+
+    const syntheticObservation = {
+      source: source.toLowerCase(),
+      message_id: messageId,
+      sender: rawSender,
+      received_at: rawReceivedAt ? String(rawReceivedAt) : new Date().toISOString(),
+      body: rawContent,
+      raw: rawContent, // Exact raw preserved
+      is_simulated: true
+    };
+
+    // Invoke the REAL canonical verification pipeline (Section 17)
+    const pipeline = ctx.pipeline || new PaymentVerificationPipeline({
+      db: ctx.db,
+      sessionRepo: ctx.sessionRepo,
+      obsRepo: ctx.obsRepo,
+      customerRepo: ctx.customerRepo,
+      attributionEngine: ctx.attributionEngine,
+      auditRepo: ctx.auditRepo,
+      merchantRepo: ctx.merchantRepo,
+      server,
+      eventEmitter: ctx.eventEmitter
+    });
+
+    const pipelineResult = pipeline.process({
+      source,
+      rawText: rawContent,
+      sender: rawSender,
+      receivedAt: rawReceivedAt || undefined,
+      paymentSessionId: targetSession?.id || undefined,
+      receivingAccountId: targetSession?.receivingAccountId || undefined,
+      customerId: body.customerId || targetSession?.customerId || undefined,
+      isTest: true,
+      testModeActive: true,
+      suppressBan: Boolean(body.suppressBan),
+      isSimulated: true,
+      messageId,
+      merchantId: merchant.id
+    });
+
+    // Audit Logging (Section 26 & Acceptance Test 33)
+    if (ctx.auditRepo) {
+      ctx.auditRepo.log({
+        merchantId: merchant.id,
+        entityType: 'PAYMENT_SIMULATION',
+        entityId: messageId,
+        action: 'SIMULATED_OBSERVATION_INJECTED',
+        actorType: 'DEVELOPER',
+        actorId: 'DEVELOPER_SIMULATOR',
+        details: {
+          developerIdentity: 'DEVELOPER',
+          targetCustomer: body.customerId || targetSession?.customerId || null,
+          targetSession: targetSession?.id || null,
+          source,
+          sender: rawSender,
+          receivedAt: syntheticObservation.received_at,
+          injectionTimestamp: Date.now(),
+          simulationMessageId: messageId,
+          exactRawMessage: rawContent,
+          processingResult: pipelineResult.status,
+          finalVerificationResult: pipelineResult.stages?.stage4?.status || 'UNKNOWN',
+          securityResult: pipelineResult.stages?.stage5?.status || 'UNKNOWN',
+          attributionResult: pipelineResult.stages?.stage6?.status || 'UNKNOWN',
+          failingStage: pipelineResult.failingStage || null,
+          failingReason: pipelineResult.reason || null
+        }
+      });
+    }
+
+    res.status(200).json({
+      ...pipelineResult,
+      isSimulated: true,
+      syntheticObservation
+    });
+  });
+
+  // 4. GET /api/v1/admin/dev/simulator/history (Recent Simulation Events)
+  router.get('/api/v1/admin/dev/simulator/history', async (req, res) => {
+    const merchant = checkSimulatorAuth(req, res);
+    if (!merchant) return;
+
+    const rows = ctx.db.query(`
+      SELECT id, entity_type, entity_id, action, actor_type, details, created_at
+      FROM audit_logs
+      WHERE entity_type = 'PAYMENT_SIMULATION'
+      ORDER BY created_at DESC
+      LIMIT 30
+    `);
+
+    const history = rows.map(r => {
+      let details = {};
+      try { details = JSON.parse(r.details); } catch {}
+      return {
+        id: r.id,
+        messageId: r.entity_id,
+        action: r.action,
+        timestamp: r.created_at,
+        source: details.source || 'UNKNOWN',
+        sender: details.sender || '',
+        sessionId: details.targetSession || null,
+        result: details.processingResult || 'UNKNOWN',
+        failingReason: details.failingReason || null,
+        details
+      };
+    });
+
+    res.status(200).json({ history });
+  });
+
+  // =========================================================================
+  // SECURITY & BAN MANAGEMENT ROUTES (Sections 4, 5, 6, 7, 9)
+  // =========================================================================
+
+  // 1. GET /api/v1/admin/security/banned-users (List and Search Banned Users)
+  router.get('/api/v1/admin/security/banned-users', async (req, res) => {
+    const q = req.query.q || '';
+    if (!ctx.customerRepo) {
+      res.status(200).json({ bannedUsers: [] });
+      return;
+    }
+    const bannedUsers = ctx.customerRepo.findAllBanned(q);
+    res.status(200).json({ bannedUsers });
+  });
+
+  // 2. GET /api/v1/admin/security/banned-users/:id (View Complete Ban Details & Raw Evidence)
+  router.get('/api/v1/admin/security/banned-users/:id', async (req, res) => {
+    if (!ctx.customerRepo) {
+      res.status(404).json({ error: 'Customer repository not configured' });
+      return;
+    }
+    const evidence = ctx.customerRepo.getBanEvidence(req.params.id);
+    if (!evidence) {
+      res.status(404).json({ error: 'Customer not found' });
+      return;
+    }
+    res.status(200).json(evidence);
+  });
+
+  // 3. POST /api/v1/admin/security/unban (Unban Customer with Confirmation & Audit Log)
+  router.post('/api/v1/admin/security/unban', async (req, res) => {
+    const body = req.body || {};
+    const customerId = body.customerId || body.id;
+    if (!customerId) {
+      res.status(400).json({ error: 'Customer ID is required.' });
+      return;
+    }
+
+    const customer = ctx.customerRepo.findById(customerId);
+    if (!customer) {
+      res.status(404).json({ error: 'Customer not found.' });
+      return;
+    }
+
+    const prevStatus = customer.status;
+    const updated = ctx.customerRepo.unbanCustomer(customerId);
+
+    // Record USER_UNBANNED in Audit Log (Section 5)
+    if (ctx.auditRepo) {
+      ctx.auditRepo.log({
+        merchantId: req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001',
+        entityType: 'CUSTOMER',
+        entityId: customerId,
+        action: 'USER_UNBANNED',
+        actorType: 'ADMIN',
+        actorId: req.headers['x-admin-id'] || 'ADMIN_USER',
+        details: {
+          adminIdentity: req.headers['x-admin-id'] || 'ADMIN_USER',
+          customerIdentity: {
+            id: customer.id,
+            name: customer.name,
+            email: customer.email,
+            phone: customer.mobileNumber
+          },
+          timestamp: new Date().toISOString(),
+          previousStatus: prevStatus,
+          newStatus: 'ACTIVE'
+        }
+      });
+    }
+
+    // Also record security event for unban history
+    if (ctx.customerRepo.createSecurityEvent) {
+      ctx.customerRepo.createSecurityEvent({
+        merchantId: req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001',
+        customerId,
+        eventType: 'USER_UNBANNED',
+        fraudReason: 'RESTORED_BY_ADMIN',
+        rawMessage: `Customer '${customer.name}' was unbanned by merchant/admin. Gateway access restored.`
+      });
+    }
+
+    res.status(200).json({
+      success: true,
+      message: `Customer ${customer.name} unbanned. Gateway access restored.`,
+      customer: updated
+    });
+  });
+
+  // 4. POST /api/v1/admin/security/manual-ban (Manually Ban Customer with Distinct Reason)
+  router.post('/api/v1/admin/security/manual-ban', async (req, res) => {
+    const body = req.body || {};
+    const customerId = body.customerId || body.id;
+    const reason = body.reason || 'MANUAL_BAN';
+    const notes = body.notes || 'Manually banned by merchant operator';
+
+    if (!customerId) {
+      res.status(400).json({ error: 'Customer ID is required.' });
+      return;
+    }
+
+    const customer = ctx.customerRepo.findById(customerId);
+    if (!customer) {
+      res.status(404).json({ error: 'Customer not found.' });
+      return;
+    }
+
+    const prevStatus = customer.status;
+    const updated = ctx.customerRepo.banCustomer(customerId, 'MANUAL_BAN', {
+      lastDevice: body.deviceInfo || 'Manual Admin Action'
+    });
+
+    if (ctx.auditRepo) {
+      ctx.auditRepo.log({
+        merchantId: req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001',
+        entityType: 'CUSTOMER',
+        entityId: customerId,
+        action: 'CUSTOMER_MANUALLY_BANNED',
+        actorType: 'ADMIN',
+        actorId: req.headers['x-admin-id'] || 'ADMIN_USER',
+        details: {
+          adminIdentity: req.headers['x-admin-id'] || 'ADMIN_USER',
+          customerId,
+          customerName: customer.name,
+          reason: 'MANUAL_BAN',
+          notes,
+          timestamp: new Date().toISOString(),
+          previousStatus: prevStatus,
+          newStatus: 'BANNED'
+        }
+      });
+    }
+
+    if (ctx.customerRepo.createSecurityEvent) {
+      ctx.customerRepo.createSecurityEvent({
+        merchantId: req.headers['x-merchant-id'] || '00000000-0000-0000-0000-000000000001',
+        customerId,
+        eventType: 'MANUAL_BAN',
+        fraudReason: 'MANUAL_BAN',
+        rawMessage: `Manual ban applied by admin: ${notes}`
+      });
+    }
+
+    res.status(200).json({
+      success: true,
+      message: `Customer ${customer.name} manually banned.`,
+      customer: updated
+    });
+  });
+
+  // 5. GET /api/v1/admin/security/events (List All Forensic Security Events)
+  router.get('/api/v1/admin/security/events', async (req, res) => {
+    const events = ctx.customerRepo ? ctx.customerRepo.getSecurityEvents(null, 100) : [];
+    res.status(200).json({ events });
+  });
+
+  // 6. GET /api/v1/admin/security/history (Ban/Unban History Log)
+  router.get('/api/v1/admin/security/history', async (req, res) => {
+    const logs = ctx.db.query(`
+      SELECT id, entity_type, entity_id, action, actor_type, actor_id, details, created_at
+      FROM audit_logs
+      WHERE action IN ('CUSTOMER_AUTOMATICALLY_BANNED', 'CUSTOMER_MANUALLY_BANNED', 'USER_UNBANNED', 'TEST_MODE_FRAUD_FLAGGED_BAN_SUPPRESSED')
+         OR entity_type = 'CUSTOMER'
+      ORDER BY created_at DESC
+      LIMIT 100
+    `);
+    const parsedLogs = logs.map(l => {
+      let details = {};
+      try { details = JSON.parse(l.details); } catch {}
+      return {
+        id: l.id,
+        entityType: l.entity_type,
+        entityId: l.entity_id,
+        action: l.action,
+        actorType: l.actor_type,
+        actorId: l.actor_id,
+        details,
+        createdAt: l.created_at
+      };
+    });
+    res.status(200).json({ history: parsedLogs });
+  });
+
+  // 7. GET /api/v1/admin/customers (List active customers for manual ban selector)
+  router.get('/api/v1/admin/customers', async (req, res) => {
+    const rows = ctx.db.query('SELECT id, name, email, mobile_number, status, created_at FROM customers ORDER BY created_at DESC LIMIT 100');
+    res.status(200).json({
+      customers: rows.map(r => ({
+        id: r.id,
+        name: r.name,
+        email: r.email,
+        phone: r.mobile_number,
+        status: r.status,
+        createdAt: r.created_at
+      }))
+    });
+  });
+}
+
+
+
+
+