elpaypg 0.0.0-stage → 2.0.0

package/src/routes/payments.routes.js

@@ -0,0 +1,446 @@
+import { Router } from 'express';
+import { toPaise, toRupeesString, resolveRuntimeUrls, PaymentStatus, safeEqual } from '../vendor/common/index.js';
+import { isTerminalStatus, toPublicOutcome, verifyRegisteredDeviceCredentials } from '../vendor/core/index.js';
+import { isPaymentOwner } from '../auth-guard.js';
+
+/**
+ * Registers merchant-facing payment routes.
+ * @param {HttpServer} server
+ * @param {{
+ *   merchantRepo: import('../vendor/db/index.js').MerchantRepository,
+ *   accountRepo: import('../vendor/db/index.js').ReceivingAccountRepository,
+ *   sessionRepo: import('../vendor/db/index.js').PaymentSessionRepository,
+ *   queueEngine: import('../vendor/core/index.js').QueueEngine,
+ *   timingEngine: import('../vendor/core/index.js').TimingEngine,
+ *   auditRepo: import('../vendor/db/index.js').AuditLogRepository,
+ *   checkoutBaseUrl: string
+ * }} ctx
+ */
+export function registerPaymentRoutes(router, ctx) {
+  function resolveCheckoutBaseUrl(merchant) {
+    return ctx.checkoutBaseUrl || 'http://localhost:5000';
+  }
+
+  // POST /api/v1/payments
+  router.post('/api/v1/payments', async (req, res) => {
+    const body = req.body || {};
+    const idempotencyKey = req.headers['idempotency-key'] || body.idempotencyKey;
+
+    // Resolve merchant (default to first/demo merchant if none passed in header)
+    const merchantId = req.headers['x-merchant-id'] || body.merchantId;
+    let merchant;
+    if (merchantId) {
+      merchant = ctx.merchantRepo.findById(merchantId);
+      if (!merchant) merchant = ctx.merchantRepo.getDefault ? ctx.merchantRepo.getDefault() : null;
+    } else {
+      merchant = ctx.merchantRepo.getDefault ? ctx.merchantRepo.getDefault() : (ctx.merchantRepo.findById('00000000-0000-0000-0000-000000000001') || ctx.merchantRepo.findAll()[0]);
+    }
+
+    if (!merchant) {
+      res.status(400).json({ error: 'Merchant not found or not configured.' });
+      return;
+    }
+
+    if (req.headers['x-merchant-key']) {
+      if (!merchant.webhookSecret || !safeEqual(req.headers['x-merchant-key'].trim(), merchant.webhookSecret)) {
+        res.status(401).json({ error: 'Invalid merchant key', code: 'INVALID_MERCHANT_KEY' });
+        return;
+      }
+    }
+
+    if (!body.orderId || !body.amount) {
+      res.status(400).json({ error: 'Missing required fields: orderId and amount.' });
+      return;
+    }
+
+    // returnUrl is echoed back to the customer's browser as a redirect target after
+    // payment, so only absolute http(s) URLs are ever stored. This is the write-side
+    // complement to the checkout page's sanitizeRedirectUrl.
+    if (body.returnUrl !== undefined && body.returnUrl !== null && body.returnUrl !== '') {
+      if (typeof body.returnUrl !== 'string') {
+        res.status(400).json({ error: 'returnUrl must be a string.' });
+        return;
+      }
+      let parsedReturnUrl;
+      try {
+        parsedReturnUrl = new URL(body.returnUrl.trim());
+      } catch {
+        res.status(400).json({ error: 'returnUrl must be an absolute http(s) URL.' });
+        return;
+      }
+      if (parsedReturnUrl.protocol !== 'http:' && parsedReturnUrl.protocol !== 'https:') {
+        res.status(400).json({ error: 'returnUrl must use the http or https scheme.' });
+        return;
+      }
+      body.returnUrl = parsedReturnUrl.href;
+    }
+
+    const deviceId = body.deviceId || req.headers['x-device-id'] || null;
+    const deviceToken = body.deviceToken || req.headers['x-device-token'] || null;
+    const deviceSignature = body.deviceSignature || req.headers['x-device-signature'] || null;
+    const signaturePayload = body.signaturePayload || req.headers['x-device-payload'] || null;
+
+    if (deviceId) {
+      const credCheck = verifyRegisteredDeviceCredentials({
+        deviceId,
+        deviceToken,
+        deviceSignature,
+        signaturePayload,
+        deviceRepo: ctx.deviceRepo
+      });
+      if (!credCheck.valid) {
+        res.status(401).json({
+          error: credCheck.error || 'DEVICE_CREDENTIALS_INVALID',
+          message: credCheck.message || 'A registered device and valid device credential are required.'
+        });
+        return;
+      }
+    }
+
+    // Check idempotency & active session state
+    const existing = ctx.sessionRepo.findByOrderId(merchant.id, body.orderId);
+    if (existing) {
+      // If SUCCESS: order is already paid, return existing completed session
+      if (existing.status === PaymentStatus.SUCCESS) {
+        res.status(200).json({
+          paymentId: existing.id,
+          orderId: existing.orderId,
+          amount: toRupeesString(existing.amountPaise),
+          amountPaise: existing.amountPaise.toString(),
+          currency: existing.currency,
+          status: existing.status,
+          checkoutUrl: `${resolveCheckoutBaseUrl(merchant)}/checkout/${existing.id}`
+        });
+        return;
+      }
+
+      // Check if existing session is stale
+      const now = Date.now();
+      const isStale = (existing.status === PaymentStatus.ACTIVE && existing.expiresAt && existing.expiresAt.getTime() <= now) ||
+        (existing.status === PaymentStatus.PROCESSING && existing.processingExpiresAt && existing.processingExpiresAt.getTime() <= now);
+      if (isStale) {
+        const terminalStatus = existing.status === PaymentStatus.PROCESSING ? PaymentStatus.FAILED : PaymentStatus.EXPIRED;
+        ctx.sessionRepo.transitionToTerminal(existing.id, terminalStatus);
+        if (existing.receivingAccountId) {
+          ctx.queueEngine.promoteNext(existing.receivingAccountId);
+        }
+        existing.status = terminalStatus;
+        if (ctx.eventEmitter) {
+          ctx.eventEmitter.emit(`PAYMENT.${terminalStatus}`, {
+            paymentId: existing.id,
+            orderId: existing.orderId,
+            merchantId: existing.merchantId,
+            amountPaise: existing.amountPaise
+          });
+        }
+      }
+
+      // If existing is non-terminal (ACTIVE, PROCESSING, QUEUED, INITIATED):
+      if ([PaymentStatus.ACTIVE, PaymentStatus.PROCESSING, PaymentStatus.QUEUED, PaymentStatus.INITIATED].includes(existing.status)) {
+        // CASE 3: Active session bound to a device + missing or different device -> DUPLICATE_SESSION_DETECTED
+        if (existing.deviceId && (!deviceId || deviceId !== existing.deviceId)) {
+          res.status(409).json({
+            error: 'DUPLICATE_SESSION_DETECTED',
+            code: 'DEVICE_SESSION_MISMATCH',
+            session_id: existing.id,
+            activeSession: {
+              paymentId: existing.id,
+              orderId: existing.orderId,
+              amount: toRupeesString(existing.amountPaise)
+            },
+            action: 'END_SESSION_AND_CREATE_NEW',
+            message: 'This payment session was created on another device. For security reasons, this session cannot be continued from this device.'
+          });
+          return;
+        }
+
+        // CASE 2: Active session + Same device -> CONTINUE ACTIVE SESSION
+        res.status(200).json({
+          paymentId: existing.id,
+          orderId: existing.orderId,
+          amount: toRupeesString(existing.amountPaise),
+          amountPaise: existing.amountPaise.toString(),
+          currency: existing.currency,
+          status: existing.status,
+          activeSessionDetected: true,
+          checkoutUrl: `${resolveCheckoutBaseUrl(merchant)}/checkout/${existing.id}`
+        });
+        return;
+      }
+
+      // CASE 4: Previous session is TERMINAL (FAILED, EXPIRED, CANCELLED) -> RETRY / NEW ATTEMPT!
+      // Invariant: Keep merchant's exact orderId untouched so webhooks, reconciliations, and reporting align.
+      body.orderId = body.orderId.replace(/-R\d+$/, '');
+    }
+
+    let amountPaise;
+    try {
+      amountPaise = toPaise(body.amount);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+      return;
+    }
+
+    const isCounterPayment = body.method === 'CASH_COUNTER' || body.method === 'CARD_COUNTER';
+
+    let receivingAccountId = null;
+    let receivingAccountSnapshot = null;
+    if (!isCounterPayment) {
+      // Resolve active receiving account for UPI
+      const receivingAccount = ctx.accountRepo.findActiveForMerchant(merchant.id);
+      if (!receivingAccount) {
+        res.status(500).json({ error: 'No active UPI receiving account configured for merchant.' });
+        return;
+      }
+      receivingAccountId = receivingAccount.id;
+      receivingAccountSnapshot = {
+        id: receivingAccount.id,
+        upiId: receivingAccount.upiId,
+        payeeName: receivingAccount.payeeName,
+        isMerchantEnabled: receivingAccount.isMerchantEnabled
+      };
+    }
+
+    // Resolve customer if provided (optional pre-existing customer)
+    let customerId = body.customerId || null;
+    if (!customerId && (body.customer?.mobileNumber || body.customer?.phoneNumber || body.customer?.email) && ctx.customerRepo) {
+      const ident = body.customer.email || body.customer.mobileNumber || body.customer.phoneNumber;
+      const existingCust = ctx.customerRepo.findByIdentifier(ident);
+      if (existingCust) {
+        customerId = existingCust.id;
+      }
+    }
+
+    // Server-side Ban Enforcement (Section 3)
+    if (customerId && ctx.customerRepo && ctx.customerRepo.isBanned(customerId)) {
+      res.status(403).json({
+        status: 'BLOCKED',
+        error: 'ACCESS BLOCKED: Your account has been temporarily blocked because suspicious payment activity was detected. Our team will review the activity before access can be restored.',
+        message: 'Your account has been temporarily blocked because suspicious payment activity was detected. Our team will review the activity before access can be restored.',
+        isBanned: true
+      });
+      return;
+    }
+
+    // Check if customer already has an active payment session on another device (CASE 3)
+    if (customerId && ctx.sessionRepo) {
+      const activeForCust = ctx.sessionRepo.findActiveForCustomer ? ctx.sessionRepo.findActiveForCustomer(customerId) : null;
+      if (activeForCust) {
+        if (activeForCust.deviceId && (!deviceId || deviceId !== activeForCust.deviceId)) {
+          res.status(409).json({
+            error: 'DUPLICATE_SESSION_DETECTED',
+            code: 'DEVICE_SESSION_MISMATCH',
+            session_id: activeForCust.id,
+            activeSession: {
+              paymentId: activeForCust.id,
+              orderId: activeForCust.orderId,
+              amount: toRupeesString(activeForCust.amountPaise)
+            },
+            action: 'END_SESSION_AND_CREATE_NEW',
+            message: 'This customer already has an active payment session on another device. For security reasons, this session cannot be continued from this device.'
+          });
+          return;
+        }
+      }
+    }
+
+    // Invariant: Do NOT start payment session timer until customer is authenticated/logged in!
+    // Customer sign in or sign up in the checkout portal is mandatory before slot activation or timer start.
+    // Digital UPI payments MUST ALWAYS start in status INITIATED without acquiring a concurrency slot or timer.
+    // Only physical counter payments (CASH_COUNTER, CARD_COUNTER) start as ACTIVE (they do not use UPI slots).
+    // The only exception for UPI auto-activation is explicit developer test suite flag: body.autoActivate === true.
+    const isExplicitTestAutoActivate = body.autoActivate === true || body.autoActivate === 'true';
+    const shouldActivateNow = isCounterPayment || isExplicitTestAutoActivate;
+    const initialStatus = isCounterPayment ? PaymentStatus.ACTIVE : PaymentStatus.INITIATED;
+
+    const sessionMetadata = {
+      ...(body.metadata || {}),
+      ...(receivingAccountSnapshot ? { receivingAccountSnapshot } : {})
+    };
+
+    if (deviceId && customerId && ctx.deviceRepo) {
+      try { ctx.deviceRepo.associateCustomer(deviceId, customerId); } catch {}
+    }
+
+    // Create session in DB
+    const session = ctx.sessionRepo.create({
+      merchantId: merchant.id,
+      customerId,
+      receivingAccountId,
+      orderId: body.orderId,
+      amountPaise,
+      currency: body.currency || 'INR',
+      method: body.method || 'UPI',
+      status: initialStatus,
+      returnUrl: body.returnUrl || null,
+      idempotencyKey: idempotencyKey || null,
+      deviceId,
+      metadata: sessionMetadata
+    });
+
+    // Enqueue or Activate slot via QueueEngine ONLY when counter payment or explicitly requested by automated test runner
+    let queueResult = { status: initialStatus, queuePosition: 0, expiresAt: null };
+    if (!isCounterPayment && receivingAccountId && shouldActivateNow) {
+      queueResult = ctx.queueEngine.enqueueOrActivate(session.id, receivingAccountId);
+
+      // If activated immediately, start Timer 1 (5 minutes)
+      if (queueResult.expiresAt) {
+        ctx.timingEngine.startActiveTimer(session.id, queueResult.expiresAt);
+      }
+      ctx.eventEmitter?.emit?.('sse:admin_counter_events', { status: queueResult.status, sessionId: session.id, orderId: session.orderId, amountPaise: session.amountPaise ? session.amountPaise.toString() : '0' });
+    }
+
+    res.status(201).json({
+      paymentId: session.id,
+      orderId: session.orderId,
+      amount: toRupeesString(amountPaise),
+      amountPaise: amountPaise.toString(),
+      currency: session.currency,
+      status: queueResult.status,
+      queuePosition: queueResult.queuePosition,
+      checkoutUrl: `${resolveCheckoutBaseUrl(merchant)}/checkout/${session.id}`
+    });
+  });
+
+  // GET /api/v1/payments/:id
+  router.get('/api/v1/payments/:id', async (req, res) => {
+    const session = ctx.sessionRepo.findById(req.params.id);
+    if (!session) {
+      res.status(404).json({ error: `Payment session not found: ${req.params.id}` });
+      return;
+    }
+
+    const publicStatus = isTerminalStatus(session.status)
+      ? toPublicOutcome(session.status)
+      : session.status;
+
+    // Fields any payment-id holder may read. Everything else is merchant-private: the raw
+    // state machine status, verification internals, merchant metadata and the return URL.
+    const publicView = {
+      paymentId: session.id,
+      orderId: session.orderId,
+      amount: toRupeesString(session.amountPaise),
+      amountPaise: session.amountPaise.toString(),
+      currency: session.currency,
+      status: publicStatus,
+      method: session.method,
+      completedAt: session.completedAt ? session.completedAt.toISOString() : null
+    };
+
+    if (!isPaymentOwner(req, session, ctx)) {
+      res.status(200).json(publicView);
+      return;
+    }
+
+    res.status(200).json({
+      ...publicView,
+      internalStatus: session.status,
+      verificationLevel: session.verificationLevel || 0,
+      verificationSources: session.verificationSources || [],
+      verificationTag: session.verificationTag || 'UNVERIFIED',
+      returnUrl: session.returnUrl,
+      metadata: session.metadata
+    });
+  });
+
+  // GET /api/v1/payments/:id/cod (Developer COD Info Endpoint)
+  router.get('/api/v1/payments/:id/cod', async (req, res) => {
+    const session = ctx.sessionRepo.findById(req.params.id);
+    if (!session) {
+      res.status(404).json({ error: `Payment session not found: ${req.params.id}` });
+      return;
+    }
+
+    // Order ids are merchant-chosen and often sequential, so the delivery contact and metadata
+    // are only for the owning merchant (or the gateway); anyone else gets the order status.
+    const owner = isPaymentOwner(req, session, ctx);
+    let customer = null;
+    if (owner && session.customerId && ctx.customerRepo) {
+      const c = ctx.customerRepo.findById(session.customerId);
+      if (c) {
+        const isOwner = isPaymentOwner(req, session, ctx);
+        customer = {
+          id: c.id,
+          name: c.name,
+          email: isOwner ? c.email : (c.email ? `${c.email.slice(0, 2)}***@${c.email.split('@')[1] || '***'}` : null),
+          mobileNumber: isOwner ? c.mobileNumber : (c.mobileNumber ? `${c.mobileNumber.slice(0, 2)}******${c.mobileNumber.slice(-2)}` : null)
+        };
+      }
+    }
+
+    res.status(200).json({
+      paymentId: session.id,
+      orderId: session.orderId,
+      amount: toRupeesString(session.amountPaise),
+      amountPaise: session.amountPaise.toString(),
+      currency: session.currency,
+      method: session.method,
+      status: session.status,
+      verificationTag: session.verificationTag,
+      isCod: session.method === 'COD',
+      customer: owner ? customer : null,
+      placedAt: session.completedAt ? (session.completedAt.toISOString ? session.completedAt.toISOString() : session.completedAt) : (session.createdAt?.toISOString ? session.createdAt.toISOString() : session.createdAt),
+      ...(owner ? { metadata: session.metadata } : {})
+    });
+  });
+
+  // GET /api/v1/orders/:orderId/cod (Developer COD Info by Merchant Order ID)
+  router.get('/api/v1/orders/:orderId/cod', async (req, res) => {
+    const merchantId = req.headers['x-merchant-id'] || req.query.merchantId;
+    let merchant;
+    if (merchantId) {
+      merchant = ctx.merchantRepo.findById(merchantId);
+      if (!merchant) merchant = ctx.merchantRepo.getDefault ? ctx.merchantRepo.getDefault() : null;
+    } else {
+      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 session = ctx.sessionRepo.findByOrderId(merchant.id, req.params.orderId);
+    if (!session) {
+      res.status(404).json({ error: `Order not found: ${req.params.orderId}` });
+      return;
+    }
+
+    // Order ids are merchant-chosen and often sequential, so the delivery contact and metadata
+    // are only for the owning merchant (or the gateway); anyone else gets the order status.
+    const owner = isPaymentOwner(req, session, ctx);
+    let customer = null;
+    if (owner && session.customerId && ctx.customerRepo) {
+      const c = ctx.customerRepo.findById(session.customerId);
+      if (c) {
+        const isOwner = isPaymentOwner(req, session, ctx);
+        customer = {
+          id: c.id,
+          name: c.name,
+          email: isOwner ? c.email : (c.email ? `${c.email.slice(0, 2)}***@${c.email.split('@')[1] || '***'}` : null),
+          mobileNumber: isOwner ? c.mobileNumber : (c.mobileNumber ? `${c.mobileNumber.slice(0, 2)}******${c.mobileNumber.slice(-2)}` : null)
+        };
+      }
+    }
+
+    res.status(200).json({
+      paymentId: session.id,
+      orderId: session.orderId,
+      amount: toRupeesString(session.amountPaise),
+      amountPaise: session.amountPaise.toString(),
+      currency: session.currency,
+      method: session.method,
+      status: session.status,
+      verificationTag: session.verificationTag,
+      isCod: session.method === 'COD',
+      customer: owner ? customer : null,
+      placedAt: session.completedAt ? (session.completedAt.toISOString ? session.completedAt.toISOString() : session.completedAt) : (session.createdAt?.toISOString ? session.createdAt.toISOString() : session.createdAt),
+      ...(owner ? { metadata: session.metadata } : {})
+    });
+  });
+}
+
+
+
+
+