Subscribers

A subscriber is a recurring account on tenant_end_customers — your own regular customer on a fixed, ISP-style line, billed automatically every cycle once a card is on file. It's a distinct concept from the two other "a guest gets access" paths this platform has:

Subscribers and Internal Accounts share one thing neither Data Plans nor vouchers get: they're the only two account types eligible for a static IP reservation, because both represent a persistent, ongoing device relationship rather than a bounded, often-anonymous purchase. On the captive portal, starting a subscription is a separate button in the "Buy Internet Access" modal, grouped apart from one-off vouchers and data plans, so it's obvious to a guest which one commits them to a recurring charge.

Configured on tenant_subscription_plans via POST /api/isn/subscription-plans (validated by _validateSubscriptionPlanBody). Each plan has:

A plan is deactivated (PATCH with {active:false}), not deleted, to stop new signups while leaving existing subscribers untouched. DELETE /api/isn/subscription-plans/:id is blocked outright (HTTP 409) while any tenant_end_customers row still references that plan_id — "Cannot delete a plan with subscribers on it — deactivate it instead."

A subscription starts one of two ways:

The Subscribers table (GET /api/isn/end-customers, capped at 200 rows, searchable by identifier/display name) shows each subscriber's plan, status (trialing / active / past_due / canceled / suspended), next_billing_date, and assigned static IP if any. A cash-paid subscriber has no card on file and is never touched by the automatic billing sweep (see panel 5) — the tenant renews them manually with POST /api/isn/end-customers/:id/mark-paid, which logs a charge_type: 'cash' row on tenant_end_customer_charges, extends next_billing_date by one interval (from whichever is later — today or the existing date, so an early renewal stacks rather than shortens, and a late one starts fresh instead of compounding missed cycles), reactivates the account if it had lapsed, and re-grants access on every device already on file for that identifier via _grantEndCustomerAccessToKnownDevices.

Deletion: a subscriber never actually charged (DELETE /api/isn/end-customers/:id) is removed outright. One with real charge history can't be — the FK from tenant_end_customer_charges to tenant_end_customers deliberately does not cascade, so the delete fails with a 409 and the message "This subscriber has billing history and can't be deleted — set their status to Canceled instead." Canceling keeps the audit trail intact while stopping future billing.

A static DHCP reservation layered onto an existing subscriber account — not a separate connection type or a real routable/public IP, and not a PPPoE tunnel. It exists for a device that needs the same LAN address every time (port forwarding, a security camera, a small office device). Available only when the subscriber's plan has static_ip_enabled turned on (checked server-side on assignment, not just hidden client-side).

Assigned via POST /api/isn/end-customers/:id/static-ip with an IPv4 address, a MAC address, and which router the subscriber connects through:

• The IPv4 address is validated with a strict per-octet regex bounding each octet to 0–255 — the looser regex this replaced accepted garbage like 999.999.999.999 as "valid" and forwarded it straight to the router.
• The MAC must match AA:BB:CC:DD:EE:FF format exactly, uppercased.
• _routerBelongsToTenant confirms the router is actually this tenant's before anything is pushed.

Once validated, it's pushed as a real DHCP static-lease command: a MikroTik script (/ip dhcp-server lease add/set, tagged with comment presida-subscriber-static) or an OpenWRT UCI script (uci set dhcp.<mac-derived-section>, restarting dnsmasq) depending on router vendor — only these two vendor families are automated today; any other vendor gets a clear refusal rather than a silent no-op. The command is logged to router_cli_audit_log (same audit trail Remote CLI uses, purpose static_ip_assign) and queued via queueRouterExec, applying the moment the router next checks in. Internal Accounts get the same mechanism with no plan gate (each internal account is already configured individually), and an SSO login inherits it automatically since an SSO login is a real internal account under the hood. It deliberately does not extend to vouchers, data plans, surveys, ads, or roaming — those are bounded/anonymous grants or (for roaming) span networks with no shared address space to reserve on.

Card-based subscriptions ride the tenant's own verified PayFast gateway (tenant_payment_gateways, provider='payfast', status='verified') — the same connection already used for one-off data-plan checkouts, nothing separate to set up. The first checkout (POST /api/subscriber/checkout/init) uses tenantPayfast.buildTokenizationCheckoutUrl with PayFast's subscription_type=2, so it both takes the first payment and tokenizes the card; the webhook (POST /api/subscriber/checkout/webhook/:tenantId) stores the encrypted token on tenant_end_customer_cards (upserted, one row per subscriber). The raw card number is never stored by this platform.

The recurring sweep — _runEndCustomerBillingCycle(), run on the same interval as ISN's own tenant-billing job: every 6 hours, plus once immediately on server startup.

Cancellation — POST /api/subscriber/cancel, callable by the subscriber themselves from the captive portal's "My Subscription" menu item ("Cancel subscription"), or by the tenant setting status to canceled from the dashboard. This only stops future billing: a subscriber's access window is capped strictly to their own next_billing_date server-side and can never be extended by re-logging in, but it also is never cut short early by canceling — access keeps running exactly until the already-paid-for period ends, then quietly doesn't renew. An SMS confirms the cancellation and states the date access keeps running until.

Guests who have a subscription get a My Subscription item in the captive portal's menu, directly below My Usage. It appears for every signed-in guest: a guest with a subscription sees everything below, anyone else sees a short note that they have no subscription yet (or, if the device could not be confirmed, a note to log out and in again). It is the one place for everything about a subscription, so My Usage and My Account no longer repeat any of it.

Tax invoices. In the ISN Portal, under Subscribers, Invoices and month-end statements holds the registered business name, address, VAT number and VAT rate (default 15%). With a VAT number saved, documents are headed TAX INVOICE and show amount excluding VAT, the VAT amount and the total (prices are treated as VAT-inclusive); without one they are headed RECEIPT. Invoice numbers are unique per payment (date plus a payment code). Check with your accountant whether your jurisdiction requires strictly sequential numbering.

Month-end billing run. The same section can download one PDF containing a statement page for every subscriber who paid in the chosen month (up to 300 subscribers per run).

Security. Every self-service route checks that the caller's session owns the identifier (_sessionOwnsIdentifier) and only ever reads or writes that one subscriber's own row inside the current captive's tenant. Invoice downloads are rate-limited per subscriber and a payment that belongs to someone else, or that did not succeed, returns "not found".

Plan UUIDs are not secret — GET /api/subscriber/plans publicly returns a tenant's own plan IDs to any guest on that tenant's captive portal (so the "Buy Internet Access" modal can list them). That meant an unscoped write to a subscriber's plan_id could, in principle, be made to point at a different tenant's plan UUID. This session's own security audit found this live and fixed it in three places:

All three now scope every tenant_subscription_plans lookup involved in writing or checking a plan_id to eq('tenant_id', tenantId), so a plan reference can never cross a tenant boundary regardless of which of these three paths it's reached through.

GET /api/isn/payments merges two differently-shaped tables into one normalized transaction list for the dashboard: tenant_data_plan_purchases (one-off data-plan buys; statuses paid/failed/expired/pending) and tenant_end_customer_charges (every subscriber charge — signup, renewal, retry, and cash; statuses success/failed/pending). Since the two tables use different status vocabularies, the merge is done in JS rather than a SQL UNION, normalizing paid → success for consistency.

Each subscription-side row is labeled by the endpoint as Subscription signup only when charge_type === 'signup', and Subscription renewal for every other charge type. In practice, a subscriber's actual first-payment charge is recorded with charge_type: 'first_payment' (not 'signup') by the checkout-init endpoint, so it currently falls into the "Subscription renewal" label along with genuine recurring (automatic sweep) and cash (manual "Mark as paid") charges — a cosmetic label mismatch worth knowing about if a subscriber's very first charge shows up as a "renewal" in this ledger. All charge types appear as real transactions either way, so a cash renewal shows up identically to a card charge for reporting purposes. The endpoint supports a type filter (data_plan / subscription / all), a status filter, free-text search, a days window (1–365, default 30), and pagination (page/pageSize, capped at 100 per page), with each query independently capped at 500 raw rows before normalization.