Add tenant direct payment token sales

API_DOCUMENTATION.md

@@ -13,13 +13,14 @@
 3. [Tenant — WiFi Plans](#3-tenant--wifi-plans)
 4. [Tenant — Dashboard](#4-tenant--dashboard)
 5. [Tenant — Sessions](#5-tenant--sessions)
-6. [Tenant — Payouts](#6-tenant--payouts)
-7. [Tenant — Alerts](#7-tenant--alerts)
-8. [Super Admin](#8-super-admin)
-9. [Captive Portal (Public)](#9-captive-portal-public)
-10. [Error Format](#10-error-format)
-11. [Enums & Constants](#11-enums--constants)
-12. [UI Building Guide](#12-ui-building-guide)
+6. [Tenant — Manual Sales](#6-tenant--manual-sales)
+7. [Tenant — Payouts](#7-tenant--payouts)
+8. [Tenant — Alerts](#8-tenant--alerts)
+9. [Super Admin](#9-super-admin)
+10. [Captive Portal (Public)](#10-captive-portal-public)
+11. [Error Format](#11-error-format)
+12. [Enums & Constants](#12-enums--constants)
+13. [UI Building Guide](#13-ui-building-guide)
 
 ---
 
@@ -258,6 +259,62 @@ Update one or more tenant notification settings.
 
 ---
 
+### GET `/api/auth/payment-settings`
+Get the tenant's direct-payment receiving settings used for manual token sales.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{
+  "payment_display_name": "Gidion Mathayo Chiyao",
+  "payment_phone": "070024519",
+  "payment_provider": "selcom",
+  "payment_instructions": "Customer pays directly, then attendant confirms.",
+  "payment_qr_image_url": null,
+  "manual_sales_enabled": true
+}
+```
+
+---
+
+### PATCH `/api/auth/payment-settings`
+Update the tenant's direct-payment receiving settings.
+
+If `manual_sales_enabled` is `true`, the account must have:
+- `payment_display_name`
+- `payment_phone`
+- `payment_provider`
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "payment_display_name": "Gidion Mathayo Chiyao",
+  "payment_phone": "070024519",
+  "payment_provider": "selcom",
+  "payment_instructions": "Pay this number, then confirm from the dashboard.",
+  "payment_qr_image_url": null,
+  "manual_sales_enabled": true
+}
+```
+
+**Response `200`:**
+```json
+{
+  "payment_display_name": "Gidion Mathayo Chiyao",
+  "payment_phone": "070024519",
+  "payment_provider": "selcom",
+  "payment_instructions": "Pay this number, then confirm from the dashboard.",
+  "payment_qr_image_url": null,
+  "manual_sales_enabled": true,
+  "message": "Payment settings updated"
+}
+```
+
+---
+
 ### PATCH `/api/auth/profile`
 Update contact name, business name, or email. Send only the fields you want to change.
 
@@ -860,7 +917,103 @@ Session history (active and ended).
 
 ---
 
-## 6. Tenant — Payouts
+## 6. Tenant — Manual Sales
+
+Manual sales are tenant-confirmed direct payments. The customer pays the tenant outside WifiBiz, the tenant confirms from the dashboard, and WifiBiz generates a token.
+
+Important accounting rule:
+- manual sales generate tokens
+- manual sales are recorded in `payments`
+- manual sales do **not** increase withdrawable platform balance
+- manual sales do **not** enter payout calculations
+
+---
+
+### GET `/api/manual-sales`
+Recent manual token sales for the authenticated tenant.
+
+**Auth:** Required
+
+**Query params:**
+- `limit` optional, default `50`, max `100`
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 41,
+    "reference": "MAN-1A2B3C4D5E6F7G8H9J0K",
+    "customer_phone": null,
+    "phone_provider": "selcom",
+    "gross_amount": 1000.00,
+    "payment_channel": "tenant_direct_manual",
+    "verification_source": "tenant_confirmed",
+    "counts_toward_balance": 0,
+    "notes": "Confirmed from counter phone",
+    "confirmed_at": "2026-05-11T08:15:00.000Z",
+    "completed_at": "2026-05-11T08:15:00.000Z",
+    "access_token_code": "ABCD-1234",
+    "device_id": 3,
+    "device_name": "Gaza",
+    "plan_id": 7,
+    "plan_name": "Siku Unlimited",
+    "duration_seconds": 86400
+  }
+]
+```
+
+---
+
+### POST `/api/manual-sales`
+Create a tenant-confirmed manual sale and generate a WiFi token from the selected plan.
+
+Plan selection is mandatory. The backend copies the selected plan's real price, duration, and speed limits into the payment/token.
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "device_id": 3,
+  "plan_id": 7,
+  "customer_phone": "0712345678",
+  "notes": "Paid via tenant Selcom QR"
+}
+```
+
+**Validation:**
+- `device_id` required
+- `plan_id` required
+- selected plan must belong to the selected device
+- selected plan must be active
+- device billing must be `trial` or `active`
+- tenant account must have manual sales enabled in payment settings
+
+**Response `201`:**
+```json
+{
+  "payment_id": 41,
+  "reference": "MAN-1A2B3C4D5E6F7G8H9J0K",
+  "payment_channel": "tenant_direct_manual",
+  "verification_source": "tenant_confirmed",
+  "counts_toward_balance": false,
+  "token_id": 88,
+  "token_code": "ABCD-1234",
+  "customer_phone": "0712345678",
+  "amount": 1000,
+  "device_id": 3,
+  "device_name": "Gaza",
+  "plan_id": 7,
+  "plan_name": "Siku Unlimited",
+  "duration_seconds": 86400,
+  "notes": "Paid via tenant Selcom QR",
+  "message": "Token generated successfully"
+}
+```
+
+---
+
+## 7. Tenant — Payouts
 
 Tenants withdraw their earned balance via M-Pesa.
 
@@ -928,7 +1081,7 @@ Request a withdrawal to M-Pesa.
 
 ---
 
-## 7. Tenant — Alerts
+## 8. Tenant — Alerts
 
 Alerts are shown in-app from two sources:
 - Omada/system alerts such as device offline, disconnected, or client-block events
@@ -980,7 +1133,7 @@ Mark an alert as resolved.
 
 ---
 
-## 8. Super Admin
+## 9. Super Admin
 
 All admin endpoints require a static admin token passed as a Bearer token.  
 This is a **separate secret** from tenant JWTs — set via `ADMIN_TOKEN` environment variable.
@@ -1178,7 +1331,7 @@ Sets `billing_status = 'active'` and extends `billing_expires_at` by 30 days fro
 
 ---
 
-## 9. Captive Portal (Public)
+## 10. Captive Portal (Public)
 
 These endpoints are hit by the AP firmware redirect and the guest's browser. No authentication required.
 
@@ -1281,7 +1434,7 @@ Authorize a guest on the WiFi using their access code.
 
 ---
 
-## 10. Error Format
+## 11. Error Format
 
 All errors follow this shape:
 
@@ -1303,7 +1456,7 @@ All errors follow this shape:
 
 ---
 
-## 11. Enums & Constants
+## 12. Enums & Constants
 
 ### Device `status`
 | Value | Meaning |
@@ -1354,7 +1507,7 @@ All errors follow this shape:
 
 ---
 
-## 12. UI Building Guide
+## 13. UI Building Guide
 
 ### Tenant Dashboard — Recommended Pages
 
@@ -1368,6 +1521,8 @@ All errors follow this shape:
 | Manage Plans | `POST /api/plans`, `PUT /api/plans/:id`, `DELETE /api/plans/:id` |
 | Session History | `GET /api/sessions` |
 | Notification Settings | `GET /api/auth/notification-preferences`, `PATCH /api/auth/notification-preferences` |
+| Payment Settings | `GET /api/auth/payment-settings`, `PATCH /api/auth/payment-settings` |
+| Manual Token Sales | `GET /api/manual-sales`, `POST /api/manual-sales`, `GET /api/plans?deviceId=` |
 | Payouts | `GET /api/payouts`, `POST /api/payouts` |
 | Alerts | `GET /api/alerts/unresolved`, `PATCH /api/alerts/:id/resolve` |
 | Profile | `GET /api/auth/me` |

schema.sql

@@ -17,6 +17,12 @@ CREATE TABLE `clients` (
   `contact_name`      VARCHAR(100)   NOT NULL,
   `email`             VARCHAR(255)   NOT NULL,
   `phone`             VARCHAR(20)    NOT NULL,
+  `payment_display_name` VARCHAR(100) DEFAULT NULL,
+  `payment_phone`     VARCHAR(20)    DEFAULT NULL,
+  `payment_provider`  VARCHAR(32)    DEFAULT NULL,
+  `payment_instructions` VARCHAR(255) DEFAULT NULL,
+  `payment_qr_image_url` VARCHAR(512) DEFAULT NULL,
+  `manual_sales_enabled` TINYINT(1)  NOT NULL DEFAULT 0,
   `password_hash`     VARCHAR(255)   NOT NULL,
   `commission_rate`   DECIMAL(5,4)   NOT NULL DEFAULT 0.0500,
   `balance`           DECIMAL(12,2)  NOT NULL DEFAULT 0.00,
@@ -180,8 +186,14 @@ CREATE TABLE `payments` (
   `client_id`           INT UNSIGNED   NOT NULL,
   `device_id`           INT UNSIGNED   NOT NULL,
   `plan_id`             INT UNSIGNED   NOT NULL,
-  `phone`               VARCHAR(20)    NOT NULL,
-  `phone_provider`      ENUM('mpesa','airtel','tigo','halopesa') NOT NULL DEFAULT 'mpesa',
+  `phone`               VARCHAR(20)    DEFAULT NULL,
+  `phone_provider`      ENUM('mpesa','selcom','airtel','tigo','halopesa','bank','other') NOT NULL DEFAULT 'mpesa',
+  `payment_channel`     ENUM('snippe','tenant_direct_manual') NOT NULL DEFAULT 'snippe',
+  `verification_source` ENUM('webhook','tenant_confirmed') DEFAULT NULL,
+  `counts_toward_balance` TINYINT(1) NOT NULL DEFAULT 1,
+  `confirmed_by_client_id` INT UNSIGNED DEFAULT NULL,
+  `confirmed_at`        TIMESTAMP      NULL DEFAULT NULL,
+  `notes`               VARCHAR(255)   DEFAULT NULL,
   `gross_amount`        DECIMAL(10,2)  NOT NULL,
   `snippe_fee`          DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
   `commission_rate`     DECIMAL(5,4)   NOT NULL DEFAULT 0.0500,

src/app.js

@@ -47,6 +47,7 @@ app.use('/api/dashboard', require('./routes/dashboard.routes'));
 app.use('/api/payouts',   require('./routes/payouts.routes'));
 app.use('/api/sessions',  require('./routes/sessions.routes'));
 app.use('/api/alerts',    require('./routes/alerts.routes'));
+app.use('/api/manual-sales', require('./routes/manualSales.routes'));
 
 // Admin API
 app.use('/api/admin', require('./routes/admin.routes'));

src/routes/auth.routes.js

@@ -12,6 +12,8 @@ const {
 const { requireAuth, signToken } = require('../middleware/auth');
 const { loginLimiter, registerLimiter, forgotPasswordLimiter, phoneOtpLimiter } = require('../middleware/rateLimiter');
 
+const ALLOWED_PAYMENT_PROVIDERS = ['mpesa', 'selcom', 'airtel', 'tigo', 'halopesa', 'bank', 'other'];
+
 // POST /api/auth/register
 router.post('/register', registerLimiter, async (req, res) => {
   const { business_name, contact_name, email, phone, password } = req.body;
@@ -301,7 +303,11 @@ router.post('/phone/confirm', requireAuth, async (req, res) => {
 router.get('/me', requireAuth, async (req, res) => {
   try {
     const client = await db.query(
-      'SELECT id, business_name, contact_name, email, phone, balance, total_earned, total_withdrawn, created_at FROM clients WHERE id = ?',
+      `SELECT id, business_name, contact_name, email, phone,
+              payment_display_name, payment_phone, payment_provider,
+              payment_instructions, payment_qr_image_url, manual_sales_enabled,
+              balance, total_earned, total_withdrawn, created_at
+       FROM clients WHERE id = ?`,
       [req.client.id]
     ).then(r => r[0]);
 
@@ -312,6 +318,154 @@ router.get('/me', requireAuth, async (req, res) => {
   }
 });
 
+// GET /api/auth/payment-settings
+router.get('/payment-settings', requireAuth, async (req, res) => {
+  try {
+    const settings = await db.queryOne(
+      `SELECT payment_display_name, payment_phone, payment_provider,
+              payment_instructions, payment_qr_image_url, manual_sales_enabled
+       FROM clients WHERE id = ?`,
+      [req.client.id]
+    );
+
+    if (!settings) return res.status(404).json({ error: 'Account not found' });
+
+    res.json({
+      payment_display_name: settings.payment_display_name,
+      payment_phone: settings.payment_phone,
+      payment_provider: settings.payment_provider,
+      payment_instructions: settings.payment_instructions,
+      payment_qr_image_url: settings.payment_qr_image_url,
+      manual_sales_enabled: Boolean(settings.manual_sales_enabled),
+    });
+  } catch (err) {
+    console.error('[auth/payment-settings GET]', err.message);
+    res.status(500).json({ error: 'Failed to fetch payment settings' });
+  }
+});
+
+// PATCH /api/auth/payment-settings
+router.patch('/payment-settings', requireAuth, async (req, res) => {
+  const {
+    payment_display_name,
+    payment_phone,
+    payment_provider,
+    payment_instructions,
+    payment_qr_image_url,
+    manual_sales_enabled,
+  } = req.body;
+
+  const updates = [];
+  const values = [];
+
+  if (payment_display_name !== undefined) {
+    if (payment_display_name !== null && typeof payment_display_name !== 'string') {
+      return res.status(400).json({ error: 'payment_display_name must be a string or null' });
+    }
+    updates.push('payment_display_name = ?');
+    values.push(payment_display_name?.trim() || null);
+  }
+
+  if (payment_phone !== undefined) {
+    if (payment_phone !== null && typeof payment_phone !== 'string') {
+      return res.status(400).json({ error: 'payment_phone must be a string or null' });
+    }
+    updates.push('payment_phone = ?');
+    values.push(payment_phone?.trim() || null);
+  }
+
+  if (payment_provider !== undefined) {
+    if (payment_provider !== null && typeof payment_provider !== 'string') {
+      return res.status(400).json({ error: 'payment_provider must be a string or null' });
+    }
+    if (payment_provider && !ALLOWED_PAYMENT_PROVIDERS.includes(payment_provider)) {
+      return res.status(400).json({ error: `payment_provider must be one of: ${ALLOWED_PAYMENT_PROVIDERS.join(', ')}` });
+    }
+    updates.push('payment_provider = ?');
+    values.push(payment_provider || null);
+  }
+
+  if (payment_instructions !== undefined) {
+    if (payment_instructions !== null && typeof payment_instructions !== 'string') {
+      return res.status(400).json({ error: 'payment_instructions must be a string or null' });
+    }
+    updates.push('payment_instructions = ?');
+    values.push(payment_instructions?.trim() || null);
+  }
+
+  if (payment_qr_image_url !== undefined) {
+    if (payment_qr_image_url !== null && typeof payment_qr_image_url !== 'string') {
+      return res.status(400).json({ error: 'payment_qr_image_url must be a string or null' });
+    }
+    updates.push('payment_qr_image_url = ?');
+    values.push(payment_qr_image_url?.trim() || null);
+  }
+
+  if (manual_sales_enabled !== undefined) {
+    if (typeof manual_sales_enabled !== 'boolean') {
+      return res.status(400).json({ error: 'manual_sales_enabled must be boolean' });
+    }
+    updates.push('manual_sales_enabled = ?');
+    values.push(manual_sales_enabled ? 1 : 0);
+  }
+
+  if (!updates.length) {
+    return res.status(400).json({ error: 'No payment setting updates provided' });
+  }
+
+  const enablingManualSales = manual_sales_enabled === true;
+
+  try {
+    const current = await db.queryOne(
+      `SELECT payment_display_name, payment_phone, payment_provider, manual_sales_enabled
+       FROM clients WHERE id = ?`,
+      [req.client.id]
+    );
+
+    if (!current) return res.status(404).json({ error: 'Account not found' });
+
+    const merged = {
+      payment_display_name: payment_display_name !== undefined ? (payment_display_name?.trim() || null) : current.payment_display_name,
+      payment_phone: payment_phone !== undefined ? (payment_phone?.trim() || null) : current.payment_phone,
+      payment_provider: payment_provider !== undefined ? (payment_provider || null) : current.payment_provider,
+      manual_sales_enabled: manual_sales_enabled !== undefined ? manual_sales_enabled : Boolean(current.manual_sales_enabled),
+    };
+
+    if (enablingManualSales || merged.manual_sales_enabled) {
+      if (!merged.payment_display_name || !merged.payment_phone || !merged.payment_provider) {
+        return res.status(400).json({
+          error: 'payment_display_name, payment_phone, and payment_provider are required when manual sales are enabled',
+        });
+      }
+    }
+
+    await db.query(
+      `UPDATE clients SET ${updates.join(', ')} WHERE id = ?`,
+      [...values, req.client.id]
+    );
+
+    const updated = await db.queryOne(
+      `SELECT payment_display_name, payment_phone, payment_provider,
+              payment_instructions, payment_qr_image_url, manual_sales_enabled
+       FROM clients WHERE id = ?`,
+      [req.client.id]
+    );
+
+    res.json({
+      payment_display_name: updated.payment_display_name,
+      payment_phone: updated.payment_phone,
+      payment_provider: updated.payment_provider,
+      payment_instructions: updated.payment_instructions,
+      payment_qr_image_url: updated.payment_qr_image_url,
+      manual_sales_enabled: Boolean(updated.manual_sales_enabled),
+      message: 'Payment settings updated',
+    });
+  } catch (err) {
+    console.error('[auth/payment-settings PATCH]', err.message);
+    res.status(500).json({ error: 'Failed to update payment settings' });
+  }
+});
+
 // GET /api/auth/notification-preferences
 router.get('/notification-preferences', requireAuth, async (req, res) => {
   try {

src/routes/manualSales.routes.js

@@ -0,0 +1,188 @@
+const router = require('express').Router();
+const db = require('../config/db');
+const { requireAuth } = require('../middleware/auth');
+const { v4: uuidv4 } = require('uuid');
+const { createAccessTokenForPayment } = require('../utils/tokenSales');
+
+const MANUAL_PAYMENT_PROVIDERS = new Set(['mpesa', 'selcom', 'airtel', 'tigo', 'halopesa', 'bank', 'other']);
+
+router.use(requireAuth);
+
+// GET /api/manual-sales
+router.get('/', async (req, res) => {
+  const limit = Math.min(parseInt(req.query.limit, 10) || 50, 100);
+
+  try {
+    const sales = await db.query(
+      `SELECT p.id, p.reference, p.phone AS customer_phone, p.phone_provider,
+              p.gross_amount, p.payment_channel, p.verification_source,
+              p.counts_toward_balance, p.notes, p.confirmed_at, p.completed_at,
+              p.access_token_code,
+              d.id AS device_id, d.name AS device_name,
+              wp.id AS plan_id, wp.name AS plan_name, wp.duration_seconds
+       FROM payments p
+       JOIN devices d ON d.id = p.device_id
+       JOIN wifi_plans wp ON wp.id = p.plan_id
+       WHERE p.client_id = ?
+         AND p.payment_channel = 'tenant_direct_manual'
+       ORDER BY COALESCE(p.confirmed_at, p.completed_at, p.created_at) DESC
+       LIMIT ?`,
+      [req.client.id, limit]
+    );
+
+    res.json(sales);
+  } catch (err) {
+    console.error('[manual-sales/list]', err.message);
+    res.status(500).json({ error: 'Failed to fetch manual sales' });
+  }
+});
+
+// POST /api/manual-sales
+router.post('/', async (req, res) => {
+  const { device_id, plan_id, customer_phone = null, notes = null } = req.body;
+
+  if (!device_id || !plan_id) {
+    return res.status(400).json({ error: 'device_id and plan_id are required' });
+  }
+  if (customer_phone !== null && typeof customer_phone !== 'string') {
+    return res.status(400).json({ error: 'customer_phone must be a string or null' });
+  }
+  if (notes !== null && typeof notes !== 'string') {
+    return res.status(400).json({ error: 'notes must be a string or null' });
+  }
+  if (notes && notes.length > 255) {
+    return res.status(400).json({ error: 'notes cannot exceed 255 characters' });
+  }
+
+  const connection = await db.pool.getConnection();
+
+  try {
+    await connection.beginTransaction();
+
+    const [clientRows] = await connection.execute(
+      `SELECT id, commission_rate, payment_display_name, payment_phone, payment_provider,
+              payment_qr_image_url, manual_sales_enabled
+       FROM clients WHERE id = ? LIMIT 1`,
+      [req.client.id]
+    );
+    const client = clientRows[0];
+
+    if (!client) {
+      await connection.rollback();
+      return res.status(404).json({ error: 'Account not found' });
+    }
+    if (!client.manual_sales_enabled) {
+      await connection.rollback();
+      return res.status(403).json({ error: 'Manual token sales are disabled for this account' });
+    }
+    if (!client.payment_display_name || !client.payment_phone || !client.payment_provider) {
+      await connection.rollback();
+      return res.status(400).json({ error: 'Complete your payment settings before generating manual tokens' });
+    }
+
+    const [deviceRows] = await connection.execute(
+      `SELECT id, name, billing_status
+       FROM devices
+       WHERE id = ? AND client_id = ? LIMIT 1`,
+      [device_id, req.client.id]
+    );
+    const device = deviceRows[0];
+
+    if (!device) {
+      await connection.rollback();
+      return res.status(404).json({ error: 'Device not found' });
+    }
+    if (!['trial', 'active'].includes(device.billing_status)) {
+      await connection.rollback();
+      return res.status(403).json({ error: 'Device billing is not active for manual token generation' });
+    }
+
+    const [planRows] = await connection.execute(
+      `SELECT id, name, duration_seconds, price,
+              down_limit, down_unit, up_limit, up_unit, is_active
+       FROM wifi_plans
+       WHERE id = ? AND device_id = ? AND client_id = ? LIMIT 1`,
+      [plan_id, device.id, req.client.id]
+    );
+    const plan = planRows[0];
+
+    if (!plan) {
+      await connection.rollback();
+      return res.status(404).json({ error: 'Plan not found' });
+    }
+    if (!plan.is_active) {
+      await connection.rollback();
+      return res.status(400).json({ error: 'Selected plan is inactive' });
+    }
+
+    const reference = `MAN-${uuidv4().replace(/-/g, '').slice(0, 20).toUpperCase()}`;
+    const provider = MANUAL_PAYMENT_PROVIDERS.has(client.payment_provider)
+      ? client.payment_provider
+      : 'other';
+
+    const [paymentResult] = await connection.execute(
+      `INSERT INTO payments
+         (reference, client_id, device_id, plan_id, phone, phone_provider,
+          payment_channel, verification_source, counts_toward_balance,
+          confirmed_by_client_id, confirmed_at, notes,
+          gross_amount, snippe_fee, commission_rate, commission_amount, client_credit,
+          status, completed_at)
+       VALUES (?, ?, ?, ?, ?, ?, 'tenant_direct_manual', 'tenant_confirmed', 0,
+               ?, NOW(), ?, ?, 0.00, 0.0000, 0.00, 0.00,
+               'completed', NOW())`,
+      [
+        reference,
+        req.client.id,
+        device.id,
+        plan.id,
+        customer_phone?.trim() || null,
+        provider,
+        req.client.id,
+        notes?.trim() || null,
+        plan.price,
+      ]
+    );
+
+    const { tokenId, code } = await createAccessTokenForPayment({
+      connection,
+      paymentId: paymentResult.insertId,
+      clientId: req.client.id,
+      deviceId: device.id,
+      planId: plan.id,
+      durationSeconds: plan.duration_seconds,
+      downLimit: plan.down_limit,
+      downUnit: plan.down_unit,
+      upLimit: plan.up_limit,
+      upUnit: plan.up_unit,
+    });
+
+    await connection.commit();
+
+    res.status(201).json({
+      payment_id: paymentResult.insertId,
+      reference,
+      payment_channel: 'tenant_direct_manual',
+      verification_source: 'tenant_confirmed',
+      counts_toward_balance: false,
+      token_id: tokenId,
+      token_code: code,
+      customer_phone: customer_phone?.trim() || null,
+      amount: parseFloat(plan.price),
+      device_id: device.id,
+      device_name: device.name,
+      plan_id: plan.id,
+      plan_name: plan.name,
+      duration_seconds: plan.duration_seconds,
+      notes: notes?.trim() || null,
+      message: 'Token generated successfully',
+    });
+  } catch (err) {
+    await connection.rollback();
+    console.error('[manual-sales/create]', err.message);
+    res.status(500).json({ error: 'Failed to generate manual token sale' });
+  } finally {
+    connection.release();
+  }
+});
+
+module.exports = router;

src/routes/portal.routes.js

@@ -30,7 +30,9 @@ router.get('/:siteId', async (req, res) => {
 
   try {
     const device = await db.query(
-      `SELECT d.*, c.business_name, c.commission_rate
+      `SELECT d.*, c.business_name, c.commission_rate,
+              c.payment_display_name, c.payment_phone, c.payment_provider,
+              c.payment_instructions, c.payment_qr_image_url, c.manual_sales_enabled
        FROM devices d JOIN clients c ON c.id = d.client_id
        WHERE d.omada_site_id = ? LIMIT 1`,
       [siteId]
@@ -115,6 +117,14 @@ router.get('/:siteId', async (req, res) => {
       businessName: device.business_name,
       deviceName:   device.name,
       customize,
+      directPayment: {
+        enabled: Boolean(device.manual_sales_enabled && device.payment_display_name && device.payment_phone && device.payment_provider),
+        displayName: device.payment_display_name || null,
+        phone: device.payment_phone || null,
+        provider: device.payment_provider || null,
+        instructions: device.payment_instructions || null,
+        qrImageUrl: device.payment_qr_image_url || null,
+      },
     };
 
     // Custom portal HTML?

src/routes/sessions.routes.js

@@ -139,6 +139,9 @@ router.post('/paid-disconnected/:tokenId/message', async (req, res) => {
     if (!token) {
       return res.status(404).json({ error: 'Paid disconnected client not found' });
     }
+    if (!token.payment_phone) {
+      return res.status(400).json({ error: 'This client has no phone number recorded for messaging' });
+    }
 
     const sent = await sms.sendSMS(token.payment_phone, text);
     if (!sent) {

src/utils/migrate.js

@@ -78,6 +78,24 @@ const migrations = [
   // 008 — Add in-app alert notification preferences to existing installs
   `ALTER TABLE client_notification_preferences ADD COLUMN purchase_alerts TINYINT(1) NOT NULL DEFAULT 1 AFTER trial_granted`,
   `ALTER TABLE client_notification_preferences ADD COLUMN system_alerts TINYINT(1) NOT NULL DEFAULT 1 AFTER purchase_alerts`,
+
+  // 009 — Tenant direct-payment settings on clients
+  `ALTER TABLE clients ADD COLUMN payment_display_name VARCHAR(100) DEFAULT NULL AFTER phone`,
+  `ALTER TABLE clients ADD COLUMN payment_phone VARCHAR(20) DEFAULT NULL AFTER payment_display_name`,
+  `ALTER TABLE clients ADD COLUMN payment_provider VARCHAR(32) DEFAULT NULL AFTER payment_phone`,
+  `ALTER TABLE clients ADD COLUMN payment_instructions VARCHAR(255) DEFAULT NULL AFTER payment_provider`,
+  `ALTER TABLE clients ADD COLUMN payment_qr_image_url VARCHAR(512) DEFAULT NULL AFTER payment_instructions`,
+  `ALTER TABLE clients ADD COLUMN manual_sales_enabled TINYINT(1) NOT NULL DEFAULT 0 AFTER payment_qr_image_url`,
+
+  // 010 — Manual/direct payment tracking fields on payments
+  `ALTER TABLE payments MODIFY COLUMN phone VARCHAR(20) NULL`,
+  `ALTER TABLE payments MODIFY COLUMN phone_provider ENUM('mpesa','selcom','airtel','tigo','halopesa','bank','other') NOT NULL DEFAULT 'mpesa'`,
+  `ALTER TABLE payments ADD COLUMN payment_channel ENUM('snippe','tenant_direct_manual') NOT NULL DEFAULT 'snippe' AFTER phone_provider`,
+  `ALTER TABLE payments ADD COLUMN verification_source ENUM('webhook','tenant_confirmed') DEFAULT NULL AFTER payment_channel`,
+  `ALTER TABLE payments ADD COLUMN counts_toward_balance TINYINT(1) NOT NULL DEFAULT 1 AFTER verification_source`,
+  `ALTER TABLE payments ADD COLUMN confirmed_by_client_id INT UNSIGNED DEFAULT NULL AFTER counts_toward_balance`,
+  `ALTER TABLE payments ADD COLUMN confirmed_at TIMESTAMP NULL DEFAULT NULL AFTER confirmed_by_client_id`,
+  `ALTER TABLE payments ADD COLUMN notes VARCHAR(255) DEFAULT NULL AFTER confirmed_at`,
 ];
 
 async function runMigrations() {
@@ -89,7 +107,7 @@ async function runMigrations() {
       const col = sql.match(/(?:ADD|MODIFY) COLUMN (\w+)/i)?.[1] ?? sql.slice(0, 60);
       console.log(`[migrate] Applied: ${col}`);
     } catch (err) {
-      if (err.errno === 1060) {
+      if (err.errno === 1060 || err.errno === 1091) {
         // Column already exists — nothing to do
       } else {
         console.error('[migrate] Migration failed:', err.message);

src/utils/tokenSales.js

@@ -0,0 +1,62 @@
+const { generateCode } = require('./generateCode');
+
+async function createAccessTokenForPayment({
+  connection,
+  paymentId,
+  clientId,
+  deviceId,
+  planId,
+  durationSeconds,
+  downLimit,
+  downUnit,
+  upLimit,
+  upUnit,
+}) {
+  if (!connection) {
+    throw new Error('Database connection is required');
+  }
+
+  let lastError = null;
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const code = generateCode();
+
+    try {
+      const [insertResult] = await connection.execute(
+        `INSERT INTO access_tokens
+           (client_id, device_id, plan_id, payment_id, code, duration_seconds,
+            down_limit, down_unit, up_limit, up_unit, status)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'unused')`,
+        [
+          clientId,
+          deviceId,
+          planId,
+          paymentId,
+          code,
+          durationSeconds,
+          downLimit,
+          downUnit,
+          upLimit,
+          upUnit,
+        ]
+      );
+
+      await connection.execute(
+        `UPDATE payments SET access_token_code = ? WHERE id = ?`,
+        [code, paymentId]
+      );
+
+      return {
+        tokenId: insertResult.insertId,
+        code,
+      };
+    } catch (err) {
+      lastError = err;
+      if (err.code !== 'ER_DUP_ENTRY') throw err;
+    }
+  }
+
+  throw lastError || new Error('Failed to generate a unique token code');
+}
+
+module.exports = { createAccessTokenForPayment };

src/views/screens/portal.ejs

@@ -77,6 +77,27 @@
       font-weight: 500;
       color: var(--text-secondary);
     }
+    .portal-kicker {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      margin-top: 14px;
+      padding: 7px 11px;
+      border-radius: 999px;
+      background: var(--nest);
+      color: var(--text-primary);
+      font-size: 10px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.12em;
+    }
+    .portal-kicker .dot {
+      width: 7px;
+      height: 7px;
+      border-radius: 50%;
+      background: var(--blue);
+      box-shadow: 0 0 0 4px rgba(0, 84, 203, 0.10);
+    }
     .signal-mark {
       display: inline-block;
       width: 28px;
@@ -325,6 +346,141 @@
       letter-spacing: 0.1em;
       color: var(--text-disabled);
     }
+    .payment-note {
+      margin-top: 14px;
+      font-size: 11px;
+      line-height: 1.55;
+      color: var(--text-secondary);
+    }
+    .manual-pay-card {
+      margin: 18px 0 6px;
+      padding: 18px;
+      background:
+        radial-gradient(circle at top right, rgba(0,84,203,0.10), transparent 38%),
+        linear-gradient(180deg, #111111 0%, #1A1A1A 100%);
+      border-radius: 18px;
+      color: #FFFFFF;
+      box-shadow: 0 18px 38px rgba(0,0,0,0.14);
+      overflow: hidden;
+      position: relative;
+    }
+    .manual-pay-card::after {
+      content: '';
+      position: absolute;
+      inset: auto -20% -40% 45%;
+      height: 120px;
+      background: radial-gradient(circle, rgba(255,255,255,0.08), transparent 70%);
+      pointer-events: none;
+    }
+    .manual-pay-head {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 14px;
+      margin-bottom: 14px;
+    }
+    .manual-pay-head h3 {
+      font-size: 17px;
+      font-weight: 800;
+      letter-spacing: -0.03em;
+      margin-bottom: 4px;
+    }
+    .manual-pay-head p {
+      font-size: 12px;
+      line-height: 1.5;
+      color: rgba(255,255,255,0.74);
+    }
+    .manual-pay-badge {
+      flex-shrink: 0;
+      padding: 7px 10px;
+      border-radius: 999px;
+      background: rgba(255,255,255,0.10);
+      border: 1px solid rgba(255,255,255,0.12);
+      font-size: 10px;
+      font-weight: 800;
+      text-transform: uppercase;
+      letter-spacing: 0.12em;
+      color: #FFFFFF;
+    }
+    .manual-pay-details {
+      display: grid;
+      gap: 10px;
+      margin-bottom: 14px;
+    }
+    .manual-pay-row {
+      display: flex;
+      justify-content: space-between;
+      gap: 12px;
+      align-items: flex-start;
+      padding-bottom: 10px;
+      border-bottom: 1px solid rgba(255,255,255,0.10);
+    }
+    .manual-pay-row:last-child {
+      border-bottom: none;
+      padding-bottom: 0;
+    }
+    .manual-pay-key {
+      font-size: 10px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.14em;
+      color: rgba(255,255,255,0.56);
+    }
+    .manual-pay-val {
+      text-align: right;
+      font-size: 14px;
+      font-weight: 700;
+      line-height: 1.4;
+      color: #FFFFFF;
+    }
+    .manual-pay-val.phone {
+      font-size: 19px;
+      letter-spacing: 0.04em;
+    }
+    .manual-pay-foot {
+      margin-top: 14px;
+      padding-top: 14px;
+      border-top: 1px solid rgba(255,255,255,0.10);
+    }
+    .manual-pay-foot p {
+      font-size: 12px;
+      line-height: 1.6;
+      color: rgba(255,255,255,0.78);
+    }
+    .manual-pay-steps {
+      display: grid;
+      gap: 8px;
+      margin-top: 12px;
+    }
+    .manual-pay-step {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      font-size: 11px;
+      font-weight: 600;
+      color: rgba(255,255,255,0.9);
+    }
+    .manual-pay-step .step-no {
+      width: 22px;
+      height: 22px;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: 50%;
+      background: rgba(255,255,255,0.12);
+      font-size: 10px;
+      font-weight: 800;
+      letter-spacing: 0.04em;
+    }
+    .quick-access-note {
+      margin-top: 14px;
+      padding: 12px 14px;
+      border-radius: 12px;
+      background: var(--nest);
+      font-size: 11px;
+      line-height: 1.6;
+      color: var(--text-secondary);
+    }
 
     /* ── Link Button ── */
     .link-btn {
@@ -479,6 +635,12 @@
         <% } %>
         <h1><%= portal.customize.displayName %></h1>
         <p><%= portal.customize.welcomeText %></p>
+        <% if (portal.directPayment.enabled) { %>
+          <div class="portal-kicker">
+            <span class="dot"></span>
+            <span>Direct payment available on this hotspot</span>
+          </div>
+        <% } %>
       </div>
 
       <!-- SCREEN 1: Plan selection & phone -->
@@ -509,7 +671,46 @@
             <% }); %>
           </div>
 
+          <% if (portal.directPayment.enabled) { %>
+            <div class="manual-pay-card">
+              <div class="manual-pay-head">
+                <div>
+                  <h3>Pay the business directly</h3>
+                  <p>Use the number below, then show payment confirmation and get your WiFi code from the attendant.</p>
+                </div>
+                <div class="manual-pay-badge"><%= String(portal.directPayment.provider || '').toUpperCase() %></div>
+              </div>
+
+              <div class="manual-pay-details">
+                <div class="manual-pay-row">
+                  <span class="manual-pay-key">Pay To</span>
+                  <span class="manual-pay-val"><%= portal.directPayment.displayName %></span>
+                </div>
+                <div class="manual-pay-row">
+                  <span class="manual-pay-key">Number</span>
+                  <span class="manual-pay-val phone"><%= portal.directPayment.phone %></span>
+                </div>
+                <% if (portal.directPayment.instructions) { %>
+                  <div class="manual-pay-row">
+                    <span class="manual-pay-key">Instructions</span>
+                    <span class="manual-pay-val"><%= portal.directPayment.instructions %></span>
+                  </div>
+                <% } %>
+              </div>
+
+              <div class="manual-pay-foot">
+                <p>The attendant confirms payment from their own phone and generates your token from the dashboard.</p>
+                <div class="manual-pay-steps">
+                  <div class="manual-pay-step"><span class="step-no">1</span><span>Choose your plan from this page.</span></div>
+                  <div class="manual-pay-step"><span class="step-no">2</span><span>Pay the business using the number above.</span></div>
+                  <div class="manual-pay-step"><span class="step-no">3</span><span>Use the WiFi code you receive to connect.</span></div>
+                </div>
+              </div>
+            </div>
+          <% } %>
+
           <div class="divider"><span>Pay via Mobile Money</span></div>
+          <p class="payment-note">Prefer instant activation? Enter your own number below to pay online and receive your WiFi code automatically.</p>
 
           <div class="input-wrap">
             <label class="field-label" for="phone-input">Phone Number</label>
@@ -529,6 +730,11 @@
 
           <div class="divider"><span>or</span></div>
           <span class="link-btn" id="show-code-entry">Enter an existing code</span>
+          <% if (portal.directPayment.enabled) { %>
+            <div class="quick-access-note">
+              Already paid the business directly? Ask for your token, then use <strong>Enter an existing code</strong> to connect here.
+            </div>
+          <% } %>
           <% if (portal.customize.supportPhone) { %>
             <p style="text-align:center;font-size:11px;color:var(--text-disabled);margin-top:16px;">
               Need help? Call <a href="tel:<%= portal.customize.supportPhone %>" style="color:var(--blue);text-decoration:none;font-weight:600;"><%= portal.customize.supportPhone %></a>