Data Plans

A Data Plan is a bundle a tenant sells directly to a guest for real money — a price, a data allowance (or unlimited), a duration, and an optional speed cap — bought right on the captive portal's connect screen with no voucher code involved. It's the "pay by card" counterpart to a voucher: the same underlying table (tenant_data_plans) backs both "Data plans" and "External voucher bundles" in the tenant dashboard, so a bundle created in either place shows up in both.

The guest flow, step by step:

• Guest taps a plan on the connect screen (home.html's "Buy internet access" modal). The browser calls POST /api/dataplan/purchase/init with the plan id and the guest's own identifier (phone/email) — the server rejects the request with 403 unless the caller's own session actually owns that identifier, which stops one guest from burning a free plan's eligibility against a stranger's phone number.
• If the guest already has a 1Voucher/OTT Voucher balance on their account that covers the price, the portal tries POST /api/dataplan/purchase/from-balance first, silently — no "pick a payment method" prompt. Only if the balance can't cover it does it fall through to a real card/QR checkout.
• For a card/QR purchase, purchase/init starts a checkout with whichever payment gateway the tenant has connected and returns one of: an inline Paystack popup, a full-page redirect URL (PayFast, Yoco, DPO Pay, or a Paystack fallback), or a QR code payload (SnapScan, Zapper). A new row is inserted into tenant_data_plan_purchases with status='pending'.
• The guest's browser polls GET /api/dataplan/purchase/status?reference=... every 2 seconds. Real settlement never happens on this poll — it only happens when the gateway's own webhook lands and calls _settleDataPlanPurchase (see panels 4–5). The poll gives up showing "still confirming" after 15 attempts (30 seconds) but access still activates automatically the moment the webhook does land — the guest isn't stuck if their payment just took longer than that. The one exception is DPO Pay, which has no webhook at all: when the guest returns, the status check itself asks DPO directly whether the payment really succeeded (see the DPO Pay row in panel 3 and the recovery notes in panel 5).
• Once status flips to paid, the portal stores the guest's identifier in localStorage so login.html recognizes them automatically on return, instead of making a guest who just paid re-enter a login form.

Configured from the dashboard's "Data plans" section (isn/business-dashboard.html, id #data-plans), validated server-side by _validateDataPlanBody. The exact fields:

Journey-based pricing is an alternate entry mode on the same form: instead of typing one name/price/duration, the tenant picks an already-mapped, per-leg-priced route from Journey presets, and the server generates one bundle per stop automatically (e.g. "Durban → Pietermaritzburg", "Durban → Bloemfontein"), each priced and timed from that route's own legs. Every other field (data cap, device limits, speed caps, FUP, promo, router restriction) still applies uniformly to all the generated bundles.

Confirmed directly from /api/dataplan/purchase/init and its webhook handlers in server.js — six providers: five that notify us by webhook, plus DPO Pay, which is checked by asking DPO directly instead. They split into groups that can coexist differently:

Paystack, PayFast, and Yoco are mutually exclusive in the dashboard's connect flow — at most one of those three is ever status='verified' for a tenant at a time, since they're all "cards." SnapScan and Zapper are QR-scan methods, not cards, so they can coexist with a card gateway and with each other — a tenant can legitimately offer three live payment options on one connect screen. DPO Pay can also run alongside a card gateway; when the tenant's Currency is NAD, the guest is offered DPO first, otherwise it is tried last so it never displaces a gateway the tenant already uses. A guest also never needs a card at all if a 1Voucher/OTT balance already covers the price (panel 1) — that path (/from-balance) skips every external gateway entirely.

Every settlement path — all five webhooks, the DPO status checks and the reconciliation sweep (panel 5) — funnels through one shared function, _settleDataPlanPurchase, and that function treats "a real payment happened" and "the right amount was paid" as two separate questions that must BOTH be true before access is granted.

Why this matters specifically for Paystack's inline checkout: the in-page popup hands the guest's own browser a publishable (Public) key and lets it call Paystack's widget directly. Nothing before the webhook ever tells Paystack what the real price was from a source the guest's browser couldn't tamper with — so without an independent re-check, a guest could in principle complete a genuine payment for a deliberately reduced amount (e.g. R1 against a R99 plan) and Paystack would still report success, because "a real payment happened" was the only thing being checked.

The actual, current check in _settleDataPlanPurchase:

• expectedAmountKobo is computed from the purchase row's own stored amount (set server-side at /purchase/init time, before the guest ever reaches a payment screen) — never from anything the gateway's callback claims the price should have been.
• paidAmountKobo is the amount the gateway's webhook (or, for the reconciliation sweep, a direct server-to-server verify call) actually reports as paid.
• DPO Pay adds a second check. DPO answers HTTP 200 to everything (even bad credentials), so only the XML result 000 counts as paid, and the currency DPO reports must equal the currency the purchase was created in. A payment made in ZAR against a NAD purchase (or the reverse) is failed and never grants access. An over- or under-payment (002) is never auto-settled: it is marked "DPO needs review" for a person to look at.
• If paidAmountKobo < expectedAmountKobo, the purchase is marked status='failed' with a logged reason, a dataplan_webhook_amount_mismatch security event is recorded, and access is never granted — regardless of what the gateway's own success flag said.

The same discipline is deliberately repeated, independently, in the separate end-customer subscriber-checkout PayFast webhook (comment explicitly references this as "the same CRITICAL bug class" already fixed here) — underpayment re-verification is now a standing pattern across every payment surface on the platform, not a one-off patch.

Before this was fixed, a process crash between "Paystack/PayFast confirms the payment" and "the code that actually grants network access runs" could leave a guest genuinely charged with no automatic way to ever get connected. The fix adds two columns to tenant_data_plan_purchases — grant_params (jsonb) and access_granted_at (timestamptz) — and changes what each status transition means:

• Step 1 — claim. When a webhook first reaches a pending row and the amount check (panel 4) passes, the row is atomically updated to status='paid' AND the exact grant plan — duration, journey preset/stop if applicable, whether strict duration is skipped — is snapshotted into grant_params in that same write. The update is conditioned on .eq('status','pending'), so if two callers (e.g. the webhook and the reconciliation sweep) race for the same row, only one of them gets a non-null row back; the other sees already_settled and does nothing further.
• Step 2 — grant. Only after that claim succeeds does the function call recordPurchase (the function that actually gives the guest a session with data/duration/speed) and, as the real completion marker, set access_granted_at.
• The crash gap this closes: if the process dies between step 1 and step 2, the row is left sitting at status='paid' with access_granted_at still null — a real, charged guest with no access and no in-memory state left to recover from. _runDataPlanReconciliationSweep runs on an interval and queries exactly this condition (status='paid', access_granted_at IS NULL, paid_at older than a 2-minute floor so it never races a normal in-flight completion). For each row it finds, it calls _settleDataPlanPurchase again — which detects the 'paid'-with-grant_params case and replays the EXACT previously-committed grant (not re-deriving it, since a journey preset could have been edited in the meantime) rather than guessing what the guest originally bought.
• A separate, older recovery path handles the "webhook itself never arrived at all" case (tenant's webhook URL misconfigured, network partition): rows still pending after 10 minutes are checked directly against Paystack's own transaction-verify API, up to a 48-hour abandonment cutoff, after which they're marked failed rather than polled forever.
• DPO Pay has its own recovery path because it never sends a webhook. A guest whose phone died or connection dropped after paying is settled the moment they reopen the portal (/api/me/usage triggers the check) or tap Buy again, and the 15-minute sweep catches anyone who never returns. A payment DPO reports as cancelled or declined (901/904) is shown as failed but re-checked for about 45 minutes in case the guest used DPO's "Retry Payment"; an expired payment (903) is final. Tapping Buy again while a payment is still open sends the guest back to the same DPO link instead of creating a second charge.

Disclosed limitation: the grant-only retry step (step 2's recovery) has no atomic claim of its own before calling recordPurchase — safe today because this app runs as a single process, but if the sweep ever ran as two concurrent processes, both could fetch the same stuck row before either sets access_granted_at, and both would grant it. This is explicitly flagged in the code as something to revisit (an intermediate "granting" sentinel) before this sweep is ever run across more than one instance.

Worth stating precisely, since the two features sit right next to each other in the dashboard and are easy to conflate: static/reserved IP addressing exists on this platform, but it belongs to the separate Subscriber accounts feature (tenant_subscription_plans / tenant_end_customers, id #end-customers in the dashboard) — recurring, login-based accounts billed on a cycle, not the one-off card purchase a Data Plan is. A subscription plan has its own "Reserve a static IP for subscribers on this plan" checkbox (static_ip_enabled); tenant_data_plans has no equivalent field at all, and _validateDataPlanBody never reads or writes one. A guest buying a one-time Data Plan never gets a reserved IP through that purchase, by design — that's a recurring-subscriber benefit.

The platform does run router bandwidth-congestion alerting (_checkRouterCongestionAndAlert, a 90% usage threshold with a 75% hysteresis clear-point so it doesn't flap) and router-offline/outage SMS alerting. Both are per-router, tenant-facing operational alerts — they tell a tenant admin their router is saturated or down. Neither is scoped to, or triggered by, a specific Data Plan purchase; a Data Plan's only direct interaction with router capacity is that its own speed cap (panel 2) is applied to the guest's session the instant access is granted, and that a guest already over the tenant's Fair Usage Policy threshold gets throttled speed applied instead of the plan's advertised speed (see panel 8), so a cheap top-up can't be used to repeatedly dodge FUP by re-buying every few minutes.