Skip to content

A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.

JavaScript
47.6 KB
Raw Blame
import { test, describe, before, after } from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';
import net from 'node:net';
import { Database, MerchantRepository } from '@youpi/db';
import { startServer } from '../index.js';
import { PaymentStatus, ObserverSource, verifyHmac } from '@youpi/common';
import { authHeadersFor, merchantHeaders } from '../../../../scripts/test-support.js';

/** A port that is free right now, for a server that is started just for one test. */
function freePort() {
  return new Promise((resolve, reject) => {
    const probe = net.createServer();
    probe.unref();
    probe.on('error', reject);
    probe.listen(0, '127.0.0.1', () => {
      const { port } = probe.address();
      probe.close(() => resolve(port));
    });
  });
}

describe('Payment API End-to-End HTTP Integration Tests', () => {
  let serverInstance;
  let baseUrl;
  let testDb;
  let merchantSecret;
  let merchantWebhookUrl;
  let merchantId;

  before(async () => {
    process.env.NODE_ENV = 'test';
    process.env.YOUPI_ALLOWED_RETURN_ORIGINS = 'https://merchant.example';
    testDb = new Database({ inMemory: true });
    // Use an ephemeral random port (e.g. 0 or high port 6199) to prevent collisions
    serverInstance = await startServer(6199, testDb);
    baseUrl = `http://localhost:${serverInstance.port}`;
    // Merchant-private fields on GET /payments/:id are only returned to the owning
    // merchant, so read the seeded secret through the repository (the raw column is
    // encrypted at rest).
    const seededMerchant = new MerchantRepository(testDb).findAll()[0];
    merchantId = seededMerchant.id;
    merchantSecret = seededMerchant.webhookSecret;
    merchantWebhookUrl = seededMerchant.webhookUrl;
  });

  after(async () => {
    await serverInstance.close();
    testDb.close();
  });

  function request(path, options = {}) {
    return new Promise((resolve, reject) => {
      // `options.baseUrl` lets a test talk to a second, isolated server.
      const url = new URL(path, options.baseUrl || baseUrl);
      const reqOpts = {
        method: options.method || 'GET',
        headers: authHeadersFor(path, { ...(path.startsWith('/api/v1/payments') ? { 'X-Merchant-Id': merchantId } : {}), ...(options.headers || {}) })
      };

      const req = http.request(url, reqOpts, res => {
        let data = '';
        res.on('data', chunk => { data += chunk; });
        res.on('end', () => {
          let body;
          try {
            body = JSON.parse(data);
          } catch {
            body = data;
          }
          resolve({ status: res.statusCode, headers: res.headers, body });
        });
      });

      req.on('error', reject);

      if (options.body) {
        const payload = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
        req.setHeader('Content-Type', 'application/json');
        req.write(payload);
      }

      req.end();
    });
  }

  test('GET /health returns status UP and recovery statistics', async () => {
    const res = await request('/health');
    assert.equal(res.status, 200);
    assert.equal(res.body.status, 'UP');
    assert.equal(res.body.service, 'payment-api');
    assert.ok(res.body.recoveryStats);
  });

  test('Complete payment lifecycle: creation, queue, payment-done, observation attribution & promotion', async () => {
    // 1. Create first payment session (Customer A -> ₹200)
    const payA = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'HTTP-ORD-001',
        amount: '200.00',
        currency: 'INR',
        returnUrl: 'https://merchant.example/success',
        autoActivate: true
      }
    });

    assert.equal(payA.status, 201);
    assert.ok(payA.body.paymentId);
    assert.equal(payA.body.status, PaymentStatus.ACTIVE);
    assert.equal(payA.body.queuePosition, 0);
    assert.ok(payA.body.checkoutUrl);

    const paymentIdA = payA.body.paymentId;

    // 2. Create second payment session concurrently (Customer B -> ₹200)
    const payB = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'HTTP-ORD-002',
        amount: '200.00',
        currency: 'INR',
        autoActivate: true
      }
    });

    assert.equal(payB.status, 201);
    assert.equal(payB.body.status, PaymentStatus.QUEUED);
    assert.equal(payB.body.queuePosition, 1);

    const paymentIdB = payB.body.paymentId;

    // 3. Customer A checks checkout state
    const stateA = await request(`/api/v1/checkout/${paymentIdA}/state`);
    assert.equal(stateA.status, 200);
    assert.equal(stateA.body.status, PaymentStatus.ACTIVE);
    assert.ok(stateA.body.upiUri.startsWith('upi://pay?'));
    assert.equal(stateA.body.canClickPaymentDone, true);
    assert.ok(stateA.body.timeRemainingSeconds > 0);

    // 4. Customer A clicks "PAYMENT DONE — CHECK MY PAYMENT"
    const doneA = await request(`/api/v1/checkout/${paymentIdA}/payment-done`, {
      method: 'POST'
    });

    assert.equal(doneA.status, 200);
    assert.equal(doneA.body.status, PaymentStatus.PROCESSING);

    // 5. Observer reports incoming ₹200 UPI payment
    const obsRes = await request('/api/v1/pollers/events', {
      method: 'POST',
      body: {
        source: ObserverSource.GOOGLE_MESSAGES,
        receivingAccountId: '00000000-0000-0000-0000-000000000002',
        amount: '200.00',
        utr: 'UTR-HTTP-999',
        rawText: 'A/C 1234 credited by Rs 200.00 via UPI/UTR-HTTP-999',
        observedAt: new Date().toISOString()
      }
    });

    assert.equal(obsRes.status, 200);
    assert.equal(obsRes.body.attribution.attributed, true);
    assert.equal(obsRes.body.attribution.outcomeStatus, PaymentStatus.OBSERVED_SUCCESS);
    assert.equal(obsRes.body.attribution.paymentSessionId, paymentIdA);

    // 6. Verify Payment A is observed, not bank-reconciled, via public API
    const verifyA = await request(`/api/v1/payments/${paymentIdA}`);
    assert.equal(verifyA.status, 200);
    assert.equal(verifyA.body.status, 'OBSERVED_SUCCESS');
    assert.equal(verifyA.body.settlementState, 'NOT_RECONCILED');
    assert.ok(verifyA.body.completedAt);

    // 7. Verify Payment B has been automatically promoted to ACTIVE in the queue!
    const stateB = await request(`/api/v1/checkout/${paymentIdB}/state`);
    assert.equal(stateB.status, 200);
    assert.equal(stateB.body.status, PaymentStatus.ACTIVE);
    assert.equal(stateB.body.queuePosition, 0);
    assert.ok(stateB.body.upiUri);
  });

  test('Customer registration, login, and decommissioned customer ticket routes', async () => {
    // 1. Customer registration
    const regRes = await request('/api/v1/customer/register', {
      method: 'POST',
      body: {
        phoneNumber: '9988776655',
        fullName: 'Rohit Verma',
        password: 'Password123!'
      }
    });
    assert.equal(regRes.status, 201);
    assert.ok(regRes.body.customerId);

    const customerId = regRes.body.customerId;

    // 2. Customer login
    const loginRes = await request('/api/v1/customer/login', {
      method: 'POST',
      body: {
        phoneNumber: '9988776655',
        password: 'Password123!'
      }
    });
    assert.equal(loginRes.status, 200);
    assert.ok(loginRes.body.token);

    // 3. Customer support ticket endpoints are decommissioned (return 404)
    const ticketRes = await request('/api/v1/customer/tickets', {
      method: 'POST',
      body: {
        customerId,
        subject: 'Need help with UPI payment',
        message: 'My app closed while paying.'
      }
    });
    assert.equal(ticketRes.status, 404);
    assert.equal(ticketRes.body.error, 'Feature not available');

    const msgRes = await request('/api/v1/customer/tickets/ticket_1/messages', {
      method: 'POST',
      body: {
        senderType: 'CUSTOMER',
        senderId: customerId,
        message: 'Hello'
      }
    });
    assert.equal(msgRes.status, 404);
    assert.equal(msgRes.body.error, 'Feature not available');
  });

  test('Counter manual payment confirmation flow', async () => {
    // Create payment session for Cash at Counter
    const payCounter = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'COUNTER-ORD-777',
        amount: '150.00',
        method: 'CASH_COUNTER'
      }
    });
    assert.equal(payCounter.status, 201);
    const paymentId = payCounter.body.paymentId;

    // Operator confirms cash received at physical counter
    const confirmRes = await request('/api/v1/admin/counter-confirm', {
      method: 'POST',
      body: {
        paymentId,
        operatorId: 'operator_desk_1',
        method: 'CASH_COUNTER'
      }
    });

    assert.equal(confirmRes.status, 200);
    assert.equal(confirmRes.body.confirmed, true);
    assert.equal(confirmRes.body.status, PaymentStatus.SUCCESS);

    const check = await request(`/api/v1/payments/${paymentId}`);
    assert.equal(check.body.status, 'SUCCESS');
  });

  test('Custom UPI ID persistence & dynamic QR injection', async () => {
    // Free slot from earlier test runs so session becomes ACTIVE
    const prevActive = serverInstance.app.context.sessionRepo.findCurrentActiveOrProcessing('00000000-0000-0000-0000-000000000002');
    if (prevActive) {
      serverInstance.app.context.sessionRepo.transitionToTerminal(prevActive.id, PaymentStatus.CANCELLED);
    }

    // 1. Update merchant receiving UPI VPA
    const upiUpdateRes = await request('/api/v1/admin/upi-settings', {
      method: 'POST',
      body: {
        upiId: 'customstore@okhdfcbank',
        payeeName: 'Custom Store India'
      }
    });

    assert.equal(upiUpdateRes.status, 200);
    assert.equal(upiUpdateRes.body.success, true);
    assert.equal(upiUpdateRes.body.receivingAccount.upiId, 'customstore@okhdfcbank');

    // 2. Create a new payment session
    const payRes = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'CUSTOM-UPI-ORD-1',
        amount: '350.00',
        autoActivate: true
      }
    });

    assert.equal(payRes.status, 201);
    const paymentId = payRes.body.paymentId;

    // 3. Verify state generates UPI URI with the new custom VPA
    const stateRes = await request(`/api/v1/checkout/${paymentId}/state`);
    assert.equal(stateRes.status, 200);
    assert.equal(stateRes.body.payeeVpa, 'customstore@okhdfcbank');
    assert.ok(stateRes.body.upiUri.includes('customstore%40okhdfcbank') || stateRes.body.upiUri.includes('customstore@okhdfcbank'));
  });

  test('Payment method toggles and white-label branding persistence', async () => {
    // 1. Merchant disables CASH_COUNTER and customizes all white-label branding elements
    const settingsRes = await request('/api/v1/admin/merchant-settings', {
      method: 'POST',
      body: {
        businessName: 'Astra Superstore',
        enabledPaymentMethods: ['UPI', 'CARD_COUNTER'],
        branding: {
          appName: 'AstraPay',
          primaryColor: '#7c3aed',
          logoUrl: 'https://cdn.example.com/astra-logo.png',
          sidebarNotice: 'Exclusive AstraPay UPI Partner',
          checkoutNotice: 'Flat 10% instant rebate on UPI',
          footerGuarantee: 'Protected by 256-Bit AstraShield'
        }
      }
    });

    assert.equal(settingsRes.status, 200);
    assert.equal(settingsRes.body.businessName, 'Astra Superstore');
    assert.deepEqual(settingsRes.body.branding.enabledPaymentMethods, ['UPI', 'CARD_COUNTER']);
    assert.equal(settingsRes.body.branding.logoUrl, 'https://cdn.example.com/astra-logo.png');
    assert.equal(settingsRes.body.branding.sidebarNotice, 'Exclusive AstraPay UPI Partner');

    // 2. Create payment and inspect checkout state
    const payRes = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'BRANDED-ORD-9',
        amount: '199.00',
        autoActivate: true
      }
    });

    const stateRes = await request(`/api/v1/checkout/${payRes.body.paymentId}/state`);
    assert.equal(stateRes.status, 200);
    assert.equal(stateRes.body.merchantName, 'Astra Superstore');
    assert.equal(stateRes.body.branding.appName, 'AstraPay');
    assert.equal(stateRes.body.branding.primaryColor, '#7c3aed');
    assert.equal(stateRes.body.branding.logoUrl, 'https://cdn.example.com/astra-logo.png');
    assert.equal(stateRes.body.branding.sidebarNotice, 'Exclusive AstraPay UPI Partner');
    assert.equal(stateRes.body.branding.checkoutNotice, 'Flat 10% instant rebate on UPI');
    assert.equal(stateRes.body.branding.footerGuarantee, 'Protected by 256-Bit AstraShield');
    assert.deepEqual(stateRes.body.enabledMethods, ['UPI', 'CARD_COUNTER']);
    assert.equal(stateRes.body.enabledMethods.includes('CASH_COUNTER'), false);
  });

  test('Customer auth binding and trigger-hook dispatch', async () => {
    // 1. Create a customer
    const regRes = await request('/api/v1/customer/register', {
      method: 'POST',
      body: {
        phoneNumber: '9111222333',
        fullName: 'Astra VIP',
        password: 'Password123!'
      }
    });
    assert.equal(regRes.status, 201);
    const customerId = regRes.body.customerId;

    // 2. Create a payment
    const payRes = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'AUTH-ORD-99',
        amount: '89.00'
      }
    });
    const paymentId = payRes.body.paymentId;

    // 3. Bind customer to payment session
    const bindRes = await request(`/api/v1/checkout/${paymentId}/bind-customer`, {
      method: 'POST',
      body: { customerId, token: regRes.body.token }
    });
    assert.equal(bindRes.status, 200);
    assert.equal(bindRes.body.success, true);
    assert.equal(bindRes.body.customer.phoneNumber, '9111222333');

    // 4. Inspect state: the customer is attached, but their contact details are NOT
    //    disclosed to an anonymous caller that only holds the payment id.
    const stateRes = await request(`/api/v1/checkout/${paymentId}/state`);
    assert.equal(stateRes.body.customer, null);

    // The customer themselves, presenting their own session token, do see their profile.
    const selfState = await request(`/api/v1/checkout/${paymentId}/state`, {
      headers: { 'x-customer-token': regRes.body.token }
    });
    assert.equal(selfState.body.customer.phoneNumber, '9111222333');

    // The owning merchant, presenting its secret, sees the customer too.
    const ownerState = await request(`/api/v1/checkout/${paymentId}/state`, {
      headers: { 'X-Merchant-Key': merchantSecret }
    });
    assert.equal(ownerState.body.customer.phoneNumber, '9111222333');

    // 5. Test action trigger hook (rejects unauthenticated requests, succeeds with customer token)
    const unauthHookRes = await request(`/api/v1/checkout/${paymentId}/trigger-hook`, {
      method: 'POST',
      body: {
        action: 'CANCEL_CLICKED',
        details: { reason: 'changed_mind' }
      }
    });
    assert.equal(unauthHookRes.status, 401);
    assert.equal(unauthHookRes.body.code, 'CUSTOMER_SESSION_REQUIRED');

    const hookRes = await request(`/api/v1/checkout/${paymentId}/trigger-hook`, {
      method: 'POST',
      headers: { 'x-customer-token': regRes.body.token },
      body: {
        action: 'CANCEL_CLICKED',
        details: { reason: 'changed_mind' }
      }
    });
    assert.equal(hookRes.status, 200);
    assert.equal(hookRes.body.success, true);
    assert.equal(hookRes.body.action, 'CANCEL_CLICKED');
  });

  test('Payment timer does not start until customer logs in or signs up', async () => {
    // Ensure slot and all queued sessions on this receiving account are cleanly reset
    testDb.execute(`
      UPDATE payment_sessions
      SET status = 'CANCELLED'
      WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING', 'QUEUED')
    `, ['00000000-0000-0000-0000-000000000002']);
    testDb.execute(`
      UPDATE payment_receiving_accounts
      SET is_slot_busy = 0, current_active_session_id = NULL
      WHERE id = ?
    `, ['00000000-0000-0000-0000-000000000002']);

    // 1. Create a payment without pre-authenticated customer
    const createRes = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'DEFERRED-TIMER-ORD-1',
        amount: '500.00'
      }
    });

    assert.equal(createRes.status, 201);
    assert.equal(createRes.body.status, 'INITIATED');
    const paymentId = createRes.body.paymentId;

    // 2. Inspect state: timer MUST NOT be running while user is unauthenticated
    const stateBeforeAuth = await request(`/api/v1/checkout/${paymentId}/state`);
    assert.equal(stateBeforeAuth.status, 200);
    assert.equal(stateBeforeAuth.body.status, 'INITIATED');
    assert.equal(stateBeforeAuth.body.timeRemainingSeconds, 0); // Timer is paused!
    assert.equal(stateBeforeAuth.body.canClickPaymentDone, false);

    // 3. User registers or signs in
    const regRes = await request('/api/v1/customer/register', {
      method: 'POST',
      body: {
        phoneNumber: '9444555666',
        fullName: 'Deferred User',
        password: 'Password123!'
      }
    });
    const customerId = regRes.body.customerId;

    // 4. User logs in and binds customer to payment session
    const bindRes = await request(`/api/v1/checkout/${paymentId}/bind-customer`, {
      method: 'POST',
      body: { customerId, token: regRes.body.token }
    });

    assert.equal(bindRes.status, 200);
    assert.equal(bindRes.body.status, 'ACTIVE');
    assert.ok(bindRes.body.expiresAt);

    // 5. Inspect state: 5-minute timer is NOW active and counting down!
    const stateAfterAuth = await request(`/api/v1/checkout/${paymentId}/state`);
    assert.equal(stateAfterAuth.body.status, 'ACTIVE');
    assert.ok(stateAfterAuth.body.timeRemainingSeconds > 280); // Full 5 minutes started only now!
    assert.equal(stateAfterAuth.body.canClickPaymentDone, true);
  });

  test('Queue Sync Invariant: When Session A expires, queued Session B is immediately promoted to ACTIVE with armed timer', async () => {
    // Ensure slot and queue are clean
    testDb.execute(`
      UPDATE payment_sessions
      SET status = 'CANCELLED'
      WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING', 'QUEUED')
    `, ['00000000-0000-0000-0000-000000000002']);
    testDb.execute(`
      UPDATE payment_receiving_accounts
      SET is_slot_busy = 0, current_active_session_id = NULL
      WHERE id = ?
    `, ['00000000-0000-0000-0000-000000000002']);

    // 1. Session A is ACTIVE
    const payA = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'QUEUE-SYNC-A',
        amount: '200.00',
        autoActivate: true
      }
    });
    assert.equal(payA.body.status, PaymentStatus.ACTIVE);
    assert.equal(payA.body.queuePosition, 0);

    // 2. Session B is created and placed in QUEUED
    const payB = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'QUEUE-SYNC-B',
        amount: '200.00',
        autoActivate: true
      }
    });
    assert.equal(payB.body.status, PaymentStatus.QUEUED);
    assert.equal(payB.body.queuePosition, 1);

    // 3. User A expires (via client expiry trigger / endpoint)
    const expireRes = await request(`/api/v1/checkout/${payA.body.paymentId}/expire`, {
      method: 'POST'
    });
    assert.equal(expireRes.status, 200);

    // Verify Session A is EXPIRED
    const checkA = await request(`/api/v1/payments/${payA.body.paymentId}`);
    assert.equal(checkA.body.status, 'EXPIRED');

    // 4. Session B MUST now be ACTIVE!
    const checkB = await request(`/api/v1/checkout/${payB.body.paymentId}/state`);
    assert.equal(checkB.body.status, PaymentStatus.ACTIVE);
    assert.equal(checkB.body.queuePosition, 0);
    assert.ok(checkB.body.timeRemainingSeconds > 280); // Timer started!
    assert.ok(checkB.body.upiUri); // QR code generated!
  });

  test('2-Level Payment Verification Engine: Upgrades verification tier from L1 (SMS) to L2 (Dual: SMS + Gmail)', async () => {
    // Ensure slot and queue are clean
    testDb.execute(`
      UPDATE payment_sessions
      SET status = 'CANCELLED'
      WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING', 'QUEUED')
    `, ['00000000-0000-0000-0000-000000000002']);
    testDb.execute(`
      UPDATE payment_receiving_accounts
      SET is_slot_busy = 0, current_active_session_id = NULL
      WHERE id = ?
    `, ['00000000-0000-0000-0000-000000000002']);

    // 1. Create a payment session for ₹650.00
    const payRes = await request('/api/v1/payments', {
      method: 'POST',
      body: {
        orderId: 'VERIFY-TIER-ORD-1',
        amount: '650.00',
        autoActivate: true
      }
    });
    const paymentId = payRes.body.paymentId;

    // 2. Customer clicks Payment Done -> moves to PROCESSING
    await request(`/api/v1/checkout/${paymentId}/payment-done`, { method: 'POST' });

    // 3. Observation 1: Google Messages SMS arrives -> Level 1 (L1 Single Verification)
    const obs1 = await request('/api/v1/pollers/events', {
      method: 'POST',
      body: {
        source: 'GOOGLE_MESSAGES',
        receivingAccountId: '00000000-0000-0000-0000-000000000002',
        amount: '650.00',
        utr: 'UTR-TIER-001',
        rawText: 'A/C 1234 credited by Rs 650.00 via UPI/UTR-TIER-001',
        observedAt: new Date().toISOString()
      }
    });

    assert.equal(obs1.status, 200);
    assert.equal(obs1.body.attribution.attributed, true);
    assert.equal(obs1.body.attribution.verificationLevel, 1);
    assert.ok(obs1.body.attribution.verificationTag.includes('Single Verification') || obs1.body.attribution.verificationTag.includes('SMS'));

    // Check payment status: must be SUCCESS with Level 1
    const checkL1 = await request(`/api/v1/payments/${paymentId}`, { headers: merchantHeaders(merchantSecret) });
    assert.equal(checkL1.body.status, 'OBSERVED_SUCCESS');
    assert.equal(checkL1.body.settlementState, 'NOT_RECONCILED');
    assert.equal(checkL1.body.verificationLevel, 1);
    assert.deepEqual(checkL1.body.verificationSources, ['GOOGLE_MESSAGES']);

    // 4. Observation 2: Gmail arrives 2 seconds later -> Upgrades to Level 2 (Dual Verification: SMS + Gmail)
    const obs2 = await request('/api/v1/pollers/events', {
      method: 'POST',
      body: {
        source: 'GMAIL',
        receivingAccountId: '00000000-0000-0000-0000-000000000002',
        amount: '650.00',
        utr: 'UTR-TIER-001',
        rawText: 'Dear Customer, INR 650.00 credited to your account via UPI/UTR-TIER-001',
        observedAt: new Date().toISOString()
      }
    });

    assert.equal(obs2.status, 200);
    assert.equal(obs2.body.attribution.verificationLevel, 2);
    assert.ok(obs2.body.attribution.verificationTag.includes('Dual Verification'));

    const checkL2 = await request(`/api/v1/payments/${paymentId}`, { headers: merchantHeaders(merchantSecret) });
    assert.equal(checkL2.body.verificationLevel, 2);
    assert.ok(checkL2.body.verificationSources.includes('GOOGLE_MESSAGES'));
    assert.ok(checkL2.body.verificationSources.includes('GMAIL'));

    // Final verification from Admin API: Level 2 Dual Standard
    const adminCheck = await request('/api/v1/admin/payments');
    const pRecord = adminCheck.body.payments.find(p => p.id === paymentId);
    assert.ok(pRecord);
    assert.equal(pRecord.verificationLevel, 2);
    assert.equal(pRecord.verificationSources.length, 2);
  });

  test('Merchant webhook URL & secret persistence and HMAC-SHA256 signed event delivery', async () => {
    // 1. Start an ephemeral mock webhook receiver
    let receivedPayload = null;
    let receivedHeaders = null;
    let webhookResolve;
    const webhookReceivedPromise = new Promise(resolve => {
      webhookResolve = resolve;
    });

    const mockReceiver = http.createServer((req, res) => {
      let body = '';
      req.on('data', chunk => { body += chunk; });
      req.on('end', () => {
        receivedHeaders = req.headers;
        receivedPayload = body;
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ received: true }));
        webhookResolve();
      });
    });

    await new Promise(resolve => mockReceiver.listen(0, resolve));
    const receiverPort = mockReceiver.address().port;
    const receiverUrl = `http://localhost:${receiverPort}/api/webhook`;

    try {
      // 2. Persist custom webhook URL and secret via admin API
      const customSecret = 'sec_wh_supersecret_key_778899';
      const updateRes = await request('/api/v1/admin/merchant-settings', {
        method: 'POST',
        body: {
          webhookUrl: receiverUrl,
          webhookSecret: customSecret
        }
      });

      assert.equal(updateRes.status, 200);
      assert.equal(updateRes.body.webhookUrl, receiverUrl);
      assert.equal(updateRes.body.webhookSecret, customSecret);

      // 3. Read back via GET /api/v1/admin/merchant-settings
      const getMerchantRes = await request('/api/v1/admin/merchant-settings');
      assert.equal(getMerchantRes.status, 200);
      assert.equal(getMerchantRes.body.webhookUrl, receiverUrl);
      assert.equal(getMerchantRes.body.webhookSecret, customSecret);

      // 4. Also read back via GET /api/v1/admin/all-settings
      const getAllRes = await request('/api/v1/admin/all-settings');
      assert.equal(getAllRes.status, 200);
      assert.equal(getAllRes.body.webhookUrl, receiverUrl);
      assert.equal(getAllRes.body.webhookSecret, customSecret);

      // 5. Create a payment session
      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'WEBHOOK-TEST-ORD-1',
          amount: '450.00',
          method: 'CASH_COUNTER'
        }
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;

      // 6. Complete payment via counter confirmation to trigger PAYMENT.SUCCESS
      const confirmRes = await request('/api/v1/admin/counter-confirm', {
        method: 'POST',
        body: {
          paymentId,
          operatorId: 'admin_wh_tester'
        }
      });
      assert.equal(confirmRes.status, 200);
      assert.equal(confirmRes.body.confirmed, true);

      // 7. Wait for webhook delivery to arrive at mockReceiver
      await Promise.race([
        webhookReceivedPromise,
        new Promise((_, reject) => setTimeout(() => reject(new Error('Webhook delivery timed out')), 5000))
      ]);

      assert.ok(receivedPayload);
      assert.ok(receivedHeaders);

      // 8. Verify delivery headers
      assert.equal(receivedHeaders['x-gateway-event'], 'SUCCESS');
      assert.ok(receivedHeaders['x-gateway-signature'].startsWith('sha256='));
      assert.ok(receivedHeaders['x-gateway-delivery-id']);
      assert.ok(receivedHeaders['x-gateway-timestamp']);

      // 9. Verify payload contents
      const parsedBody = JSON.parse(receivedPayload);
      assert.equal(parsedBody.event, 'SUCCESS');
      assert.equal(parsedBody.paymentId, paymentId);
      assert.equal(parsedBody.orderId, 'WEBHOOK-TEST-ORD-1');
      assert.equal(parsedBody.amount, '450.00');

      // 10. Cryptographically verify signature using the custom secret
      const sig = receivedHeaders['x-gateway-signature'].replace('sha256=', '');
      const validSig = verifyHmac(receivedPayload, customSecret, sig);
      assert.equal(validSig, true);

      // Verify wrong secret fails
      const invalidSig = verifyHmac(receivedPayload, 'wrong_secret_123', sig);
      assert.equal(invalidSig, false);

      // 11. Test non-destructive update: update only businessName and verify webhook config is preserved!
      const partialUpdate = await request('/api/v1/admin/merchant-settings', {
        method: 'POST',
        body: {
          businessName: 'Preserved Store LLC'
        }
      });
      assert.equal(partialUpdate.status, 200);
      assert.equal(partialUpdate.body.businessName, 'Preserved Store LLC');
      assert.equal(partialUpdate.body.webhookUrl, receiverUrl);
      assert.equal(partialUpdate.body.webhookSecret, customSecret);

    } finally {
      await new Promise(cb => mockReceiver.close(cb));
    }
  });

  test('A delivery that failed is sent again by the retry daemon', async () => {
    // The engine knows how to send a failed delivery again — it re-signs the
    // stored payload and sends it with the same delivery id. But knowing how
    // is not the same as doing it: the retry has to be *scheduled* by
    // something, and until the daemon existed nothing scheduled it. A
    // merchant whose server was restarting at the moment of the event simply
    // never heard about the payment.
    //
    // This is the test for the daemon: the first delivery fails, the second
    // one succeeds, and nothing but the daemon sends the second one.
    //
    // It runs on its own server, with its own database and a shortened daemon
    // tick, so that the suite's shared server keeps the production default.
    // A one-second tick on the shared server competes with the timing
    // sensitive tests for the same event loop and the same SQLite connection.
    const attempts = [];
    let firstAttemptResolve;
    const firstAttemptPromise = new Promise(resolve => { firstAttemptResolve = resolve; });

    const mockReceiver = http.createServer((req, res) => {
      let body = '';
      req.on('data', chunk => { body += chunk; });
      req.on('end', () => {
        attempts.push({ headers: req.headers, body });
        if (attempts.length === 1) {
          // The merchant's server is not up yet.
          res.writeHead(500, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify({ error: 'not ready' }));
          firstAttemptResolve();
          return;
        }
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ received: true }));
      });
    });

    await new Promise(resolve => mockReceiver.listen(0, resolve));
    const receiverPort = mockReceiver.address().port;
    const receiverUrl = `http://localhost:${receiverPort}/api/webhook`;
    const customSecret = 'sec_wh_retry_test_key_9911';

    const retryDb = new Database({ inMemory: true });
    const previousInterval = process.env.WEBHOOK_RETRY_INTERVAL_MS;
    // The daemon is created when the server starts, so the tick has to be set
    // before startServer() — and put back afterwards.
    process.env.WEBHOOK_RETRY_INTERVAL_MS = '1000';
    let retryServer = null;

    try {
      const retryPort = await freePort();
      retryServer = await startServer(retryPort, retryDb);
      const retryBase = `http://localhost:${retryServer.port}`;

      const updateRes = await request('/api/v1/admin/merchant-settings', {
        method: 'POST',
        body: { webhookUrl: receiverUrl, webhookSecret: customSecret },
        baseUrl: retryBase
      });
      assert.equal(updateRes.status, 200);

      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: { orderId: 'WEBHOOK-RETRY-ORD-1', amount: '75.00', method: 'CASH_COUNTER' },
        baseUrl: retryBase
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;

      const confirmRes = await request('/api/v1/admin/counter-confirm', {
        method: 'POST',
        body: { paymentId, operatorId: 'admin_wh_retry_tester' },
        baseUrl: retryBase
      });
      assert.equal(confirmRes.status, 200);

      // The first delivery reaches the receiver and is refused.
      await Promise.race([
        firstAttemptPromise,
        new Promise((_, reject) => setTimeout(() => reject(new Error('The first delivery never arrived')), 5000))
      ]);
      assert.equal(attempts.length, 1);

      // The engine records a write-ahead row before the request and updates
      // attempt_count >= 1 once the response has come back, so wait until
      // the first attempt has finalized.
      let failedRow = null;
      const rowDeadline = Date.now() + 5000;
      while (Date.now() < rowDeadline) {
        failedRow = retryDb.queryOne(
          'SELECT id, attempt_count, is_successful, next_retry_at FROM webhook_deliveries WHERE payment_id = ?',
          [paymentId]
        );
        if (failedRow && failedRow.attempt_count >= 1) break;
        await new Promise(resolve => setTimeout(resolve, 50));
      }
      assert.ok(failedRow, 'the failed delivery was not recorded');
      assert.equal(failedRow.is_successful, 0);
      assert.equal(failedRow.attempt_count, 1);
      assert.ok(failedRow.next_retry_at, 'a failed delivery must be scheduled for a retry');

      // Make it due now. The backoff is the engine's business, and waiting it
      // out would make this test take half a minute for no extra confidence.
      retryDb.execute(
        'UPDATE webhook_deliveries SET next_retry_at = ? WHERE id = ?',
        [new Date(Date.now() - 1000).toISOString(), failedRow.id]
      );

      // The daemon sends it again, on its own.
      const retryDeadline = Date.now() + 10000;
      while (Date.now() < retryDeadline && attempts.length < 2) {
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      assert.equal(attempts.length, 2, 'the failed delivery was never retried');

      // The retry is the *same* delivery: same id, same signed payload.
      assert.equal(attempts[1].headers['x-gateway-delivery-id'], attempts[0].headers['x-gateway-delivery-id']);
      assert.equal(attempts[1].body, attempts[0].body);
      assert.equal(
        attempts[1].headers['x-gateway-signature'],
        attempts[0].headers['x-gateway-signature'],
        'the stored payload is re-signed, not re-built'
      );

      let settledRow = null;
      const settleDeadline = Date.now() + 3000;
      while (Date.now() < settleDeadline) {
        settledRow = retryDb.queryOne(
          'SELECT attempt_count, is_successful, response_status FROM webhook_deliveries WHERE id = ?',
          [failedRow.id]
        );
        if (settledRow && settledRow.attempt_count === 2 && settledRow.is_successful === 1) break;
        await new Promise(resolve => setTimeout(resolve, 50));
      }
      assert.equal(settledRow?.attempt_count, 2);
      assert.equal(settledRow?.is_successful, 1);
      assert.equal(settledRow?.response_status, 200);
    } finally {
      if (retryServer) await retryServer.close();
      retryDb.close();
      if (previousInterval === undefined) {
        delete process.env.WEBHOOK_RETRY_INTERVAL_MS;
      } else {
        process.env.WEBHOOK_RETRY_INTERVAL_MS = previousInterval;
      }
      await new Promise(cb => mockReceiver.close(cb));
    }
  });

  test('Auto-detection in ACTIVE state without Payment Done click: immediate SUCCESS, L1 to L2 upgrade, exactly 1 webhook', async () => {
    // 1. Clean slot and queue
    testDb.execute(`
      UPDATE payment_sessions
      SET status = 'CANCELLED'
      WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING', 'QUEUED')
    `, ['00000000-0000-0000-0000-000000000002']);
    testDb.execute(`
      UPDATE payment_receiving_accounts
      SET is_slot_busy = 0, current_active_session_id = NULL
      WHERE id = ?
    `, ['00000000-0000-0000-0000-000000000002']);

    // 2. Setup mock receiver tracking webhook count
    let webhookDeliveries = [];
    const mockReceiver = http.createServer((req, res) => {
      let body = '';
      req.on('data', chunk => { body += chunk; });
      req.on('end', () => {
        webhookDeliveries.push({ headers: req.headers, body: JSON.parse(body || '{}') });
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ received: true }));
      });
    });

    await new Promise(resolve => mockReceiver.listen(0, resolve));
    const receiverPort = mockReceiver.address().port;
    const receiverUrl = `http://localhost:${receiverPort}/autodetect-webhook`;

    try {
      // 3. Configure webhook URL
      await request('/api/v1/admin/merchant-settings', {
        method: 'POST',
        body: {
          webhookUrl: receiverUrl,
          webhookSecret: 'secret_autodetect_test_9988'
        }
      });
      // This test rotates the merchant secret; re-read so merchant-scoped reads still pass.
      merchantSecret = new MerchantRepository(testDb).findAll()[0].webhookSecret;

      // 4. Create payment session in ACTIVE state (customer scanning QR, did NOT click Payment Done)
      const payRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'AUTODETECT-ORD-777',
          amount: '320.00',
          autoActivate: true
        }
      });
      assert.equal(payRes.status, 201);
      assert.equal(payRes.body.status, PaymentStatus.ACTIVE);
      const paymentId = payRes.body.paymentId;

      // Ensure customer is in ACTIVE state, not PROCESSING
      const checkBefore = await request(`/api/v1/payments/${paymentId}`);
      assert.equal(checkBefore.body.status, PaymentStatus.ACTIVE);

      // 5. Channel 1: Google Messages SMS arrives while user is on QR screen (NO manual button click!)
      const obs1 = await request('/api/v1/pollers/events', {
        method: 'POST',
        body: {
          source: 'GOOGLE_MESSAGES',
          receivingAccountId: '00000000-0000-0000-0000-000000000002',
          amount: '320.00',
          utr: 'UTR-NOCLICK-999',
          rawText: 'A/C 1234 credited by Rs 320.00 via UPI/UTR-NOCLICK-999',
          observedAt: new Date().toISOString()
        }
      });
      assert.equal(obs1.status, 200);
      assert.equal(obs1.body.attribution.attributed, true);
      assert.equal(obs1.body.attribution.verificationLevel, 1);

      // Payment MUST be immediately SUCCESS for customer
      const checkAfterObs1 = await request(`/api/v1/payments/${paymentId}`, { headers: merchantHeaders(merchantSecret) });
      assert.equal(checkAfterObs1.body.status, 'OBSERVED_SUCCESS');
      assert.equal(checkAfterObs1.body.verificationLevel, 1);

      // Checkout state MUST reflect SUCCESS immediately
      const stateAfterObs1 = await request(`/api/v1/checkout/${paymentId}/state`);
      assert.equal(stateAfterObs1.body.status, 'OBSERVED_SUCCESS');

      // Wait 150ms for webhook dispatch
      await new Promise(r => setTimeout(r, 150));
      assert.equal(webhookDeliveries.length, 1);
      assert.equal(webhookDeliveries[0].body.event, 'OBSERVED_SUCCESS');
      assert.equal(webhookDeliveries[0].body.settlementState, 'NOT_RECONCILED');
      assert.equal(webhookDeliveries[0].body.orderId, 'AUTODETECT-ORD-777');
      assert.equal(webhookDeliveries[0].body.amount, '320.00');

      // 6. Channel 2: Gmail credit notification arrives 500ms later during verification sweep
      const obs2 = await request('/api/v1/pollers/events', {
        method: 'POST',
        body: {
          source: 'GMAIL',
          receivingAccountId: '00000000-0000-0000-0000-000000000002',
          amount: '320.00',
          utr: 'UTR-NOCLICK-999',
          rawText: 'Dear Customer, INR 320.00 credited to your account via UPI/UTR-NOCLICK-999',
          observedAt: new Date().toISOString()
        }
      });
      assert.equal(obs2.status, 200);
      assert.equal(obs2.body.attribution.verificationLevel, 2);

      // Invariant: Verification level in admin upgrades to L2 (Dual Verification)
      const checkAfterObs2 = await request(`/api/v1/payments/${paymentId}`, { headers: merchantHeaders(merchantSecret) });
      assert.equal(checkAfterObs2.body.verificationLevel, 2);
      assert.deepEqual(checkAfterObs2.body.verificationSources.sort(), ['GMAIL', 'GOOGLE_MESSAGES'].sort());

      // Invariant: Second observation MUST NOT trigger duplicate webhook delivery!
      await new Promise(r => setTimeout(r, 150));
      assert.equal(webhookDeliveries.length, 1); // Exactly 1 delivery!

    } finally {
      await new Promise(cb => mockReceiver.close(cb));
    }
  });

  describe('Terminal Payment State HTTP Route Protections (Issue #4)', () => {
    test('POST /api/v1/checkout/:id/retry-new-payment rejects terminal sessions with HTTP 400', async () => {
      const prevActive = serverInstance.app.context.sessionRepo.findCurrentActiveOrProcessing('00000000-0000-0000-0000-000000000002');
      if (prevActive) {
        const terminalStatus = prevActive.status === PaymentStatus.PROCESSING ? PaymentStatus.FAILED : PaymentStatus.CANCELLED;
        serverInstance.app.context.sessionRepo.transitionToTerminal(prevActive.id, terminalStatus);
      }

      // Create and cancel a payment session
      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'ORD-RETRY-TERM',
          amount: '150.00',
          currency: 'INR',
          autoActivate: true
        }
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;

      // Cancel the session
      const cancelRes = await request(`/api/v1/checkout/${paymentId}/cancel`, {
        method: 'POST'
      });
      assert.equal(cancelRes.status, 200);

      // Attempt retry-new-payment on the cancelled session
      const retryRes = await request(`/api/v1/checkout/${paymentId}/retry-new-payment`, {
        method: 'POST'
      });
      assert.equal(retryRes.status, 400);
      assert.ok(retryRes.body.error.includes('Cannot retry payment for terminal session'));
    });

    test('POST /api/v1/checkout/:id/select-method rejects PROCESSING sessions with HTTP 400', async () => {
      const prevActive = serverInstance.app.context.sessionRepo.findCurrentActiveOrProcessing('00000000-0000-0000-0000-000000000002');
      if (prevActive) {
        const terminalStatus = prevActive.status === PaymentStatus.PROCESSING ? PaymentStatus.FAILED : PaymentStatus.CANCELLED;
        serverInstance.app.context.sessionRepo.transitionToTerminal(prevActive.id, terminalStatus);
      }

      // Create and activate a payment session
      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'ORD-METHOD-PROC',
          amount: '180.00',
          currency: 'INR',
          autoActivate: true
        }
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;
      assert.equal(createRes.body.status, PaymentStatus.ACTIVE);

      // Move to PROCESSING via payment-done
      const doneRes = await request(`/api/v1/checkout/${paymentId}/payment-done`, {
        method: 'POST'
      });
      assert.equal(doneRes.status, 200);
      assert.equal(doneRes.body.status, PaymentStatus.PROCESSING);

      // Attempt select-method on the processing session
      const switchRes = await request(`/api/v1/checkout/${paymentId}/select-method`, {
        method: 'POST',
        body: { method: 'COD' }
      });
      assert.equal(switchRes.status, 400);
      assert.ok(switchRes.body.error.includes('Cannot switch payment method while payment is in PROCESSING status'));
    });

    test('POST /api/v1/checkout/:id/confirm-cod rejects PROCESSING sessions with HTTP 400', async () => {
      const prevActive = serverInstance.app.context.sessionRepo.findCurrentActiveOrProcessing('00000000-0000-0000-0000-000000000002');
      if (prevActive) {
        const terminalStatus = prevActive.status === PaymentStatus.PROCESSING ? PaymentStatus.FAILED : PaymentStatus.CANCELLED;
        serverInstance.app.context.sessionRepo.transitionToTerminal(prevActive.id, terminalStatus);
      }

      // Create and activate a payment session
      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'ORD-COD-PROC',
          amount: '220.00',
          currency: 'INR',
          autoActivate: true
        }
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;
      assert.equal(createRes.body.status, PaymentStatus.ACTIVE);

      // Move to PROCESSING
      const doneRes = await request(`/api/v1/checkout/${paymentId}/payment-done`, {
        method: 'POST'
      });
      assert.equal(doneRes.status, 200);
      assert.equal(doneRes.body.status, PaymentStatus.PROCESSING);

      // Attempt confirm-cod on processing session
      const codRes = await request(`/api/v1/checkout/${paymentId}/confirm-cod`, {
        method: 'POST'
      });
      assert.equal(codRes.status, 400);
      assert.ok(codRes.body.error.includes('Cannot place COD order while payment is in PROCESSING status'));
    });

    test('POST /api/v1/checkout/:id/confirm-cod rejects terminal sessions with HTTP 400', async () => {
      const prevActive = serverInstance.app.context.sessionRepo.findCurrentActiveOrProcessing('00000000-0000-0000-0000-000000000002');
      if (prevActive) {
        const terminalStatus = prevActive.status === PaymentStatus.PROCESSING ? PaymentStatus.FAILED : PaymentStatus.CANCELLED;
        serverInstance.app.context.sessionRepo.transitionToTerminal(prevActive.id, terminalStatus);
      }

      const createRes = await request('/api/v1/payments', {
        method: 'POST',
        body: {
          orderId: 'ORD-COD-TERM',
          amount: '250.00',
          currency: 'INR',
          autoActivate: true
        }
      });
      assert.equal(createRes.status, 201);
      const paymentId = createRes.body.paymentId;

      // Cancel the session
      await request(`/api/v1/checkout/${paymentId}/cancel`, {
        method: 'POST'
      });


      // Attempt confirm-cod on cancelled session
      const codRes = await request(`/api/v1/checkout/${paymentId}/cancel`, {
        method: 'POST'
      });
      const codAfterCancel = await request(`/api/v1/checkout/${paymentId}/confirm-cod`, {
        method: 'POST'
      });
      assert.equal(codAfterCancel.status, 400);
      assert.ok(codAfterCancel.body.error.includes('Cannot place COD order for terminal session'));
    });

    test('Merchant API key rotation requires X-Merchant-Key and rejects public-key/placeholder authentication', async () => {
      // 1. Inspect merchant settings via admin API
      const settingsBefore = await request('/api/v1/admin/merchant-settings');
      assert.equal(settingsBefore.status, 200);
      assert.ok(settingsBefore.body.merchantId);
      assert.equal(settingsBefore.body.publishableKey, settingsBefore.body.merchantId);
      assert.equal(settingsBefore.body.merchantKey, '', 'legacy webhook secrets must not be returned as merchant API keys');

      // 2. Rotate Merchant API Key via POST /api/v1/admin/merchant-key/rotate
      const rotateRes = await request('/api/v1/admin/merchant-key/rotate', {
        method: 'POST',
        body: { merchantId: settingsBefore.body.merchantId }
      });
      assert.equal(rotateRes.status, 200);
      assert.equal(rotateRes.body.success, true);
      assert.ok(rotateRes.body.merchantKey.startsWith('mk_live_'), 'rotated key must start with mk_live_');

      // 3. Verify GET /api/v1/admin/merchant-settings reflects the rotated key
      const settingsAfter = await request('/api/v1/admin/merchant-settings');
      assert.equal(settingsAfter.status, 200);
      assert.equal(settingsAfter.body.merchantKey, rotateRes.body.merchantKey);

      // 4. Create payment passing the rotated mk_live_... key in X-Merchant-Key
      const payWithKeyHeader = await request('/api/v1/payments', {
        method: 'POST',
        headers: {
          'X-Merchant-Id': settingsBefore.body.merchantId,
          'X-Merchant-Key': rotateRes.body.merchantKey
        },
        body: {
          orderId: 'ORD-MK-HEADER-89',
          amount: '125.00'
        }
      });
      assert.equal(payWithKeyHeader.status, 201);

      // A secret in X-Merchant-Id is not a credential flow; the SDK never sends it.
      const payWithKeyAsId = await request('/api/v1/payments', {
        method: 'POST',
        headers: {
          'X-Merchant-Id': rotateRes.body.merchantKey
        },
        body: {
          orderId: 'ORD-MK-AS-ID-89',
          amount: '135.00'
        }
      });
      assert.equal(payWithKeyAsId.status, 400);

      // 6. Create payment when developer leaves documentation placeholder YOUR_MERCHANT_KEY in data-youpi-key
      const payWithPlaceholder = await request('/api/v1/payments', {
        method: 'POST',
        headers: {
          'X-Merchant-Id': 'YOUR_MERCHANT_KEY'
        },
        body: {
          orderId: 'ORD-MK-PLACEHOLDER-89',
          amount: '145.00'
        }
      });
      assert.equal(payWithPlaceholder.status, 400);
    });
  });
});