Merge branch 'feat/campus-scoped-staff'

Campus-scoped staff: help, docs, changelog (1.44.0)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 22:59:00 +02:00 · 2026-10-27 17:52:11 +02:00 · 2026-10-27 17:50:03 +02:00 · 2026-10-27 17:40:32 +02:00 · 2026-10-27 17:37:42 +02:00 · 2026-10-27 17:28:30 +02:00
243 changed files with 15783 additions and 2240 deletions
@@ -31,6 +31,9 @@ yarn-error.log*
 .DS_Store
 Thumbs.db

+# this install's PM2 config (made from ecosystem.config.example.js; deploys never touch it)
+/ecosystem.config.js
+
 # misc scratch / generated files
 temp/
 backend/public/uploads/
@@ -7,6 +7,267 @@ and this project follows [Semantic Versioning](https://semver.org/).

 ## [Unreleased]

+## [1.44.0] - 2026-10-27
+
+### Added
+
+- **Staff for some campuses** (Admin → Users → "Limit to campuses", while campuses are on). A
+  supervisor or staff member limited to some campuses sees only those campuses' events plus
+  events for all campuses — in every list, report, dashboard, the scanner and offline scanning.
+  - **Events for all campuses:** they can scan, register people and take payments at the door, but
+    not change them, cash them up or refund them (the event editor opens read-only).
+  - **New events** go at one of their campuses; they can't move events to another campus.
+  - **Admins and supervisors for every campus only:** the site banner, payment reconciliation and
+    open online checkouts, and donations not linked to an event.
+  - **Messages:** broadcasts only to people at their campuses or attendees of their events (no
+    typed-in addresses). **Coupons:** only for their campuses' events.
+  - Another campus's records answer "not found"; the **scanner says which campus** a ticket is
+    for. Staff still see their own registrations for any campus's event.
+  - Their dashboard says which campuses they work with. Admins are never limited, and limits are
+    ignored while campuses are off (the Campuses tab warns first). Changing someone's limits is in
+    the audit log; a campus with staff limited to it can't be deleted.
+  - Every staff and supervisor route declares how it handles campus limits, and a test fails on
+    any that doesn't (`tests/campusScopeRoutes.test.js`).
+
+## [1.43.0] - 2026-10-27
+
+### Added
+
+- **Campuses** (Site settings → Campuses, off by default) for a church with more than one campus
+  in one install. Churches with one campus see no campus fields anywhere.
+  - Admins turn campuses on, then add, order, archive and delete campuses: name, web address,
+    address, contact, colour, logo, default event location, and staff who get that campus's daily
+    summary. A campus with events can't be deleted, only archived. Turning campuses off hides
+    everything campus-related and deletes nothing.
+  - **Events** belong to one campus or to **All campuses** (church-wide). Choosing a campus fills
+    in its default location; moving an event to another campus is in the audit log. The Events
+    list in the dashboard shows each event's campus and has a campus filter.
+  - **Public site:** a campus filter on the events page, remembered in the visitor's browser and
+    starting on their home campus; a campus shows its own events plus church-wide ones. The campus
+    shows on event cards, the event page and ticket PDFs. **Campus pages** at `/campus/<slug>`
+    (also in the sitemap).
+  - **Home campus** on the profile page.
+  - **Reports and dashboards:** a campus filter on Reports (all reports and the funnel) and on the
+    admin and supervisor dashboards' past-month tiles, with a church-wide total.
+  - **Broadcasts:** "Everyone at a campus" in Email and WhatsApp broadcasts — people whose home
+    campus it is, plus (ticked) people who registered for its events in the last 12 months. News
+    consent still applies.
+  - **Daily summary:** campus recipients also get the summary of their campus's events.
+  - The Hub heartbeat reports whether campuses are on and how many there are (`campusCount`).
+  - Campus-scoped staff (supervisors and staff limited to some campuses) follow in 1.44.0.
+- The privacy notice lists the new `hope_events_campus` browser-storage item.
+
+### Fixed
+
+- "Request update" (1.42.0) wasn't written to the audit log: the `hub_update_requested` action was
+  missing from the database. The request itself always worked.
+
+## [1.42.1] - 2026-10-27
+
+### Changed
+
+- **The production Hub's public key is built in** (`backend/src/hub/publicKey.js`), so sites can
+  check licences without `HUB_PUBLIC_KEY` in their `.env`. `HUB_PUBLIC_KEY` still overrides it (for
+  a local Hub while developing).
+
+## [1.42.0] - 2026-10-27
+
+### Changed
+
+- **"Request update" instead of the deploy command.** When a new version is out, Site settings →
+  Licence shows a **Request update** button instead of `bash scripts/deploy.sh …`. It sends a
+  signed request to the Hub (`docs/hub-protocol.md` §3a), which tells the provider; the site never
+  updates itself. Afterwards it shows "Update requested on …" until the site runs that version, and
+  the "update available" banner for admins goes away. Logged in the audit log
+  (`hub_update_requested`). Needs Cross Events Hub 1.1.0; an older Hub answers "The Hub doesn't take
+  update requests yet".
+
+## [1.41.3] - 2026-10-27
+
+### Changed
+
+- **The platform is now called Cross Events** (and the Hub, Cross Events Hub): Site settings →
+  Licence, the "update available" banner, the setup wizard, the audit log, help and the docs.
+  Technical names stay as they are (`hope-events` repo, PM2 and nginx names, install folder, browser
+  storage keys), so existing installs and sign-ins keep working.
+
+## [1.41.2] - 2026-10-27
+
+### Fixed
+
+- **Background jobs page showed last-run times two hours ahead** (e.g. 12:55 at 10:55). Prisma's
+  Postgres adapter dropped the time-zone offset of pg-boss's timestamps; the query now reads them
+  as UTC. Job history itself was never wrong. `APP_TIMEZONE` is now in `backend/.env.example` and
+  SETTINGS.md.
+
+## [1.41.1] - 2026-10-27
+
+### Changed
+
+- **No licence now means read-only**, the same as a suspended licence: a site that isn't connected
+  to the Hub can't create events, registrations or payments until a licence key is connected
+  (admins see a red banner). `LICENCE_CHECK_DISABLED=true` switches this off outside production,
+  for the end-to-end tests.
+- **Read-only mode also blocks editing events**, their options and their variants (suspended,
+  revoked and unlicensed sites).
+- The site **checks in with the Hub 30 seconds after starting**, and 30 seconds after a licence
+  key is connected, instead of waiting up to 15 minutes.
+
+### Fixed
+
+- A site the Hub no longer knows (`INSTALL_NOT_FOUND`, e.g. the licence was released) kept showing
+  "Active" on its old licence. It now drops the connection and licence, and shows "No licence".
+
+## [1.41.0] - 2026-10-26
+
+### Added
+
+- **Hope Events Hub connection** (`docs/hub-protocol.md`). Each install connects to the Hub
+  (`events-hub.crosscode.co.za`) with a licence key:
+  - **Licence step in `/setup`** (on the last screen), and **Site settings → Licence** for existing
+    installs: connect, see the licence (licensed to, plan, end date, grace period), the last check-in,
+    and "Check now".
+  - A **heartbeat every 15 minutes** (`hub-heartbeat` job; `HUB_HEARTBEAT_ENABLED=false` to switch off):
+    version, health (database, background jobs, last backup, free disk, server errors, pending
+    migrations) and totals (users, events, registrations, tickets, check-ins, payment providers, income
+    as a range only). Never anyone's personal information.
+  - **Licences are checked on the site** with the Hub's public key, so a Hub outage never switches a
+    site off and a licence can't be faked by editing the database:
+    - **Grace period** (licence past its end date, default 14 days): everything works; **only site
+      admins** see "Licence needs renewing — X days left".
+    - **Suspended or revoked**: read-only — no new events, registrations, tickets, payments, waitlist
+      places, coupons or bundles. Tickets still scan; all data can still be viewed and exported;
+      refunds, cancellations and privacy requests still work.
+    - Not connected yet: works as before; admins see "Connect to the Hub".
+  - **Update available**: admins see when a newer version is out, with the command to run.
+- **`/health`** — status, version, database, background jobs and last backup, for monitoring.
+- **Install script** (`scripts/install.sh`): a fresh Ubuntu server to a running site in one command —
+  Node 20, PostgreSQL, PM2, nginx, HTTPS, configuration, migrations, build; then `/setup`.
+
+### Changed
+
+- The generic settings endpoints never read or write the Hub connection (install id, secret, licence).
+
+## [1.40.0] - 2026-10-23
+
+### Added
+
+- **POPIA toolkit, part 3.** Three new tabs on Admin → Privacy (POPIA):
+  - **Readiness** (now the first tab): a checklist with a score — Information Officer and legal details set, privacy notice published, operators described (no generic names, a location for each), retention reviewed and the job running, no overdue requests, breaches reported to the Regulator, unsubscribe links working (`BACKEND_URL` on https), email set up, WhatsApp STOP replies arriving, two-factor login required, backups running. Each open item links to where you fix it.
+  - **Retention**: how long personal information is kept, with what each setting would affect right now. A nightly job (`retention`, 03:30; `RETENTION_JOBS_ENABLED=false` to switch off) applies it:
+    - **Inactive accounts** — no login, registration, payment or being named as an attendee for **5 years**: a warning by email (or WhatsApp) 30 days before, then the account is anonymised. Logging in keeps it. Never staff, supervisors or admins, and never while they have a registration for an upcoming event. **On by default.**
+    - **Attendee form answers** — deleted 12 months after the event.
+    - **Login history** — kept 24 months.
+    - **Payer names and emails in Yoco/PayFast notifications** — removed after 24 months (payments themselves are kept).
+    - **Audit log, access log and "view as" sessions** — kept 5 years.
+    - Medical details, visit statistics and backups keep their existing settings, shown alongside. "Run now" applies them straight away.
+  - **Breaches**: a register of security compromises (what happened, what information, who, consequences, what was done, advice to the people affected), with status and the dates the Information Regulator and the people affected were told. Each entry has a draft message for the people affected and a summary for the Regulator's form, ready to copy.
+- **Children's and medical information** is flagged in the access log (medical lists, and anything about an event that asks for parental consent), with a filter.
+- The privacy notice gets a `{retention}` placeholder — one line per retention period, following the settings. The built-in notice uses it; if you already published your own version, add a line with `{retention}` to your retention section.
+
+## [1.39.0] - 2026-10-23
+
+### Added
+
+- **POPIA toolkit, part 2: the admin side.** A new **Admin → Privacy (POPIA)** page with four tabs:
+  - **Privacy notice editor.** The privacy notice is now editable. It starts from the built-in text (updated for 1.38.0's privacy page, news opt-in, unsubscribe and STOP), one box per section; add, remove and reorder sections, save drafts, preview, and **publish numbered versions**. Placeholders such as `{org}`, `{ioName}`, `{ioEmail}`, `{medicalRetentionDays}` and `{operators}` are filled in when the notice is shown, so it follows Site settings and the operator register. Earlier versions stay readable on the privacy page (`/legal/privacy?version=N`).
+  - **Re-accepting the notice.** When publishing, tick "Significant change" (and say what changed) to ask everyone to accept the new version: they're asked once, after their next login, with a link to delete their account instead. Sign-up records which version was accepted. Acceptances are counted per version.
+  - **Operators** — the register of outside services that handle personal information (Yoco, PayFast, WAWP, WhatsApp, email and hosting providers, Google Maps, Sentry), with what each receives and where. Those in use are listed in the notice.
+  - **Consent log** — every news opt-in/opt-out (and how), every privacy notice acceptance, and every parental consent answer, searchable by person.
+  - **Access log** — who downloaded, emailed or opened personal information in bulk: report PDFs/Excel files (and reports emailed or WhatsApped), attendance registers, certificate downloads, room/group lists, attendee form answers, the parental consent and medical lists, database backups, and every "view as" session. With how many records each time.
+- The contact page shows the Information Officer (when set in Site settings → Legal), with a link to the privacy notice.
+- "Download my data" includes the privacy notice versions you accepted.
+
+### Changed
+
+- Deleting someone's personal data also removes the IP addresses kept with their consent and notice records (the records stay as proof).
+
+## [1.38.0] - 2026-10-23
+
+### Added
+
+- **POPIA toolkit, part 1: privacy for the people in the system.**
+  - **Privacy page** (My account → Privacy): choose News & announcements by email and/or WhatsApp, see the history of those choices, **download my data** (a readable PDF, or the complete copy as JSON: account, registrations and the people registered, form answers, parental consent, payments, tickets and check-ins, certificates, feedback, communication choices), **ask for a correction**, and **delete my account**.
+  - **Two kinds of bulk message.** When emailing or WhatsApping attendees, or sending a broadcast, choose **Event update** (about an event the recipients registered for — goes to everyone selected) or **News & announcements** (only to people who opted in, with an unsubscribe link). Attendee messages default to event updates, broadcasts to news, and the next-event promo automation is always news. Previews say how many people were skipped.
+  - **Unsubscribe**: every news email ends with an unsubscribe link and carries one-click unsubscribe headers (Gmail, Apple Mail); every event update says why it was sent and links to the preferences. News WhatsApps end with "Reply STOP" and a link. Unsubscribed addresses without an account are remembered too.
+  - **WhatsApp STOP**: replying STOP (or "unsubscribe") to the church's number stops WhatsApp news and sends a confirmation. Needs WAWP's webhook pointed at the URL shown in Site settings → WhatsApp (it carries a secret, since WAWP doesn't sign webhooks).
+  - **News opt-in**: an unticked "news and announcements" box on sign-up. Existing accounts stay opted in (logged as "existing account") and are asked once, after their next login, to confirm or opt out. Every change is logged with when and how.
+  - **Data requests** (Admin → Data requests): correction and deletion requests with a 30-day due date, emailed to the Information Officer and admins, with a daily reminder for ones due within a week or overdue (`privacy` job, 08:00; `PRIVACY_JOBS_ENABLED=false` to switch off). Completing or rejecting a request emails the person and is in the audit log.
+
+### Changed
+
+- **Deleting an account is now a request.** "Delete my account" (and "Also delete my personal data" when closing an account) closes the account straight away; the personal information is deleted when an admin completes the request — after any registration for an upcoming event has been cancelled or the event is over.
+- **Deleting personal data now goes much further.** Before, it only cleared the account's name, email and phone. Now it also removes the names and details of the people they registered (and their own details on other people's bookings), form answers, parental-consent details, sponsor names, feedback authorship, pending transfer requests, certificate names, login history, and payer names/emails kept from Yoco and PayFast notifications. Payments, registrations, tickets and check-ins are kept, as "Deleted User", for the books and reports. Admin → Users → Anonymise uses the same deletion, and is refused while the person has a registration for an upcoming event.
+- "Download my data" is blocked while an admin is viewing as someone else.
+
+## [1.37.4] - 2026-10-23
+
+### Fixed
+
+- **Deploy script** (`scripts/deploy.sh`): without a tag it now deploys the latest `main`. The PM2 config is per install: `ecosystem.config.js` is no longer in git (the repo has `ecosystem.config.example.js`), so deploys stop overwriting the install's app names and port; the script keeps the install's copy across checkouts and rollbacks, and creates it from the example on a fresh install. The script also runs from a temporary copy (so checking out a new version of it mid-deploy is safe), and a failure rolls back once.
+
+## [1.37.3] - 2026-10-23
+
+### Fixed
+
+- The production build (and so the deploy) failed on unescaped quotes in the Payments help text.
+
+## [1.37.2] - 2026-10-23
+
+### Added
+
+- **Payment status checks** for when a provider's notification never arrives. Payments → Reconcile has a new "Waiting for payment" list: online checkouts from the last 14 days with no payment yet, each with "Check status" (and "Check all"). For PayFast it looks the payment up in PayFast's transaction history and, if PayFast received it, records it exactly as the notification would have (same amount check, tickets and emails). A background job does this every 15 minutes for checkouts between 10 minutes and 3 days old (`payment-status`, switch off with `PAYMENT_STATUS_JOB_ENABLED=false`). Yoco's API has no way to look a payment up, so Yoco checkouts show "can't check" — find them in the Yoco portal and record them with Reconcile, as before.
+- **Test connection** on the PayFast settings card: checks the saved merchant ID and passphrase with PayFast.
+
+## [1.37.1] - 2026-10-23
+
+### Changed
+
+- **No "Pay online" when it can't be used.** When no payment provider is switched on, or the amount is under the R15 minimum, the registration success page, My Events ("Make payment" and "Make donation"), the donate page, "Sponsor a spot", the donation box on the register form and the supervisor Payment Link tab no longer offer online payment. Where it helps, they say why and to pay at the event instead.
+- Roadmap: SnapScan and Zapper are dropped (Yoco and PayFast are enough); later releases move up two versions — POPIA toolkit is next as 1.38.0.
+
+## [1.37.0] - 2026-10-23
+
+### Added
+
+- **PayFast.** A second online payment provider (card, instant EFT and more). Switch it on in Site settings → Payments, then enter the merchant ID, merchant key and salt passphrase from your PayFast (or Sandbox) dashboard and choose Sandbox or Live. Payments are confirmed by PayFast's notification (ITN) at `/api/webhooks/payfast`, which is checked the way PayFast requires: the signature, that it came from PayFast, that PayFast confirms it, and that the amount matches the checkout. PayFast starts switched off.
+- **Choosing how to pay.** When more than one provider is on, payers choose on a new "Pay online" page (`/pay/…`). Payment links in emails, WhatsApp and invoices go there too, so they work for every provider.
+- Payer-facing wording no longer says Yoco: "Pay online" after registering, a neutral redirect message, and the Terms and Privacy pages name both providers (Yoco or PayFast), including that PayFast may receive your name and email to fill in its payment page.
+- A payment of a different amount from the checkout (e.g. changed along the way) isn't recorded automatically: it waits in "Unreconciled Online Payments" with a note explaining why.
+
+## [1.36.0] - 2026-10-23
+
+### Added
+
+- **Site settings → Payments** (replaces the Yoco tab): turn each online payment provider on or off and set their order. The first one enabled and set up is used by default. Yoco's keys and webhook settings are on the same tab. Yoco is the only provider for now; PayFast, SnapScan and Zapper follow in the next releases. If no provider is on and set up, online payments are off and people pay at the door.
+
+### Changed
+
+- Online payments go through one payment provider layer (`backend/src/payments`). Yoco works exactly as before: the same checkout, the same webhook URL (`/api/webhooks/yoco`) and the same reconciliation.
+- **Online payments must be at least R15**, for every kind of online payment (balance, part-payment, donation, sponsorship). A smaller balance is paid at the door.
+- Payments record which provider took them (`provider`, e.g. "yoco"); existing online payments are marked as Yoco. The payment method (card, Apple Pay…) is unchanged, so cashups and reports add up as before. Provider fees are still never deducted or added — they're handled at cashup.
+- Yoco transactions are now "provider transactions" (`/api/provider-transactions`, with `/api/yoco-transactions` still working). The Payments page's reconcile list is called "Unreconciled Online Payments" and shows the provider. The database table is renamed in place, so stored transactions are kept.
+- The checkout endpoint is now `POST /api/payments/checkout` (with an optional `provider`); `/api/payments/yoco-checkout` still works.
+
+## [1.35.1] - 2026-10-23
+
+### Added
+
+- **Waitlist per session.** On pick-sessions events, a full session shows "Join waitlist" in the session list, and the waitlist works per session: when a place in that session frees up, the next person waiting for it gets the offer. Offers never run past the session's start, and nobody is offered a session that has started or was cancelled. The claim link ticks the session for them. My Events, the claim page and the supervisor Waitlist page show which session an entry is for.
+- **"All sessions" tickets on pick-sessions events let people choose their sessions.** When an event's "How people book" is "Pick sessions", every ticket now shows the session list. A ticket set to "All sessions" is still one ticket at one price, whatever is ticked. The ticket then only scans on the ticked sessions (online and offline), and the attendance register, certificates, session reminders and session capacity follow them. Tickets and the ticket email list the ticked dates. A ticket set to "Pick sessions" is still charged per session. Events booked as "The whole course" show no session list. Bookings made before this cover every session, as before.
+- **Session picker at the door.** The At the door "Select items" pop-up now has the session picker for per-session tickets, so walk-ins can be booked straight in. For a new attendee, a place in today's session is selected by default when there's room.
+
+### Changed
+
+- Per-session tickets show their list of sessions straight away (on the registration page, Manual registration, At the door and the self-service kiosk). Before, the list only appeared after pressing "+", so it wasn't obvious you could choose sessions. Ticking a session sets the quantity to 1.
+
+### Fixed
+
+- Per-session stock limits on pick-sessions tickets weren't being enforced, and the public event page lost all stock information on events with such a ticket.
+- The offline-scanning service worker served the app's script files from its cache first, for good. On a development server, where those files keep their names when they change, a browser that had opened the scanner kept running old code on every page, even after a hard reload. It now fetches them from the network and uses the cache only when offline. Its cache is renamed, so old copies are cleared.
+- At the door, editing a registration that has per-session tickets could no longer be saved ("below the quantity already issued").
+- Whole-course tickets: the waitlist now also counts room in sessions that have a capacity, so it no longer says "places available" when a session is full. Places held for waitlist offers now count towards session capacity.
+
 ## [1.35.0] - 2026-10-23

 ### Added
@@ -0,0 +1,342 @@
+# Deploying Cross Events behind frp
+
+This guide is for a server that is **not reachable from the internet directly**: it runs
+`frpc`, which opens a tunnel to `frps` on a public server (the "VPS"). Visitors reach the VPS,
+and frp carries the traffic through to this server. The frp client config lives at
+**`/etc/frp/frpc.ini`**.
+
+For a server with a public IP, `scripts/install.sh` does everything (see the README). Behind frp
+it needs a few changes, because:
+
+- **HTTPS can't be set up by the installer.** DNS points at the VPS, not at this server, so
+  `certbot --nginx` can't work the usual way. HTTPS ends either on the VPS or in `frpc`.
+- **There are more proxies in the way.** The app must be told which of them to trust, or it sees
+  every visitor as `127.0.0.1` (rate limiting then treats everyone as one person, and PayFast
+  payment notifications fail their IP check).
+- **The app must know the site is HTTPS** even though nginx on this server only speaks HTTP;
+  otherwise it builds `http://` links (event images, payment return URLs).
+
+## 1. How the traffic flows
+
+Pick the setup that matches how your other frp sites get HTTPS.
+
+**A. HTTPS ends on the VPS** (nginx/Caddy on the VPS holds the certificate) — recommended if the
+VPS already does this for other sites:
+
+```
+visitor ──https──▶ VPS nginx/Caddy ──http──▶ frps (vhost_http_port) ══tunnel══▶ frpc ──▶ nginx :80 ──▶ app
+```
+
+**B. HTTPS ends in frpc** (the VPS only runs frps; the certificate lives on this server and
+frpc's `https2http` plugin uses it):
+
+```
+visitor ──https──▶ frps (vhost_https_port) ══tunnel══▶ frpc https2http ──▶ nginx 127.0.0.1:8080 ──▶ app
+visitor ──http───▶ frps (vhost_http_port)  ══tunnel══▶ frpc ──▶ nginx :80 (certificate check + redirect to https)
+```
+
+On this server, nginx sends `/api`, `/uploads`, `/health` and `/docs` to the backend (port 5000)
+and everything else to the Next.js site (port 3000), the same as a normal install.
+
+## 2. Before you start
+
+- Ubuntu 22.04 or 24.04 on this server, with `frpc` already installed and connected (it runs as
+  a systemd service, usually `frpc.service`).
+- The site's DNS record (e.g. `events.yourchurch.org`) points at the **VPS**.
+- On the VPS, `frps.ini` has `vhost_http_port` set (and `vhost_https_port` for setup B). Note
+  the values; you need them below.
+- The licence key for this site from the Cross Events Hub.
+
+## 3. Install the app
+
+On this server, as root, run the installer **without** its certificate step:
+
+```bash
+curl -fsSLO https://c-git.crosscode.co.za/joshua/hope-events/raw/branch/main/scripts/install.sh
+sudo bash install.sh --domain events.yourchurch.org --no-ssl --version v1.41.2
+```
+
+It installs Node 20, PostgreSQL, PM2 and nginx, creates the database, writes the config, builds
+and starts the app (in `/opt/hope-events`, run by the `hopeevents` user). Use `--name`, `--dir`,
+`--web-port` and `--api-port` if other apps already use those names or ports; adjust the ports
+below to match.
+
+### Switch the URLs to https
+
+With `--no-ssl` the installer writes `http://` addresses. Change them to `https://`:
+
+```bash
+cd /opt/hope-events
+sudo sed -i 's#=http://#=https://#' backend/.env frontend/.env.production
+grep -E 'URL=' backend/.env frontend/.env.production   # all should now start with https://
+```
+
+While `backend/.env` is open, set which proxies to trust (all of them run on loopback in both
+setups; see [step 7](#7-check-that-visitor-addresses-come-through) to confirm):
+
+```bash
+sudo sed -i 's#^TRUST_PROXY=.*#TRUST_PROXY=loopback#' backend/.env
+```
+
+`NEXT_PUBLIC_API_URL` is baked in when the site is built, so rebuild the frontend and restart:
+
+```bash
+sudo -u hopeevents -H bash -lc 'cd /opt/hope-events/frontend && npm run build'
+sudo -u hopeevents -H bash -lc 'cd /opt/hope-events && pm2 reload ecosystem.config.js --update-env'
+```
+
+Keep `JWT_SECRET` in `backend/.env` as it is: it also encrypts the secrets stored in the
+database (SMTP, payment keys).
+
+## 4. nginx on this server
+
+The installer wrote `/etc/nginx/sites-available/hope-events`. Replace it with the version for
+your setup, changing the domain (and the ports if you changed them).
+
+### Setup A (HTTPS on the VPS)
+
+```nginx
+# Shows the forwarded-for chain in the access log (see step 7). Safe to keep.
+log_format hope_proxy '$remote_addr xff="$http_x_forwarded_for" "$request" $status';
+
+server {
+    listen 80;
+    server_name events.yourchurch.org;
+    client_max_body_size 25m;
+    access_log /var/log/nginx/hope-events.access.log hope_proxy;
+
+    # Visitors only reach this through the VPS over HTTPS, so tell the app so.
+    location ~ ^/(api|uploads|health|docs)(/|$) {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+}
+```
+
+The VPS nginx/Caddy must redirect plain HTTP to HTTPS and pass the `Host` header through to frps
+unchanged (frps picks the site by its host name). For nginx on the VPS, roughly:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name events.yourchurch.org;
+    # ssl_certificate / ssl_certificate_key from certbot on the VPS
+    client_max_body_size 25m;
+    location / {
+        proxy_pass http://127.0.0.1:8080;          # frps vhost_http_port
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+### Setup B (HTTPS in frpc)
+
+Port 80 only answers certificate checks and redirects everything else; the real site is on
+`127.0.0.1:8080`, which only frpc's `https2http` plugin reaches.
+
+```nginx
+log_format hope_proxy '$remote_addr xff="$http_x_forwarded_for" "$request" $status';
+
+server {
+    listen 80;
+    server_name events.yourchurch.org;
+    location /.well-known/acme-challenge/ { root /var/www/certbot; }
+    location / { return 301 https://$host$request_uri; }
+}
+
+server {
+    listen 127.0.0.1:8080;
+    server_name events.yourchurch.org;
+    client_max_body_size 25m;
+    access_log /var/log/nginx/hope-events.access.log hope_proxy;
+
+    location ~ ^/(api|uploads|health|docs)(/|$) {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+}
+```
+
+Then, for either setup:
+
+```bash
+sudo mkdir -p /var/www/certbot          # setup B only
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+## 5. frpc: `/etc/frp/frpc.ini`
+
+Back it up first, then **add** a section for the site below the existing ones. Leave `[common]`
+(server address, port, token) and the other sections as they are. Section names must be unique
+across everything connected to your frps.
+
+```bash
+sudo cp /etc/frp/frpc.ini /etc/frp/frpc.ini.bak-$(date +%F)
+sudo nano /etc/frp/frpc.ini
+```
+
+### Setup A
+
+```ini
+[hope-events-http]
+type = http
+local_ip = 127.0.0.1
+local_port = 80
+custom_domains = events.yourchurch.org
+```
+
+### Setup B
+
+```ini
+# Plain HTTP: certificate checks and the redirect to https
+[hope-events-http]
+type = http
+local_ip = 127.0.0.1
+local_port = 80
+custom_domains = events.yourchurch.org
+
+# HTTPS: frpc holds the certificate and passes plain HTTP to nginx on 127.0.0.1:8080
+[hope-events-https]
+type = https
+custom_domains = events.yourchurch.org
+plugin = https2http
+plugin_local_addr = 127.0.0.1:8080
+plugin_crt_path = /etc/letsencrypt/live/events.yourchurch.org/fullchain.pem
+plugin_key_path = /etc/letsencrypt/live/events.yourchurch.org/privkey.pem
+plugin_header_X-Forwarded-Proto = https
+```
+
+Restart frpc and check it registered the new sections without errors:
+
+```bash
+sudo systemctl restart frpc
+sudo journalctl -u frpc -n 30 --no-pager      # look for "start proxy success" for each section
+```
+
+> Newer frp releases (0.52+) prefer `frpc.toml`, but still read `.ini`. Don't mix the two: if
+> your service already uses `frpc.ini`, keep adding to it.
+
+### Certificate (setup B only)
+
+Request it through the tunnel with the webroot method (not `--nginx`, which would rewrite the
+nginx config), then have renewals restart frpc so it loads the new certificate:
+
+```bash
+sudo apt-get install -y certbot
+sudo certbot certonly --webroot -w /var/www/certbot -d events.yourchurch.org \
+  -m you@yourchurch.org --agree-tos --non-interactive
+echo 'systemctl restart frpc' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-frpc.sh
+sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-frpc.sh
+sudo systemctl restart frpc
+```
+
+frpc needs to be able to read the certificate files (it does when it runs as root, the usual
+setup). If the `[hope-events-https]` section fails to start, check `journalctl -u frpc`.
+
+## 6. Finish in the browser
+
+1. Open `https://events.yourchurch.org/health` — it should answer with the version.
+2. Open `https://events.yourchurch.org/setup`: create the admin account.
+3. **Site settings → Licence**: enter the licence key to connect to the Hub. The site checks in
+   every 15 minutes from then on (outgoing HTTPS to `events-hub.crosscode.co.za`, which frp
+   doesn't affect).
+4. Configure SMTP, payments (Yoco/PayFast webhooks use the `https://` `BACKEND_URL`), branding,
+   etc. in Site settings.
+
+## 7. Check that visitor addresses come through
+
+Open the site from your phone (on mobile data, so it isn't your own network), then on the
+server:
+
+```bash
+sudo tail -n 5 /var/log/nginx/hope-events.access.log
+```
+
+The `xff="…"` part is what the app sees, with nginx's own entry added at the end:
+
+- `xff="<your phone's IP>, 127.0.0.1"` (only `127.0.0.1` after the real address): good,
+  `TRUST_PROXY=loopback` is right.
+- `xff="<your phone's IP>, 203.0.113.10"` (a non-local address after it, e.g. the VPS's): add
+  that address: `TRUST_PROXY=loopback,203.0.113.10`, then
+  `pm2 reload ecosystem.config.js --update-env`.
+- Your phone's IP doesn't appear at all: frp isn't passing the visitor's address on (can happen
+  with setup B on some frp versions). Rate limiting and the PayFast IP check will then misbehave.
+  Fix it by moving TLS to the VPS (setup A), or with frp's `proxy_protocol_version = v2` on the
+  frpc section plus nginx's `listen … proxy_protocol` and `set_real_ip_from 127.0.0.1;
+  real_ip_header proxy_protocol;`.
+
+The backend logs the setting it uses at startup: `pm2 logs hope-events-backend | grep trust`.
+
+## 8. Updating
+
+Nothing about frp changes for updates. On the server:
+
+```bash
+cd /opt/hope-events
+sudo -u hopeevents -H bash scripts/deploy.sh v1.41.2     # or no tag for the latest main
+```
+
+It backs up the database, checks out the release, installs, migrates, builds and reloads PM2,
+and goes back to the previous version if anything fails first. `backend/.env`,
+`frontend/.env.production`, `ecosystem.config.js` and the nginx/frpc configs are not in git, so
+updates keep your changes from this guide.
+
+### Deploying from CI over SSH
+
+The Gitea workflow deploys on a `v*` tag by SSHing to `DEPLOY_HOST`. Behind frp, that needs an
+SSH tunnel too, e.g. in `frpc.ini`:
+
+```ini
+[hope-events-ssh]
+type = tcp
+local_ip = 127.0.0.1
+local_port = 22
+remote_port = 6022
+```
+
+Then use the VPS as `DEPLOY_HOST`. The workflow's `ssh` call (`.gitea/workflows/ci.yml`) doesn't
+take a port yet, so add `-p 6022` there (or a `DEPLOY_PORT` secret) before relying on it. Only
+open this if you need it: it exposes this server's SSH on the VPS. Use key-only login. Deploying
+by hand (above) needs none of this.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| frps shows "404 Not Found" page | The `custom_domains` value doesn't match the address typed, or frpc didn't start that section (`journalctl -u frpc`). |
+| 502 Bad Gateway | nginx is up but the app isn't: `sudo -u hopeevents pm2 ls` and `pm2 logs`. |
+| Site loads but login/API calls fail (CORS) | `FRONTEND_URL` in `backend/.env` is still `http://`, or the frontend wasn't rebuilt after changing `NEXT_PUBLIC_API_URL`. |
+| Images or links use `http://` (browser "mixed content" warnings) | nginx isn't sending `X-Forwarded-Proto https`, or `TRUST_PROXY` isn't set. |
+| "Too many requests" for everyone at once | All visitors look like one address: see step 7. |
+| PayFast payments stay pending | Same as above: the PayFast notification's IP check sees the proxy, not PayFast. |
+| Uploads over ~1 MB fail | `client_max_body_size` missing on this server's nginx or the VPS's. |
+| Redirect loop (setup B) | The site's `server` block is on port 80 instead of `127.0.0.1:8080`, or `plugin_local_addr` points at port 80. |
@@ -1,4 +1,4 @@
-# Hope Events — Feature Overview
+# Cross Events — Feature Overview

 A complete map of what the platform does, grouped by who uses it. For setup and
 deployment see [README.md](./README.md); for the API see
@@ -29,11 +29,13 @@ WhatsApp · PM2 for process management · optional Sentry for error monitoring.
 13. [Cashup & event costs](#cashup--event-costs)
 14. [Reports](#reports)
 15. [Site settings & setup wizard](#site-settings--setup-wizard)
-16. [Accounts & security](#accounts--security)
-17. [Help system](#help-system)
-18. [Background jobs](#background-jobs)
-19. [Operations](#operations)
-20. [Page map](#page-map)
+16. [Multi-campus](#multi-campus)
+17. [Accounts & security](#accounts--security)
+18. [Privacy (POPIA)](#privacy-popia)
+19. [Help system](#help-system)
+20. [Background jobs](#background-jobs)
+21. [Operations](#operations)
+22. [Page map](#page-map)

 ---

@@ -104,7 +106,12 @@ Feedback → Attendance**.
  whole-course tickets. Sessions can have a capacity (picked places plus whole-course
  tickets); a per-session ticket's stock limit is places per session. Picked tickets
  only scan on their own session; reminders, the register and certificates follow
-  the sessions each person booked. Not available on youth events.
+  the sessions each person booked. "All sessions" tickets on such an event also show
+  the sessions: people tick the ones they'll come to and pay the ticket's one price; the
+  ticket scans, reminds and counts towards capacity for those sessions only. The waitlist
+  works per session (a full session shows "Join waitlist"). Bookable from the registration page, Manual registration,
+  At the door (today's session is preselected) and the kiosk. Not available on youth
+  events.
 - **Late joining** (multi-day) — registration closes when the first session
  starts, or later (until session N) with late joining on. Late joiners pay
  full price, a pro-rata price for the sessions left (rounded to the nearest
@@ -169,7 +176,8 @@ Feedback → Attendance**.
  emailed/WhatsApped a claim link and the places are held for them (24 hours by
  default) so nobody else can buy them. Unclaimed offers expire and move on; people
  who asked for more than came free can be offered what's free or skipped. Claiming
-  works without logging in. People can leave from My Events.
+  works without logging in. People can leave from My Events. On pick-sessions events
+  people wait for a particular session; offers never run past the session's start.
 - **Parental consent (youth events)** — on events that require it, every attendee
  gives a date of birth; for anyone under 18, a parent or guardian gets an email and
  a WhatsApp with a consent link. They read the event's consent text, optionally give
@@ -194,7 +202,17 @@ Feedback → Attendance**.

 - **Online card payments via Yoco** — checkout for the full outstanding balance,
  confirmed by a signed webhook. Keys and the webhook are set up from
-  Site Settings → Yoco.
+  Site Settings → Payments, where providers are switched on or off and put in order
+  (the first one is the default). Online payments are at least R15; payments are
+  recorded at the full amount and provider fees are dealt with at cashup.
+- **PayFast** — the second online provider (card, instant EFT…), with sandbox and live
+  modes. When several providers are on, payers choose on the "Pay online" page; a
+  payment of a different amount from the checkout is held for review instead of being
+  recorded. When no provider is on (or the amount is under R15), nothing offers to pay
+  online.
+- **Payment status checks** — if a provider's notification never arrives, Payments →
+  Reconcile → "Waiting for payment" checks with the provider (PayFast; Yoco's API can't be
+  asked) and records what it finds. A job checks recent PayFast checkouts every 15 minutes.
 - **Payment links** — supervisors can generate and send a Yoco link for any
  amount (including partial).
 - **Manual payments** — cash, card, EFT, voucher or other, recorded by staff.
@@ -245,7 +263,7 @@ Feedback → Attendance**.
  Supervisors can **assign** a donation (fully or partly) to someone's
  registration and **unassign** it later. Assignments are kept as separate
  records, so the original donation never changes.
- **Yoco reconciliation** — imported Yoco transactions can be matched to a
+- **Online payment reconciliation** — provider (Yoco) transactions can be matched to a
  registration, recorded as a donation (optionally choosing the donor), or
  ignored.
 - **Invoices & receipts** — branded PDFs: an invoice (itemised, early-bird
@@ -327,6 +345,8 @@ Every user picks a **notification preference**: Email, WhatsApp, or Both.
  outstanding balance).
 - **Broadcasts** — ad-hoc email/WhatsApp to any users or addresses, not tied to
  one event.
+- **Message type** — Event update or News & announcements; news only reaches people
+  who opted in (see [Privacy](#privacy-popia)).
 - **Automations** — schedule a sequence of lifecycle emails for an event
  (pre-event, final reminder, thank-you, promo for another event).
 - **Manage scheduled** — view, edit or delete queued jobs per channel. Sends
@@ -428,6 +448,8 @@ logout controls. Disconnected sessions are recovered automatically.
 - **Manage users** — server-side search and filters (role, active), paging,
  edit role and notification preference, revoke sessions, delete or
  **anonymise** personal data.
+- **Data requests** — POPIA correction and deletion requests (see
+  [Privacy](#privacy-popia)).
 - **Registrations** — all registrations, with filters (event, status, text),
  status counts, revenue and outstanding totals, and per-registration options,
  form answers and payments (with who recorded each one).
@@ -490,18 +512,48 @@ applied without a restart. Secrets are encrypted with AES-256-GCM.
 | Tab | Contains |
 |-----|----------|
 | Organisation | Name, tagline, contact email/phone, address (with map link) |
+| Campuses | Off by default. Turn on, then add, order, archive or delete campuses (name, web address, address, contact, colour, logo, default event location, daily-summary recipients) |
 | Branding | Primary/secondary/accent colours, logo, favicon, colours suggested from the logo, live website/email preview on desktop and mobile |
 | Notifications | Registrations inbox and admin notification emails |
 | Email | SMTP host/port/TLS/user/password/from, with a "Test connection" button |
 | Legal | Operator, Information Officer, website, effective date for the Terms/Privacy pages |
 | WhatsApp | WAWP credentials, connect a number, status/restart/logout |
-| Yoco | Secret key (masked, test/live), webhook secret (generate by registering with Yoco, or enter), list/delete the account's webhooks |
+| Payments | Online payment providers: Enabled toggle and order; PayFast merchant ID/key, passphrase and sandbox/live; Yoco's secret key (masked, test/live), webhook secret (generate by registering with Yoco, or enter), list/delete the account's webhooks |
 | Backups | List, run now, download database backups |

 See [SETTINGS.md](./SETTINGS.md) for the default of every setting.

 ---

+## Multi-campus
+
+For a church with several campuses in one install (Site settings → Campuses, off by
+default — single-campus churches never see campus fields).
+
+- **Events** belong to one campus or to **All campuses** (church-wide). Choosing a campus fills in
+  its default location. Moving an event to another campus is in the audit log.
+- **Public site:** a campus filter on the events page, remembered per visitor and starting on their
+  home campus; a campus shows its own events plus church-wide ones. The campus shows on event cards,
+  the event page and ticket PDFs. Each campus has a page at `/campus/<slug>` (also in the sitemap).
+- **People** choose a home campus on their profile.
+- **Reports and dashboards:** a campus filter on Reports (every report and the funnel) and on the
+  admin/supervisor dashboards' month-over-month tiles, with a church-wide total.
+- **Messages:** "Everyone at a campus" in Email and WhatsApp broadcasts — home campus, plus (ticked)
+  people who registered for its events in the last 12 months. News consent still applies.
+- **Daily summary:** campus recipients get the summary of their campus's events.
+- **Turning it off** hides everything campus-related; nothing is deleted. A campus with events can't
+  be deleted, only archived.
+- **Staff for some campuses** (Admin → Users → "Limit to campuses"): a supervisor or staff member
+  sees only their campuses' events plus events for all campuses — every list, report, dashboard
+  and scanner follows it. For church-wide events they can scan, register people and take payments
+  at the door, but not change, cash up or refund them. The site banner, payment reconciliation and
+  donations not linked to an event are for admins and unscoped supervisors; broadcasts only reach
+  people at their campuses or their events' attendees; coupons only for their campuses' events.
+  Another campus's records answer "not found"; the scanner says which campus a ticket is for.
+  Admins are never limited; limits are ignored while campuses are off.
+
+---
+
 ## Accounts & security

 - Register, log in, forgot/reset password, activate account (for accounts
@@ -520,13 +572,78 @@ See [SETTINGS.md](./SETTINGS.md) for the default of every setting.
  (`TRUST_PROXY` to read real IPs behind a proxy).
 - **Security event log** — logins, password changes and resets, with device
  and IP.
- **Account closure** — deactivate, or anonymise personal data while keeping
-  financial records.
+- **Account closure** — deactivate, or close and ask for the personal data to be
+  deleted (see [Privacy](#privacy-popia)).
 - **Upload hardening** — server-generated filenames, and uploads served with a
  sandbox CSP and `nosniff`.

 ---

+## Privacy (POPIA)
+
+Tools that help a church handle personal information the way POPIA expects. They
+support compliance; wording and retention choices are for the church's Information
+Officer.
+
+**For everyone** — the **Privacy** page (`/dashboard/user/privacy`):
+
+- **News & announcements** opt-in per channel (email, WhatsApp), with the history of
+  every choice: when, and how (sign-up, privacy page, unsubscribe link, STOP reply…).
+  Sign-up has an unticked opt-in box; accounts that never answered are asked once
+  after logging in.
+- **Download my data** — readable PDF, or the complete copy as JSON.
+- **Correct my data** — profile fields directly; anything else as a correction request.
+- **Delete my account** — closes the account at once and files a deletion request.
+
+**Bulk messages** are either an **Event update** (about an event the recipients
+registered for; always sent) or **News & announcements** (only to people who opted in
+on that channel and haven't unsubscribed). News emails carry an unsubscribe link and
+one-click `List-Unsubscribe` headers; news WhatsApps end with "Reply STOP" and a link.
+Event updates say why they were sent and link to the preferences. A STOP reply on
+WhatsApp turns off WhatsApp news (through WAWP's `message` webhook, checked against a
+secret in the webhook URL).
+
+**Privacy notice** (`/legal/privacy`) — edited in **Admin → Privacy (POPIA)**
+(`/dashboard/admin/privacy`): sections start from the built-in text; drafts, preview,
+and published, numbered versions (earlier ones stay readable with `?version=N`).
+Placeholders (`{org}`, `{ioName}`, `{ioEmail}`, `{website}`, `{orgEmail}`,
+`{medicalRetentionDays}`, `{operators}`) are filled in from Site settings and the
+operator register. A version marked as a significant change is accepted once by everyone
+after their next login; sign-up records the version accepted. The contact page shows the
+Information Officer.
+
+**Registers and logs** (same admin page):
+
+- **Operators** — the services that process personal information (payment, WhatsApp,
+  email, hosting, maps, error monitoring), what each receives and where; those in use
+  are listed in the notice.
+- **Consent log** — news opt-ins/opt-outs, privacy notice acceptances and parental consent
+  answers, searchable.
+- **Access log** — every bulk export or view of personal information (reports, attendance
+  registers, certificates, group lists, form answers, consent and medical lists, backups)
+  and every "view as" session, with the number of records. Children's and medical
+  information is flagged (medical lists, and anything about a youth event).
+- **Retention** — how long each kind of personal information is kept, applied by a nightly
+  job: inactive accounts anonymised after 5 years (warning 30 days before; never staff
+  roles or people with an upcoming registration), form answers deleted 12 months after
+  the event, login history kept 24 months, payer details in payment notifications removed
+  after 24 months, audit/access logs kept 5 years. The notice's `{retention}` placeholder
+  lists them.
+- **Breaches** — the register of security compromises, with when the Information Regulator
+  and the people affected were told, and drafts of both notifications.
+- **Readiness** — a scored checklist of what's set up, each item linking to its fix.
+
+**For admins** — **Data requests** (`/dashboard/admin/data-requests`): correction and
+deletion requests with a 30-day due date, emailed to the Information Officer and
+admins, reminded daily when due within a week. Completing a deletion anonymises the
+person: name, contact details, the people they registered, form answers, consent
+details, sponsor names, login history and payer details in provider notifications are
+removed; payments, registrations, tickets and check-ins stay as "Deleted User". It
+waits while they have a registration for an upcoming event. Everything is in the audit
+log.
+
+---
+
 ## Help system

 A floating **"Need help?"** button on every page opens a page-specific guide
@@ -550,9 +667,13 @@ can't start, the same jobs run on in-process timers.
 | Scheduled email/WhatsApp worker | Polls every 30 s (`SCHEDULED_EMAILS_INTERVAL_MS`) and purges sent jobs after 24 h (not on the queue) |
 | `daily-summary` — daily event summary email | 07:00 daily (`DAILY_SUMMARY_ENABLED=false` to disable) |
 | `waitlist` — expire unclaimed offers, offer freed places | Every 10 minutes (`WAITLIST_JOB_ENABLED=false`) |
+| `payment-status` — look up PayFast checkouts (10 min – 3 days old) whose notification never arrived, and record them | Every 15 minutes (`PAYMENT_STATUS_JOB_ENABLED=false`) |
 | `feedback` — post-event feedback forms and their 3-day reminder | Every 15 minutes (`FEEDBACK_JOB_ENABLED=false`) |
 | `sessions` — session reminders, and certificates for events that ended in the last 14 days | Every 5 minutes (`SESSION_JOBS_ENABLED=false`) |
 | `consent` — parental consent reminders, and deleting medical details after events | 09:00 daily (`CONSENT_JOBS_ENABLED=false`) |
+| `privacy` — remind admins of privacy requests due within a week or overdue | 08:00 daily (`PRIVACY_JOBS_ENABLED=false`) |
+| `retention` — delete/anonymise personal information past its retention period (Admin → Privacy → Retention) | 03:30 daily (`RETENTION_JOBS_ENABLED=false`) |
+| `hub-heartbeat` — check in with the Cross Events Hub and pick up licence changes (only once connected) | Every 15 minutes (`HUB_HEARTBEAT_ENABLED=false`) |
 | `analytics-rollup` — roll raw visit rows older than 90 days into daily totals | 04:15 daily (`ANALYTICS_ROLLUP_ENABLED=false`) |
 | `backup` — database backup (`pg_dump`, gzipped, 14-day retention) | 02:00 daily (`BACKUP_ENABLED=false`) |
 | `temp-cleanup` — temp files older than 7 days in `/temp` | 03:00 daily |
@@ -561,6 +682,18 @@ can't start, the same jobs run on in-process timers.

 ## Operations

+- **Install script** (`scripts/install.sh`) — a fresh Ubuntu server to a running site: Node 20,
+  PostgreSQL, PM2, nginx, HTTPS, configuration, migrations and build; then `/setup`.
+- **Cross Events Hub** — every install connects with a licence key (`/setup`, or Site settings →
+  Licence) and checks in every 15 minutes with its version, health and totals (no personal
+  information; income as a range). Licences are signed tokens checked on the site, so a Hub outage
+  never switches it off: past the end date there's a grace period (banner for site admins only),
+  then — or when suspended, revoked or not licensed — the site is read-only (events can't be
+  created or edited; no new registrations or payments; tickets still scan, data can be exported).
+  The site checks in 30 seconds after starting and after a licence key is connected. Admins see when an update is available and press **Request update**,
+  which tells the provider through the Hub (the site never updates itself).
+  See `docs/hub-protocol.md`.
+- **`/health`** — status, version, database, background jobs and last backup.
 - **PM2** (`ecosystem.config.js`) runs backend and frontend, restarting either
  one above 500 MB of memory.
 - **Sentry** error monitoring when `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` are
@@ -587,10 +720,12 @@ can't start, the same jobs run on in-process timers.
 |------|-----|------|
 | `/` | Public | Home |
 | `/events`, `/events/[id]` | Public | Event list and detail |
+| `/campus/[slug]` | Public | A campus's page and its events (while campuses are on) |
 | `/[alias]` | Public | Event short link |
 | `/register/[eventId]` | Public / User | Registration |
 | `/registration/success` | Public / User | Confirmation, form and pay |
-| `/payment/success`, `/payment/failure`, `/payment/cancel` | Public | Yoco return pages |
+| `/pay/[id]` | Public | Pay online: choose a provider, or go on to PayFast |
+| `/payment/success`, `/payment/failure`, `/payment/cancel` | Public | Return pages after paying online |
 | `/forms` | Public / User | Attendee forms |
 | `/contact`, `/legal/terms`, `/legal/privacy`, `/lockdown-rules` | Public | Info pages |
 | `/login`, `/register`, `/forgot-password`, `/reset-password`, `/activate-account` | Public | Accounts |
@@ -598,9 +733,10 @@ can't start, the same jobs run on in-process timers.
 | `/consent/[token]` | Parent/guardian | Give or decline parental consent |
 | `/waitlist/claim/[token]` | Public | Claim a waitlist place |
 | `/certificates/verify/[code]` | Public | Check a completion certificate |
+| `/unsubscribe?t=…` | Public | Unsubscribe from news (link in news emails/WhatsApps) |
 | `/self-service` | Supervisor-unlocked | Kiosk |
 | `/set-banner` | Supervisor | Site banner |
-| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/reset-password`) | User | My Events |
+| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/reset-password`) | User | My Events |
 | `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`) | Staff | Staff tools |
 | `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools |
-| `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/audit-log`, `/settings`) | Admin | Admin tools |
+| `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/audit-log`, `/data-requests`, `/privacy`, `/settings`) | Admin | Admin tools |
@@ -1,6 +1,6 @@
-# Hope Events Platform
+# Cross Events Platform

-Hope Events is a full-stack event management platform that allows users to browse events, register for them, make payments, and manage their tickets.
+Cross Events is a full-stack event management platform that allows users to browse events, register for them, make payments, and manage their tickets.

 ## Project Structure

@@ -67,7 +67,7 @@ Documentation: see Frontend README for environment and scripts.
  Example for default backend: NEXT_PUBLIC_API_URL=http://localhost:5000

 - Organisation name, logo, brand colour, and notification emails are configured via the admin panel (Admin → Site Settings) and do not need to be set in .env files.
- Yoco payments are set up in Admin → Site Settings → Yoco: paste the secret key, then generate the webhook (or enter its secret). YOCO_SECRET_KEY / YOCO_WEBHOOK_SECRET in backend/.env still work as fallbacks.
+- Yoco payments are set up in Admin → Site Settings → Payments: paste the secret key, then generate the webhook (or enter its secret). YOCO_SECRET_KEY / YOCO_WEBHOOK_SECRET in backend/.env still work as fallbacks.

 ### 3) Run the apps

@@ -98,8 +98,38 @@ Documentation: see Frontend README for environment and scripts.

 ## Deployment

-To update a running install to a release: `bash scripts/deploy.sh v1.34.0` on the server
-(backs up the database, migrates, builds, reloads PM2).
+### A new install
+
+On a fresh Ubuntu 22.04/24.04 server, with the domain's DNS already pointing at it:
+
+```bash
+curl -fsSLO https://c-git.crosscode.co.za/joshua/hope-events/raw/branch/main/scripts/install.sh
+sudo bash install.sh --domain events.yourchurch.org --email you@yourchurch.org [--version v1.41.0]
+```
+
+It installs Node 20, PostgreSQL (with its own database and a random password), PM2, nginx (the
+API, uploads, `/health` and `/docs` to the backend, everything else to the site) and an HTTPS
+certificate, writes `backend/.env` and `frontend/.env.production`, migrates, builds and starts the
+app. Then open `https://<domain>/setup`: create the admin account and enter the **licence key**
+to connect the site to the Cross Events Hub. Several installs can share a server with different
+`--name`, `--dir`, `--web-port` and `--api-port`. Run `--help` for all options.
+
+Behind an frp tunnel (no public IP on the server)? See [DEPLOYMENT.md](DEPLOYMENT.md).
+
+### Updating
+
+To update a running install, on the server in the repo folder:
+
+- `bash scripts/deploy.sh` — the latest `main`
+- `bash scripts/deploy.sh v1.37.4` — a tagged release
+
+It backs up the database, checks the version out, installs, migrates, builds and reloads PM2.
+If anything fails before the reload, it goes back to the previous version (the running app
+isn't touched).
+
+PM2 uses the install's own `ecosystem.config.js` (app names, frontend port). It isn't in git,
+so deploys never change it; the first deploy creates it from `ecosystem.config.example.js` —
+set names that match your PM2 apps (`pm2 ls`) and the port you use.

 ### Backend Deployment

@@ -156,7 +186,7 @@ To update a running install to a release: `bash scripts/deploy.sh v1.34.0` on th
 - **`OptionVariant` model**: event options can now have sub-variants (sizes, colours, ticket types — e.g. Adult/Child/VIP under a single "Ticket" option). Variants have an optional `price` override and their own `stockLimit`.
 - **Stock limits**: `stockLimit` added to `EventOption` and `EarlyBirdTier`. A value of `0` means unlimited. All stock counts exclude cancelled registrations.
 - **Early-bird concurrency handling**: once a Yoco checkout has been issued at an early-bird price, that price is honoured even if another user simultaneously exhausts the tier's stock. Stock-based forfeiture only applies at registration time (via `resolveOptionPrice`). Deadline expiry at payment time forfeits the price; stock races after the checkout is issued do not.
- **Early-bird stock forfeiture**: if a tier's deadline passes after registration but before payment, `refreshPricingForRegistration` (called before every Yoco checkout) re-evaluates the tier and updates `priceSnapshot`. If prices changed, `POST /api/payments/yoco-checkout` returns `{ priceUpdated: true, newTotal }` (HTTP 200) so the frontend can show a warning before retrying.
+- **Early-bird stock forfeiture**: if a tier's deadline passes after registration but before payment, `refreshPricingForRegistration` (called before every Yoco checkout) re-evaluates the tier and updates `priceSnapshot`. If prices changed, `POST /api/payments/checkout` returns `{ priceUpdated: true, newTotal }` (HTTP 200) so the frontend can show a warning before retrying.
 - **`priceSnapshot` / `appliedTierId`** on `RegistrationOption`: price and tier are snapshotted at registration creation. `computeRegistrationTotalDue` uses `priceSnapshot` as authoritative when present (legacy rows without a snapshot fall back to deadline-only re-evaluation).
 - **Cancelled registration tickets**: `GET /api/tickets/mytickets` now excludes tickets from cancelled registrations at the database level.
 - **Cancellation payment guard**: `DELETE /api/registrations/:id` blocks non-admins from cancelling a registration that has positive payments. Admins can cancel at any time.
@@ -17,6 +17,7 @@ in-process settings cache TTL) without a server restart.
 | `org_email` | *(blank)* | No fallback in most places. **Exception:** the Terms of Use / Privacy Policy pages default to `privacy@example.com` (an obvious placeholder) if unset — see the Legal section below. |
 | `org_phone` / `org_address` | *(blank)* | No fallback — simply omitted wherever shown if unset. |
 | `app_base_url` | `APP_BASE_URL` or `FRONTEND_URL` env var, else `http://localhost:3001` | Used to build links in emails (password reset, ticket delivery, etc.). Should always be set in production. |
+| `APP_TIMEZONE` (env) | `Africa/Johannesburg` | The site's time zone (an IANA name, e.g. `Europe/London`): background job schedules (e.g. the 07:00 daily summary), session dates and printed times. Also sent to the Hub in the heartbeat. Needs a backend restart. |

 ## Branding

@@ -57,12 +58,16 @@ or Branding tab has been saved even once — the wizard always writes
 | `smtp_user` / `smtp_pass` | *(blank)* | Stored AES-256-GCM encrypted (key derived from `JWT_SECRET`). |
 | `smtp_from` | *(blank)* | If blank, outgoing mail's `From:` address falls back to the literal `no-reply@crosscode.local`. |

-## Payments (Yoco)
+## Payments

-Managed in the Yoco tab (through `/api/yoco`, not the generic settings endpoints).
+Managed in the Payments tab (through `/api/payments/providers/settings` and `/api/yoco`, not the generic settings endpoints).

 | Setting | Default when unset | Notes |
 |---|---|---|
+| `payfast_merchant_id` / `payfast_merchant_key` | `PAYFAST_MERCHANT_ID` / `PAYFAST_MERCHANT_KEY` env vars, else *(blank)* | From the PayFast (or Sandbox) dashboard. Both are needed before PayFast can take payments. The key isn't secret (it's in the payment form), so it's shown in full. Managed through `/api/payfast`. |
+| `payfast_passphrase` | `PAYFAST_PASSPHRASE` env var, else *(blank)* | Stored encrypted. Must match the dashboard's salt passphrase exactly, or PayFast refuses payments ("signature does not match"). |
+| `payfast_mode` | `PAYFAST_MODE` env var, else `sandbox` | `sandbox` or `live`: where payers are sent and where notifications are confirmed. |
+| `payment_providers` | Yoco enabled | JSON `{ order: [...], enabled: { yoco: true } }`: which online payment providers are on, and their order (the first one enabled and set up is the default). Providers not listed yet come last, switched off (Yoco on, as it was the only provider). If none is on and set up, online payments are off. |
 | `yoco_secret_key` | `YOCO_SECRET_KEY` env var, else *(blank)* | Stored AES-256-GCM encrypted. If blank, online checkouts and sponsorships fail with "online payments are not configured". |
 | `yoco_webhook_secret` | `YOCO_WEBHOOK_SECRET` env var, else *(blank)* | Stored encrypted. If blank, Yoco webhooks are rejected, so payments aren't confirmed automatically. |
 | `yoco_webhook_id` | *(blank)* | The Yoco webhook whose secret is stored, set when it's generated from the tab. Used to mark it "Active" and to clear the secret when it's deleted. |
@@ -75,16 +80,47 @@ Managed in the Yoco tab (through `/api/yoco`, not the generic settings endpoints
 | `legal_io_name` | `"[not yet configured]"` | Same reasoning as `legal_operator_name`. |
 | `legal_io_email` | `"io@example.com"` | Rendered as a `mailto:` link, so the placeholder stays a syntactically valid address on the IANA-reserved `example.com` domain rather than a bracketed non-email string that would break the link. |
 | `legal_website_url` | `"example.com"` | Same reasoning — used to build an `https://` link. |
-| `legal_effective_date` | `"[not yet set]"` | Plain text only, no link — a bracketed placeholder is fine here. |
+| `legal_effective_date` | `"[not yet set]"` | Plain text only, no link — a bracketed placeholder is fine here. Only used by the built-in privacy notice: once a version is published in Admin → Privacy, its publish date is the effective date. |
 | `notify_user_on_impersonation` | `"false"` | When `"true"`, a user is emailed (with the reason) whenever an admin views their account with Impersonate. Set under Site Settings → Legal → Support access. |
 | `consent_medical_retention_days` | `30` | Youth events: medical and emergency details from parental consent forms are deleted this many days after the event ends (daily 09:00 job). The consent record itself — who agreed, when, to which text — is kept. Set under Site Settings → Legal. |
 | `org_email` (as used on legal pages specifically) | `"privacy@example.com"` | Different fallback than `org_email`'s general default (blank) — also rendered as a `mailto:` link, so it needs to stay a valid-looking address. |

+## Campuses
+
+| Setting | Default when unset | Notes |
+|---|---|---|
+| `campuses_enabled` | `false` | Site settings → Campuses → "Use campuses". Changed only through `PUT /api/campuses/settings` (audited); hidden from the generic settings endpoints. Off hides campus fields and filters everywhere; campuses and each event's campus are kept. The campuses themselves are in the `Campus` table. |
+
+## Cross Events Hub (licence)
+
+| Setting | Default when unset | Notes |
+|---|---|---|
+| `HUB_URL` (env) | `https://events-hub.crosscode.co.za` | Where the Hub runs. |
+| `HUB_PUBLIC_KEY` (env) | The production key built into `backend/src/hub/publicKey.js` | Only for a local or test Hub. Licence tokens are checked with this key. |
+| `HUB_HEARTBEAT_ENABLED` (env) | `true` | The 15-minute `hub-heartbeat` job (plus one check-in 30 s after starting and after connecting). Off means the licence isn't refreshed — after 30 days the site goes into grace, then read-only. |
+| `LICENCE_CHECK_DISABLED` (env) | `false` | `true` turns read-only mode off — **ignored when `NODE_ENV=production`**. For the end-to-end tests and local development without a Hub. |
+| `hub_install_id`, `hub_install_secret` (encrypted), `hub_licence`, `hub_last_heartbeat_at`, `hub_last_error`, `hub_latest_version` | — | Written only by `src/hub/client.js` when connecting and on each heartbeat. Never readable or writable through the generic settings endpoints. Deleting them disconnects the site (it becomes "no licence", which is read-only). The heartbeat deletes the install and licence keys itself when the Hub answers `INSTALL_NOT_FOUND`. |
+
 ## WhatsApp

 | Setting | Default when unset | Notes |
 |---|---|---|
 | `WAWP_ACCESS_TOKEN` / `WAWP_INSTANCE_ID` | `WAWP_ACCESS_TOKEN`/`WAWP_INSTANCE_ID` env vars, else *(blank)* | No hardcoded default — WhatsApp sending is simply unavailable until both are configured (Admin → Site Settings → WhatsApp). |
+| `WAWP_WEBHOOK_SECRET` | Generated (random) the first time the WhatsApp tab is opened | Part of the webhook URL shown in Site Settings → WhatsApp (`/api/whatsapp/webhook?secret=…`). WAWP doesn't sign webhooks, so incoming messages (STOP replies) are only acted on when the secret matches. Not editable in the UI; delete the row to get a new one (then update the URL in WAWP). The URL uses `BACKEND_URL`. |
+
+## Privacy (POPIA)
+
+| Setting | Default when unset | Notes |
+|---|---|---|
+| `legal_io_email` (Information Officer, Site Settings → Legal) | — | Also where new privacy requests and the daily "requests due" reminder are emailed, together with all admins. The `io@example.com` placeholder is skipped. |
+| `PRIVACY_JOBS_ENABLED` (env) | `true` | The daily 08:00 `privacy` job that reminds admins of requests due within a week or overdue. |
+| `retention_policies` | Inactive accounts 60 months (on), form answers 12, login history 24, payment details 24, audit/access logs 60 — all on | Admin → Privacy → Retention (JSON `{ policies: { key: { enabled, months } }, reviewedAt, reviewedBy }`). Minimums: inactive accounts and logs 12 months, login history and payment details 3, form answers 1; maximum 240. Saving marks them reviewed (readiness check). |
+| `retention_last_run` | — | When the `retention` job last ran and what it did (readiness check: within 2 days). |
+| `RETENTION_JOBS_ENABLED` (env) | `true` | The nightly 03:30 `retention` job. Off means nothing expires automatically. |
+| `wawp_webhook_last_seen` | — | Set when WAWP's webhook arrives with the right secret; the readiness page uses it to check WhatsApp STOP is set up. |
+| `privacy_notice_draft` | — | The unpublished draft from Admin → Privacy → Privacy notice (JSON). Published versions are in the `PrivacyNotice` table. With no published version the built-in notice (`backend/src/utils/privacyNotice.js`) is shown. The notice's org name, Information Officer, website, emails and medical retention days come from the settings above when it's shown. |
+
+People's News & announcements opt-in is per account (`User.newsEmail`, `User.newsWhatsApp`), not a site setting. Unsubscribe links are signed with `JWT_SECRET` and don't expire — changing `JWT_SECRET` breaks links in emails already sent.

 ## Backups

@@ -13,6 +13,10 @@ JWT_SECRET=your_jwt_secret_here_minimum_32_characters
 PORT=5000
 NODE_ENV=development

+# Time zone for background job schedules (e.g. the 07:00 daily summary), session dates
+# and printed times. An IANA name, e.g. Africa/Johannesburg or Europe/London.
+APP_TIMEZONE=Africa/Johannesburg
+
 # Set this if the app runs behind a reverse proxy (e.g. nginx on a separate
 # server) so rate limiting reads the real client IP instead of the proxy's.
 # Accepts a hop count ("1"), "true"/"false", or comma-separated IP(s)/CIDR(s)
@@ -39,6 +43,16 @@ FRONTEND_URL=http://localhost:3000
 # YOCO_SECRET_KEY=sk_test_...
 # YOCO_WEBHOOK_SECRET=whsec_...

+# ─── Payments (PayFast) — optional fallbacks ──────────────────────────────────
+# Preferred: Admin → Site Settings → Payments → PayFast. Only used if the database has no value.
+# PAYFAST_MERCHANT_ID=
+# PAYFAST_MERCHANT_KEY=
+# PAYFAST_PASSPHRASE=
+# PAYFAST_MODE=sandbox
+# PayFast notifications (ITNs) must come from a PayFast address. Behind a reverse proxy, set
+# TRUST_PROXY so the real address is seen. Only for testing through a tunnel:
+# PAYFAST_SKIP_IP_CHECK=true
+
 # ─── Public URLs ──────────────────────────────────────────────────────────────
 # Used to build links in emails (password reset, activation, etc.)
 APP_BASE_URL=https://your-frontend-domain.com
@@ -59,6 +73,20 @@ CONSENT_JOBS_ENABLED=true
 # Waitlist: expire unclaimed offers and offer freed places (every 10 minutes by default)
 WAITLIST_JOB_ENABLED=true
 # WAITLIST_JOB_INTERVAL_MS=600000
+# Payments: every 15 minutes, look up PayFast checkouts whose notification never arrived
+PAYMENT_STATUS_JOB_ENABLED=true
+# Privacy (POPIA): daily 08:00 reminder to admins of data requests due within a week
+PRIVACY_JOBS_ENABLED=true
+# Privacy (POPIA): nightly 03:30 retention job (Admin → Privacy → Retention). Note: inactive
+# accounts are anonymised after 5 years by default (with a warning 30 days before).
+RETENTION_JOBS_ENABLED=true
+
+# ─── Cross Events Hub (licence and health) ─────────────────────────────────────
+# Where the Hub runs. The site checks in every 15 minutes once connected (Site settings → Licence).
+# HUB_URL=https://events-hub.crosscode.co.za
+# For a local or test Hub only: its public key (the release has the production key built in).
+# HUB_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----"
+HUB_HEARTBEAT_ENABLED=true
 # Nightly database backup at 02:00 (requires the `pg_dump` binary on this host).
 # Retention count is set via Admin → Site Settings → Backups (default 14).
 BACKUP_ENABLED=true
@@ -1,4 +1,4 @@
-# Hope Events — API Documentation
+# Cross Events — API Documentation

 Full interactive docs (with request/response examples) are available at `GET /docs?token=<admin-jwt>` on the running backend.

@@ -18,6 +18,7 @@ Tokens are issued by `POST /api/users/login`.
 - [Event Options & Variants](#event-options--variants)
 - [Event Attachments](#event-attachments)
 - [Registrations](#registrations)
+- [Privacy (POPIA)](#privacy-popia)
 - [Coupons](#coupons)
 - [Parental consent](#parental-consent)
 - [Waitlist](#waitlist)
@@ -41,8 +42,9 @@ Tokens are issued by `POST /api/users/login`.
 - [Sections](#sections)
 - [Banner](#banner)
 - [Forms](#forms)
- [Yoco Transactions](#yoco-transactions)
+- [Provider Transactions](#provider-transactions)
 - [WhatsApp Admin](#whatsapp-admin)
+- [Hub and licence](#hub-and-licence)
 - [Webhooks](#webhooks)
 - [Settings](#settings)
 - [Setup](#setup)
@@ -465,7 +467,11 @@ In a pick-mode event, a `pick` option is bought per session: registration lines
 session becomes its own registration line (`RegistrationOption.sessionId`) and ticket.
 Capacity counts picked places plus whole-course main tickets; a pick option's
 `stockLimit` is per session. `PUT /api/registrations/:id/options` refuses pick options and
-leaves picked lines untouched. Pick-mode events stay open until the last session starts
+leaves picked lines untouched. An `all` option in a pick-mode event may also send
+`sessionIds`: it stays one line and one ticket at one price, with the sessions kept in
+`RegistrationOption.sessionIds` (empty = every session). That ticket only scans on those
+sessions, and capacity, reminders, the register and certificates follow them; adding more
+of the same ticket to a registration merges the sessions. Pick-mode events stay open until the last session starts
 (`wholeCourseClosesAt` gives when whole-course tickets stop). Single-event responses add
 `booked` and `placesLeft` per session and `sessionAvailability` per pick option.

@@ -504,10 +510,10 @@ Events with `waitlistEnabled` (plus `waitlistOfferHours`, default 24, and `waitl

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| POST | `/api/waitlist` | optional | Join: `{ eventId, eventOptionId, variantId?, quantity }` (+ `guestName`, `guestEmail`, `guestPhone` when not logged in on a guest event). Only when the line can't cover the quantity |
+| POST | `/api/waitlist` | optional | Join: `{ eventId, eventOptionId, variantId?, sessionId?, quantity }` (+ `guestName`, `guestEmail`, `guestPhone` when not logged in on a guest event). Only when the line can't cover the quantity. `sessionId` is required for a pick-sessions option (one session per entry) and refused otherwise |
 | GET | `/api/waitlist/mine` | user+ | My active entries |
 | DELETE | `/api/waitlist/:id` | user+ | Leave (an open offer moves on) |
-| GET | `/api/waitlist/claim/:token` | public | What a claim link offers |
+| GET | `/api/waitlist/claim/:token` | public | What a claim link offers (with `sessionId`, `sessionName`, `lineName` for a per-session offer; `eventStart` is the session's start) |
 | GET | `/api/waitlist/events/:eventId` | staff+ | The queue for an event |
 | POST | `/api/waitlist/:id/offer` | supervisor+ | Offer now (`{ quantity? }`), even over the stock limit |
 | POST | `/api/waitlist/:id/move` | supervisor+ | `{ direction: "up" \| "down" }` |
@@ -519,6 +525,7 @@ How offers work:
 - A job every 10 minutes (`waitlist` job; `WAITLIST_JOB_ENABLED`, `JOB_SCHEDULE_WAITLIST`) expires unclaimed offers and re-offers.
 - Claiming means registering with `POST /api/registrations` plus `waitlistToken`. The token stands in for logging in, and the held places are released to the claimer.
 - Manual registration and adding places to an existing booking are now checked against stock too.
+- Pick-sessions options are waited for per session: free places are that session's (stock per session and session capacity), an offer expires no later than the session's start, and sessions that started or were cancelled aren't offered. For main tickets, free places also take session capacity into account, and held places count towards it.

 ## Parental consent

@@ -545,6 +552,55 @@ Check-in rules:
 - `POST /api/tickets/scan/:qrCode` returns `403 { code: "CONSENT_REQUIRED" }` unless consent is given.
 - Supervisors can pass `overrideConsent: true`, which is audited as `consent_override`.

+## Privacy (POPIA)
+
+The data subject's tools, unsubscribe links and the admin data-requests inbox (`src/utils/privacy.js`, `src/controllers/privacyController.js`).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/privacy/me` | user | `{ news: { email, whatsapp }, newsAskedAt, canWhatsApp, notificationPreference, history, requests }` |
+| PUT | `/api/privacy/me/news` | user | `{ email?: bool, whatsapp?: bool, source?: "prompt" }` — change the news opt-in (WhatsApp needs a valid phone). Logged in `CommunicationConsent`; `source: "prompt"` is the one-time question after login |
+| GET | `/api/privacy/me/export` | user | Download my data as JSON (`?format=pdf` for a readable PDF). Recorded as a completed self-service `access` request. 403 while impersonating; rate-limited |
+| POST | `/api/privacy/me/requests` | user | `{ type: "correction", details }` or `{ type: "deletion", password, details? }`. Deletion closes the account at once (deactivated, sessions revoked, news off). 409 if one of that type is already open. Emails the Information Officer + admins |
+| GET | `/api/privacy/unsubscribe/:token` | public (signed token) | What the link is for: an account (masked email, news state) or an address |
+| POST | `/api/privacy/unsubscribe/:token` | public (signed token) | `{ channels?: ["email","whatsapp"] }` — turn news off (default both) |
+| POST | `/api/privacy/unsubscribe/:token/one-click` | public (signed token) | RFC 8058 one-click (from the `List-Unsubscribe` header) — email news off. GET redirects to `/unsubscribe` |
+| GET | `/api/privacy/requests?status=open\|closed\|all` | admin | Data requests (not self-service downloads), with `overdue` and, for open deletions, `blockers` (registrations for events that haven't ended) |
+| POST | `/api/privacy/requests/:id/complete` | admin | `{ response? }` (required for corrections; emailed). Deletion: anonymises the account — 409 while it has blockers. Audited as `data_request_completed` (+ `user_anonymised`) |
+| POST | `/api/privacy/requests/:id/reject` | admin | `{ response, cancelled?: bool }` — reject (or mark withdrawn); a deletion reopens the account. Audited as `data_request_rejected` |
+
+Privacy notice, operators and logs (`src/utils/privacyNotice.js`, `src/utils/accessLog.js`, `src/controllers/privacyAdminController.js`):
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/privacy/notice?version=N` | public | The notice (current, or version N) with placeholders filled in: `{ version, builtIn, current, effectiveDate, changeSummary, sections: [{ id, title, body }], versions }`. Version 0 = the built-in notice, only while nothing is published |
+| POST | `/api/privacy/me/notice/accept` | user | Accept the current version (recorded in `NoticeAcceptance`, `User.noticeVersionAccepted`). 403 while impersonating |
+| GET | `/api/privacy/notice/draft` | admin | Editor state: `sections` (raw, with placeholders), `rendered`, `isDraft`, `savedAt`, `versions` (with acceptance counts), `builtIn` (the built-in sections), `placeholders` |
+| PUT | `/api/privacy/notice/draft` | admin | `{ sections }` — save the draft (AppSetting `privacy_notice_draft`) |
+| DELETE | `/api/privacy/notice/draft` | admin | Discard the draft |
+| POST | `/api/privacy/notice/publish` | admin | `{ sections, changeSummary?, requiresAcceptance? }` — publish the next version and clear the draft. `requiresAcceptance` needs a `changeSummary`. Audited as `privacy_notice_published` |
+| GET / POST | `/api/privacy/operators` | admin | The operator register / add one `{ name, purpose, dataShared?, location?, website?, active? }` |
+| PUT / DELETE | `/api/privacy/operators/:id` | admin | Change / remove an operator (audited as `operator_*`) |
+| GET | `/api/privacy/consent-log?type=news\|notice\|parental&q=&page=` | admin | News opt-in changes, notice acceptances, or parental consent answers (50 per page) |
+| GET | `/api/privacy/access-log?action=&actorId=&from=&to=&page=` | admin | Bulk exports/views of personal information, with `actions` (labels) and `actors` for the filters |
+| GET | `/api/privacy/readiness` | admin | `{ score, passed, total, checks: [{ key, label, ok, detail, href, applies }] }` |
+| GET | `/api/privacy/retention` | admin | `{ policies, definitions, reviewedAt, reviewedBy, preview, lastRun, related }` — `preview` is what the next run would affect |
+| PUT | `/api/privacy/retention` | admin | `{ policies: { inactive_accounts\|form_answers\|login_history\|payment_details\|audit_logs: { enabled, months } } }` — all five required. Audited as `retention_policies_updated` |
+| POST | `/api/privacy/retention/run` | admin | Run the retention job now: `{ result, state }` |
+| GET / POST | `/api/privacy/breaches` | admin | The breach register / record one `{ title, discoveredAt, description, dataAffected, occurredAt?, peopleAffected?, whoAffected?, consequences?, actionsTaken?, adviceToPeople?, causedBy? }` |
+| PUT | `/api/privacy/breaches/:id` | admin | Change any of those, `status` (open\|contained\|closed), `regulatorNotifiedAt`, `peopleNotifiedAt`. Audited as `breach_updated` |
+
+The `retention` job (03:30, `RETENTION_JOBS_ENABLED=false` to disable) works through each switched-on policy. Inactive accounts: role `user`, not anonymised, whose latest of created / last login (`User.lastLoginAt`) / registration or its event's end / named as attendee / payment is older than the period. Those within 30 days of it are warned (email, else WhatsApp; `User.inactivityWarnedAt`), and those warned at least 30 days ago — after their last activity — are anonymised unless they have a registration for an upcoming event. Logging in clears the warning. At most 300 warnings and 200 anonymisations per run. Payment details: `ProviderTransaction.raw` and `ProviderCheckout.request` older than the period are scrubbed and marked `_scrubbed`. Access log rows carry `sensitive` (medical lists, and anything for an event with `requiresParentalConsent`); `?sensitive=true` filters them.
+
+Placeholders in notice sections: `{org}`, `{orgEmail}`, `{website}`, `{ioName}`, `{ioEmail}`, `{medicalRetentionDays}`, and — each on a line of its own — `{operators}` (one bullet per active operator) and `{retention}` (one bullet per retention period). Login and `GET /api/users/profile` return `noticePromptPending` — true when a version with `requiresAcceptance` is newer than the one the person accepted. Sign-up records an acceptance of the current version (source `signup`).
+
+Access log actions (`DataAccessLog.action`): `report_pdf`, `report_excel`, `report_email`, `report_whatsapp` (`/api/reports/*`, with the row count), `attendance_export`, `certificates_download`, `group_lists` (or `medical_list` with `?medical=true`), `form_responses` (first page of a list), `consent_list`, `medical_list`, `backup_download`, `impersonation`.
+
+Notes:
+- Requests are due 30 days after they're made. The `privacy` job (08:00, `PRIVACY_JOBS_ENABLED=false` to disable) emails the Information Officer (`legal_io_email`) and admins about open requests due within 7 days or overdue.
+- **Anonymising** (also `POST /api/users/:id/anonymize`) keeps payments, registrations, tickets and check-ins, and removes: the account's name/email/phone/password, the details of attendees on their registrations and their own attendee rows elsewhere, parental-consent details, form answers and drafts, feedback authorship and invites, waiting waitlist places, pending transfer requests, names on transfers and certificates, sponsor names/messages, login history, password resets and 2FA challenges, and payer fields in provider webhook payloads and checkouts.
+- Sign-up (`POST /api/users`) takes `newsOptIn: bool`. Login and `GET /api/users/profile` return `newsPromptPending` (never answered the opt-in question).
+
 ## Coupons

 | Method | Path | Auth | Description |
@@ -570,7 +626,15 @@ Options and variants also accept an optional `staffPrice`, charged automatically
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
 | POST | `/api/payments` | supervisor+ | Record manual payment (cash/EFT) |
-| POST | `/api/payments/yoco-checkout` | user+ | Initiate Yoco checkout; re-evaluates early-bird pricing first — returns `{ priceUpdated: true, newTotal }` if prices changed |
+| POST | `/api/payments/checkout` | user+ | Start an online checkout (also `/api/payments/yoco-checkout`); `provider` optional (default: first enabled provider); at least R15; re-evaluates early-bird pricing first — returns `{ priceUpdated: true, newTotal }` if prices changed |
+| POST | `/api/payments/checkout/send` | supervisor+ | Send a generated payment link by email or WhatsApp (also `/api/payments/yoco-checkout/send`) |
+| GET | `/api/payments/providers` | public | Providers people can pay with now (enabled and set up), in order: `{ providers: [{ id, label }], minimumAmount: 15 }` |
+| GET | `/api/payments/providers/settings` | admin | Every provider with `enabled`, `configured` and `capabilities` (`refund`, `getTransaction`, `listTransactions`) |
+| GET | `/api/payments/pay/:id` | public (checkout id) | The payer's page for a checkout: `{ status: open\|paid, amount, description, provider, providers, cancelUrl, redirectUrl, form }`. `form` (`{ action, fields }`) is set once a form provider (PayFast) is chosen — the page posts it |
+| POST | `/api/payments/pay/:id` | public (checkout id) | `{ provider }` → starts the checkout with that provider: `{ provider, redirectUrl }` (Yoco) or `{ provider, form }` (PayFast). 409 when already paid |
+| GET | `/api/payments/checkouts/open` | supervisor+ | Online checkouts from the last 14 days with no payment yet: `{ checkouts: [{ id, provider, providerLabel, canCheck, amount, description, type, registrationId, payer, createdAt }], days }` |
+| POST | `/api/payments/checkouts/check` | supervisor+ | `{ ids? }` (default: every open one) → asks each provider and records payments it received: `{ results: { [checkoutId]: { status: paid\|recorded\|needs_review\|not_paid\|cant_check, note? } }, recorded, message }`. PayFast: transaction history (API); Yoco: `cant_check` |
+| PUT | `/api/payments/providers/settings` | admin | `{ providers: [{ id, enabled }] }` in display order. Audit logged (`payment_providers_updated`) |
 | GET | `/api/payments/mypayments` | user+ | Own payments |
 | GET | `/api/payments/:id` | user+ | Payment by ID |
 | GET | `/api/payments/registration/:registrationId` | user+ | Payments for a registration |
@@ -590,7 +654,7 @@ Options and variants also accept an optional `staffPrice`, charged automatically
 }
 ```

-### POST /api/payments/yoco-checkout
+### POST /api/payments/checkout
 ```json
 {
  "registrationId": "reg-uuid-...",
@@ -643,6 +707,8 @@ Returns: `{ redirectUrl }` or `{ priceUpdated: true, newTotal, message }` if ear

 Dynamic placeholders: `{{name}}`, `{{event.title}}`, `{{event.start}}`, `{{event.link}}`, `{{balance}}`, `{{promo.title}}`, `{{promo.link}}`

+**Message kind (POPIA).** Every bulk send — these broadcasts, WhatsApp broadcasts, and `POST /api/events/:id/email-attendees` / `whatsapp-attendees` (and their `/schedule`) — takes `kind`: `"update"` or `"news"`. Broadcasts default to `news`, attendee messages to `update`; `promoEventId` (the next-event promo automation) forces `news`, `template: "tickets"` forces `update`. `news` goes only to accounts opted in on that channel (`User.newsEmail` / `newsWhatsApp`) and skips addresses in `MessagingOptOut`; it gets an unsubscribe link (email: plus `List-Unsubscribe` / `List-Unsubscribe-Post` headers; WhatsApp: "Reply STOP"). `update` emails get a footer saying why they were sent. Responses (and dry runs) include `kind` and `skipped`. See [Privacy](#privacy-popia).
+
 ---

 ## WhatsApp Broadcasts
@@ -739,16 +805,16 @@ Groups of event options shown as labelled sections on the registration page (e.g

 ---

-## Yoco Transactions
+## Provider Transactions

-Raw webhook events from Yoco. Used for reconciling payments that weren't matched automatically.
+Transactions payment providers sent by webhook (`ProviderTransaction`, one per provider + external id). Used for reconciling payments that weren't matched automatically. Each item has `provider`, `providerLabel` and the checkout `metadata`. Also served at `/api/yoco-transactions` (the older name).

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| GET | `/api/yoco-transactions` | supervisor+ | All Yoco webhook transactions |
-| GET | `/api/yoco-transactions/unreconciled` | supervisor+ | Transactions not yet matched to a payment |
-| POST | `/api/yoco-transactions/:id/reconcile` | supervisor+ | Manually link transaction to a registration |
-| POST | `/api/yoco-transactions/:id/ignore` | supervisor+ | Mark transaction as intentionally ignored |
+| GET | `/api/provider-transactions` | supervisor+ | All transactions (`?provider=yoco&reconciled=&ignored=`) |
+| GET | `/api/provider-transactions/unreconciled` | supervisor+ | Transactions not yet matched to a payment (`?provider=`) |
+| POST | `/api/provider-transactions/:id/reconcile` | supervisor+ | Record it as a payment on a registration (`{ registrationId }`) or a donation (`{ eventId, userId? }`); the payment gets the transaction's provider |
+| POST | `/api/provider-transactions/:id/ignore` | supervisor+ | Mark transaction as intentionally ignored |

 ---

@@ -758,7 +824,7 @@ Manages the WAWP WhatsApp API instance. Credentials are stored in `AppSetting` (

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| GET | `/api/whatsapp/config` | admin | Get current WAWP credentials |
+| GET | `/api/whatsapp/config` | admin | Get current WAWP credentials, and `webhookUrl` (with its secret) to paste into WAWP |
 | POST | `/api/whatsapp/config` | admin | Save WAWP credentials to DB |
 | GET | `/api/whatsapp/status` | admin | WAWP session status |
 | GET | `/api/whatsapp/qr` | admin | QR code for WhatsApp device linking |
@@ -771,12 +837,62 @@ Manages the WAWP WhatsApp API instance. Credentials are stored in `AppSetting` (

 ---

+## Hub and licence
+
+The connection to the Cross Events Hub (`src/hub/`, protocol in `docs/hub-protocol.md`).
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/health` | public | `{ status, version, db, jobs, lastBackupAt }` — 503 when the database is down |
+| GET | `/api/hub/status` | admin | `{ state: active\|grace\|suspended\|revoked\|unlicensed, readOnly, daysLeft, endsAt, graceEndsAt, licence, connected, keyConfigured, hubUrl, lastHeartbeatAt, lastError, version, latestVersion, updateAvailable }` |
+| POST | `/api/hub/connect` | admin (incl. the `/setup` token) | `{ licenceKey }` — registers with the Hub; stores the install id, encrypted secret and licence token. Hub errors pass through with their `code` (`LICENCE_NOT_FOUND`, `LICENCE_IN_USE`, `LICENCE_REVOKED`, `HUB_UNREACHABLE`, …). Audited as `hub_connected` |
+| POST | `/api/hub/heartbeat` | admin | Check in now; returns the status |
+| POST | `/api/hub/update-request` | admin | Ask the Hub for this site to be updated (protocol §3a); the provider is told, nothing runs on the site. Returns the status with `updateRequest: { requestedAt, version }` until the site runs that version. `409 UP_TO_DATE`; audited as `hub_update_requested` |
+
+**Read-only mode** (licence suspended, revoked, or past its grace period): `403 { code: "LICENCE_READ_ONLY" }` on `POST /api/events`, event options and variants, `POST /api/registrations` (and `/manual`), `PUT /api/registrations/:id/options`, `POST /api/payments`, `/payments/checkout` (`/send`), `/payments/yoco-checkout` (`/send`), `/payments/pay/:id`, `POST /api/waitlist`, `POST /api/coupons`, `POST /api/bundles/event/:id`. Everything else — scanning, exports, refunds, cancellations, privacy requests, settings — keeps working, and payment webhooks for payments already started are still processed.
+
+## Campuses
+
+Multi-campus (`src/utils/campuses.js`), off by default. While off, every campus field and filter
+below is ignored and `GET /api/campuses` returns `{ enabled: false, campuses: [] }`.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/campuses` | public | `{ enabled, campuses }` — active campuses in order |
+| GET | `/api/campuses/by-slug/:slug` | public | One active campus (its `/campus/<slug>` page); 404 when archived or off |
+| GET | `/api/campuses/admin` | admin | All campuses incl. archived, with `notifyRecipients` and `_count { events, homeOf }` |
+| PUT | `/api/campuses/settings` | admin | `{ enabled }` — audited as `campuses_toggled` (the `campuses_enabled` setting can't be changed through `PUT /api/settings`) |
+| POST | `/api/campuses` | admin | `{ name, slug?, address?, contactName?, contactEmail?, contactPhone?, colour? (#rrggbb), logoUrl?, defaultLocation? }`; 409 when the slug is taken |
+| PUT | `/api/campuses/:id` | admin | Same fields, plus `notifyRecipientIds` (staff only) and `archived` |
+| PUT | `/api/campuses/order` | admin | `{ ids: [...] }` |
+| DELETE | `/api/campuses/:id` | admin | Only without events — otherwise `409 CAMPUS_HAS_EVENTS` (archive instead) |
+| GET | `/api/campuses/:id/audience` | supervisor+ | `{ campus, users }` — home campus, plus `?registrants=true` people registered for its events in the last 12 months (not cancelled). Broadcasts send to these ids as usual, so news consent still applies |
+
+**Campus-scoped staff (1.44.0):** a supervisor or staff member with campus limits
+(`PUT /api/users/:id { scopedCampusIds }`, admin; `GET /api/users/:id` returns `scopedCampuses`;
+`GET /api/users/profile` returns `campusScope`, null when unscoped or campuses are off) only sees
+their campuses' events plus church-wide ones on every staff/supervisor endpoint
+(`src/utils/campusScope.js`). Responses for out-of-scope records:
+- `404 { message: "Not found" }` — another campus's event or record (nothing leaks).
+- `403 { code: "OTHER_CAMPUS" }` — the scanner (`/api/tickets/scan-preview|qr|scan/:qrCode`), naming the ticket's campus.
+- `403 { code: "CHURCH_WIDE_EVENT" }` — changing, cashing up or refunding an event for all campuses.
+- `403 { code: "CAMPUS_SCOPED" }` — banner, payment reconciliation, open checkouts, unlinked donations, typed-in broadcast addresses or recipients outside their campuses.
+- `409 { code: "CAMPUS_HAS_SCOPED_STAFF" }` on `DELETE /api/campuses/:id` while staff are limited to it.
+
+**Campus on other endpoints:**
+- Events carry `campusId` (null = all campuses) and `campus { id, name, slug, colour }`. `POST`/`PUT /api/events` take `campusId` (`''`/`null` = all campuses; an archived campus can stay but can't be newly chosen); moving an event is audited as `event_campus_changed`.
+- `GET /api/events?campus=<slug|id>` — that campus's events plus church-wide ones. `GET /api/events/all?campus=<id|slug|all>` — one campus, or church-wide only.
+- `GET /api/stats/overview?campus=<id|slug|all>`.
+- `PUT /api/users/profile` takes `homeCampusId`; `GET` returns it.
+
 ## Webhooks

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| POST | `/api/webhooks/yoco` | HMAC-verified | Yoco payment webhook — verifies `X-Yoco-Signature`, creates `Payment` + `YocoTransaction`, updates registration status, generates tickets |
-| POST | `/api/webhooks/whatsapp` | — | WAWP inbound event webhook |
+| POST | `/api/webhooks/payfast` | PayFast ITN | Form-encoded. Checked as PayFast requires: signature (every posted field + passphrase), sender is a PayFast host (`PAYFAST_SKIP_IP_CHECK=true` turns this off for tunnels; behind a proxy set `TRUST_PROXY`), PayFast answers VALID at `/eng/query/validate`, and `amount_gross` equals the checkout (otherwise held for review with a `note`). `COMPLETE` records the payment (`provider: "payfast"`) |
+| POST | `/api/webhooks/yoco` | HMAC-verified | Yoco payment webhook — verifies the `webhook-signature` header (src/payments/providers/yoco.js), creates `Payment` (`provider: "yoco"`) + `ProviderTransaction`, updates registration status, generates tickets (src/payments/webhook.js). Processed even when Yoco is switched off, so checkouts already started complete |
+| POST | `/api/whatsapp/webhook?secret=…` | secret in URL | WAWP events (the URL to paste into WAWP is on `GET /api/whatsapp/config` as `webhookUrl`). `session.status` FAILED → automatic session recovery (works without the secret). `message` → a STOP/unsubscribe reply turns off WhatsApp news for that number and sends a confirmation; only with a matching secret, since WAWP doesn't sign webhooks. Senders identified only by a WhatsApp LID (no phone number) are ignored |
+| POST | `/api/webhooks/whatsapp` | — | Old placeholder, does nothing — use `/api/whatsapp/webhook` |

 ---

@@ -796,7 +912,11 @@ For what each individual setting key defaults to when it's never been saved, see

 ## Yoco

-Managed from Admin → Site Settings → Yoco. `YOCO_SECRET_KEY` / `YOCO_WEBHOOK_SECRET` in `.env` are fallbacks used only when the database has no value.
+Managed from Admin → Site Settings → Payments.
+
+PayFast: `GET /api/payfast/config` (admin) → `{ merchantId, merchantKey, passphraseMasked, hasPassphrase, mode, notifyUrl, notifyUrlProblem, configured }`; `PUT /api/payfast/config` (admin) `{ merchantId?, merchantKey?, passphrase?, mode? }` ('' clears; the passphrase is stored encrypted; audit logged as `payfast_config_updated`); `POST /api/payfast/test` (admin) checks the saved settings with a signed PayFast API ping.
+
+Every checkout is stored as a `ProviderCheckout` (amount, metadata, request): `POST /api/payments/checkout` returns `checkoutId` (ours) and a `redirectUrl` — the provider's page, or `/pay/<checkoutId>` when the payer must choose or a form has to be posted. Registrations keep that `checkoutId`; webhooks find the checkout by our id or the provider's. `YOCO_SECRET_KEY` / `YOCO_WEBHOOK_SECRET` in `.env` are fallbacks used only when the database has no value.

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
@@ -1,6 +1,6 @@
-# Hope Events — Backend API
+# Cross Events — Backend API

-Node.js + Express REST API for the Hope Events platform used by Hope Family Church (`events.hopehenley.co.za`).
+Node.js + Express REST API for the Cross Events platform used by Hope Family Church (`events.hopehenley.co.za`).

 ---

@@ -1,12 +1,12 @@
 {
  "name": "event-management-backend",
-  "version": "1.35.0",
+  "version": "1.44.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "event-management-backend",
-      "version": "1.35.0",
+      "version": "1.44.0",
      "hasInstallScript": true,
      "dependencies": {
        "@prisma/adapter-pg": "^7.10.1",
@@ -1,6 +1,6 @@
 {
  "name": "event-management-backend",
-  "version": "1.35.0",
+  "version": "1.44.0",
  "description": "Event Management System Backend",
  "main": "src/index.js",
  "scripts": {
@@ -0,0 +1,8 @@
+-- AlterTable
+ALTER TABLE "WaitlistEntry" ADD COLUMN     "sessionId" TEXT;
+
+-- CreateIndex
+CREATE INDEX "WaitlistEntry_sessionId_idx" ON "WaitlistEntry"("sessionId");
+
+-- AddForeignKey
+ALTER TABLE "WaitlistEntry" ADD CONSTRAINT "WaitlistEntry_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "EventSession"("id") ON DELETE CASCADE ON UPDATE CASCADE;
@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "RegistrationOption" ADD COLUMN     "sessionIds" TEXT[] DEFAULT ARRAY[]::TEXT[];
@@ -0,0 +1,23 @@
+-- Payment providers (1.36.0). YocoTransaction becomes ProviderTransaction: renamed in place
+-- so every stored transaction is kept (Prisma's generated plan drops and recreates it).
+
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'payment_providers_updated';
+
+-- Rename YocoTransaction → ProviderTransaction
+ALTER TABLE "YocoTransaction" RENAME TO "ProviderTransaction";
+ALTER TABLE "ProviderTransaction" RENAME CONSTRAINT "YocoTransaction_pkey" TO "ProviderTransaction_pkey";
+ALTER TABLE "ProviderTransaction" RENAME CONSTRAINT "YocoTransaction_paymentId_fkey" TO "ProviderTransaction_paymentId_fkey";
+ALTER INDEX "YocoTransaction_paymentId_idx" RENAME TO "ProviderTransaction_paymentId_idx";
+
+-- Which provider sent it; external ids are unique per provider
+ALTER TABLE "ProviderTransaction" ADD COLUMN "provider" TEXT NOT NULL DEFAULT 'yoco';
+DROP INDEX "YocoTransaction_externalId_key";
+CREATE UNIQUE INDEX "ProviderTransaction_provider_externalId_key" ON "ProviderTransaction"("provider", "externalId");
+
+-- Payment.provider: every online payment so far came through Yoco (linked to a transaction,
+-- or the donation split off one)
+ALTER TABLE "Payment" ADD COLUMN "provider" TEXT;
+UPDATE "Payment" SET "provider" = 'yoco'
+WHERE "id" IN (SELECT "paymentId" FROM "ProviderTransaction" WHERE "paymentId" IS NOT NULL)
+   OR "originalPaymentId" IN (SELECT "paymentId" FROM "ProviderTransaction" WHERE "paymentId" IS NOT NULL);
@@ -0,0 +1,24 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'payfast_config_updated';
+
+-- AlterTable
+ALTER TABLE "ProviderTransaction" ADD COLUMN     "note" TEXT;
+
+-- CreateTable
+CREATE TABLE "ProviderCheckout" (
+    "id" TEXT NOT NULL,
+    "provider" TEXT,
+    "externalId" TEXT,
+    "redirectUrl" TEXT,
+    "amountCents" INTEGER NOT NULL,
+    "currency" TEXT NOT NULL DEFAULT 'ZAR',
+    "metadata" JSONB NOT NULL,
+    "request" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ProviderCheckout_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "ProviderCheckout_provider_externalId_idx" ON "ProviderCheckout"("provider", "externalId");
@@ -0,0 +1,102 @@
+-- CreateEnum
+CREATE TYPE "DataRequestType" AS ENUM ('access', 'correction', 'deletion');
+
+-- CreateEnum
+CREATE TYPE "DataRequestStatus" AS ENUM ('open', 'completed', 'rejected', 'cancelled');
+
+-- AlterEnum
+-- This migration adds more than one value to an enum.
+-- With PostgreSQL versions 11 and earlier, this is not possible
+-- in a single migration. This can be worked around by creating
+-- multiple migrations, each migration adding only one value to
+-- the enum.
+
+
+ALTER TYPE "AdminAuditAction" ADD VALUE 'data_request_completed';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'data_request_rejected';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'user_anonymised';
+
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN     "newsAskedAt" TIMESTAMP(3),
+ADD COLUMN     "newsEmail" BOOLEAN NOT NULL DEFAULT false,
+ADD COLUMN     "newsWhatsApp" BOOLEAN NOT NULL DEFAULT false;
+
+-- CreateTable
+CREATE TABLE "CommunicationConsent" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT,
+    "address" TEXT,
+    "channel" TEXT NOT NULL,
+    "granted" BOOLEAN NOT NULL,
+    "source" TEXT NOT NULL,
+    "ip" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "CommunicationConsent_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "MessagingOptOut" (
+    "id" TEXT NOT NULL,
+    "channel" TEXT NOT NULL,
+    "address" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "MessagingOptOut_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "DataRequest" (
+    "id" TEXT NOT NULL,
+    "type" "DataRequestType" NOT NULL,
+    "status" "DataRequestStatus" NOT NULL DEFAULT 'open',
+    "userId" TEXT,
+    "name" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "details" TEXT,
+    "response" TEXT,
+    "selfService" BOOLEAN NOT NULL DEFAULT false,
+    "dueAt" TIMESTAMP(3) NOT NULL,
+    "closedAt" TIMESTAMP(3),
+    "handledById" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "DataRequest_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "CommunicationConsent_userId_createdAt_idx" ON "CommunicationConsent"("userId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "CommunicationConsent_address_idx" ON "CommunicationConsent"("address");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "MessagingOptOut_channel_address_key" ON "MessagingOptOut"("channel", "address");
+
+-- CreateIndex
+CREATE INDEX "DataRequest_status_dueAt_idx" ON "DataRequest"("status", "dueAt");
+
+-- CreateIndex
+CREATE INDEX "DataRequest_userId_idx" ON "DataRequest"("userId");
+
+-- AddForeignKey
+ALTER TABLE "CommunicationConsent" ADD CONSTRAINT "CommunicationConsent_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "DataRequest" ADD CONSTRAINT "DataRequest_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "DataRequest" ADD CONSTRAINT "DataRequest_handledById_fkey" FOREIGN KEY ("handledById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- Existing accounts: kept opted in to news (WhatsApp only when they have a phone number),
+-- logged as "existing_account", and asked once at their next login (newsAskedAt stays null).
+UPDATE "User" SET "newsEmail" = true, "newsWhatsApp" = ("phoneNumber" IS NOT NULL)
+WHERE "isActive" = true AND "email" NOT LIKE '%@deleted.invalid' AND "email" NOT LIKE '%@deleted.local' AND "email" NOT LIKE '%@guest.local';
+
+INSERT INTO "CommunicationConsent" ("id", "userId", "channel", "granted", "source")
+SELECT gen_random_uuid()::text, "id", 'email', true, 'existing_account' FROM "User" WHERE "newsEmail" = true;
+
+INSERT INTO "CommunicationConsent" ("id", "userId", "channel", "granted", "source")
+SELECT gen_random_uuid()::text, "id", 'whatsapp', true, 'existing_account' FROM "User" WHERE "newsWhatsApp" = true;
@@ -0,0 +1,110 @@
+-- AlterEnum
+-- This migration adds more than one value to an enum.
+-- With PostgreSQL versions 11 and earlier, this is not possible
+-- in a single migration. This can be worked around by creating
+-- multiple migrations, each migration adding only one value to
+-- the enum.
+
+
+ALTER TYPE "AdminAuditAction" ADD VALUE 'privacy_notice_published';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'operator_created';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'operator_updated';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'operator_deleted';
+
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN     "noticeVersionAccepted" INTEGER;
+
+-- CreateTable
+CREATE TABLE "PrivacyNotice" (
+    "id" TEXT NOT NULL,
+    "version" INTEGER NOT NULL,
+    "sections" JSONB NOT NULL,
+    "changeSummary" TEXT,
+    "requiresAcceptance" BOOLEAN NOT NULL DEFAULT false,
+    "publishedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "publishedById" TEXT,
+
+    CONSTRAINT "PrivacyNotice_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "NoticeAcceptance" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT,
+    "version" INTEGER NOT NULL,
+    "source" TEXT NOT NULL,
+    "ip" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "NoticeAcceptance_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Operator" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "purpose" TEXT NOT NULL,
+    "dataShared" TEXT NOT NULL,
+    "location" TEXT,
+    "website" TEXT,
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "order" INTEGER NOT NULL DEFAULT 0,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Operator_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "DataAccessLog" (
+    "id" TEXT NOT NULL,
+    "actorId" TEXT,
+    "actorRole" TEXT NOT NULL,
+    "action" TEXT NOT NULL,
+    "what" TEXT NOT NULL,
+    "eventId" TEXT,
+    "records" INTEGER,
+    "ip" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "DataAccessLog_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "PrivacyNotice_version_key" ON "PrivacyNotice"("version");
+
+-- CreateIndex
+CREATE INDEX "NoticeAcceptance_userId_createdAt_idx" ON "NoticeAcceptance"("userId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "NoticeAcceptance_version_idx" ON "NoticeAcceptance"("version");
+
+-- CreateIndex
+CREATE INDEX "DataAccessLog_createdAt_idx" ON "DataAccessLog"("createdAt");
+
+-- CreateIndex
+CREATE INDEX "DataAccessLog_actorId_createdAt_idx" ON "DataAccessLog"("actorId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "DataAccessLog_action_createdAt_idx" ON "DataAccessLog"("action", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "PrivacyNotice" ADD CONSTRAINT "PrivacyNotice_publishedById_fkey" FOREIGN KEY ("publishedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "NoticeAcceptance" ADD CONSTRAINT "NoticeAcceptance_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "DataAccessLog" ADD CONSTRAINT "DataAccessLog_actorId_fkey" FOREIGN KEY ("actorId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- The operator register starts with the services Hope Events itself uses. Admins correct the
+-- details (e.g. which email and hosting provider) in Admin → Privacy → Operators.
+INSERT INTO "Operator" ("id", "name", "purpose", "dataShared", "location", "website", "active", "order", "updatedAt") VALUES
+  (gen_random_uuid()::text, 'Yoco', 'Card payments', 'Payment amount and reference; card details are entered on Yoco''s own page', 'South Africa', 'https://www.yoco.com', true, 1, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'PayFast', 'Online payments', 'Name, email address, payment amount and reference', 'South Africa', 'https://payfast.io', true, 2, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'WAWP', 'Delivering WhatsApp messages', 'Mobile number and message content', NULL, 'https://wawp.net', true, 3, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'WhatsApp (Meta Platforms)', 'The WhatsApp messaging service', 'Mobile number and message content', NULL, 'https://www.whatsapp.com/legal/privacy-policy', true, 4, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'Email delivery provider', 'Sending emails (the SMTP server in Site settings)', 'Name, email address and message content', NULL, NULL, true, 5, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'Hosting provider', 'The servers this site and its database run on', 'All information held by the site', 'South Africa', NULL, true, 6, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'Google Maps', 'Maps on event pages', 'Your device''s IP address and browser details when a map loads', NULL, 'https://policies.google.com/privacy', true, 7, CURRENT_TIMESTAMP),
+  (gen_random_uuid()::text, 'Sentry', 'Error monitoring (only when it is set up)', 'Technical error reports, which can include the signed-in user''s id', NULL, 'https://sentry.io', false, 8, CURRENT_TIMESTAMP);
@@ -0,0 +1,57 @@
+-- CreateEnum
+CREATE TYPE "BreachStatus" AS ENUM ('open', 'contained', 'closed');
+
+-- AlterEnum
+-- This migration adds more than one value to an enum.
+-- With PostgreSQL versions 11 and earlier, this is not possible
+-- in a single migration. This can be worked around by creating
+-- multiple migrations, each migration adding only one value to
+-- the enum.
+
+
+ALTER TYPE "AdminAuditAction" ADD VALUE 'retention_policies_updated';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'retention_run';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'breach_recorded';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'breach_updated';
+
+-- AlterTable
+ALTER TABLE "DataAccessLog" ADD COLUMN     "sensitive" BOOLEAN NOT NULL DEFAULT false;
+
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN     "inactivityWarnedAt" TIMESTAMP(3),
+ADD COLUMN     "lastLoginAt" TIMESTAMP(3);
+
+-- CreateTable
+CREATE TABLE "SecurityBreach" (
+    "id" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "status" "BreachStatus" NOT NULL DEFAULT 'open',
+    "discoveredAt" TIMESTAMP(3) NOT NULL,
+    "occurredAt" TIMESTAMP(3),
+    "description" TEXT NOT NULL,
+    "dataAffected" TEXT NOT NULL,
+    "peopleAffected" INTEGER,
+    "whoAffected" TEXT,
+    "consequences" TEXT,
+    "actionsTaken" TEXT,
+    "adviceToPeople" TEXT,
+    "causedBy" TEXT,
+    "regulatorNotifiedAt" TIMESTAMP(3),
+    "peopleNotifiedAt" TIMESTAMP(3),
+    "createdById" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "SecurityBreach_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "SecurityBreach_status_discoveredAt_idx" ON "SecurityBreach"("status", "discoveredAt");
+
+-- AddForeignKey
+ALTER TABLE "SecurityBreach" ADD CONSTRAINT "SecurityBreach_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- Last login, from the login history (which the retention job will start expiring).
+UPDATE "User" u SET "lastLoginAt" = l.at
+FROM (SELECT "userId", MAX("createdAt") AS at FROM "SecurityEvent" WHERE "type" = 'login' AND "userId" IS NOT NULL GROUP BY "userId") l
+WHERE u."id" = l."userId";
@@ -0,0 +1,3 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'hub_connected';
+
@@ -0,0 +1,76 @@
+-- AlterEnum
+-- This migration adds more than one value to an enum.
+-- With PostgreSQL versions 11 and earlier, this is not possible
+-- in a single migration. This can be worked around by creating
+-- multiple migrations, each migration adding only one value to
+-- the enum.
+
+
+ALTER TYPE "AdminAuditAction" ADD VALUE 'hub_update_requested';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'campuses_toggled';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'campus_created';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'campus_updated';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'campus_archived';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'campus_deleted';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'event_campus_changed';
+
+-- AlterTable
+ALTER TABLE "Event" ADD COLUMN     "campusId" TEXT;
+
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN     "homeCampusId" TEXT;
+
+-- CreateTable
+CREATE TABLE "Campus" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "slug" TEXT NOT NULL,
+    "address" TEXT,
+    "contactName" TEXT,
+    "contactEmail" TEXT,
+    "contactPhone" TEXT,
+    "colour" TEXT,
+    "logoUrl" TEXT,
+    "defaultLocation" TEXT,
+    "order" INTEGER NOT NULL DEFAULT 0,
+    "archivedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Campus_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "_CampusNotifyRecipients" (
+    "A" TEXT NOT NULL,
+    "B" TEXT NOT NULL,
+
+    CONSTRAINT "_CampusNotifyRecipients_AB_pkey" PRIMARY KEY ("A","B")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Campus_slug_key" ON "Campus"("slug");
+
+-- CreateIndex
+CREATE INDEX "Campus_order_idx" ON "Campus"("order");
+
+-- CreateIndex
+CREATE INDEX "_CampusNotifyRecipients_B_index" ON "_CampusNotifyRecipients"("B");
+
+-- CreateIndex
+CREATE INDEX "Event_campusId_idx" ON "Event"("campusId");
+
+-- CreateIndex
+CREATE INDEX "User_homeCampusId_idx" ON "User"("homeCampusId");
+
+-- AddForeignKey
+ALTER TABLE "User" ADD CONSTRAINT "User_homeCampusId_fkey" FOREIGN KEY ("homeCampusId") REFERENCES "Campus"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Event" ADD CONSTRAINT "Event_campusId_fkey" FOREIGN KEY ("campusId") REFERENCES "Campus"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "_CampusNotifyRecipients" ADD CONSTRAINT "_CampusNotifyRecipients_A_fkey" FOREIGN KEY ("A") REFERENCES "Campus"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "_CampusNotifyRecipients" ADD CONSTRAINT "_CampusNotifyRecipients_B_fkey" FOREIGN KEY ("B") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
@@ -0,0 +1,19 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'user_campus_scope_changed';
+
+-- CreateTable
+CREATE TABLE "_UserCampusScope" (
+    "A" TEXT NOT NULL,
+    "B" TEXT NOT NULL,
+
+    CONSTRAINT "_UserCampusScope_AB_pkey" PRIMARY KEY ("A","B")
+);
+
+-- CreateIndex
+CREATE INDEX "_UserCampusScope_B_index" ON "_UserCampusScope"("B");
+
+-- AddForeignKey
+ALTER TABLE "_UserCampusScope" ADD CONSTRAINT "_UserCampusScope_A_fkey" FOREIGN KEY ("A") REFERENCES "Campus"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "_UserCampusScope" ADD CONSTRAINT "_UserCampusScope_B_fkey" FOREIGN KEY ("B") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
@@ -75,6 +75,19 @@ model User {
  notificationPreference NotificationPreference @default(email)
  twoFactorEnabled       Boolean                @default(false)
  twoFactorMethod        TwoFactorMethod?
+  // POPIA: opted in to "News & announcements" (marketing) bulk messages, per channel.
+  // Event updates to registrants don't depend on these. History in CommunicationConsent.
+  newsEmail              Boolean                @default(false)
+  newsWhatsApp           Boolean                @default(false)
+  // When the person last answered the news opt-in question. Null = ask at next login.
+  newsAskedAt            DateTime?
+  // The privacy notice version they last accepted (0 = the built-in notice). Null = never
+  // recorded. Asked again when a version that needs re-acceptance is newer.
+  noticeVersionAccepted  Int?
+  // Retention: when they last logged in (kept here because login history itself expires),
+  // and when they were warned that their inactive account is about to be deleted.
+  lastLoginAt            DateTime?
+  inactivityWarnedAt     DateTime?
  registrations          Registration[]
  payments               Payment[]
  paymentsRecorded       Payment[]              @relation("PaymentRecordedBy")
@@ -121,6 +134,53 @@ model User {
  trustedDevices      TrustedDevice[]
  certificates        Certificate[]
  certificatesIssued  Certificate[] @relation("CertificateIssuedBy")
+  communicationConsents CommunicationConsent[]
+  dataRequests        DataRequest[]
+  dataRequestsHandled DataRequest[] @relation("DataRequestHandledBy")
+  noticesPublished    PrivacyNotice[]
+  noticeAcceptances   NoticeAcceptance[]
+  dataAccessLogs      DataAccessLog[]
+  breachesRecorded    SecurityBreach[]
+
+  // Multi-campus (only used while Site settings → Campuses is on).
+  homeCampusId        String?
+  homeCampus          Campus?  @relation("UserHomeCampus", fields: [homeCampusId], references: [id], onDelete: SetNull)
+  campusSummaries     Campus[] @relation("CampusNotifyRecipients")
+  // Campus-scoped staff (1.44.0): a supervisor/staff member limited to these campuses (their
+  // events plus events for all campuses). Empty = unscoped. Ignored for admins and while
+  // campuses are off (utils/campusScope.js).
+  scopedCampuses      Campus[] @relation("UserCampusScope")
+
+  @@index([homeCampusId])
+}
+
+// A campus of the church (Site settings → Campuses, off by default). Events belong to one
+// campus, or to all campuses when Event.campusId is null. Archived instead of deleted once
+// it has events.
+model Campus {
+  id               String    @id @default(uuid())
+  name             String
+  slug             String    @unique
+  address          String?
+  contactName      String?
+  contactEmail     String?
+  contactPhone     String?
+  // Accent colour (#rrggbb) and logo shown with the campus on the public site.
+  colour           String?
+  logoUrl          String?
+  // Pre-fills Event.location when an event is created for this campus.
+  defaultLocation  String?
+  order            Int       @default(0)
+  archivedAt       DateTime?
+  createdAt        DateTime  @default(now())
+  updatedAt        DateTime  @updatedAt
+  events           Event[]
+  homeOf           User[]    @relation("UserHomeCampus")
+  // Get the daily summary for this campus's events (on top of each event's own recipients).
+  notifyRecipients User[]    @relation("CampusNotifyRecipients")
+  scopedStaff      User[]    @relation("UserCampusScope")
+
+  @@index([order])
 }

 model Event {
@@ -167,6 +227,9 @@ model Event {
  contactPhone            String?
  contactEmail            String?
  location                String?
+  // Multi-campus: null = all campuses (also every event while campuses are off).
+  campusId                String?
+  campus                  Campus?           @relation(fields: [campusId], references: [id], onDelete: Restrict)
  createdAt               DateTime          @default(now())
  updatedAt               DateTime          @updatedAt
  createdById             String?
@@ -226,6 +289,7 @@ model Event {
  @@index([createdById])
  @@index([closedById])
  @@index([reopenedById])
+  @@index([campusId])
 }

 model EventOption {
@@ -344,6 +408,9 @@ model RegistrationOption {
  // everything else.
  sessionId      String?
  session        EventSession?               @relation(fields: [sessionId], references: [id], onDelete: Restrict)
+  // An all-sessions option on a "pick sessions" event: the sessions chosen (one line,
+  // one ticket, one price). Empty = every session.
+  sessionIds     String[]                    @default([])

  @@index([registrationId])
  @@index([eventOptionId])
@@ -390,6 +457,9 @@ model Payment {
  externalId        String?           @unique
  status            String?
  originalPaymentId String?
+  // Online payments: the payment provider that took it (src/payments, e.g. "yoco"). Null for
+  // payments recorded by staff. Payment.method stays the wallet type (card, apple_pay, …).
+  provider          String?
  createdAt         DateTime          @default(now())
  user              User              @relation(fields: [userId], references: [id], onDelete: Restrict)
  recordedBy        User?             @relation("PaymentRecordedBy", fields: [recordedById], references: [id], onDelete: SetNull)
@@ -397,7 +467,7 @@ model Payment {
  event             Event?            @relation(fields: [eventId], references: [id], onDelete: SetNull)
  originalPayment   Payment?          @relation("SplitPayments", fields: [originalPaymentId], references: [id], onDelete: SetNull)
  splitPayments     Payment[]         @relation("SplitPayments")
-  YocoTransaction   YocoTransaction[]
+  providerTransactions ProviderTransaction[]

  @@index([userId])
  @@index([recordedById])
@@ -557,12 +627,34 @@ enum AdminAuditAction {
  yoco_config_updated
  yoco_webhook_registered
  yoco_webhook_deleted
+  payment_providers_updated
+  payfast_config_updated
  event_sessions_changed
  attendance_marked
  attendance_unmarked
  certificate_issued
  certificate_revoked
  job_run_manual
+  data_request_completed
+  data_request_rejected
+  user_anonymised
+  privacy_notice_published
+  operator_created
+  operator_updated
+  operator_deleted
+  retention_policies_updated
+  retention_run
+  breach_recorded
+  breach_updated
+  hub_connected
+  hub_update_requested
+  campuses_toggled
+  campus_created
+  campus_updated
+  campus_archived
+  campus_deleted
+  event_campus_changed
+  user_campus_scope_changed
 }

 // Append-only audit trail for admin/supervisor-initiated actions with money or
@@ -677,9 +769,12 @@ model FormDraft {

 // Stores all webhook events from Yoco. If a Payment is created (registration or donation),
 // the record is marked reconciled and linked via paymentId. Otherwise, remains unreconciled.
-model YocoTransaction {
+// A transaction a payment provider told us about (by webhook). Matched to a Payment when it
+// belongs to one of our checkouts; the rest wait on the Payments page to be reconciled.
+model ProviderTransaction {
  id          String    @id @default(uuid())
-  externalId  String    @unique // Yoco payment/event id
+  provider    String    @default("yoco") // payment provider id (src/payments)
+  externalId  String    // the provider's payment/event id
  amount      Int?
  currency    String?
  createdDate DateTime?
@@ -690,12 +785,37 @@ model YocoTransaction {
  paymentId   String?
  payment     Payment?  @relation(fields: [paymentId], references: [id], onDelete: SetNull)
  raw         Json?
+  // Why it wasn't recorded automatically and needs a look (e.g. paid a different amount
+  // from the checkout).
+  note        String?
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt

+  @@unique([provider, externalId])
  @@index([paymentId])
 }

+// An online checkout we started: what it's for and how much, so the payment that comes back
+// can be checked against it. Its id is the payer's link (/pay/<id>) and, for PayFast, the
+// m_payment_id. `provider` is null until the payer picks one (when several are enabled).
+model ProviderCheckout {
+  id          String    @id @default(uuid())
+  provider    String?
+  // The provider's own checkout id (Yoco) and where it sends the payer.
+  externalId  String?
+  redirectUrl String?
+  amountCents Int
+  currency    String    @default("ZAR")
+  // Who/what the payment is for: registrationId, userId, eventId, type, donationAmount, …
+  metadata    Json
+  // Everything needed to start the checkout with any provider: lineItems, return URLs, payer.
+  request     Json
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([provider, externalId])
+}
+
 model Section {
  id        String   @id @default(uuid())
  eventId   String
@@ -1364,6 +1484,8 @@ model WaitlistEntry {
  eventId         String
  eventOptionId   String
  variantId       String?
+  // "Pick sessions" options: the session they're waiting for. Null for everything else.
+  sessionId       String?
  userId          String
  quantity        Int
  position        Int
@@ -1379,12 +1501,14 @@ model WaitlistEntry {
  event           Event          @relation(fields: [eventId], references: [id], onDelete: Cascade)
  eventOption     EventOption    @relation(fields: [eventOptionId], references: [id], onDelete: Cascade)
  variant         OptionVariant? @relation(fields: [variantId], references: [id], onDelete: Cascade)
+  session         EventSession?  @relation(fields: [sessionId], references: [id], onDelete: Cascade)
  user            User           @relation(fields: [userId], references: [id], onDelete: Cascade)
  registration    Registration?  @relation(fields: [registrationId], references: [id], onDelete: SetNull)

  @@index([eventId, status, position])
  @@index([eventOptionId, status])
  @@index([variantId])
+  @@index([sessionId])
  @@index([userId])
  @@index([registrationId])
 }
@@ -1483,6 +1607,7 @@ model EventSession {
  usages      TicketUsage[]
  reminders   SessionReminderLog[]
  registrationOptions RegistrationOption[]
+  waitlistEntries     WaitlistEntry[]

  @@index([eventId, startsAt])
 }
@@ -1526,3 +1651,181 @@ model Certificate {
  @@index([ticketId])
  @@index([issuedById])
 }
+
+// ─── POPIA ────────────────────────────────────────────────────────────────────
+
+// Every change to someone's "News & announcements" opt-in: who, which channel, on or off,
+// when and how. Append-only — it's the proof of consent. `address` is set instead of
+// userId for people without an account (an ad-hoc broadcast address that unsubscribed).
+model CommunicationConsent {
+  id        String   @id @default(uuid())
+  userId    String?
+  user      User?    @relation(fields: [userId], references: [id], onDelete: SetNull)
+  address   String?
+  channel   String // email | whatsapp
+  granted   Boolean
+  // signup | privacy_centre | prompt | unsubscribe_link | whatsapp_stop | existing_account | admin
+  source    String
+  ip        String?
+  createdAt DateTime @default(now())
+
+  @@index([userId, createdAt])
+  @@index([address])
+}
+
+// Addresses (email, or phone as 27…) that unsubscribed from news without an account,
+// e.g. ad-hoc broadcast recipients. News broadcasts skip them.
+model MessagingOptOut {
+  id        String   @id @default(uuid())
+  channel   String // email | whatsapp
+  address   String
+  source    String
+  createdAt DateTime @default(now())
+
+  @@unique([channel, address])
+}
+
+enum DataRequestType {
+  access
+  correction
+  deletion
+}
+
+enum DataRequestStatus {
+  open
+  completed
+  rejected
+  cancelled
+}
+
+// A POPIA request from a data subject. Name and email are copied in so the request
+// still shows who made it after the account is anonymised.
+model DataRequest {
+  id          String            @id @default(uuid())
+  type        DataRequestType
+  status      DataRequestStatus @default(open)
+  userId      String?
+  user        User?             @relation(fields: [userId], references: [id], onDelete: SetNull)
+  name        String
+  email       String
+  details     String?
+  // The admin's answer, sent to the requester when the request is closed.
+  response    String?
+  // Made and fulfilled by the person themselves (e.g. "Download my data").
+  selfService Boolean           @default(false)
+  dueAt       DateTime
+  closedAt    DateTime?
+  handledById String?
+  handledBy   User?             @relation("DataRequestHandledBy", fields: [handledById], references: [id], onDelete: SetNull)
+  createdAt   DateTime          @default(now())
+  updatedAt   DateTime          @updatedAt
+
+  @@index([status, dueAt])
+  @@index([userId])
+}
+
+// A published version of the privacy notice (versions start at 1). With none published,
+// the built-in notice from utils/privacyNotice.js is shown as version 0. Section bodies
+// keep their {placeholders} (org name, Information Officer, operators…), filled in when
+// shown, so the notice follows Site settings and the operator register.
+model PrivacyNotice {
+  id                 String   @id @default(uuid())
+  version            Int      @unique
+  sections           Json // [{ id, title, body }]
+  changeSummary      String?
+  // Everyone is asked to accept this version again after logging in.
+  requiresAcceptance Boolean  @default(false)
+  publishedAt        DateTime @default(now())
+  publishedById      String?
+  publishedBy        User?    @relation(fields: [publishedById], references: [id], onDelete: SetNull)
+}
+
+// Someone accepted a version of the privacy notice. Append-only proof, like
+// CommunicationConsent.
+model NoticeAcceptance {
+  id        String   @id @default(uuid())
+  userId    String?
+  user      User?    @relation(fields: [userId], references: [id], onDelete: SetNull)
+  version   Int
+  source    String // signup | prompt
+  ip        String?
+  createdAt DateTime @default(now())
+
+  @@index([userId, createdAt])
+  @@index([version])
+}
+
+// A third party that processes personal information for the church (POPIA "operator"):
+// payment providers, WhatsApp and email delivery, hosting… Active ones are listed in the
+// privacy notice.
+model Operator {
+  id         String   @id @default(uuid())
+  name       String
+  purpose    String
+  dataShared String
+  location   String?
+  website    String?
+  active     Boolean  @default(true)
+  order      Int      @default(0)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+}
+
+// Someone exported or viewed personal information in bulk: report exports, the attendance
+// register, certificate downloads, group lists, form answers, the consent and medical lists,
+// backups, and viewing the site as another user.
+model DataAccessLog {
+  id        String   @id @default(uuid())
+  actorId   String?
+  actor     User?    @relation(fields: [actorId], references: [id], onDelete: SetNull)
+  actorRole String
+  // report_pdf | report_excel | report_email | report_whatsapp | attendance_export |
+  // certificates_download | group_lists | form_responses | consent_list | medical_list |
+  // backup_download | impersonation
+  action    String
+  what      String
+  eventId   String?
+  records   Int?
+  // Children's or special personal information (youth events, medical details).
+  sensitive Boolean  @default(false)
+  ip        String?
+  createdAt DateTime @default(now())
+
+  @@index([createdAt])
+  @@index([actorId, createdAt])
+  @@index([action, createdAt])
+}
+
+enum BreachStatus {
+  open
+  contained
+  closed
+}
+
+// POPIA s22: a security compromise — what happened, whose information, what was done, and
+// when the Information Regulator and the people affected were told.
+model SecurityBreach {
+  id                  String       @id @default(uuid())
+  title               String
+  status              BreachStatus @default(open)
+  discoveredAt        DateTime
+  occurredAt          DateTime?
+  description         String
+  dataAffected        String
+  peopleAffected      Int?
+  // Free text: who (groups of people, events…), since a breach can involve people without accounts.
+  whoAffected         String?
+  consequences        String?
+  actionsTaken        String?
+  adviceToPeople      String?
+  // Who caused it, if known (POPIA asks for this when notifying).
+  causedBy            String?
+  regulatorNotifiedAt DateTime?
+  peopleNotifiedAt    DateTime?
+  createdById         String?
+  createdBy           User?        @relation(fields: [createdById], references: [id], onDelete: SetNull)
+  createdAt           DateTime     @default(now())
+  updatedAt           DateTime     @updatedAt
+
+  @@index([status, discoveredAt])
+}
@@ -287,6 +287,10 @@ const getSetLists = async (req, res) => {
    if (!set) throw allocationError('Allocation set not found', 404);
    const withMedical = req.query.medical === 'true';
    const members = await groupMembers(set.groups.map(g => g.id), { withMedical });
+    require('../utils/accessLog').logDataAccess(req, {
+      action: withMedical ? 'medical_list' : 'group_lists', what: `${set.name} lists — ${set.event?.title || 'event'}${withMedical ? ' (with medical details)' : ''}`,
+      eventId: set.eventId, records: members.length,
+    });
    if (withMedical) {
      logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'medical_list_viewed', targetType: 'AllocationSet', targetId: set.id, metadata: { eventId: set.eventId, attendees: members.length }, ip: getClientIp(req) });
    }
@@ -21,9 +21,13 @@ const trackStage = async (req, res) => {
 // @access  Private/Supervisor
 const getFunnel = async (req, res) => {
  try {
-    const eventIds = String(req.query.eventIds || '').split(',').map(s => s.trim()).filter(Boolean).slice(0, 50);
-    if (eventIds.length === 0) { res.status(400); throw new Error('Choose at least one event'); }
-    const events = await prisma.event.findMany({ where: { id: { in: eventIds } }, select: { id: true, title: true } });
+    const asked = String(req.query.eventIds || '').split(',').map(s => s.trim()).filter(Boolean).slice(0, 50);
+    if (asked.length === 0) { res.status(400); throw new Error('Choose at least one event'); }
+    // Campus-scoped supervisors only get the events they can see.
+    const scopeWhere = await require('../utils/campusScope').listWhere(req);
+    const events = await prisma.event.findMany({ where: { id: { in: asked }, ...scopeWhere }, select: { id: true, title: true } });
+    const eventIds = events.map(e => e.id);
+    if (eventIds.length === 0) { res.status(404); throw new Error('Event not found'); }
    const total = await funnelFor(eventIds, { from: req.query.from, to: req.query.to });
    // Per event too, so events can be compared.
    const perEvent = [];
@@ -42,7 +42,7 @@ async function buildRegister(eventId) {
      holder: { select: { name: true } },
      user: { select: { name: true, email: true, phoneNumber: true } },
      usages: { select: { quantityRedeemed: true, sessionId: true, manual: true } },
-      registrationOption: { select: { registrationId: true, eventOptionId: true, variantId: true, sessionId: true, eventOption: { select: { name: true } }, variant: { select: { name: true } } } },
+      registrationOption: { select: { registrationId: true, eventOptionId: true, variantId: true, sessionId: true, sessionIds: true, eventOption: { select: { name: true } }, variant: { select: { name: true } } } },
      certificates: { select: { id: true, code: true, issuedAt: true, revokedAt: true, manual: true, emailedAt: true } },
    },
    orderBy: { createdAt: 'asc' },
@@ -68,9 +68,10 @@ async function buildRegister(eventId) {
    const cert = t.certificates[0] || null;
    return {
      ticketId: t.id,
-      // Picked sessions: which sessions this person booked, and the ticket for each.
+      // Picked or ticked sessions: which sessions this person booked, and the ticket for each
+      // (an all-sessions ticket with sessions ticked is one ticket for all of them).
      bookedSessions: g.sessionIds,
-      sessionTickets: g.sessionIds ? Object.fromEntries(g.tickets.map(tk => [tk.registrationOption.sessionId, tk.id])) : null,
+      sessionTickets: g.sessionIds ? Object.fromEntries(g.tickets.flatMap(tk => (tk.registrationOption.sessionId ? [[tk.registrationOption.sessionId, tk.id]] : g.sessionIds.map(id => [id, tk.id])))) : null,
      name: t.attendee?.name || t.holder?.name || t.user?.name || '',
      bookedBy: t.attendee || t.holder ? t.user?.name || '' : '',
      email: t.user?.email || '',
@@ -117,7 +118,7 @@ const markAttendance = async (req, res) => {
    const { eventId } = req.params;
    const { ticketId, present } = req.body || {};
    const sessionKey = String(req.body?.sessionId || '');
-    const ticket = await prisma.ticket.findUnique({ where: { id: String(ticketId || '') }, include: { usages: true, event: { select: { scheduleType: true, cashupStatus: true } }, registrationOption: { select: { sessionId: true } } } });
+    const ticket = await prisma.ticket.findUnique({ where: { id: String(ticketId || '') }, include: { usages: true, event: { select: { scheduleType: true, cashupStatus: true } }, registrationOption: { select: { sessionId: true, sessionIds: true } } } });
    if (!ticket || ticket.eventId !== eventId) throw notFound('Ticket not found for this event');
    if (ticket.event.cashupStatus === 'closed') throw badRequest('This event is closed — reopen it to change attendance.');
    const multi = ticket.event.scheduleType === 'sessions';
@@ -126,7 +127,7 @@ const markAttendance = async (req, res) => {
      const session = await prisma.eventSession.findUnique({ where: { id: sessionKey } });
      if (!session || session.eventId !== eventId) throw notFound('Session not found for this event');
      if (session.cancelledAt) throw badRequest('That session was cancelled');
-      if (ticket.registrationOption?.sessionId && ticket.registrationOption.sessionId !== session.id) throw badRequest('That ticket is for a different session');
+      if (ticket.registrationOption && !require('../utils/sessions').lineCovers(ticket.registrationOption, session.id)) throw badRequest('That ticket isn\'t booked for this session');
      sessionId = session.id;
    } else if (sessionKey !== WHOLE_EVENT) {
      throw badRequest('This event has no sessions');
@@ -174,6 +175,10 @@ const exportRegister = async (req, res) => {
  try {
    const reg = await buildRegister(req.params.eventId);
    const cols = reg.columns.filter(c => !c.cancelled);
+    require('../utils/accessLog').logDataAccess(req, {
+      action: 'attendance_export', what: `Attendance register — ${reg.event.title} (${req.query.format === 'pdf' ? 'PDF' : 'Excel'})`,
+      eventId: req.params.eventId, records: reg.rows.length,
+    });
    if (req.query.format === 'pdf') {
      const doc = new PDFDocument({ size: 'A4', layout: 'landscape', margin: 36 });
      res.setHeader('Content-Type', 'application/pdf');
@@ -319,6 +324,7 @@ const downloadEventCertificates = async (req, res) => {
    const certs = await prisma.certificate.findMany({ where: { eventId: event.id, revokedAt: null }, orderBy: { name: 'asc' } });
    if (certs.length === 0) throw badRequest('No certificates have been issued for this event yet.');
    const pdf = await certificates.renderCertificatesPdf(certs, event);
+    require('../utils/accessLog').logDataAccess(req, { action: 'certificates_download', what: `Certificates — ${event.title}`, eventId: event.id, records: certs.length });
    res.setHeader('Content-Type', 'application/pdf');
    res.setHeader('Content-Disposition', `attachment; filename="${`Certificates - ${event.title}`.replace(/[^a-z0-9 -]/gi, '').slice(0, 80)}.pdf"`);
    res.send(pdf);
@@ -44,6 +44,7 @@ const downloadBackup = async (req, res) => {
      res.status(404);
      throw new Error('Backup not found');
    }
+    require('../utils/accessLog').logDataAccess(req, { action: 'backup_download', what: `Database backup ${filename}` });
    res.download(filePath, filename);
  } catch (e) {
    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(e) });
@@ -30,6 +30,7 @@ function buildEventContext(event) {
 }

 const { replacePlaceholders } = require('../utils/placeholders');
+const { normaliseKind, filterRecipients, bulkEmailFooter } = require('../utils/privacy');

 function parseFreeformEmails(lines) {
  // Supports formats:
@@ -103,16 +104,16 @@ const previewBroadcast = async (req, res) => {
      if (!email) continue;
      if (!map.has(email)) map.set(email, { email, name: r.name || '' });
    }
-    const recipients = Array.from(map.values());
+    const kind = normaliseKind(req.body?.kind) || 'news';
+    const { recipients, skipped } = await filterRecipients(Array.from(map.values()), { channel: 'email', kind });

    // Optionally resolve event info for link/title placeholder
    let event = null;
    if (eventId && typeof eventId === 'string') {
      event = await prisma.event.findUnique({ where: { id: eventId } });
    }
-    const eventCtx = buildEventContext(event);

-    return res.json({ matched: recipients.length, recipients: recipients.slice(0, 20), event: event ? { id: event.id, title: event.title } : null, placeholders: ['{{name}}','{{event.title}}','{{event.start}}','{{event.link}}'] });
+    return res.json({ kind, matched: recipients.length, skipped, recipients: recipients.slice(0, 20), event: event ? { id: event.id, title: event.title } : null, placeholders: ['{{name}}','{{event.title}}','{{event.start}}','{{event.link}}'] });
  } catch (error) {
    return res.status(400).json({ message: error.message });
  }
@@ -147,9 +148,12 @@ const sendBroadcast = async (req, res) => {
      if (!email) continue;
      if (!map.has(email)) map.set(email, { email, name: r.name || '' });
    }
-    const recipients = Array.from(map.values());
+    // Ad-hoc broadcasts are News & announcements unless the sender marks them as an event
+    // update; news skips people who haven't opted in or unsubscribed.
+    const kind = normaliseKind(req.body?.kind) || 'news';
+    const { recipients, skipped } = await filterRecipients(Array.from(map.values()), { channel: 'email', kind });
    if (recipients.length === 0) {
-      return res.status(400).json({ message: 'No valid recipients' });
+      return res.status(400).json({ message: skipped ? 'Everyone selected has unsubscribed from news.' : 'No valid recipients' });
    }

    // Resolve event
@@ -177,9 +181,10 @@ const sendBroadcast = async (req, res) => {
        eventLinkHtml: eventCtx.eventLinkHtml,
      } : ctxBase;
      const finalSubject = await replacePlaceholders(subject, ctxBase);
-      const finalHtml = html ? await replacePlaceholders(html, ctxForHtml) : undefined;
-      const finalText = (!html ? await replacePlaceholders(text || '', ctxBase) : undefined);
-      await sendMail({ to: rcpt.email, subject: finalSubject, html: finalHtml, text: finalText });
+      const footer = bulkEmailFooter({ kind, recipient: rcpt, eventTitle: eventCtx.eventTitle });
+      const finalHtml = html ? (await replacePlaceholders(html, ctxForHtml)) + footer.html : undefined;
+      const finalText = (!html ? (await replacePlaceholders(text || '', ctxBase)) + footer.text : undefined);
+      await sendMail({ to: rcpt.email, subject: finalSubject, html: finalHtml, text: finalText, headers: footer.headers });
    }));

    const sent = results.filter(r => r.status === 'fulfilled').length;
@@ -189,7 +194,7 @@ const sendBroadcast = async (req, res) => {
      }
    });

-    return res.json({ matched: recipients.length, sent });
+    return res.json({ kind, matched: recipients.length, skipped, sent });
  } catch (error) {
    return res.status(400).json({ message: error.message });
  }
@@ -200,13 +205,13 @@ const sendBroadcast = async (req, res) => {
 // @access  Private/Supervisor or Admin
 const scheduleBroadcast = async (req, res) => {
  try {
-    const { scheduledAt, subject, html, text, userIds, emails, eventId } = req.body || {};
+    const { scheduledAt, subject, html, text, userIds, emails, eventId, kind } = req.body || {};
    if (!scheduledAt) return res.status(400).json({ message: 'scheduledAt is required' });
    const when = new Date(scheduledAt);
    if (isNaN(when.getTime())) return res.status(400).json({ message: 'scheduledAt must be a valid ISO date-time' });
    if (!subject || !(html || text)) return res.status(400).json({ message: 'Subject and message (html or text) are required' });

-    const payload = { subject, html, text, userIds, emails, eventId };
+    const payload = { subject, html, text, userIds, emails, eventId, kind };

    const recipientSummary = await describeBroadcastRecipients({ userIds, emails: parseFreeformEmails(emails) });

@@ -0,0 +1,193 @@
+const prisma = require('../config/db');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { getClientIp } = require('../utils/requestUtils');
+const { logAdminAction } = require('../utils/adminAudit');
+const { invalidate: invalidateSettingsCache, warmCache } = require('../utils/settingsCache');
+const { SETTING_KEY, CAMPUS_PUBLIC_SELECT, campusesEnabled, cleanCampusInput, campusAudienceWhere } = require('../utils/campuses');
+
+const audit = (req, action, campus, metadata) => logAdminAction({
+  actorId: req.user.id, actorRole: req.user.role, action, targetType: 'Campus', targetId: campus?.id, metadata: { name: campus?.name, ...metadata }, ip: getClientIp(req),
+});
+
+// A slug that's already taken → a message instead of a Prisma error.
+function friendlyError(e) {
+  if (e?.code === 'P2002') return 'Another campus already uses that web address — choose a different one.';
+  return e.message || safeErrorMessage(e);
+}
+
+const ADMIN_INCLUDE = {
+  notifyRecipients: { select: { id: true, name: true, email: true } },
+  _count: { select: { events: true, homeOf: true, scopedStaff: true } },
+};
+
+// @desc    Whether campuses are on, and the active campuses (public site filters, event cards)
+// @route   GET /api/campuses
+// @access  Public
+const getCampuses = async (req, res) => {
+  try {
+    const enabled = await campusesEnabled();
+    const campuses = enabled
+      ? await prisma.campus.findMany({ where: { archivedAt: null }, select: CAMPUS_PUBLIC_SELECT, orderBy: [{ order: 'asc' }, { name: 'asc' }] })
+      : [];
+    res.json({ enabled, campuses });
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    A campus landing page: the campus (active only)
+// @route   GET /api/campuses/by-slug/:slug
+// @access  Public
+const getCampusBySlug = async (req, res) => {
+  try {
+    const campus = (await campusesEnabled())
+      ? await prisma.campus.findFirst({ where: { slug: String(req.params.slug), archivedAt: null }, select: CAMPUS_PUBLIC_SELECT })
+      : null;
+    if (!campus) return res.status(404).json({ message: 'Campus not found' });
+    res.json(campus);
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    All campuses with archived ones, event counts and summary recipients (Site settings → Campuses)
+// @route   GET /api/campuses/admin
+// @access  Private/Admin
+const getCampusesAdmin = async (req, res) => {
+  try {
+    const [enabled, campuses] = await Promise.all([
+      campusesEnabled(),
+      prisma.campus.findMany({ include: ADMIN_INCLUDE, orderBy: [{ archivedAt: { sort: 'asc', nulls: 'first' } }, { order: 'asc' }, { name: 'asc' }] }),
+    ]);
+    res.json({ enabled, campuses });
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    Turn campuses on or off (off hides campus fields and filters; nothing is deleted)
+// @route   PUT /api/campuses/settings   body: { enabled }
+// @access  Private/Admin
+const updateCampusSettings = async (req, res) => {
+  try {
+    const enabled = req.body?.enabled === true;
+    await prisma.appSetting.upsert({ where: { key: SETTING_KEY }, update: { value: String(enabled) }, create: { key: SETTING_KEY, value: String(enabled) } });
+    invalidateSettingsCache();
+    await warmCache();
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'campuses_toggled', targetType: 'AppSetting', metadata: { enabled }, ip: getClientIp(req) });
+    res.json({ enabled });
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    Add a campus (added at the end of the list)
+// @route   POST /api/campuses
+// @access  Private/Admin
+const createCampus = async (req, res) => {
+  try {
+    const { data, error } = cleanCampusInput(req.body);
+    if (error) return res.status(400).json({ message: error });
+    const last = await prisma.campus.aggregate({ _max: { order: true } });
+    const campus = await prisma.campus.create({ data: { ...data, order: (last._max.order ?? -1) + 1 }, include: ADMIN_INCLUDE });
+    audit(req, 'campus_created', campus, { slug: campus.slug });
+    res.status(201).json(campus);
+  } catch (e) {
+    res.status(e?.code === 'P2002' ? 409 : 400).json({ message: friendlyError(e) });
+  }
+};
+
+// @desc    Change a campus: details, summary recipients, archived or not
+// @route   PUT /api/campuses/:id   body: campus fields, notifyRecipientIds?, archived?
+// @access  Private/Admin
+const updateCampus = async (req, res) => {
+  try {
+    const existing = await prisma.campus.findUnique({ where: { id: req.params.id } });
+    if (!existing) return res.status(404).json({ message: 'Campus not found' });
+    const { data, error } = cleanCampusInput(req.body, { partial: true });
+    if (error) return res.status(400).json({ message: error });
+
+    if (Array.isArray(req.body?.notifyRecipientIds)) {
+      const ids = req.body.notifyRecipientIds.filter(x => typeof x === 'string' && x);
+      // Summaries go to people who run events — never to ordinary users.
+      const staff = await prisma.user.findMany({ where: { id: { in: ids }, role: { in: ['admin', 'supervisor', 'staff'] } }, select: { id: true } });
+      data.notifyRecipients = { set: staff.map(u => ({ id: u.id })) };
+    }
+    let archiveChange = null;
+    if (req.body?.archived !== undefined) {
+      const archived = req.body.archived === true;
+      if (archived !== !!existing.archivedAt) {
+        data.archivedAt = archived ? new Date() : null;
+        archiveChange = archived;
+      }
+    }
+
+    const campus = await prisma.campus.update({ where: { id: existing.id }, data, include: ADMIN_INCLUDE });
+    if (archiveChange !== null) audit(req, 'campus_archived', campus, { archived: archiveChange });
+    const changed = Object.keys(data).filter(k => k !== 'archivedAt');
+    if (changed.length) audit(req, 'campus_updated', campus, { changed });
+    res.json(campus);
+  } catch (e) {
+    res.status(e?.code === 'P2002' ? 409 : 400).json({ message: friendlyError(e) });
+  }
+};
+
+// @desc    Put the campuses in this order (filters and lists follow it)
+// @route   PUT /api/campuses/order   body: { ids: [...] }
+// @access  Private/Admin
+const reorderCampuses = async (req, res) => {
+  try {
+    const ids = Array.isArray(req.body?.ids) ? req.body.ids.filter(x => typeof x === 'string') : [];
+    if (!ids.length) return res.status(400).json({ message: 'Send the campus ids in their new order.' });
+    await prisma.$transaction(ids.map((id, order) => prisma.campus.updateMany({ where: { id }, data: { order } })));
+    res.json({ ok: true });
+  } catch (e) {
+    res.status(400).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    Delete a campus that has no events (otherwise archive it). Home campus is cleared.
+// @route   DELETE /api/campuses/:id
+// @access  Private/Admin
+const deleteCampus = async (req, res) => {
+  try {
+    const campus = await prisma.campus.findUnique({ where: { id: req.params.id }, include: { _count: { select: { events: true, scopedStaff: true } } } });
+    if (!campus) return res.status(404).json({ message: 'Campus not found' });
+    // Deleting would drop their limit and leave them unscoped (seeing every campus).
+    if (campus._count.scopedStaff > 0) {
+      return res.status(409).json({ code: 'CAMPUS_HAS_SCOPED_STAFF', message: `${campus._count.scopedStaff} staff member${campus._count.scopedStaff === 1 ? ' is' : 's are'} limited to ${campus.name}. Change their campuses in Admin → Users first, or archive the campus.` });
+    }
+    if (campus._count.events > 0) {
+      return res.status(409).json({ code: 'CAMPUS_HAS_EVENTS', message: `${campus.name} has ${campus._count.events} event${campus._count.events === 1 ? '' : 's'}, so it can't be deleted. Archive it instead.` });
+    }
+    await prisma.campus.delete({ where: { id: campus.id } });
+    audit(req, 'campus_deleted', campus, { slug: campus.slug });
+    res.json({ message: 'Campus deleted' });
+  } catch (e) {
+    res.status(400).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    "Everyone at campus X" for the email/WhatsApp composers: home campus X, plus (with
+//          ?registrants=true) people registered for X's events in the last 12 months. The
+//          composer sends to these ids as usual, so news consent is still checked on sending.
+// @route   GET /api/campuses/:id/audience?registrants=true
+// @access  Private/Supervisor
+const getCampusAudience = async (req, res) => {
+  try {
+    const campus = await prisma.campus.findUnique({ where: { id: req.params.id }, select: { id: true, name: true } });
+    if (!campus) return res.status(404).json({ message: 'Campus not found' });
+    const scope = await require('../utils/campusScope').scopeFor(req);
+    if (scope && !scope.campusIds.includes(campus.id)) return res.status(404).json({ message: 'Campus not found' });
+    const users = await prisma.user.findMany({
+      where: campusAudienceWhere(campus.id, { includeRegistrants: req.query.registrants === 'true' }),
+      select: { id: true, name: true, email: true, phoneNumber: true },
+      orderBy: { name: 'asc' },
+    });
+    res.json({ campus, users });
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+module.exports = { getCampusAudience, getCampuses, getCampusBySlug, getCampusesAdmin, updateCampusSettings, createCampus, updateCampus, reorderCampuses, deleteCampus };
@@ -291,9 +291,12 @@ const resolvePending = async (req, res) => {
 const getCashupAudit = async (req, res) => {
  try {
    const { eventId, from, to } = req.query;
+    // Campus-scoped supervisors only see cashups they could do: their campuses' events.
+    const scope = await require('../utils/campusScope').scopeFor(req);

    const where = {};
    if (eventId) where.eventId = eventId;
+    if (scope) where.event = require('../utils/campusScope').manageWhere(scope);
    if (from || to) {
      where.createdAt = {};
      if (from) where.createdAt.gte = new Date(from);
@@ -156,6 +156,7 @@ const listEventConsent = async (req, res) => {
    const { event, rows } = await consentRows(req.params.eventId);
    if (!event) { res.status(404); throw new Error('Event not found'); }
    const counts = rows.reduce((c, r) => { c[r.status] = (c[r.status] || 0) + 1; return c; }, {});
+    require('../utils/accessLog').logDataAccess(req, { action: 'consent_list', what: `Parental consent — ${event.title}`, eventId: event.id, records: rows.length });
    res.json({
      event: { id: event.id, title: event.title, startDate: event.startDate, requiresParentalConsent: event.requiresParentalConsent, consentTextVersion: event.consentTextVersion },
      counts,
@@ -255,6 +256,7 @@ const medicalList = async (req, res) => {
      targetType: 'Event', targetId: event.id, metadata: { attendees: list.length },
      ip: getClientIp(req),
    });
+    require('../utils/accessLog').logDataAccess(req, { action: 'medical_list', what: `Medical list — ${event.title}`, eventId: event.id, records: list.length });
    res.json({ event: { id: event.id, title: event.title, startDate: event.startDate }, rows: list });
  } catch (error) {
    fail(res, error);
@@ -5,18 +5,29 @@ const { getClientIp } = require('../utils/requestUtils');
 const { normalizeCode, previewCoupon, buildCouponLines, describeCoupon, countCouponUses } = require('../utils/coupons');
 const { resolveOptionPrice, resolveVariantTierPrice } = require('../utils/pricing');
 const { describeBundle } = require('../utils/bundles');
+const { scopeFor, couponAllowed, listWhere } = require('../utils/campusScope');

 const TYPES = ['percent', 'fixed', 'comp'];
 const ROLES = ['user', 'staff', 'supervisor', 'admin'];
 const STAFF_ROLES = ['staff', 'supervisor', 'admin'];

 const COUPON_DETAIL_INCLUDE = {
-  events: { include: { event: { select: { id: true, title: true, startDate: true } } } },
+  events: { include: { event: { select: { id: true, title: true, startDate: true, campusId: true } } } },
  options: { include: { eventOption: { select: { id: true, name: true, eventId: true } }, variant: { select: { id: true, name: true } } } },
  allowedUsers: { include: { user: { select: { id: true, name: true, email: true } } } },
  createdBy: { select: { id: true, name: true } },
 };

+// Campus-scoped supervisors: only coupons limited to events at their campuses (couponAllowed).
+const couponCampuses = coupon => (coupon.events || []).map(ce => ce.event?.campusId ?? null);
+async function eventIdsAllowed(scope, eventIds) {
+  if (!scope) return true;
+  if (!eventIds || eventIds.length === 0) return false; // a coupon for every event
+  const events = await prisma.event.findMany({ where: { id: { in: eventIds } }, select: { campusId: true } });
+  return events.length === eventIds.length && couponAllowed(scope, events.map(e => e.campusId));
+}
+const SCOPED_COUPON_MSG = 'Supervisors for some campuses can only make coupons limited to events at their campuses.';
+
 const optionalDate = (v, label) => {
  if (v === undefined) return undefined;
  if (v === null || v === '') return null;
@@ -119,7 +130,9 @@ function relationWrites({ eventIds, scopes, userIds }, isCreate) {
 // @access  Private/Supervisor
 const listCoupons = async (req, res) => {
  try {
-    const coupons = await prisma.coupon.findMany({ include: COUPON_DETAIL_INCLUDE, orderBy: { createdAt: 'desc' } });
+    const scope = await scopeFor(req);
+    const coupons = (await prisma.coupon.findMany({ include: COUPON_DETAIL_INCLUDE, orderBy: { createdAt: 'desc' } }))
+      .filter(c => couponAllowed(scope, couponCampuses(c)));
    const totals = await prisma.couponRedemption.groupBy({
      by: ['couponId'],
      where: { releasedAt: null, registration: { status: { not: 'cancelled' } } },
@@ -157,7 +170,7 @@ const getCoupon = async (req, res) => {
        },
      },
    });
-    if (!coupon) { res.status(404); throw new Error('Coupon not found'); }
+    if (!coupon || !couponAllowed(await scopeFor(req), couponCampuses(coupon))) { res.status(404); throw new Error('Coupon not found'); }
    res.json({ ...coupon, summary: describeCoupon(coupon) });
  } catch (error) {
    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
@@ -173,6 +186,7 @@ const createCoupon = async (req, res) => {
    try {
      parsed = await parseCouponBody(req.body || {}, { isCreate: true });
    } catch (e) { res.status(400); throw e; }
+    if (!(await eventIdsAllowed(await scopeFor(req), parsed.eventIds))) { res.status(403); throw new Error(SCOPED_COUPON_MSG); }
    if (await prisma.coupon.findUnique({ where: { code: parsed.data.code } })) {
      res.status(409); throw new Error(`The code ${parsed.data.code} already exists`);
    }
@@ -198,12 +212,14 @@ const createCoupon = async (req, res) => {
 // @access  Private/Supervisor
 const updateCoupon = async (req, res) => {
  try {
-    const existing = await prisma.coupon.findUnique({ where: { id: req.params.id } });
-    if (!existing) { res.status(404); throw new Error('Coupon not found'); }
+    const existing = await prisma.coupon.findUnique({ where: { id: req.params.id }, include: { events: { include: { event: { select: { campusId: true } } } } } });
+    const scope = await scopeFor(req);
+    if (!existing || !couponAllowed(scope, couponCampuses(existing))) { res.status(404); throw new Error('Coupon not found'); }
    let parsed;
    try {
      parsed = await parseCouponBody({ type: existing.type, ...req.body }, { isCreate: false });
    } catch (e) { res.status(400); throw e; }
+    if (parsed.eventIds !== undefined && !(await eventIdsAllowed(scope, parsed.eventIds))) { res.status(403); throw new Error(SCOPED_COUPON_MSG); }
    if (parsed.data.code && parsed.data.code !== existing.code) {
      const used = await prisma.couponRedemption.count({ where: { couponId: existing.id } });
      if (used > 0) { res.status(400); throw new Error('This code has been used, so it can\'t be renamed. Turn it off and create a new one instead.'); }
@@ -250,8 +266,11 @@ async function basketBuyer(req, forUserId) {
 /** Prices a basket the same way registration will, as coupon/bundle lines. */
 async function priceBasket(event, options, buyer) {
  const registrationOptions = [];
-  // A "pick sessions" line counts once per chosen session.
-  const expanded = (options || []).flatMap(o => (Array.isArray(o.sessionIds) && o.sessionIds.length ? o.sessionIds.map(sessionId => ({ ...o, sessionId })) : [o]));
+  // A "pick sessions" line counts once per chosen session (an all-sessions ticket with
+  // sessions ticked is still one line at one price).
+  const { isPickOption } = require('../utils/sessions');
+  const perSession = (o) => isPickOption(event, event.eventOptions.find(x => x.id === o.eventOptionId));
+  const expanded = (options || []).flatMap(o => (Array.isArray(o.sessionIds) && o.sessionIds.length && perSession(o) ? o.sessionIds.map(sessionId => ({ ...o, sessionId })) : [o]));
  for (const o of expanded) {
    const eo = event.eventOptions.find(x => x.id === o.eventOptionId);
    const qty = Number(o.quantity || 0);
@@ -324,9 +343,10 @@ const listRedemptions = async (req, res) => {
    const eventIds = String(req.query.eventIds || '').split(',').map(s => s.trim()).filter(Boolean);
    const from = req.query.from ? new Date(req.query.from) : null;
    const to = req.query.to ? new Date(req.query.to) : null;
+    const scopeEvent = await listWhere(req, 'event'); // { event: … } or {}
    const where = {
      releasedAt: null,
-      registration: { status: { not: 'cancelled' }, ...(eventIds.length ? { eventId: { in: eventIds } } : {}) },
+      registration: { status: { not: 'cancelled' }, ...(eventIds.length ? { eventId: { in: eventIds } } : {}), ...scopeEvent },
      ...(from || to ? { createdAt: { ...(from && !isNaN(from) ? { gte: from } : {}), ...(to && !isNaN(to) ? { lte: to } : {}) } } : {}),
    };
    const rows = await prisma.couponRedemption.findMany({
@@ -343,7 +363,7 @@ const listRedemptions = async (req, res) => {
    // discounts are recalculated, so dates go by when the registration was made.
    const regDate = from || to ? { createdAt: { ...(from && !isNaN(from) ? { gte: from } : {}), ...(to && !isNaN(to) ? { lte: to } : {}) } } : {};
    const bundleRows = await prisma.registrationBundle.findMany({
-      where: { registration: { status: { not: 'cancelled' }, ...(eventIds.length ? { eventId: { in: eventIds } } : {}), ...regDate } },
+      where: { registration: { status: { not: 'cancelled' }, ...(eventIds.length ? { eventId: { in: eventIds } } : {}), ...regDate, ...scopeEvent } },
      include: {
        bundle: { include: { items: { include: { eventOption: { select: { name: true } }, variant: { select: { name: true } } } } } },
        registration: { select: { id: true, status: true, createdAt: true, user: { select: { id: true, name: true, email: true } }, event: { select: { id: true, title: true } } } },
@@ -8,6 +8,20 @@ const { assertEventOpen } = require('../utils/cashupUtils');
 const { logAdminAction } = require('../utils/adminAudit');
 const { getClientIp } = require('../utils/requestUtils');
 const sessionsUtil = require('../utils/sessions');
+const { campusesEnabled, campusForEvent, campusWhere, resolveCampusFilter, EVENT_CAMPUS_SELECT } = require('../utils/campuses');
+const { scopeFor, canView, canManage, eventWhere: scopeEventWhere, withScope } = require('../utils/campusScope');
+
+/** A campus-scoped supervisor may only create or move events to one of their campuses. */
+async function assertCampusAllowed(req, campusId) {
+  const scope = await scopeFor(req);
+  if (scope && !canManage(scope, campusId)) {
+    const err = new Error(campusId == null
+      ? 'Choose one of your campuses — events for all campuses are set up by admins and supervisors for every campus.'
+      : 'You can only put events at your own campuses.');
+    err.statusCode = 403;
+    throw err;
+  }
+}

 const SESSIONS_INCLUDE = { orderBy: { startsAt: 'asc' }, include: { _count: { select: { usages: true } } } };

@@ -125,6 +139,11 @@ const createEvent = async (req, res) => {
  try {
    const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, allowSponsorships, sponsorshipGoalSpots, showSponsorshipProgress, contactName, contactPhone, contactEmail, location } = req.body;

+    const campusPick = await campusForEvent(req.body.campusId, { enabled: await campusesEnabled() });
+    if (campusPick.error) { const err = new Error(campusPick.error); err.statusCode = 400; throw err; }
+    // Not choosing a campus means all campuses, which a scoped supervisor can't create.
+    await assertCampusAllowed(req, campusPick.campusId === undefined ? null : campusPick.campusId);
+
    const data = {
      id: uuidv4(),
      title,
@@ -160,6 +179,7 @@ const createEvent = async (req, res) => {
      contactPhone: contactPhone || null,
      contactEmail: contactEmail || null,
      location: location || null,
+      ...(campusPick.campusId !== undefined ? { campusId: campusPick.campusId } : {}),
      ...scheduleData(req.body),
    };
    if (data.scheduleType === 'sessions') {
@@ -325,15 +345,19 @@ const getEvents = async (req, res) => {
    // Determine if Prisma Client supports EarlyBirdTier relation (i.e., migration+generate applied)
    const canIncludeTiers = !!(prisma && prisma.earlyBirdTier && typeof prisma.earlyBirdTier.findMany === 'function');
    const eventOptionsInclude = canIncludeTiers ? { include: { earlyBirdTiers: true } } : true;
+    // ?campus=<slug or id>: that campus's events plus church-wide ones.
+    const enabled = await campusesEnabled();
+    const campusFilter = campusWhere(enabled ? await resolveCampusFilter(req.query.campus) : '', { enabled, withAllCampuses: true });
    try {
      events = await prisma.event.findMany({
        where: {
          isActive: true,
          isHidden: false,
          goLiveAt: { lte: new Date() },
-          endDate: { gte: new Date() }
+          endDate: { gte: new Date() },
+          ...campusFilter,
        },
-        include: { eventOptions: eventOptionsInclude, sessions: SESSIONS_INCLUDE }
+        include: { eventOptions: eventOptionsInclude, sessions: SESSIONS_INCLUDE, campus: { select: EVENT_CAMPUS_SELECT } }
      });
    } catch (e) {
      // Fallback if goLiveAt/isHidden not available yet (pre-migration)
@@ -383,6 +407,7 @@ const getAllEvents = async (req, res) => {
      include: {
        eventOptions: canIncludeTiers ? { include: { earlyBirdTiers: true } } : true,
        sessions: SESSIONS_INCLUDE,
+        campus: { select: EVENT_CAMPUS_SELECT },
      }
    });

@@ -413,6 +438,10 @@ const getEventsAll = async (req, res) => {
    if (!includeInactive) where.isActive = true;
    if (!includePast) where.endDate = { gte: new Date() };
    if (excludeClosed) where.cashupStatus = { not: 'closed' };
+    // ?campus=<id, slug or 'all'>: one campus's events, or only church-wide ones.
+    const enabled = await campusesEnabled();
+    Object.assign(where, campusWhere(enabled ? await resolveCampusFilter(req.query.campus) : '', { enabled }));
+    const scoped = withScope(where, scopeEventWhere(await scopeFor(req)));

    const canIncludeTiers = !!(prisma && prisma.earlyBirdTier && typeof prisma.earlyBirdTier.findMany === 'function');
    const canIncludeVariants = !!(prisma && prisma.optionVariant && typeof prisma.optionVariant.findMany === 'function');
@@ -420,11 +449,12 @@ const getEventsAll = async (req, res) => {
      ? { earlyBirdTiers: true, ...(canIncludeVariants ? { variants: { orderBy: { order: 'asc' } } } : {}) }
      : undefined;
    const events = await prisma.event.findMany({
-      where,
+      where: scoped,
      include: {
        eventOptions: optionInclude ? { include: optionInclude } : true,
        form: { include: { fields: true } },
        sessions: SESSIONS_INCLUDE,
+        campus: { select: EVENT_CAMPUS_SELECT },
      },
      orderBy: { startDate: 'asc' }
    });
@@ -452,7 +482,7 @@ const getEventById = async (req, res) => {
    const optionInclude = canIncludeTiers
      ? { earlyBirdTiers: true, ...(canIncludeVariants ? { variants: { orderBy: { order: 'asc' } } } : {}) }
      : undefined;
-    const includeObj = { eventOptions: optionInclude ? { include: optionInclude } : true, sessions: SESSIONS_INCLUDE };
+    const includeObj = { eventOptions: optionInclude ? { include: optionInclude } : true, sessions: SESSIONS_INCLUDE, campus: { select: EVENT_CAMPUS_SELECT } };

    // Staff/supervisor/admin need the creator + notify-recipient list to populate the
    // event edit screen's Notifications step; public callers don't need this.
@@ -496,9 +526,12 @@ const getEventById = async (req, res) => {
    }

    // Public gating: hide inactive or not-yet-live events from everyone except staff/supervisor/admin,
-    // who need to load inactive events for cashup, editing, etc.
-    const isStaffOrHigher = !!(req.user && ['admin', 'supervisor', 'staff'].includes(req.user.role));
+    // who need to load inactive events for cashup, editing, etc. Campus-scoped staff get the
+    // public view of other campuses' events (and not their notification recipients).
+    const isStaffOrHigher = !!(req.user && ['admin', 'supervisor', 'staff'].includes(req.user.role)) && canView(await scopeFor(req), event.campusId);
    if (!isStaffOrHigher) {
+      delete event.createdBy;
+      delete event.notifyRecipients;
      if (event.isActive === false) {
        res.status(404);
        throw new Error('Event not found');
@@ -627,7 +660,7 @@ const getEventIcs = async (req, res) => {

    // Same public-visibility gate as getEventById — a hidden/not-yet-live event's
    // details shouldn't be enumerable via this route either.
-    const isStaffOrHigher = !!(req.user && ['admin', 'supervisor', 'staff'].includes(req.user.role));
+    const isStaffOrHigher = !!(req.user && ['admin', 'supervisor', 'staff'].includes(req.user.role)) && canView(await scopeFor(req), event.campusId);
    if (!isStaffOrHigher) {
      if (event.isActive === false) {
        res.status(404);
@@ -688,6 +721,13 @@ const updateEvent = async (req, res) => {

    const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, isActive, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, allowSponsorships, sponsorshipGoalSpots, showSponsorshipProgress, contactName, contactPhone, contactEmail, location } = req.body;

+    const campusPick = await campusForEvent(req.body.campusId, { enabled: await campusesEnabled(), currentCampusId: event.campusId });
+    if (campusPick.error) throw new Error(campusPick.error);
+    const campusChanged = campusPick.campusId !== undefined && campusPick.campusId !== event.campusId;
+    if (campusChanged) {
+      try { await assertCampusAllowed(req, campusPick.campusId); } catch (e) { return res.status(403).json({ message: e.message }); }
+    }
+
    const data = {
      title: title || event.title,
      description: description !== undefined ? description : event.description,
@@ -725,6 +765,7 @@ const updateEvent = async (req, res) => {
      contactPhone: contactPhone !== undefined ? (contactPhone || null) : event.contactPhone,
      contactEmail: contactEmail !== undefined ? (contactEmail || null) : event.contactEmail,
      location: location !== undefined ? (location || null) : event.location,
+      ...(campusChanged ? { campusId: campusPick.campusId } : {}),
      updatedAt: new Date(),
      redirectUrl: redirectUrl !== undefined ? redirectUrl : event.redirectUrl,
      ...scheduleData(req.body, event),
@@ -749,6 +790,12 @@ const updateEvent = async (req, res) => {
          : null;
      });
      sessionsUtil.forgetSchedule(updatedEvent.id);
+      if (campusChanged) {
+        logAdminAction({
+          actorId: req.user.id, actorRole: req.user.role, action: 'event_campus_changed',
+          targetType: 'Event', targetId: updatedEvent.id, metadata: { from: event.campusId, to: campusPick.campusId }, ip: getClientIp(req),
+        });
+      }
      if (sessionChanges && Object.values(sessionChanges).some(n => n > 0)) {
        logAdminAction({
          actorId: req.user.id, actorRole: req.user.role, action: 'event_sessions_changed',
@@ -1586,8 +1633,16 @@ const emailEventAttendees = async (req, res) => {
      }
    }

+    // POPIA: an "update" (about this event) goes to everyone selected; "news" (the next-event
+    // promo, or when the sender says so) only to people who opted in. Tickets are always sent.
+    const { normaliseKind, filterRecipients, bulkEmailFooter } = require('../utils/privacy');
+    const kind = template === 'tickets' ? 'update' : (promoEvent ? 'news' : (normaliseKind(req.body?.kind) || 'update'));
+    const allowed = await filterRecipients(recipients, { channel: 'email', kind });
+    recipients.length = 0;
+    recipients.push(...allowed.recipients);
+
    if (dryRun) {
-      return res.json({ eventId, matched: recipients.length, recipients: recipients.slice(0, 20) });
+      return res.json({ eventId, kind, matched: recipients.length, skipped: allowed.skipped, recipients: recipients.slice(0, 20) });
    }

    const { sendMail } = require('../utils/email');
@@ -1613,7 +1668,7 @@ const emailEventAttendees = async (req, res) => {

    const baseUrl = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');

-    // Generates a live Yoco checkout link for the recipient's first registration with an
+    // Generates a live checkout link for the recipient's first registration with an
    // outstanding balance — only called when the template actually uses {{payment.link}}, to
    // avoid an unnecessary Yoco API call per recipient otherwise.
    function makePaymentLinkResolver(regs) {
@@ -1624,8 +1679,8 @@ const emailEventAttendees = async (req, res) => {
          return due - paid > 0.01;
        });
        if (!reg) return '';
-        const { createRegistrationCheckoutInternal } = require('./paymentController');
-        const result = await createRegistrationCheckoutInternal(reg.id, reg.userId, {
+        const { createRegistrationCheckout } = require('../payments/checkouts');
+        const result = await createRegistrationCheckout(reg.id, reg.userId, {
          successUrl: `${baseUrl}/payment/success`,
          cancelUrl: `${baseUrl}/payment/cancel`,
          failureUrl: `${baseUrl}/payment/failure`,
@@ -1730,10 +1785,11 @@ const emailEventAttendees = async (req, res) => {

        // Always perform placeholder replacement on whatever we have
        const finalSubject = await replacePlaceholders(subj || '', ctxBase);
-        const finalHtml = h ? await replacePlaceholders(h, ctxHtml) : undefined;
-        const finalText = (!h ? await replacePlaceholders(t || '', ctxBase) : undefined);
+        const footer = bulkEmailFooter({ kind, recipient: rcpt, eventTitle: event.title });
+        const finalHtml = h ? (await replacePlaceholders(h, ctxHtml)) + footer.html : undefined;
+        const finalText = (!h ? (await replacePlaceholders(t || '', ctxBase)) + footer.text : undefined);

-        await sendMail({ to: rcpt.email, subject: finalSubject, html: finalHtml, text: finalText });
+        await sendMail({ to: rcpt.email, subject: finalSubject, html: finalHtml, text: finalText, headers: footer.headers });
      }));
      results.forEach((r, i) => {
        if (r.status === 'rejected') {
@@ -1824,10 +1880,15 @@ const whatsappEventAttendees = async (req, res) => {
        uniqMap.set(phone, { phone, name: r.user?.name || '', userId: r.user?.id, registrationId: r.id });
      }
    }
-    const recipients = Array.from(uniqMap.values());
+    // POPIA: see emailEventAttendees — news only to people who opted in to WhatsApp news.
+    const { normaliseKind, filterRecipients, whatsAppNewsFooter } = require('../utils/privacy');
+    const promoEventId = req.body?.promoEventId;
+    const kind = template === 'tickets' ? 'update' : (promoEventId ? 'news' : (normaliseKind(req.body?.kind) || 'update'));
+    const allowed = await filterRecipients(Array.from(uniqMap.values()), { channel: 'whatsapp', kind });
+    const recipients = allowed.recipients;

    if (dryRun) {
-      return res.json({ eventId, matched: recipients.length, recipients: recipients.slice(0, 20) });
+      return res.json({ eventId, kind, matched: recipients.length, skipped: allowed.skipped, recipients: recipients.slice(0, 20) });
    }

    const { sendText } = require('../utils/whatsapp');
@@ -1855,7 +1916,7 @@ const whatsappEventAttendees = async (req, res) => {
    const baseUrl = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
    const eventLink = `${baseUrl}/events/${encodeURIComponent(event.id)}`;

-    // Generates a live Yoco checkout link for the recipient's first registration with an
+    // Generates a live checkout link for the recipient's first registration with an
    // outstanding balance — only called when the template actually uses {{payment.link}}.
    function makePaymentLinkResolver(regs) {
      return async () => {
@@ -1865,8 +1926,8 @@ const whatsappEventAttendees = async (req, res) => {
          return due - paid > 0.01;
        });
        if (!reg) return '';
-        const { createRegistrationCheckoutInternal } = require('./paymentController');
-        const result = await createRegistrationCheckoutInternal(reg.id, reg.userId, {
+        const { createRegistrationCheckout } = require('../payments/checkouts');
+        const result = await createRegistrationCheckout(reg.id, reg.userId, {
          successUrl: `${baseUrl}/payment/success`,
          cancelUrl: `${baseUrl}/payment/cancel`,
          failureUrl: `${baseUrl}/payment/failure`,
@@ -1927,7 +1988,7 @@ const whatsappEventAttendees = async (req, res) => {
        }

        const finalMessage = await replacePlaceholders(msg || '', ctx);
-        await sendText(rcpt.phone, finalMessage);
+        await sendText(rcpt.phone, kind === 'news' ? finalMessage + whatsAppNewsFooter(rcpt) : finalMessage);
      }));
      results.forEach((r, i) => {
        if (r.status === 'rejected') {
@@ -1955,7 +2016,7 @@ function describeAttendeeFilter(filter) {
 const scheduleEmailEventAttendees = async (req, res) => {
  try {
    const eventId = req.params.id;
-    const { scheduledAt, subject, html, text, filter, template } = req.body || {};
+    const { scheduledAt, subject, html, text, filter, template, kind } = req.body || {};

    // Validate event
    const event = await prisma.event.findUnique({ where: { id: eventId } });
@@ -1973,7 +2034,7 @@ const scheduleEmailEventAttendees = async (req, res) => {
    }

    // Build payload matching emailEventAttendees body
-    const payload = { subject, html, text, filter: filter || {}, template };
+    const payload = { subject, html, text, filter: filter || {}, template, kind };

    const { addJob } = require('../utils/scheduledEmails');
    const created = addJob({
@@ -1996,7 +2057,7 @@ const scheduleEmailEventAttendees = async (req, res) => {
 const scheduleWhatsappEventAttendees = async (req, res) => {
  try {
    const eventId = req.params.id;
-    const { scheduledAt, message, filter, template } = req.body || {};
+    const { scheduledAt, message, filter, template, kind } = req.body || {};

    const event = await prisma.event.findUnique({ where: { id: eventId } });
    if (!event) { res.status(404); throw new Error('Event not found'); }
@@ -2010,7 +2071,7 @@ const scheduleWhatsappEventAttendees = async (req, res) => {
      throw new Error('message is required unless template is "tickets"');
    }

-    const payload = { message, filter: filter || {}, template };
+    const payload = { message, filter: filter || {}, template, kind };

    const { addJob } = require('../utils/scheduledEmails');
    const created = addJob({
@@ -151,7 +151,7 @@ const getSummary = async (req, res) => {
  try {
    const ids = String(req.query.eventIds || '').split(',').map(s => s.trim()).filter(Boolean).slice(0, 50);
    const forms = await prisma.feedbackForm.findMany({
-      where: { eventId: { in: ids } },
+      where: { eventId: { in: ids }, ...(await require('../utils/campusScope').listWhere(req, 'event')) },
      include: {
        event: { select: { id: true, title: true, startDate: true } },
        fields: { orderBy: { order: 'asc' } },
@@ -16,6 +16,7 @@ const listFormResponses = async (req, res) => {
    const registrationFilter = {};
    if (eventId) registrationFilter.eventId = String(eventId);
    if (userId) registrationFilter.userId = String(userId);
+    Object.assign(registrationFilter, await require('../utils/campusScope').listWhere(req, 'event'));
    if (Object.keys(registrationFilter).length > 0) {
      // Prisma relation filter requires `is` wrapper
      where.registration = { is: registrationFilter };
@@ -43,6 +44,17 @@ const listFormResponses = async (req, res) => {

    const nextCursor = responses.length === take ? responses[responses.length - 1].id : null;

+    // The first page of a list (not one registration's own form, nor the next pages of the
+    // same list) is logged as a bulk view of form answers.
+    if (!registrationId && !cursor && responses.length) {
+      require('../utils/accessLog').logDataAccess(req, {
+        action: 'form_responses',
+        what: `Attendee form answers${responses[0].registration?.event && eventId ? ` — ${responses[0].registration.event.title}` : ''}`,
+        eventId: eventId ? String(eventId) : null,
+        records: responses.length,
+      });
+    }
+
    res.json({ items: responses, nextCursor });
  } catch (error) {
    res.status(400).json({ message: error.message });
@@ -0,0 +1,110 @@
+const prisma = require('../config/db');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { getClientIp } = require('../utils/requestUtils');
+const { logAdminAction } = require('../utils/adminAudit');
+const { licenceStatus } = require('../hub/licence');
+const hub = require('../hub/client');
+const { APP_VERSION } = require('../hub/report');
+
+function compareVersions(a, b) {
+  const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+}
+
+/** An update request still waiting: until this site runs the version that was asked for. */
+function pendingUpdateRequest(version, requestedAt, requestedVersion) {
+  if (!requestedAt || !requestedVersion || compareVersions(version, requestedVersion) >= 0) return null;
+  return { requestedAt, version: requestedVersion };
+}
+
+/** What the admin pages show: licence state, Hub connection, version and update. */
+async function statusPayload({ fresh = false } = {}) {
+  const s = await licenceStatus({ fresh });
+  return {
+    state: s.state,
+    readOnly: s.readOnly,
+    daysLeft: s.daysLeft,
+    endsAt: s.endsAt,
+    graceEndsAt: s.graceEndsAt,
+    licence: s.claims ? {
+      customer: s.claims.customer,
+      plan: s.claims.plan,
+      status: s.claims.status,
+      licenceExpiresAt: s.claims.licenceExpiresAt,
+      graceDays: s.claims.graceDays,
+      issuedAt: s.claims.issuedAt,
+      validUntil: s.claims.validUntil,
+      limits: s.claims.limits || {},
+    } : null,
+    connected: s.connected,
+    keyConfigured: s.keyConfigured,
+    hubUrl: hub.hubUrl(),
+    lastHeartbeatAt: s.lastHeartbeatAt,
+    lastError: s.lastError,
+    version: APP_VERSION,
+    latestVersion: s.latestVersion,
+    updateAvailable: !!(s.latestVersion && compareVersions(APP_VERSION, s.latestVersion) < 0),
+    updateRequest: pendingUpdateRequest(APP_VERSION, s.updateRequestedAt, s.updateRequestedVersion),
+  };
+}
+
+// @desc    Licence and Hub status (for the admin banner and Site settings → Licence)
+// @route   GET /api/hub/status
+// @access  Private/Admin
+const getStatus = async (req, res) => {
+  try {
+    res.json(await statusPayload());
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    Connect this install to the Hub with a licence key (also the /setup licence step)
+// @route   POST /api/hub/connect   body: { licenceKey }
+// @access  Private/Admin
+const connect = async (req, res) => {
+  try {
+    const licenceKey = String(req.body?.licenceKey || '').trim();
+    if (!licenceKey) { res.status(400); throw new Error('Enter your licence key.'); }
+    const me = await prisma.user.findUnique({ where: { id: req.user.id }, select: { name: true, email: true } });
+    const claims = await hub.connect(licenceKey, me);
+    hub.heartbeatSoon();
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'hub_connected', targetType: 'hub', metadata: { customer: claims.customer, hubUrl: hub.hubUrl() }, ip: getClientIp(req) });
+    res.json(await statusPayload({ fresh: true }));
+  } catch (e) {
+    const status = e.statusCode || (res.statusCode === 200 ? 400 : res.statusCode);
+    res.status(status >= 500 && e.code ? 502 : status).json({ message: e.message || safeErrorMessage(e), code: e.code });
+  }
+};
+
+// @desc    Send a heartbeat now (checks the connection and picks up licence changes)
+// @route   POST /api/hub/heartbeat
+// @access  Private/Admin
+const heartbeatNow = async (req, res) => {
+  try {
+    await hub.heartbeat();
+    res.json(await statusPayload({ fresh: true }));
+  } catch (e) {
+    res.status(502).json({ message: e.message || safeErrorMessage(e), code: e.code, status: await statusPayload({ fresh: true }).catch(() => null) });
+  }
+};
+
+// @desc    Ask the Hub for this site to be updated (the provider is told; nothing runs here)
+// @route   POST /api/hub/update-request
+// @access  Private/Admin
+const requestUpdate = async (req, res) => {
+  try {
+    const result = await hub.requestUpdate();
+    if (!result.alreadyRequested) {
+      logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'hub_update_requested', targetType: 'hub', metadata: { from: APP_VERSION, to: result.version }, ip: getClientIp(req) });
+    }
+    res.json(await statusPayload({ fresh: true }));
+  } catch (e) {
+    const status = e.statusCode && e.statusCode < 500 && e.code !== 'INSTALL_NOT_FOUND' ? e.statusCode : 502;
+    res.status(status).json({ message: e.message || safeErrorMessage(e), code: e.code });
+  }
+};
+
+module.exports = { getStatus, connect, heartbeatNow, requestUpdate, statusPayload, compareVersions, pendingUpdateRequest };
@@ -30,6 +30,7 @@ const startImpersonation = async (req, res) => {
      actorId: req.user.id, actorRole: req.user.role, action: 'impersonation_started', targetType: 'User', targetId: target.id,
      metadata: { sessionId: session.id, reason: session.reason, targetName: target.name, expiresAt }, ip: getClientIp(req),
    });
+    require('../utils/accessLog').logDataAccess(req, { action: 'impersonation', what: `Viewed as ${target.name} — ${session.reason}` });

    // Optional: tell the user (Site Settings → Security).
    const { getSettingSync } = require('../utils/settingsCache');
@@ -0,0 +1,97 @@
+const prisma = require('../config/db');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { encrypt } = require('../utils/encryption');
+const { invalidate: invalidateSettingsCache, warmCache } = require('../utils/settingsCache');
+const { logAdminAction } = require('../utils/adminAudit');
+const { getClientIp } = require('../utils/requestUtils');
+const { maskSecret } = require('../utils/yoco');
+const {
+  KEY_MERCHANT_ID, KEY_MERCHANT_KEY, KEY_PASSPHRASE, KEY_MODE,
+  getPayfastConfig, payfastNotifyUrl, notifyUrlProblem,
+} = require('../utils/payfast');
+
+const fail = (res, e) => res.status(e.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: safeErrorMessage(e) });
+
+// @desc  PayFast settings (passphrase masked) and the ITN notify URL
+// @route GET /api/payfast/config
+// @access Admin
+const getConfig = async (req, res) => {
+  try {
+    const c = await getPayfastConfig();
+    const notifyUrl = payfastNotifyUrl();
+    res.json({
+      merchantId: c.merchantId,
+      merchantKey: c.merchantKey,
+      passphraseMasked: c.passphrase ? maskSecret(c.passphrase) : '',
+      hasPassphrase: !!c.passphrase,
+      mode: c.mode,
+      notifyUrl,
+      notifyUrlProblem: notifyUrlProblem(notifyUrl),
+      configured: !!(c.merchantId && c.merchantKey),
+    });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc  Save PayFast settings ('' clears the passphrase; omitted fields stay as they are)
+// @route PUT /api/payfast/config   { merchantId?, merchantKey?, passphrase?, mode? }
+// @access Admin
+const updateConfig = async (req, res) => {
+  try {
+    const { merchantId, merchantKey, passphrase, mode } = req.body || {};
+    const updates = {};
+    if (typeof merchantId === 'string') {
+      const v = merchantId.trim();
+      if (v && !/^\d{5,12}$/.test(v)) { res.status(400); throw new Error('The merchant ID is a number, e.g. 10000100.'); }
+      updates[KEY_MERCHANT_ID] = v;
+    }
+    if (typeof merchantKey === 'string') {
+      const v = merchantKey.trim();
+      if (v && !/^[A-Za-z0-9]{8,32}$/.test(v)) { res.status(400); throw new Error('The merchant key is letters and numbers, as shown on your PayFast dashboard.'); }
+      updates[KEY_MERCHANT_KEY] = v;
+    }
+    if (typeof passphrase === 'string') {
+      // PayFast passphrases are 32 characters at most; spaces at the ends are trimmed by PayFast.
+      if (passphrase.trim().length > 32) { res.status(400); throw new Error('The passphrase can be at most 32 characters.'); }
+      updates[KEY_PASSPHRASE] = passphrase.trim();
+    }
+    if (mode !== undefined) {
+      if (!['sandbox', 'live'].includes(mode)) { res.status(400); throw new Error('Mode is sandbox or live.'); }
+      updates[KEY_MODE] = mode;
+    }
+    if (!Object.keys(updates).length) { res.status(400); throw new Error('Nothing to save'); }
+
+    await prisma.$transaction(Object.entries(updates).map(([key, value]) => {
+      const stored = value && key === KEY_PASSPHRASE ? encrypt(value) : value;
+      return prisma.appSetting.upsert({ where: { key }, update: { value: stored }, create: { key, value: stored } });
+    }));
+    invalidateSettingsCache();
+    await warmCache();
+
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'payfast_config_updated', targetType: 'AppSetting',
+      metadata: { changedKeys: Object.keys(updates), ...(updates[KEY_MODE] ? { mode: updates[KEY_MODE] } : {}) },
+      ip: getClientIp(req),
+    });
+    res.json({ message: 'PayFast settings saved' });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc  Check the saved merchant ID and passphrase with PayFast (a signed API ping)
+// @route POST /api/payfast/test
+// @access Admin
+const testConnection = async (req, res) => {
+  try {
+    const c = await getPayfastConfig();
+    if (!c.merchantId) { res.status(400); throw new Error('Save the merchant ID first.'); }
+    await require('../payments/providers/payfast').testConnection();
+    res.json({ message: `Connected to PayFast (${c.mode === 'live' ? 'live' : 'sandbox'}).` });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+module.exports = { getConfig, updateConfig, testConnection };
@@ -5,8 +5,8 @@ const { computeRegistrationTotalDue, refreshPricingForRegistration } = require('
 const { computeDonationRemaining } = require('../utils/donationUtils');
 const { logAdminAction } = require('../utils/adminAudit');
 const { getClientIp } = require('../utils/requestUtils');
-const axios = require('axios');
-const { yocoAuthHeader } = require('../utils/yoco');
+const payments = require('../payments');
+const { createRegistrationCheckout } = require('../payments/checkouts');
 const { emailTickets } = require('./ticketController');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { assertEventOpen, assertRegistrationEventOpen } = require('../utils/cashupUtils');
@@ -351,9 +351,13 @@ const getPayments = async (req, res) => {
      event: true
    };

+    // Campus-scoped supervisors: payments for events they can see (through the payment's event or
+    // its registration's), so unlinked donations aren't listed for them.
+    const scopeW = require('../utils/campusScope').eventWhere(await require('../utils/campusScope').scopeFor(req));
+    const where = Object.keys(scopeW).length ? { OR: [{ event: scopeW }, { registration: { event: scopeW } }] } : {};
    const [payments, total] = await prisma.$transaction([
-      prisma.payment.findMany({ include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
-      prisma.payment.count()
+      prisma.payment.findMany({ where, include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
+      prisma.payment.count({ where })
    ]);

    res.json({ data: payments, total, page, limit, pages: Math.ceil(total / limit) });
@@ -914,122 +918,23 @@ const unassignDonationFromRegistration = async (req, res) => {
  }
 };

-/**
- * Yoco line items for a registration: one per item at each price actually charged
- * (tranche-aware, so a line bought partly at early-bird shows both prices), plus the
- * bundle saving and coupon discount as negative lines. Previous/partial payment lines are
- * added by callers.
- */
-function checkoutLineItems(registration) {
-  const { buildLineItems, discountLines } = require('../utils/pdfDocs');
-  const items = buildLineItems(registration.registrationOptions).map(row => ({
-    displayName: row.label + (row.isEarlyBird ? ' (early bird)' : ''),
-    quantity: row.quantity,
-    pricingDetails: { price: Math.round(row.unitPrice * 100) },
-  }));
-  for (const line of discountLines(registration)) {
-    items.push({ displayName: line.label, quantity: 1, pricingDetails: { price: -Math.round(line.amount * 100) } });
-  }
-  return items;
-}
-
-// Internal helper: create a Yoco checkout for a registration and return { checkoutId, redirectUrl, amount }
-// Does NOT check user authorization — callers are responsible for ensuring the user owns the registration.
-// donationAmount (optional) is added on top as its own line; the webhook splits it off into a
-// separate donation payment using the amount carried in the checkout metadata.
-async function createRegistrationCheckoutInternal(registrationId, userId, { successUrl, cancelUrl, failureUrl, donationAmount = 0 } = {}) {
-  const registration = await prisma.registration.findUnique({
-    where: { id: registrationId },
-    include: {
-      registrationOptions: {
-        include: {
-          eventOption: { include: { earlyBirdTiers: true } },
-          variant: true,
-          tranches: true,
-        }
-      },
-      payments: true,
-      couponRedemptions: { where: { releasedAt: null }, include: { coupon: { select: { code: true } } } }, bundleApplications: { include: { bundle: { select: { name: true } } } },
-      user: { select: { id: true, name: true, email: true } },
-      event: true
-    }
-  });
-
-  if (!registration) throw new Error('Registration not found');
-
-  const totalDue = computeRegistrationTotalDue(registration, new Date());
-  const totalPaid = registration.payments.reduce((sum, p) => sum + p.amount, 0);
-  const remainingAmount = totalDue - totalPaid;
-
-  if (remainingAmount <= 0) throw new Error('This registration is already paid in full');
-
-  const donationInCents = Math.round((Number(donationAmount) || 0) * 100);
-  const amountInCents = Math.round(remainingAmount * 100) + donationInCents;
-  const idempotencyKey = `reg_${registrationId}_${amountInCents}_${Date.now()}`;
-  const lineItems = checkoutLineItems(registration);
-
-  // Show prior payments as a deduction line
-  if (totalPaid > 0) {
-    lineItems.push({
-      displayName: 'Previous Payments',
-      quantity: 1,
-      pricingDetails: { price: -Math.round(totalPaid * 100) }
-    });
-  }
-  // Paying full remaining — no "Partial Payment" line needed
-  if (donationInCents > 0) {
-    lineItems.push({ displayName: 'Donation', quantity: 1, pricingDetails: { price: donationInCents } });
-  }
-
-  const checkoutData = {
-    amount: amountInCents,
-    currency: 'ZAR',
-    metadata: {
-      registrationId, userId, eventId: registration.eventId, eventTitle: registration.event.title, type: 'registration_payment',
-      ...(donationInCents > 0 ? { donationAmount: (donationInCents / 100).toFixed(2) } : {})
-    },
-    successUrl,
-    cancelUrl,
-    failureUrl,
-    lineItems
-  };
-
-  const response = await axios.post(
-    'https://payments.yoco.com/api/checkouts',
-    checkoutData,
-    { headers: { 'Content-Type': 'application/json', 'Authorization': await yocoAuthHeader(), 'Idempotency-Key': idempotencyKey } }
-  );
-
-  await prisma.registration.update({
-    where: { id: registrationId },
-    data: { checkoutId: response.data.id, updatedAt: new Date() }
-  });
-
-  return {
-    checkoutId: response.data.id,
-    redirectUrl: response.data.redirectUrl,
-    amount: amountInCents / 100,
-    registration: { id: registration.id, eventId: registration.eventId, eventTitle: registration.event.title }
-  };
-}
-
-// @desc    Create a Yoco checkout for a registration
-// @route   POST /api/payments/yoco-checkout
+// @desc    Start an online checkout: a registration's balance (all of it, or part of it, plus
+//          an optional donation) or a donation to an event. `provider` picks the payment
+//          provider; by default the first one enabled in Site settings → Payments.
+// @route   POST /api/payments/checkout  (also /api/payments/yoco-checkout)
 // @access  Private
-const createYocoCheckout = async (req, res) => {
+const createCheckout = async (req, res) => {
  try {
-    const { registrationId, eventId, amount, donationAmount, successUrl, cancelUrl, failureUrl } = req.body;
+    const { registrationId, eventId, amount, donationAmount, successUrl, cancelUrl, failureUrl, provider } = req.body;
    const userId = req.user.id;

-    // Validate required parameters for either registration payment or donation
    if (!registrationId && !eventId) {
      res.status(400);
      throw new Error('Either registrationId or eventId is required');
    }

-    // Branch 1: Registration payment — delegate to internal helper
+    // A registration's balance
    if (registrationId) {
-      // Authorisation check (the internal helper skips this)
      const reg = await prisma.registration.findUnique({ where: { id: registrationId }, select: { userId: true, eventId: true, event: { select: { endDate: true } } } });
      if (!reg) { res.status(404); throw new Error('Registration not found'); }
      if (reg.userId !== userId && req.user.role !== 'admin' && req.user.role !== 'supervisor') {
@@ -1042,10 +947,9 @@ const createYocoCheckout = async (req, res) => {
      await assertEventOpen(reg.eventId, res);

      // Refresh early-bird pricing — updates priceSnapshot if any tier has expired or sold out.
-      // Must run before totalDue is computed so the correct price is used for the checkout amount.
+      // Must run before the balance is worked out so the checkout charges the right price.
      const { changed: priceChanged } = await refreshPricingForRegistration(registrationId);
      if (priceChanged) {
-        // Re-fetch with fresh priceSnapshot values
        const freshReg = await prisma.registration.findUnique({
          where: { id: registrationId },
          include: {
@@ -1062,47 +966,10 @@ const createYocoCheckout = async (req, res) => {
        });
      }

-      // If a specific partial amount was passed, fall through to the old inline path
+      // Part of the balance (supervisor payments page)
      if (amount && !isNaN(parseFloat(amount))) {
-        // Re-use old inline logic for partial payments
-        const registration = await prisma.registration.findUnique({
-          where: { id: registrationId },
-          include: {
-            registrationOptions: {
-              include: {
-                eventOption: { include: { earlyBirdTiers: true } },
-                variant: true,
-                tranches: true,
-              }
-            },
-            payments: true,
-            couponRedemptions: { where: { releasedAt: null }, include: { coupon: { select: { code: true } } } }, bundleApplications: { include: { bundle: { select: { name: true } } } },
-            user: { select: { id: true, name: true, email: true } },
-            event: true
-          }
-        });
-        const totalDue = computeRegistrationTotalDue(registration, new Date());
-        const totalPaid = registration.payments.reduce((sum, p) => sum + p.amount, 0);
-        const remainingAmount = totalDue - totalPaid;
-        if (remainingAmount <= 0) { res.status(400); throw new Error('This registration is already paid in full'); }
-        const requested = parseFloat(amount);
-        if (requested <= 0) { res.status(400); throw new Error('Amount must be greater than 0'); }
-        if (remainingAmount >= 15 && requested < 15) { res.status(400); throw new Error('Minimum payment is R15'); }
-        const charge = Math.min(requested, remainingAmount);
-        const amountInCents = Math.round(charge * 100);
-        const lineItems = checkoutLineItems(registration);
-        // Previous payments deduction
-        if (totalPaid > 0) {
-          lineItems.push({ displayName: 'Previous Payments', quantity: 1, pricingDetails: { price: -Math.round(totalPaid * 100) } });
-        }
-        // Partial payment deduction — amount being deferred to a future payment
-        if (charge < remainingAmount) {
-          lineItems.push({ displayName: 'Partial Payment', quantity: 1, pricingDetails: { price: -Math.round((remainingAmount - charge) * 100) } });
-        }
-        const checkoutData = { amount: amountInCents, currency: 'ZAR', metadata: { registrationId, userId, eventId: registration.eventId, eventTitle: registration.event.title, type: 'registration_payment' }, successUrl, cancelUrl, failureUrl, lineItems };
-        const response = await axios.post('https://payments.yoco.com/api/checkouts', checkoutData, { headers: { 'Content-Type': 'application/json', 'Authorization': await yocoAuthHeader(), 'Idempotency-Key': `reg_${registrationId}_${amountInCents}_${Date.now()}` } });
-        await prisma.registration.update({ where: { id: registrationId }, data: { checkoutId: response.data.id, updatedAt: new Date() } });
-        return res.status(200).json({ checkoutId: response.data.id, redirectUrl: response.data.redirectUrl, amount: charge, registration: { id: registration.id, eventId: registration.eventId, eventTitle: registration.event.title } });
+        const result = await createRegistrationCheckout(registrationId, userId, { successUrl, cancelUrl, failureUrl, amount: parseFloat(amount), provider });
+        return res.status(200).json(result);
      }

      // Optional donation added at registration ("Donation amount" on the register form)
@@ -1110,85 +977,64 @@ const createYocoCheckout = async (req, res) => {
      if (donationAmount !== undefined && donationAmount !== null && donationAmount !== '') {
        donation = Math.round(parseFloat(donationAmount) * 100) / 100;
        if (!(donation >= 0) || donation > 100000) { res.status(400); throw new Error('Invalid donation amount'); }
-        if (donation > 0 && donation < 15) { res.status(400); throw new Error('Minimum donation is R15'); }
+        if (donation > 0 && donation < payments.MIN_ONLINE_AMOUNT) { res.status(400); throw new Error(`Minimum donation is R${payments.MIN_ONLINE_AMOUNT}`); }
      }

-      const result = await createRegistrationCheckoutInternal(registrationId, userId, { successUrl, cancelUrl, failureUrl, donationAmount: donation });
+      const result = await createRegistrationCheckout(registrationId, userId, { successUrl, cancelUrl, failureUrl, donationAmount: donation, provider });
      return res.status(200).json(result);
    }

-    // Branch 2: Donation to an event
-    if (eventId) {
-      // Validate event
-      const event = await prisma.event.findUnique({ where: { id: eventId } });
-      if (!event) {
-        res.status(404);
-        throw new Error('Event not found');
-      }
-      if (!event.isActive) {
-        res.status(400);
-        throw new Error('Cannot make donation to inactive event');
-      }
-      if (event.cashupStatus === 'closed') {
-        res.status(400);
-        throw new Error('This event is closed and no longer accepting donations.');
-      }
-
-      const amt = parseFloat(amount);
-      if (!(amt > 0)) {
-        res.status(400);
-        throw new Error('Valid amount is required for donation');
-      }
-      if (amt < 15) {
-        res.status(400);
-        throw new Error('Minimum donation is R15');
-      }
-
-      const amountInCents = Math.round(amt * 100);
-      const idempotencyKey = `don_${eventId}_${amountInCents}_${Date.now()}`;
-      const metadata = {
-        userId,
-        eventId,
-        eventTitle: event.title,
-        type: 'donation',
-        isDonation: true
-      };
-
-      const checkoutData = {
-        amount: amountInCents,
-        currency: 'ZAR',
-        metadata,
-        successUrl,
-        cancelUrl,
-        failureUrl,
-        lineItems: [
-          { displayName: `Donation to ${event.title}`, quantity: 1, pricingDetails: { price: amountInCents } }
-        ]
-      };
-
-      const response = await axios.post(
-        'https://payments.yoco.com/api/checkouts',
-        checkoutData,
-        { headers: { 'Content-Type': 'application/json', 'Authorization': await yocoAuthHeader(), 'Idempotency-Key': idempotencyKey } }
-      );
-
-      return res.status(200).json({
-        checkoutId: response.data.id,
-        redirectUrl: response.data.redirectUrl,
-        amount: amt,
-        event: { id: event.id, title: event.title }
-      });
+    // A donation to an event
+    const event = await prisma.event.findUnique({ where: { id: eventId } });
+    if (!event) {
+      res.status(404);
+      throw new Error('Event not found');
    }
-  } catch (error) {
-    console.error('Yoco checkout error:', error.response?.data || error.message);
-    res.status(error.statusCode || error.response?.status || 400).json({ 
-      message: error.response?.data?.message || error.message 
+    if (!event.isActive) {
+      res.status(400);
+      throw new Error('Cannot make donation to inactive event');
+    }
+    if (event.cashupStatus === 'closed') {
+      res.status(400);
+      throw new Error('This event is closed and no longer accepting donations.');
+    }
+
+    const amt = parseFloat(amount);
+    if (!(amt > 0)) {
+      res.status(400);
+      throw new Error('Valid amount is required for donation');
+    }
+    if (amt < payments.MIN_ONLINE_AMOUNT) {
+      res.status(400);
+      throw new Error(`Minimum donation is R${payments.MIN_ONLINE_AMOUNT}`);
+    }
+
+    const amountInCents = Math.round(amt * 100);
+    const checkout = await payments.createCheckout(provider, {
+      amountCents: amountInCents,
+      metadata: { userId, eventId, eventTitle: event.title, type: 'donation', isDonation: true },
+      lineItems: [{ name: `Donation to ${event.title}`, quantity: 1, unitCents: amountInCents }],
+      description: `Donation to ${event.title}`,
+      payer: { name: req.user.name || '', email: req.user.email || '' },
+      successUrl, cancelUrl, failureUrl,
+      idempotencyKey: `don_${eventId}_${amountInCents}_${Date.now()}`,
    });
+
+    return res.status(200).json({
+      checkoutId: checkout.checkoutId,
+      redirectUrl: checkout.redirectUrl,
+      provider: checkout.provider,
+      amount: amt,
+      event: { id: event.id, title: event.title }
+    });
+  } catch (error) {
+    console.error('Checkout error:', error.message);
+    res.status(error.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: error.message });
  }
 };

-// @desc    Deliver a previously-generated Yoco payment link to the registrant via email or WhatsApp
-// @route   POST /api/payments/yoco-checkout/send
+// @desc    Deliver a previously-generated payment link to the registrant via email or WhatsApp
+// @route   POST /api/payments/checkout/send  (also /api/payments/yoco-checkout/send)
 // @access  Private/Supervisor
 const sendPaymentLink = async (req, res) => {
  try {
@@ -1477,8 +1323,7 @@ module.exports = {
  getPaymentsByEvent,
  assignDonationToRegistration,
  unassignDonationFromRegistration,
-  createYocoCheckout,
-  createRegistrationCheckoutInternal,
+  createCheckout,
  sendPaymentLink,
  createRefund,
  getPaymentStats,
@@ -0,0 +1,177 @@
+const prisma = require('../config/db');
+const payments = require('../payments');
+const { checkoutPaid, checkCheckouts, openCheckouts } = require('../payments/status');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { invalidate: invalidateSettingsCache, warmCache } = require('../utils/settingsCache');
+const { logAdminAction } = require('../utils/adminAudit');
+const { getClientIp } = require('../utils/requestUtils');
+
+const fail = (res, e) => res.status(e.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: safeErrorMessage(e) });
+
+// @desc    Payment providers people can pay with now (enabled and set up), in display order
+// @route   GET /api/payments/providers
+// @access  Public
+const listPaymentProviders = async (req, res) => {
+  try {
+    const providers = await payments.availableProviders();
+    res.json({ providers: providers.map(p => ({ id: p.id, label: p.label })), minimumAmount: payments.MIN_ONLINE_AMOUNT });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc    Every provider with its Enabled flag, order and whether it's set up
+// @route   GET /api/payments/providers/settings
+// @access  Admin
+const getPaymentProviderSettings = async (req, res) => {
+  try {
+    res.json({ providers: await payments.providerSettings(), minimumAmount: payments.MIN_ONLINE_AMOUNT });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc    Turn providers on/off and set their order
+// @route   PUT /api/payments/providers/settings   { providers: [{ id, enabled }] } (in display order)
+// @access  Admin
+const updatePaymentProviderSettings = async (req, res) => {
+  try {
+    const list = req.body?.providers;
+    if (!Array.isArray(list) || list.length === 0) { res.status(400); throw new Error('providers must be a list'); }
+    const unknown = list.find(p => !payments.getProvider(p?.id));
+    if (unknown) { res.status(400); throw new Error(`Unknown payment provider: ${unknown?.id}`); }
+
+    const before = await payments.providerSettings();
+    const value = payments.serializeProviderSettings(list);
+    await prisma.appSetting.upsert({ where: { key: payments.SETTINGS_KEY }, update: { value }, create: { key: payments.SETTINGS_KEY, value } });
+    invalidateSettingsCache();
+    await warmCache();
+    const after = await payments.providerSettings();
+
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'payment_providers_updated', targetType: 'AppSetting',
+      metadata: { before: before.map(p => ({ id: p.id, enabled: p.enabled })), after: after.map(p => ({ id: p.id, enabled: p.enabled })) },
+      ip: getClientIp(req),
+    });
+    res.json({ message: 'Payment providers saved', providers: after });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+/** A checkout and whether it has been paid (a payment came back for it, or its registration is paid). */
+async function loadCheckout(id) {
+  const checkout = await prisma.providerCheckout.findUnique({ where: { id: String(id || '') } });
+  if (!checkout) return null;
+  return { checkout, paid: await checkoutPaid(checkout) };
+}
+
+const providerList = (list) => list.map(p => ({ id: p.id, label: p.label }));
+
+// @desc    A checkout for the payer's page (/pay/:id): amount, what it's for, the providers
+//          they can pay with, and — once a form provider (PayFast) is chosen — its signed form
+// @route   GET /api/payments/pay/:id
+// @access  Public (the checkout id is the credential)
+const getPayPage = async (req, res) => {
+  try {
+    const found = await loadCheckout(req.params.id);
+    if (!found) { res.status(404); throw new Error('This payment link is not valid.'); }
+    const { checkout, paid } = found;
+    const request = checkout.request || {};
+    const out = {
+      id: checkout.id,
+      status: paid ? 'paid' : 'open',
+      amount: checkout.amountCents / 100,
+      description: request.description || '',
+      provider: checkout.provider,
+      providers: providerList(await payments.availableProviders()),
+      cancelUrl: request.cancelUrl || null,
+      redirectUrl: null,
+      form: null,
+    };
+    if (!paid && checkout.provider) {
+      const provider = payments.getProvider(checkout.provider);
+      if (checkout.redirectUrl) out.redirectUrl = checkout.redirectUrl;
+      else if (provider) out.form = (await payments.startCheckout(checkout, provider)).form || null;
+    }
+    res.json(out);
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc    Start a checkout with the provider the payer picked
+// @route   POST /api/payments/pay/:id   { provider }
+// @access  Public (the checkout id is the credential)
+const choosePayProvider = async (req, res) => {
+  try {
+    const found = await loadCheckout(req.params.id);
+    if (!found) { res.status(404); throw new Error('This payment link is not valid.'); }
+    if (found.paid) { res.status(409); throw new Error('This has already been paid.'); }
+    const provider = payments.getProvider(req.body?.provider);
+    if (!provider) { res.status(400); throw new Error('Choose how you\'d like to pay.'); }
+    const usable = (await payments.availableProviders()).some(p => p.id === provider.id);
+    if (!usable) { res.status(400); throw new Error(`Paying with ${provider.label} isn't available right now.`); }
+    const started = await payments.startCheckout(found.checkout, provider);
+    res.json({ provider: provider.id, redirectUrl: started.form ? null : started.redirectUrl, form: started.form || null });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+const OPEN_DAYS = 14;
+
+/** An open checkout for the Payments page: who/what it's for, and whether its provider can be asked. */
+async function describeCheckout(c, users) {
+  const meta = c.metadata || {};
+  const provider = payments.getProvider(c.provider);
+  return {
+    id: c.id,
+    provider: c.provider,
+    providerLabel: provider?.label || c.provider,
+    canCheck: !!provider?.findPayments,
+    amount: c.amountCents / 100,
+    description: c.request?.description || meta.eventTitle || '',
+    type: meta.type || null,
+    registrationId: meta.registrationId || null,
+    payer: users.get(meta.userId) || c.request?.payer?.name || null,
+    createdAt: c.createdAt,
+  };
+}
+
+// @desc    Online checkouts started in the last 14 days that have no payment yet
+// @route   GET /api/payments/checkouts/open
+// @access  Supervisor
+const listOpenCheckouts = async (req, res) => {
+  try {
+    const open = await openCheckouts({ since: new Date(Date.now() - OPEN_DAYS * 24 * 60 * 60 * 1000) });
+    const userIds = [...new Set(open.map(c => c.metadata?.userId).filter(Boolean))];
+    const users = new Map((await prisma.user.findMany({ where: { id: { in: userIds } }, select: { id: true, name: true } })).map(u => [u.id, u.name]));
+    res.json({ checkouts: await Promise.all(open.map(c => describeCheckout(c, users))), days: OPEN_DAYS });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+// @desc    Ask the providers whether open checkouts were paid, and record what they find
+// @route   POST /api/payments/checkouts/check   { ids?: string[] } (default: every open one)
+// @access  Supervisor
+const checkCheckoutStatus = async (req, res) => {
+  try {
+    const ids = Array.isArray(req.body?.ids) ? req.body.ids.map(String).slice(0, 200) : null;
+    const list = ids
+      ? await prisma.providerCheckout.findMany({ where: { id: { in: ids } } })
+      : await openCheckouts({ since: new Date(Date.now() - OPEN_DAYS * 24 * 60 * 60 * 1000) });
+    const results = await checkCheckouts(list);
+    const out = Object.fromEntries(results);
+    const recorded = [...results.values()].filter(r => r.status === 'recorded').length;
+    res.json({ results: out, recorded, message: recorded ? `Found and recorded ${recorded} payment${recorded === 1 ? '' : 's'}.` : 'No new payments found.' });
+  } catch (e) {
+    fail(res, e);
+  }
+};
+
+module.exports = {
+  listPaymentProviders, getPaymentProviderSettings, updatePaymentProviderSettings, getPayPage, choosePayProvider,
+  listOpenCheckouts, checkCheckoutStatus,
+};
@@ -0,0 +1,447 @@
+const prisma = require('../config/db');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { getClientIp } = require('../utils/requestUtils');
+const { logAdminAction } = require('../utils/adminAudit');
+const { ACCESS_ACTIONS } = require('../utils/accessLog');
+const notice = require('../utils/privacyNotice');
+
+const fail = (res, error) => res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+
+const PAGE_SIZE = 50;
+const page = req => Math.max(parseInt(req.query.page, 10) || 1, 1);
+
+// ─── Privacy notice ───────────────────────────────────────────────────────────
+
+// @desc    The privacy notice as published (current, or ?version=N), placeholders filled in
+// @route   GET /api/privacy/notice
+// @access  Public
+const getNotice = async (req, res) => {
+  try {
+    const version = req.query.version != null ? parseInt(req.query.version, 10) : null;
+    if (req.query.version != null && !(version >= 0)) { res.status(400); throw new Error('Invalid version'); }
+    const result = await notice.publicNotice(version);
+    if (!result) { res.status(404); throw new Error('That version of the privacy notice does not exist.'); }
+    res.json(result);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Accept the current privacy notice
+// @route   POST /api/privacy/me/notice/accept
+// @access  Private
+const acceptMyNotice = async (req, res) => {
+  try {
+    if (req.impersonation) { res.status(403); throw new Error('Not available while viewing as another user.'); }
+    const version = await notice.acceptNotice(req.user.id, { source: 'prompt', ip: getClientIp(req) });
+    res.json({ version });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+async function versionList() {
+  const [versions, counts] = await Promise.all([
+    prisma.privacyNotice.findMany({
+      orderBy: { version: 'desc' },
+      select: { version: true, publishedAt: true, changeSummary: true, requiresAcceptance: true, publishedBy: { select: { name: true } } },
+    }),
+    prisma.noticeAcceptance.groupBy({ by: ['version'], _count: { _all: true } }),
+  ]);
+  const byVersion = new Map(counts.map(c => [c.version, c._count._all]));
+  return versions.map(v => ({ ...v, publishedBy: v.publishedBy?.name || null, acceptances: byVersion.get(v.version) || 0 }));
+}
+
+// @desc    The editor: the draft (or current text), how it reads, and the published versions
+// @route   GET /api/privacy/notice/draft
+// @access  Private/Admin
+const getNoticeDraft = async (req, res) => {
+  try {
+    const draft = await notice.getDraft();
+    const ctx = await notice.noticeContext();
+    res.json({
+      ...draft,
+      rendered: notice.renderSections(draft.sections, ctx),
+      placeholders: notice.PLACEHOLDERS,
+      versions: await versionList(),
+      builtIn: notice.defaultSections(),
+    });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Save the draft (body.sections)
+// @route   PUT /api/privacy/notice/draft
+// @access  Private/Admin
+const saveNoticeDraft = async (req, res) => {
+  try {
+    const sections = await notice.saveDraft(req.body?.sections);
+    res.json({ sections, rendered: notice.renderSections(sections, await notice.noticeContext()), isDraft: true, savedAt: new Date() });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Throw the draft away (back to the current published text)
+// @route   DELETE /api/privacy/notice/draft
+// @access  Private/Admin
+const discardNoticeDraft = async (req, res) => {
+  try {
+    await notice.discardDraft();
+    res.json({ message: 'Draft discarded.' });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Publish body.sections as the next version (body.changeSummary, body.requiresAcceptance)
+// @route   POST /api/privacy/notice/publish
+// @access  Private/Admin
+const publishNotice = async (req, res) => {
+  try {
+    const { sections, changeSummary, requiresAcceptance } = req.body || {};
+    if (requiresAcceptance && !String(changeSummary || '').trim()) {
+      res.status(400);
+      throw new Error('Say what changed — people see it when they are asked to accept the new version.');
+    }
+    const published = await notice.publish({ sections, changeSummary, requiresAcceptance, publishedById: req.user.id });
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'privacy_notice_published', targetType: 'privacy_notice', targetId: published.id,
+      metadata: { version: published.version, requiresAcceptance: published.requiresAcceptance, changeSummary: published.changeSummary }, ip: getClientIp(req),
+    });
+    res.status(201).json({ version: published.version, publishedAt: published.publishedAt, requiresAcceptance: published.requiresAcceptance });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Operators ────────────────────────────────────────────────────────────────
+
+const OPERATOR_FIELDS = ['name', 'purpose', 'dataShared', 'location', 'website'];
+
+function operatorData(body, { partial = false } = {}) {
+  const data = {};
+  for (const f of OPERATOR_FIELDS) {
+    if (body?.[f] === undefined) continue;
+    const v = body[f] == null ? '' : String(body[f]).trim().slice(0, f === 'name' ? 200 : 1000);
+    data[f] = v || (f === 'location' || f === 'website' ? null : '');
+  }
+  if (typeof body?.active === 'boolean') data.active = body.active;
+  if (Number.isInteger(body?.order)) data.order = body.order;
+  if ((!partial || 'name' in data) && !data.name) throw new Error('Give the operator a name.');
+  if ((!partial || 'purpose' in data) && !data.purpose) throw new Error('Say what the operator does for you.');
+  if (data.website && !/^https?:\/\//i.test(data.website)) data.website = `https://${data.website}`;
+  return data;
+}
+
+// @desc    The operator register
+// @route   GET /api/privacy/operators
+// @access  Private/Admin
+const listOperators = async (req, res) => {
+  try {
+    res.json(await prisma.operator.findMany({ orderBy: [{ order: 'asc' }, { name: 'asc' }] }));
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @route   POST /api/privacy/operators
+const createOperator = async (req, res) => {
+  try {
+    const data = operatorData(req.body);
+    if (data.order === undefined) data.order = (await prisma.operator.count()) + 1;
+    const op = await prisma.operator.create({ data });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'operator_created', targetType: 'operator', targetId: op.id, metadata: { name: op.name }, ip: getClientIp(req) });
+    res.status(201).json(op);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @route   PUT /api/privacy/operators/:id
+const updateOperator = async (req, res) => {
+  try {
+    const existing = await prisma.operator.findUnique({ where: { id: req.params.id } });
+    if (!existing) { res.status(404); throw new Error('Operator not found'); }
+    const op = await prisma.operator.update({ where: { id: existing.id }, data: operatorData(req.body, { partial: true }) });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'operator_updated', targetType: 'operator', targetId: op.id, metadata: { name: op.name, active: op.active }, ip: getClientIp(req) });
+    res.json(op);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @route   DELETE /api/privacy/operators/:id
+const deleteOperator = async (req, res) => {
+  try {
+    const existing = await prisma.operator.findUnique({ where: { id: req.params.id } });
+    if (!existing) { res.status(404); throw new Error('Operator not found'); }
+    await prisma.operator.delete({ where: { id: existing.id } });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'operator_deleted', targetType: 'operator', targetId: existing.id, metadata: { name: existing.name }, ip: getClientIp(req) });
+    res.json({ message: 'Operator removed.' });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Consent log ──────────────────────────────────────────────────────────────
+
+// Filter on the person's name or email.
+function personWhere(q) {
+  return q ? { OR: [{ name: { contains: q, mode: 'insensitive' } }, { email: { contains: q, mode: 'insensitive' } }] } : undefined;
+}
+
+// @desc    Proof of consent: ?type=news (news opt-in changes), notice (privacy notice
+//          acceptances) or parental (parental consent answers); ?q= name/email; ?page=
+// @route   GET /api/privacy/consent-log
+// @access  Private/Admin
+const consentLog = async (req, res) => {
+  try {
+    const type = String(req.query.type || 'news');
+    const q = String(req.query.q || '').trim();
+    const skip = (page(req) - 1) * PAGE_SIZE;
+    const user = { select: { name: true, email: true } };
+
+    if (type === 'news') {
+      const where = q ? { OR: [{ user: personWhere(q) }, { address: { contains: q, mode: 'insensitive' } }] } : {};
+      const [rows, total] = await Promise.all([
+        prisma.communicationConsent.findMany({ where, orderBy: { createdAt: 'desc' }, skip, take: PAGE_SIZE, include: { user } }),
+        prisma.communicationConsent.count({ where }),
+      ]);
+      return res.json({
+        total, pageSize: PAGE_SIZE,
+        rows: rows.map(r => ({ id: r.id, at: r.createdAt, name: r.user?.name || null, email: r.user?.email || r.address, channel: r.channel, granted: r.granted, source: r.source, ip: r.ip })),
+      });
+    }
+    if (type === 'notice') {
+      const where = q ? { user: personWhere(q) } : {};
+      const [rows, total] = await Promise.all([
+        prisma.noticeAcceptance.findMany({ where, orderBy: { createdAt: 'desc' }, skip, take: PAGE_SIZE, include: { user } }),
+        prisma.noticeAcceptance.count({ where }),
+      ]);
+      return res.json({
+        total, pageSize: PAGE_SIZE,
+        rows: rows.map(r => ({ id: r.id, at: r.createdAt, name: r.user?.name || null, email: r.user?.email || null, version: r.version, source: r.source, ip: r.ip })),
+      });
+    }
+    if (type === 'parental') {
+      const where = {
+        status: { in: ['given', 'declined'] },
+        ...(q ? { OR: [{ attendee: { name: { contains: q, mode: 'insensitive' } } }, { parentName: { contains: q, mode: 'insensitive' } }, { parentEmail: { contains: q, mode: 'insensitive' } }, { signedName: { contains: q, mode: 'insensitive' } }] } : {}),
+      };
+      const [rows, total] = await Promise.all([
+        prisma.consentRequest.findMany({
+          where, orderBy: { respondedAt: 'desc' }, skip, take: PAGE_SIZE,
+          select: { id: true, status: true, signedName: true, parentName: true, textVersion: true, photoConsent: true, respondedAt: true, ip: true, medicalPurgedAt: true, attendee: { select: { name: true } }, event: { select: { title: true } } },
+        }),
+        prisma.consentRequest.count({ where }),
+      ]);
+      return res.json({
+        total, pageSize: PAGE_SIZE,
+        rows: rows.map(r => ({
+          id: r.id, at: r.respondedAt, child: r.attendee?.name, event: r.event?.title, status: r.status, signedName: r.signedName,
+          parentName: r.parentName, textVersion: r.textVersion, photoConsent: r.photoConsent, ip: r.ip, medicalDeleted: !!r.medicalPurgedAt,
+        })),
+      });
+    }
+    res.status(400);
+    throw new Error('type must be news, notice or parental');
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Access log ───────────────────────────────────────────────────────────────
+
+// @desc    Who exported or viewed personal information in bulk (?action=, ?actorId=, ?from=, ?to=, ?page=)
+// @route   GET /api/privacy/access-log
+// @access  Private/Admin
+const accessLog = async (req, res) => {
+  try {
+    const where = {};
+    if (req.query.action) where.action = String(req.query.action);
+    if (req.query.sensitive === 'true') where.sensitive = true;
+    if (req.query.actorId) where.actorId = String(req.query.actorId);
+    if (req.query.from || req.query.to) {
+      where.createdAt = {};
+      if (req.query.from) where.createdAt.gte = new Date(String(req.query.from));
+      if (req.query.to) where.createdAt.lte = new Date(String(req.query.to));
+    }
+    const [rows, total, actors] = await Promise.all([
+      prisma.dataAccessLog.findMany({ where, orderBy: { createdAt: 'desc' }, skip: (page(req) - 1) * PAGE_SIZE, take: PAGE_SIZE, include: { actor: { select: { name: true } } } }),
+      prisma.dataAccessLog.count({ where }),
+      prisma.dataAccessLog.findMany({ where: { actorId: { not: null } }, distinct: ['actorId'], select: { actorId: true, actor: { select: { name: true } } } }),
+    ]);
+    res.json({
+      total, pageSize: PAGE_SIZE,
+      actions: ACCESS_ACTIONS,
+      actors: actors.map(a => ({ id: a.actorId, name: a.actor?.name || 'Unknown' })),
+      rows: rows.map(r => ({ id: r.id, at: r.createdAt, actor: r.actor?.name || 'Deleted user', actorRole: r.actorRole, action: r.action, what: r.what, records: r.records, eventId: r.eventId, ip: r.ip, sensitive: r.sensitive })),
+    });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Readiness ────────────────────────────────────────────────────────────────
+
+// @desc    POPIA readiness checklist with a score
+// @route   GET /api/privacy/readiness
+// @access  Private/Admin
+const getReadiness = async (req, res) => {
+  try {
+    res.json(await require('../utils/readiness').readiness());
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Retention ────────────────────────────────────────────────────────────────
+
+async function retentionState() {
+  const retention = require('../utils/retention');
+  const { getSetting } = require('../utils/settingsCache');
+  const current = await retention.getPolicies();
+  const [preview, lastRun, medicalDays, backupCount] = await Promise.all([
+    retention.preview(current.policies),
+    retention.lastRun(),
+    getSetting('consent_medical_retention_days', ''),
+    getSetting('backup_retain_count', ''),
+  ]);
+  return {
+    ...current,
+    definitions: Object.fromEntries(Object.entries(retention.POLICIES).map(([k, d]) => [k, { label: d.label, description: d.description, minMonths: d.minMonths, defaults: d.defaults }])),
+    preview,
+    lastRun,
+    related: { medicalDays: parseInt(medicalDays, 10) || 30, backupCount: parseInt(backupCount, 10) || 14, analyticsDays: 90 },
+  };
+}
+
+// @desc    Retention policies, what they'd affect now, and the last run
+// @route   GET /api/privacy/retention
+// @access  Private/Admin
+const getRetention = async (req, res) => {
+  try {
+    res.json(await retentionState());
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Save retention policies (body.policies: { key: { enabled, months } })
+// @route   PUT /api/privacy/retention
+// @access  Private/Admin
+const saveRetention = async (req, res) => {
+  try {
+    const saved = await require('../utils/retention').savePolicies(req.body?.policies, { reviewedBy: req.user.name });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'retention_policies_updated', targetType: 'retention', metadata: saved.policies, ip: getClientIp(req) });
+    res.json(await retentionState());
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Run the retention job now
+// @route   POST /api/privacy/retention/run
+// @access  Private/Admin
+const runRetentionNow = async (req, res) => {
+  try {
+    const result = await require('../utils/retention').runRetention(new Date());
+    res.json({ result, state: await retentionState() });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Breach register ──────────────────────────────────────────────────────────
+
+const BREACH_TEXT = ['title', 'description', 'dataAffected', 'whoAffected', 'consequences', 'actionsTaken', 'adviceToPeople', 'causedBy'];
+const BREACH_DATES = ['discoveredAt', 'occurredAt', 'regulatorNotifiedAt', 'peopleNotifiedAt'];
+
+function breachData(body, { partial = false } = {}) {
+  const data = {};
+  for (const f of BREACH_TEXT) {
+    if (body?.[f] === undefined) continue;
+    const v = body[f] == null ? '' : String(body[f]).trim().slice(0, f === 'title' ? 200 : 10000);
+    data[f] = v || (['title', 'description', 'dataAffected'].includes(f) ? '' : null);
+  }
+  for (const f of BREACH_DATES) {
+    if (body?.[f] === undefined) continue;
+    if (body[f] === null || body[f] === '') { data[f] = null; continue; }
+    const d = new Date(body[f]);
+    if (Number.isNaN(d.getTime())) throw new Error(`${f} is not a valid date.`);
+    data[f] = d;
+  }
+  if (body?.peopleAffected !== undefined) {
+    const n = body.peopleAffected === null || body.peopleAffected === '' ? null : parseInt(body.peopleAffected, 10);
+    if (n !== null && (!Number.isInteger(n) || n < 0)) throw new Error('People affected must be a whole number.');
+    data.peopleAffected = n;
+  }
+  if (body?.status !== undefined) {
+    if (!['open', 'contained', 'closed'].includes(body.status)) throw new Error('status must be open, contained or closed');
+    data.status = body.status;
+  }
+  for (const f of ['title', 'description', 'dataAffected']) {
+    if ((!partial || f in data) && !data[f]) throw new Error({ title: 'Give it a short title.', description: 'Describe what happened.', dataAffected: 'Say what information was affected.' }[f]);
+  }
+  if (!partial && !data.discoveredAt) throw new Error('When was it discovered?');
+  if (partial && 'discoveredAt' in data && !data.discoveredAt) throw new Error('When was it discovered?');
+  return data;
+}
+
+// @route   GET /api/privacy/breaches
+const listBreaches = async (req, res) => {
+  try {
+    res.json(await prisma.securityBreach.findMany({ orderBy: { discoveredAt: 'desc' }, include: { createdBy: { select: { name: true } } } }));
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @route   POST /api/privacy/breaches
+const createBreach = async (req, res) => {
+  try {
+    const breach = await prisma.securityBreach.create({ data: { ...breachData(req.body), createdById: req.user.id } });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'breach_recorded', targetType: 'security_breach', targetId: breach.id, metadata: { title: breach.title }, ip: getClientIp(req) });
+    res.status(201).json(breach);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @route   PUT /api/privacy/breaches/:id
+const updateBreach = async (req, res) => {
+  try {
+    const existing = await prisma.securityBreach.findUnique({ where: { id: req.params.id } });
+    if (!existing) { res.status(404); throw new Error('Not found'); }
+    const data = breachData(req.body, { partial: true });
+    const breach = await prisma.securityBreach.update({ where: { id: existing.id }, data });
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'breach_updated', targetType: 'security_breach', targetId: breach.id, metadata: { title: breach.title, changed: Object.keys(data), status: breach.status }, ip: getClientIp(req) });
+    res.json(breach);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+module.exports = {
+  getReadiness,
+  getRetention,
+  saveRetention,
+  runRetentionNow,
+  listBreaches,
+  createBreach,
+  updateBreach,
+  getNotice,
+  acceptMyNotice,
+  getNoticeDraft,
+  saveNoticeDraft,
+  discardNoticeDraft,
+  publishNotice,
+  listOperators,
+  createOperator,
+  updateOperator,
+  deleteOperator,
+  consentLog,
+  accessLog,
+};
@@ -0,0 +1,358 @@
+const prisma = require('../config/db');
+const { comparePassword } = require('../config/auth');
+const { safeErrorMessage } = require('../utils/errorUtils');
+const { getClientIp } = require('../utils/requestUtils');
+const { logAdminAction } = require('../utils/adminAudit');
+const { isValidZAPhone } = require('../utils/whatsapp');
+const privacy = require('../utils/privacy');
+
+const fail = (res, error) => res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+
+const REQUEST_LABEL = { access: 'access to your information', correction: 'correction of your information', deletion: 'deletion of your account and personal information' };
+
+function frontendUrl() {
+  return String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+}
+
+function sendPrivacyEmail(to, subject, content) {
+  const { sendMail, buildPrivacyEmail } = require('../utils/email');
+  if (!to) return;
+  sendMail({ to, subject, ...buildPrivacyEmail(content) }).catch(() => {});
+}
+
+/** Tell the Information Officer (when set) and the admins that a request came in. */
+async function notifyAdminsOfRequest(request) {
+  const to = await privacy.privacyContacts();
+  const url = `${frontendUrl()}/dashboard/admin/data-requests`;
+  for (const email of to) {
+    sendPrivacyEmail(email, `New privacy request: ${request.type}`, {
+      name: '',
+      heading: 'New privacy request',
+      paragraphs: [
+        `${request.name} (${request.email}) asked for ${REQUEST_LABEL[request.type]}.`,
+        ...(request.details ? [`Their message: ${request.details}`] : []),
+        `POPIA asks for an answer within 30 days — by ${request.dueAt.toLocaleDateString('en-ZA')}. Open the Data requests page to handle it: ${url}`,
+      ],
+    });
+  }
+}
+
+/**
+ * "Delete my account" (password already checked by the caller): lock the account straight
+ * away and file a deletion request. The personal information is removed when an admin
+ * approves — registrations for upcoming events have to be sorted out first.
+ */
+async function requestAccountDeletion(user, { details = null } = {}) {
+  const request = await privacy.createDataRequest({ user, type: 'deletion', details: details ? String(details).trim() : null });
+  await prisma.user.update({ where: { id: user.id }, data: { isActive: false, tokenVersion: { increment: 1 }, newsEmail: false, newsWhatsApp: false } });
+  await require('../utils/twoFactor').clearTrustedDevices(user.id);
+  const blockers = await privacy.deletionBlockers(user.id);
+  sendPrivacyEmail(user.email, 'We received your request to delete your account', {
+    name: user.name,
+    heading: 'Deletion request received',
+    paragraphs: [
+      'We received your request to delete your account and personal information. Your account has been closed, so you can no longer log in.',
+      blockers.length
+        ? `You still have a registration for ${blockers.map(b => b.eventTitle).join(', ')}. Your information is deleted after that, or sooner if the registration is cancelled. Contact us if you'd like to cancel it.`
+        : 'We will remove your personal information within 30 days and let you know when it is done.',
+      'Records we must keep by law, such as payment amounts and dates, are kept without your name on them.',
+      'If you did not ask for this, contact us immediately.',
+    ],
+  });
+  notifyAdminsOfRequest(request).catch(() => {});
+  return request;
+}
+
+// ─── The person themselves ────────────────────────────────────────────────────
+
+// @desc    My privacy settings: news opt-in, consent history, my requests
+// @route   GET /api/privacy/me
+// @access  Private
+const getMyPrivacy = async (req, res) => {
+  try {
+    const user = await prisma.user.findUnique({
+      where: { id: req.user.id },
+      select: { phoneNumber: true, notificationPreference: true, newsEmail: true, newsWhatsApp: true, newsAskedAt: true },
+    });
+    if (!user) { res.status(404); throw new Error('User not found'); }
+    const [history, requests] = await Promise.all([
+      privacy.consentHistory(req.user.id),
+      prisma.dataRequest.findMany({
+        where: { userId: req.user.id, selfService: false },
+        orderBy: { createdAt: 'desc' },
+        select: { id: true, type: true, status: true, details: true, response: true, createdAt: true, closedAt: true },
+      }),
+    ]);
+    res.json({
+      news: { email: user.newsEmail, whatsapp: user.newsWhatsApp },
+      newsAskedAt: user.newsAskedAt,
+      canWhatsApp: isValidZAPhone(user.phoneNumber),
+      notificationPreference: user.notificationPreference,
+      history,
+      requests,
+    });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Change my News & announcements opt-in
+// @route   PUT /api/privacy/me/news
+// @access  Private
+const updateMyNews = async (req, res) => {
+  try {
+    const { email, whatsapp, source } = req.body || {};
+    // 'prompt' = the one-time question after login; anything else is the privacy centre.
+    const fromPrompt = source === 'prompt';
+    const updated = await privacy.setNewsPreferences(
+      req.user.id,
+      { email: typeof email === 'boolean' ? email : undefined, whatsapp: typeof whatsapp === 'boolean' ? whatsapp : undefined },
+      { source: fromPrompt ? 'prompt' : 'privacy_centre', ip: getClientIp(req), answered: true, logAll: fromPrompt },
+    );
+    if (!updated) { res.status(404); throw new Error('User not found'); }
+    res.json({ news: { email: updated.newsEmail, whatsapp: updated.newsWhatsApp }, newsAskedAt: updated.newsAskedAt });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Download my data (JSON, or a readable PDF with ?format=pdf)
+// @route   GET /api/privacy/me/export
+// @access  Private
+const exportMyData = async (req, res) => {
+  try {
+    // An admin viewing as this person must not walk off with their whole record.
+    if (req.impersonation) { res.status(403); throw new Error('Not available while viewing as another user.'); }
+    const data = await privacy.exportUserData(req.user.id);
+    if (!data) { res.status(404); throw new Error('User not found'); }
+    // Kept as a closed access request: the record that the person got their data.
+    await privacy.createDataRequest({ user: { id: req.user.id, name: data.account.name, email: data.account.email }, type: 'access', selfService: true });
+    const stamp = new Date().toISOString().slice(0, 10);
+    if (req.query.format === 'pdf') {
+      const pdf = await privacy.dataExportPdf(data);
+      res.setHeader('Content-Type', 'application/pdf');
+      res.setHeader('Content-Disposition', `attachment; filename="my-data-${stamp}.pdf"`);
+      return res.send(pdf);
+    }
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Content-Disposition', `attachment; filename="my-data-${stamp}.json"`);
+    res.send(JSON.stringify(data, null, 2));
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Make a privacy request: correction (details required) or deletion (password required)
+// @route   POST /api/privacy/me/requests
+// @access  Private
+const createMyRequest = async (req, res) => {
+  try {
+    const { type, details, password } = req.body || {};
+    if (!['correction', 'deletion'].includes(type)) { res.status(400); throw new Error('type must be correction or deletion'); }
+    const user = await prisma.user.findUnique({ where: { id: req.user.id } });
+    if (!user) { res.status(404); throw new Error('User not found'); }
+
+    const open = await prisma.dataRequest.findFirst({ where: { userId: user.id, type, status: 'open' } });
+    if (open) { res.status(409); throw new Error(`You already have an open ${type} request.`); }
+
+    if (type === 'correction') {
+      if (!details || !String(details).trim()) { res.status(400); throw new Error('Tell us what needs correcting.'); }
+      const request = await privacy.createDataRequest({ user, type, details: String(details).trim() });
+      notifyAdminsOfRequest(request).catch(() => {});
+      return res.status(201).json({ request, message: 'Your request was sent. We will get back to you by email.' });
+    }
+
+    if (!(await comparePassword(password || '', user.password))) { res.status(400); throw new Error('Incorrect password'); }
+    const request = await requestAccountDeletion(user, { details });
+    res.status(201).json({ request, message: 'Your account is closed and your deletion request was sent.' });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// ─── Unsubscribe links (no login) ─────────────────────────────────────────────
+
+// @desc    What an unsubscribe link refers to
+// @route   GET /api/privacy/unsubscribe/:token
+// @access  Public (signed token)
+const getUnsubscribe = async (req, res) => {
+  try {
+    const info = await privacy.describeUnsubscribe(req.params.token);
+    if (!info) { res.status(404); throw new Error('This unsubscribe link is not valid.'); }
+    res.json(info);
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Unsubscribe from news (body.channels: ['email','whatsapp'], default both)
+// @route   POST /api/privacy/unsubscribe/:token
+// @access  Public (signed token)
+const postUnsubscribe = async (req, res) => {
+  try {
+    const channels = Array.isArray(req.body?.channels) ? req.body.channels : undefined;
+    const result = await privacy.unsubscribe(req.params.token, { channels, ip: getClientIp(req) });
+    if (!result) { res.status(404); throw new Error('This unsubscribe link is not valid.'); }
+    res.json({ message: 'You have been unsubscribed.' });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    One-click unsubscribe (RFC 8058) from the List-Unsubscribe header — email only
+// @route   POST /api/privacy/unsubscribe/:token/one-click
+// @access  Public (signed token)
+const oneClickUnsubscribe = async (req, res) => {
+  try {
+    await privacy.unsubscribe(req.params.token, { channels: ['email'], ip: getClientIp(req) });
+  } catch { /* mail apps ignore the body; never fail loudly */ }
+  res.status(200).send('Unsubscribed');
+};
+
+// @desc    A person opening the List-Unsubscribe link in a browser: send them to the page
+// @route   GET /api/privacy/unsubscribe/:token/one-click
+// @access  Public
+const oneClickRedirect = (req, res) => {
+  res.redirect(302, `${frontendUrl()}/unsubscribe?t=${encodeURIComponent(req.params.token)}`);
+};
+
+// ─── Admin: data requests inbox ───────────────────────────────────────────────
+
+// @desc    Data requests (?status=open|closed|all, default open)
+// @route   GET /api/privacy/requests
+// @access  Private/Admin
+const listRequests = async (req, res) => {
+  try {
+    const status = String(req.query.status || 'open');
+    const where = { selfService: false };
+    if (status === 'open') where.status = 'open';
+    else if (status === 'closed') where.status = { not: 'open' };
+    const rows = await prisma.dataRequest.findMany({
+      where,
+      orderBy: status === 'open' ? { dueAt: 'asc' } : { createdAt: 'desc' },
+      take: 200,
+      include: { handledBy: { select: { name: true } }, user: { select: { isActive: true, phoneNumber: true } } },
+    });
+    const requests = await Promise.all(rows.map(async r => ({
+      id: r.id, type: r.type, status: r.status, name: r.name, email: r.email, details: r.details, response: r.response,
+      dueAt: r.dueAt, closedAt: r.closedAt, createdAt: r.createdAt, userId: r.userId,
+      handledBy: r.handledBy?.name || null,
+      overdue: r.status === 'open' && r.dueAt < new Date(),
+      blockers: r.type === 'deletion' && r.status === 'open' && r.userId ? await privacy.deletionBlockers(r.userId) : [],
+    })));
+    const openCount = status === 'open' ? requests.length : await prisma.dataRequest.count({ where: { selfService: false, status: 'open' } });
+    res.json({ requests, openCount });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+async function loadOpenRequest(req, res) {
+  const request = await prisma.dataRequest.findUnique({ where: { id: req.params.id } });
+  if (!request) { res.status(404); throw new Error('Request not found'); }
+  if (request.status !== 'open') { res.status(409); throw new Error('This request is already closed.'); }
+  return request;
+}
+
+// @desc    Complete a request. Deletion: anonymises the account (refused while it has a
+//          registration for an upcoming event). body.response is emailed to the person.
+// @route   POST /api/privacy/requests/:id/complete
+// @access  Private/Admin
+const completeRequest = async (req, res) => {
+  try {
+    const request = await loadOpenRequest(req, res);
+    const response = req.body?.response ? String(req.body.response).trim().slice(0, 5000) : null;
+    if (request.type === 'correction' && !response) { res.status(400); throw new Error('Say what was corrected — it is emailed to the person.'); }
+
+    let counts = null;
+    if (request.type === 'deletion' && request.userId) {
+      const blockers = await privacy.deletionBlockers(request.userId);
+      if (blockers.length) {
+        res.status(409);
+        throw new Error(`Cancel (and refund where needed) these registrations first: ${blockers.map(b => b.eventTitle).join(', ')}.`);
+      }
+      counts = await privacy.anonymiseUser(request.userId);
+      logAdminAction({
+        actorId: req.user.id, actorRole: req.user.role, action: 'user_anonymised', targetType: 'user', targetId: request.userId,
+        metadata: { dataRequestId: request.id, ...counts }, ip: getClientIp(req),
+      });
+    }
+
+    const closed = await prisma.dataRequest.update({
+      where: { id: request.id },
+      data: { status: 'completed', response, closedAt: new Date(), handledById: req.user.id },
+    });
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'data_request_completed', targetType: 'data_request', targetId: request.id,
+      metadata: { type: request.type, name: request.name }, ip: getClientIp(req),
+    });
+
+    sendPrivacyEmail(request.email, request.type === 'deletion' ? 'Your personal information has been deleted' : 'Your privacy request has been completed', {
+      name: request.name,
+      heading: request.type === 'deletion' ? 'Your information has been deleted' : 'Request completed',
+      paragraphs: [
+        request.type === 'deletion'
+          ? 'Your account and personal information have been deleted. Records we must keep by law, such as payment amounts and dates, are kept without your name on them. Backups that still contain your information are deleted as they age out.'
+          : `We have completed your request for ${REQUEST_LABEL[request.type]}.`,
+        ...(response ? [response] : []),
+      ],
+    });
+    res.json({ request: closed, anonymised: counts });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+// @desc    Reject or cancel a request (body.response says why; emailed). Rejecting a
+//          deletion request opens the account again (e.g. the person changed their mind).
+// @route   POST /api/privacy/requests/:id/reject
+// @access  Private/Admin
+const rejectRequest = async (req, res) => {
+  try {
+    const request = await loadOpenRequest(req, res);
+    const response = req.body?.response ? String(req.body.response).trim().slice(0, 5000) : '';
+    if (!response) { res.status(400); throw new Error('Give a reason — it is emailed to the person.'); }
+    const cancelled = req.body?.cancelled === true;
+
+    if (request.type === 'deletion' && request.userId) {
+      await prisma.user.update({ where: { id: request.userId }, data: { isActive: true } });
+    }
+    const closed = await prisma.dataRequest.update({
+      where: { id: request.id },
+      data: { status: cancelled ? 'cancelled' : 'rejected', response, closedAt: new Date(), handledById: req.user.id },
+    });
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'data_request_rejected', targetType: 'data_request', targetId: request.id,
+      metadata: { type: request.type, name: request.name, cancelled, reactivated: request.type === 'deletion' }, ip: getClientIp(req),
+    });
+    sendPrivacyEmail(request.email, cancelled ? 'Your privacy request was cancelled' : 'About your privacy request', {
+      name: request.name,
+      heading: cancelled ? 'Request cancelled' : 'About your request',
+      paragraphs: [
+        `Your request for ${REQUEST_LABEL[request.type]} was ${cancelled ? 'cancelled' : 'not carried out'}.`,
+        response,
+        ...(request.type === 'deletion' ? ['Your account is open again — you can log in as before.'] : []),
+        ...(cancelled ? [] : ['If you disagree, you may complain to the Information Regulator (inforegulator.org.za).']),
+      ],
+    });
+    res.json({ request: closed });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
+module.exports = {
+  getMyPrivacy,
+  updateMyNews,
+  exportMyData,
+  createMyRequest,
+  getUnsubscribe,
+  postUnsubscribe,
+  oneClickUnsubscribe,
+  oneClickRedirect,
+  listRequests,
+  completeRequest,
+  rejectRequest,
+  notifyAdminsOfRequest,
+  requestAccountDeletion,
+};
@@ -0,0 +1,239 @@
+const prisma = require('../config/db');
+const { generateTicketsForRegistration } = require('../utils/ticketUtils');
+const { emailTickets } = require('./ticketController');
+const { getProvider } = require('../payments');
+
+const canReconcile = (req) => !!req.user && ['admin', 'supervisor'].includes(req.user.role);
+// The checkout metadata (who/what the payment was for), read by the provider that sent it.
+const metadataOf = (tx) => {
+  const provider = getProvider(tx.provider);
+  try { return (provider && tx.raw ? provider.parseWebhook(tx.raw).transaction.metadata : null) || {}; } catch { return {}; }
+};
+const withLabel = (tx) => ({ ...tx, providerLabel: getProvider(tx.provider)?.label || tx.provider, metadata: metadataOf(tx) });
+
+// @desc    Payment provider transactions (optionally filter by provider, reconciled, ignored)
+// @route   GET /api/provider-transactions  (also /api/yoco-transactions)
+// @access  Private/Admin or Supervisor
+const getAllProviderTransactions = async (req, res) => {
+  try {
+    if (!canReconcile(req)) return res.status(403).json({ success: false, message: 'Forbidden' });
+
+    const { reconciled, ignored, provider } = req.query;
+    const where = {};
+    if (typeof reconciled !== 'undefined') where.reconciled = String(reconciled) === 'true';
+    if (typeof ignored !== 'undefined') where.ignored = String(ignored) === 'true';
+    if (provider) where.provider = String(provider);
+
+    const items = await prisma.providerTransaction.findMany({ where, orderBy: [{ createdDate: 'desc' }, { createdAt: 'desc' }] });
+    return res.status(200).json({ success: true, data: items.map(withLabel) });
+  } catch (error) {
+    console.error('Failed to fetch provider transactions:', error);
+    return res.status(500).json({ success: false, message: 'Server error', details: error.message });
+  }
+};
+
+// @desc    Unreconciled provider transactions (not reconciled and not ignored)
+// @route   GET /api/provider-transactions/unreconciled  (also /api/yoco-transactions/unreconciled)
+// @access  Private/Admin or Supervisor
+const getUnreconciledProviderTransactions = async (req, res) => {
+  try {
+    if (!canReconcile(req)) return res.status(403).json({ success: false, message: 'Forbidden' });
+
+    const items = await prisma.providerTransaction.findMany({
+      where: { reconciled: false, ignored: false, ...(req.query.provider ? { provider: String(req.query.provider) } : {}) },
+      orderBy: { createdDate: 'desc' },
+    });
+    return res.status(200).json({ success: true, data: items.map(withLabel) });
+  } catch (error) {
+    console.error('Failed to fetch unreconciled provider transactions:', error);
+    return res.status(500).json({ success: false, message: 'Server error', details: error.message });
+  }
+};
+
+// @desc    Reconcile a provider transaction to a Registration or Donation (creates Payment)
+// @route   POST /api/provider-transactions/:id/reconcile  (also /api/yoco-transactions/:id/reconcile)
+// @access  Private/Admin or Supervisor
+const reconcileProviderTransaction = async (req, res) => {
+  try {
+    if (!canReconcile(req)) return res.status(403).json({ success: false, message: 'Forbidden' });
+
+    const { id } = req.params;
+    const { registrationId, eventId, userId: bodyUserId } = req.body || {};
+
+    const tx = await prisma.providerTransaction.findUnique({ where: { id } });
+    if (!tx) return res.status(404).json({ success: false, message: 'Transaction not found' });
+    if (tx.reconciled && tx.paymentId) {
+      return res.status(409).json({ success: false, message: 'Already reconciled', data: withLabel(tx) });
+    }
+
+    // Load registration if provided
+    let registration = null;
+    if (registrationId) {
+      registration = await prisma.registration.findUnique({
+        where: { id: registrationId },
+        include: {
+          event: true,
+          user: true,
+          registrationOptions: { include: { eventOption: true } },
+          payments: true
+        }
+      });
+      if (!registration) return res.status(404).json({ success: false, message: 'Registration not found' });
+    }
+
+    // Determine payment fields
+    const amountFloat = typeof tx.amount === 'number' ? (tx.amount / 100) : 0;
+    if (!amountFloat || amountFloat <= 0) {
+      return res.status(400).json({ success: false, message: 'Invalid amount on the transaction for reconciliation' });
+    }
+
+    const metadata = metadataOf(tx);
+
+    // Resolve a valid userId for the Payment to satisfy FK constraints
+    let resolvedUserId = null;
+    if (registration?.userId) {
+      resolvedUserId = registration.userId;
+    } else if (bodyUserId) {
+      // Staff explicitly picked the donor while reconciling (e.g. as a donation) — trust that
+      // over metadata guesswork, but still verify the user actually exists.
+      try {
+        const exists = await prisma.user.findUnique({ where: { id: String(bodyUserId) } });
+        if (exists) resolvedUserId = String(bodyUserId);
+      } catch {}
+    }
+    if (!resolvedUserId && metadata.userId) {
+      try {
+        const exists = await prisma.user.findUnique({ where: { id: String(metadata.userId) } });
+        if (exists) resolvedUserId = String(metadata.userId);
+      } catch {}
+    }
+    if (!resolvedUserId && req.user?.id) {
+      // Fallback to the acting supervisor/admin to avoid FK violations
+      resolvedUserId = req.user.id;
+    }
+    if (!resolvedUserId) {
+      return res.status(400).json({ success: false, message: 'Unable to resolve a valid user for this payment' });
+    }
+
+    const paymentData = {
+      amount: amountFloat,
+      method: tx.methodType || 'card',
+      provider: tx.provider,
+      userId: resolvedUserId,
+      recordedById: req.user?.id || null, // staff who performed the reconciliation
+      registrationId: registration?.id || null,
+      eventId: registration?.eventId || eventId || null,
+      isDonation: !registration?.id,
+      externalId: tx.externalId || undefined,
+      status: 'completed'
+    };
+
+    // Ensure donation has an eventId
+    if (!registration && !paymentData.eventId) {
+      return res.status(400).json({ success: false, message: 'eventId is required when reconciling as donation' });
+    }
+
+    // Keep the provider's creation time so early-bird pricing is evaluated correctly
+    const createdAt = tx.createdDate || tx.createdAt || new Date();
+    const payment = await prisma.payment.create({ data: { ...paymentData, createdAt } });
+
+    // Update registration status and generate tickets if paid. Ticket generation stays
+    // synchronous so `generatedTickets` can be in the response; emailing is backgrounded below.
+    let generatedTickets = [];
+    if (registration) {
+      try {
+        const updatedReg = await updateRegistrationStatus(registration.id);
+        if (updatedReg && updatedReg.status === 'paid') {
+          try {
+            generatedTickets = await generateTicketsForRegistration(registration.id);
+          } catch (genErr) {
+            console.error('Error generating tickets after reconciliation:', genErr);
+          }
+        }
+      } catch (e) {
+        // log but do not fail reconciliation
+        console.warn('Failed to update registration after reconciliation:', e?.message || e);
+      }
+    }
+
+    // Fire-and-forget: payment confirmation email, then ticket email/WhatsApp (guarantees order)
+    const { sendPaymentEmails } = require('../utils/notifications');
+    const _rxPaymentId = payment.id;
+    const _rxUserId = registration?.userId;
+    const _rxRegId = registration?.id;
+    const _rxShouldEmailTickets = Array.isArray(generatedTickets) && generatedTickets.length > 0;
+    (async () => {
+      try { await sendPaymentEmails(_rxPaymentId); } catch (e) { console.error('Failed to send payment emails after reconciliation:', e); }
+      if (_rxShouldEmailTickets && _rxUserId) {
+        const mockReq = { user: { id: _rxUserId }, body: { registrationId: _rxRegId } };
+        const mockRes = { status: () => mockRes, json: () => {} };
+        try { await emailTickets(mockReq, mockRes); } catch (e) { console.error('Error emailing tickets after reconciliation:', e); }
+      }
+    })();
+
+    const updatedTx = await prisma.providerTransaction.update({ where: { id: tx.id }, data: { reconciled: true, paymentId: payment.id } });
+
+    return res.status(200).json({ success: true, data: { transaction: withLabel(updatedTx), payment, generatedTickets: generatedTickets.length ? generatedTickets : undefined } });
+  } catch (error) {
+    console.error('Failed to reconcile provider transaction:', error);
+    // A Payment with the same externalId already exists: link to it instead
+    if (error?.code === 'P2002') {
+      try {
+        const tx = await prisma.providerTransaction.findUnique({ where: { id: req.params.id } });
+        const existing = tx ? await prisma.payment.findFirst({ where: { externalId: tx.externalId } }) : null;
+        if (existing) {
+          const updatedTx = await prisma.providerTransaction.update({ where: { id: tx.id }, data: { reconciled: true, paymentId: existing.id } });
+          return res.status(200).json({ success: true, data: { transaction: withLabel(updatedTx), payment: existing }, message: 'Linked to existing payment' });
+        }
+      } catch {}
+    }
+    return res.status(500).json({ success: false, message: 'Server error', details: error?.message || String(error) });
+  }
+};
+
+// Minimal registration status update mirroring webhook logic
+async function updateRegistrationStatus(registrationId) {
+  const registration = await prisma.registration.findUnique({
+    where: { id: registrationId },
+    include: {
+      registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } } } },
+      payments: true
+    }
+  });
+  if (!registration) return null;
+  const totalPaid = (registration.payments || []).reduce((s, p) => s + (p.amount || 0), 0);
+  const totalDue = require('../utils/pricing').computeRegistrationTotalDue(registration, new Date());
+  let newStatus = 'pending';
+  if (totalPaid >= totalDue) newStatus = 'paid';
+  else if (totalPaid > 0) newStatus = 'partial_paid';
+  return prisma.registration.update({ where: { id: registrationId }, data: { status: newStatus, updatedAt: new Date() } });
+}
+
+// @desc    Ignore a provider transaction (mark as ignored and reconciled without creating a payment)
+// @route   POST /api/provider-transactions/:id/ignore  (also /api/yoco-transactions/:id/ignore)
+// @access  Private/Admin or Supervisor
+const ignoreProviderTransaction = async (req, res) => {
+  try {
+    if (!canReconcile(req)) return res.status(403).json({ success: false, message: 'Forbidden' });
+    const { id } = req.params;
+    const tx = await prisma.providerTransaction.findUnique({ where: { id } });
+    if (!tx) return res.status(404).json({ success: false, message: 'Transaction not found' });
+
+    if (tx.reconciled && tx.ignored) {
+      return res.status(200).json({ success: true, data: withLabel(tx), message: 'Already ignored' });
+    }
+
+    const updated = await prisma.providerTransaction.update({ where: { id }, data: { ignored: true, reconciled: true } });
+    return res.status(200).json({ success: true, data: withLabel(updated) });
+  } catch (error) {
+    console.error('Failed to ignore provider transaction:', error);
+    return res.status(500).json({ success: false, message: 'Server error', details: error?.message || String(error) });
+  }
+};
+
+module.exports = {
+  getAllProviderTransactions,
+  getUnreconciledProviderTransactions,
+  reconcileProviderTransaction,
+  ignoreProviderTransaction
+};
@@ -53,7 +53,7 @@ const ACTIVE_COUPONS_INCLUDE = {
  select: { id: true, discountAmount: true, createdAt: true, coupon: { select: { id: true, code: true, type: true, value: true, description: true } } },
 };
 const { BUNDLE_APPS_INCLUDE } = require('../utils/bundles');
-const { registrationClosesAt, wholeCourseClosesAt, expandPickLines, assertSessionCapacity, isPickOption } = require('../utils/sessions');
+const { registrationClosesAt, wholeCourseClosesAt, expandPickLines, assertSessionCapacity, isPickOption, mergeSessionIds } = require('../utils/sessions');

 /**
 * Coupon lines for options that haven't been saved yet, so a code can be checked
@@ -226,11 +226,12 @@ const createRegistration = async (req, res) => {
    // "Pick sessions" options become one line per chosen session; whole-course tickets
    // on such an event still close when the whole course does.
    const lines = expandPickLines(event, options, { now });
-    if (event.attendanceMode === 'pick' && lines.some(l => !l.sessionId) && now >= wholeCourseClosesAt(event, event.sessions)) {
+    // (An all-sessions ticket with sessions ticked is checked per session instead.)
+    if (event.attendanceMode === 'pick' && lines.some(l => !l.sessionId && !l.sessionIds?.length) && now >= wholeCourseClosesAt(event, event.sessions)) {
      res.status(400);
      throw new Error('Whole-course tickets are no longer on sale — choose the sessions you want instead.');
    }
-    await assertSessionCapacity(event, lines);
+    await assertSessionCapacity(event, lines, undefined, { excludeEntryId: waitlistOffer?.id });

    // Validate each option and resolve prices / check stock.
    // Options are independent of each other, so resolve them concurrently. Errors are marked
@@ -347,7 +348,7 @@ const createRegistration = async (req, res) => {
            }),
            prisma.registrationOption.update({
              where: { id: existing.id },
-              data: { quantity: existing.quantity + opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null }
+              data: { quantity: existing.quantity + opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null, ...(existing.sessionId ? {} : { sessionIds: mergeSessionIds(existing.sessionIds, opt.sessionIds) }) }
            })
          ]);
        } else {
@@ -359,6 +360,7 @@ const createRegistration = async (req, res) => {
              quantity: opt.quantity,
              variantId: opt.variantId || null,
              sessionId: opt.sessionId || null,
+              sessionIds: opt.sessionIds || [],
              appliedTierId: opt.appliedTierId || null,
              priceSnapshot: opt.priceSnapshot,
              tranches: {
@@ -407,6 +409,7 @@ const createRegistration = async (req, res) => {
              quantity: option.quantity,
              variantId: option.variantId || null,
              sessionId: option.sessionId || null,
+              sessionIds: option.sessionIds || [],
              appliedTierId: option.appliedTierId || null,
              priceSnapshot: option.priceSnapshot,
              tranches: {
@@ -562,8 +565,10 @@ const getRegistrations = async (req, res) => {
    // Pagination is opt-in via ?page/?limit to keep existing callers (which expect a plain
    // array of every registration) working unchanged; callers that pass either param get back
    // the { data, total, page, limit, pages } shape used by /api/payments and /api/users.
+    // Campus-scoped staff: registrations for events they can see.
+    const where = await require('../utils/campusScope').listWhere(req, 'event');
    if (typeof req.query.page === 'undefined' && typeof req.query.limit === 'undefined') {
-      const registrations = await prisma.registration.findMany({ include });
+      const registrations = await prisma.registration.findMany({ where, include });
      return res.json(attachComputedTotalsToList(registrations));
    }

@@ -572,8 +577,8 @@ const getRegistrations = async (req, res) => {
    const skip = (page - 1) * limit;

    const [registrations, total] = await prisma.$transaction([
-      prisma.registration.findMany({ include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
-      prisma.registration.count()
+      prisma.registration.findMany({ where, include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
+      prisma.registration.count({ where })
    ]);

    res.json({ data: attachComputedTotalsToList(registrations), total, page, limit, pages: Math.ceil(total / limit) });
@@ -1193,6 +1198,8 @@ const createManualRegistration = async (req, res) => {
                quantity: existing.quantity + opt.quantity,
                priceSnapshot: opt.priceSnapshot,
                appliedTierId: opt.appliedTierId || null,
+                // More of an all-sessions ticket: it covers the sessions of both bookings.
+                ...(existing.sessionId ? {} : { sessionIds: mergeSessionIds(existing.sessionIds, opt.sessionIds) }),
              }
            })
          ]);
@@ -1205,6 +1212,7 @@ const createManualRegistration = async (req, res) => {
            quantity: opt.quantity,
            variantId: opt.variantId || null,
            sessionId: opt.sessionId || null,
+            sessionIds: opt.sessionIds || [],
            appliedTierId: opt.appliedTierId || null,
            priceSnapshot: opt.priceSnapshot,
            tranches: {
@@ -1274,6 +1282,7 @@ const createManualRegistration = async (req, res) => {
              quantity: option.quantity,
              variantId: option.variantId || null,
              sessionId: option.sessionId || null,
+              sessionIds: option.sessionIds || [],
              appliedTierId: option.appliedTierId || null,
              priceSnapshot: option.priceSnapshot,
              tranches: {
@@ -1358,20 +1367,20 @@ const createManualRegistration = async (req, res) => {
      await generateTicketsForRegistration(registration.id);
    } catch {}

-    // For paid registrations, generate a Yoco checkout link to include in the email
+    // For paid registrations, generate a checkout link to include in the email
    let yocoPaymentUrl = null;
    if (registration.status !== 'paid') {
      try {
-        const { createRegistrationCheckoutInternal } = require('./paymentController');
+        const { createRegistrationCheckout } = require('../payments/checkouts');
        const baseUrl = process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001';
-        const checkout = await createRegistrationCheckoutInternal(registrationId, userId, {
+        const checkout = await createRegistrationCheckout(registrationId, userId, {
          successUrl: `${baseUrl}/payment/success`,
          cancelUrl: `${baseUrl}/payment/cancel`,
          failureUrl: `${baseUrl}/payment/failure`,
        });
        yocoPaymentUrl = checkout.redirectUrl || null;
      } catch (e) {
-        console.warn('Could not create Yoco checkout for self-service email:', e?.message || e);
+        console.warn('Could not create a checkout for the self-service email:', e?.message || e);
      }
    }

@@ -397,6 +397,13 @@ function writeTableRows(ws, startRow, columns, rows) {
  return { nextRow: r, dataStartRow };
 }

+// POPIA access log: who took which report out of the system, and how many rows.
+function logReport(req, action) {
+  const { logDataAccess, reportRowCount } = require('../utils/accessLog');
+  const p = req.body || {};
+  logDataAccess(req, { action, what: [p.title || 'Report', p.subtitle].filter(Boolean).join(' — '), records: reportRowCount(p) });
+}
+
 // POST /api/reports/pdf
 // body: { title, subtitle?, kind: 'table'|'layered', table?, layered?, stats?, chart?, note?, orientation? }
 const generatePdf = async (req, res) => {
@@ -410,6 +417,7 @@ const generatePdf = async (req, res) => {
    doc.pipe(res);
    drawReportPdf(doc, { title, subtitle, kind, table, layered, stats, chart, note, extraTables });
    doc.end();
+    logReport(req, 'report_pdf');
  } catch (e) {
    res.status(400).json({ message: e.message });
  }
@@ -426,6 +434,7 @@ const generateExcel = async (req, res) => {
    res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
    await wb.xlsx.write(res);
    res.end();
+    logReport(req, 'report_excel');
  } catch (e) {
    res.status(400).json({ message: e.message });
  }
@@ -462,6 +471,7 @@ const emailPdf = async (req, res) => {

    try { fs.unlinkSync(filePath); } catch {}

+    logReport(req, 'report_email');
    res.json({ message: `Report emailed to ${user.email}` });
  } catch (e) {
    res.status(400).json({ message: e.message });
@@ -489,6 +499,7 @@ const whatsappPdf = async (req, res) => {
    const filename = `${(title || 'report').replace(/[^a-z0-9]/gi, '_').toLowerCase()}.pdf`;
    await sendPdf(user.phoneNumber, filePath, filename, caption || title || 'Report');

+    logReport(req, 'report_whatsapp');
    res.json({ message: `Report sent to your WhatsApp` });
  } catch (e) {
    res.status(400).json({ message: e.message });
@@ -1,4 +1,20 @@
 const { listJobs, getJob, updateJob, deleteJob } = require('../utils/scheduledEmails');
+const prisma = require('../config/db');
+const { scopeFor, eventWhere } = require('../utils/campusScope');
+
+/**
+ * The jobs a campus-scoped supervisor may see and change: messages for events they can see, and
+ * broadcasts they scheduled themselves. Everyone else sees every job.
+ */
+async function visibleJobs(req, jobs) {
+  const scope = await scopeFor(req);
+  if (!scope) return jobs;
+  const ids = [...new Set(jobs.map(j => j.eventId).filter(Boolean))];
+  const seen = ids.length
+    ? new Set((await prisma.event.findMany({ where: { id: { in: ids }, ...eventWhere(scope) }, select: { id: true } })).map(e => e.id))
+    : new Set();
+  return jobs.filter(j => (j.eventId ? seen.has(j.eventId) : j.createdById === req.user.id));
+}

 // Normalize job for client UI
 function toClient(job) {
@@ -34,7 +50,7 @@ function toClient(job) {
 const listScheduledEmails = async (req, res) => {
  try {
    const { channel } = req.query || {};
-    const raw = listJobs(channel ? { channel: String(channel) } : {});
+    const raw = await visibleJobs(req, listJobs(channel ? { channel: String(channel) } : {}));
    const filtered = raw
    // Provide most-relevant first: queued -> sending -> error -> recent sent
    .sort((a, b) => {
@@ -59,7 +75,7 @@ const updateScheduledEmail = async (req, res) => {
  try {
    const { id } = req.params;
    const job = getJob(id);
-    if (!job) return res.status(404).json({ message: 'Job not found' });
+    if (!job || !(await visibleJobs(req, [job])).length) return res.status(404).json({ message: 'Job not found' });
    if (job.status !== 'queued') return res.status(400).json({ message: 'Only queued jobs can be edited' });

    const { scheduledAt, subject, html, text, message } = req.body || {};
@@ -92,7 +108,7 @@ const deleteScheduledEmail = async (req, res) => {
  try {
    const { id } = req.params;
    const job = getJob(id);
-    if (!job) return res.status(404).json({ message: 'Job not found' });
+    if (!job || !(await visibleJobs(req, [job])).length) return res.status(404).json({ message: 'Job not found' });
    if (job.status !== 'queued') return res.status(400).json({ message: 'Only queued jobs can be deleted' });
    const ok = deleteJob(id);
    if (!ok) return res.status(404).json({ message: 'Job not found' });
@@ -10,9 +10,8 @@ const getSections = async (req, res) => {
    try {
        const { eventId } = req.query;

-        const where = eventId && eventId !== 'all'
-            ? { eventId }
-            : undefined;
+        const { withScope, listWhere } = require('../utils/campusScope');
+        const where = withScope(eventId && eventId !== 'all' ? { eventId } : {}, await listWhere(req, 'event'));

        const sections = await prisma.section.findMany({
            where,
@@ -8,9 +8,19 @@ const { logAdminAction } = require('../utils/adminAudit');
 const { getClientIp } = require('../utils/requestUtils');

 // Keys safe to return without auth — includes legal keys needed by public legal pages
-// Yoco secrets are only readable (masked) and writable through /api/yoco — never
-// through the generic settings endpoints.
-const YOCO_PRIVATE_KEYS = new Set(['yoco_secret_key', 'yoco_webhook_secret', 'yoco_webhook_id']);
+// Payment provider settings are only readable (secrets masked) and writable through
+// /api/yoco and /api/payfast — never through the generic settings endpoints.
+const PAYMENT_PRIVATE_KEYS = new Set([
+  'yoco_secret_key', 'yoco_webhook_secret', 'yoco_webhook_id',
+  'payfast_merchant_id', 'payfast_merchant_key', 'payfast_passphrase', 'payfast_mode',
+]);
+
+// The Hub connection (install id and secret, licence token) is only written by src/hub —
+// an admin editing it here could borrow another install's licence.
+const HUB_PRIVATE_KEYS = new Set(require('../hub/client').HUB_KEYS);
+// Changed through /api/campuses/settings (audited as campuses_toggled), read through GET /api/campuses.
+const CAMPUS_KEYS = new Set([require('../utils/campuses').SETTING_KEY]);
+const PRIVATE_KEYS = new Set([...PAYMENT_PRIVATE_KEYS, ...HUB_PRIVATE_KEYS, ...CAMPUS_KEYS]);

 const PUBLIC_KEYS = [
  'org_name', 'org_tagline', 'org_email', 'org_phone', 'org_address',
@@ -50,7 +60,7 @@ const getAllSettings = async (req, res) => {
    const rows = await prisma.appSetting.findMany();
    const settings = {};
    for (const r of rows) {
-      if (YOCO_PRIVATE_KEYS.has(r.key)) continue;
+      if (PRIVATE_KEYS.has(r.key)) continue;
      if (ENCRYPTED_KEYS.has(r.key)) {
        // Return a sentinel so the UI knows the value is set, without exposing it.
        // smtp_user (email address) we can safely return as-is after decryption so
@@ -86,7 +96,7 @@ const updateSettings = async (req, res) => {
    }

    const ops = Object.entries(updates)
-      .filter(([k, v]) => v !== undefined && v !== null && !YOCO_PRIVATE_KEYS.has(k))
+      .filter(([k, v]) => v !== undefined && v !== null && !PRIVATE_KEYS.has(k))
      .map(([key, value]) => {
        let storedValue = String(value);

@@ -125,7 +135,7 @@ const updateSettings = async (req, res) => {
        actorRole: req.user.role,
        action: 'settings_updated',
        targetType: 'AppSetting',
-        metadata: { changedKeys: Object.keys(updates).filter(k => updates[k] !== undefined && updates[k] !== null && !YOCO_PRIVATE_KEYS.has(k)) },
+        metadata: { changedKeys: Object.keys(updates).filter(k => updates[k] !== undefined && updates[k] !== null && !PRIVATE_KEYS.has(k)) },
        ip: getClientIp(req),
      });
    }
@@ -202,7 +212,7 @@ const runSetup = async (req, res) => {

    const toSave = { ...settings, setup_complete: 'true' };
    const ops = Object.entries(toSave)
-      .filter(([k, v]) => v !== undefined && v !== null && String(v).trim() !== '' && !YOCO_PRIVATE_KEYS.has(k))
+      .filter(([k, v]) => v !== undefined && v !== null && String(v).trim() !== '' && !PRIVATE_KEYS.has(k))
      .map(([key, value]) => {
        let storedValue = String(value);
        if (ENCRYPTED_KEYS.has(key)) storedValue = encrypt(storedValue);
@@ -1,5 +1,4 @@
-const axios = require('axios');
-const { yocoAuthHeader } = require('../utils/yoco');
+const payments = require('../payments');
 const prisma = require('../config/db');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { sponsorshipError, spotPrice, sponsorshipCharge, poolSummary } = require('../utils/sponsorship');
@@ -45,7 +44,7 @@ const getEventSponsorship = async (req, res) => {
  }
 };

-// @desc    Start a Yoco checkout to sponsor spots (or a custom amount) at an event
+// @desc    Start an online checkout to sponsor spots (or a custom amount) at an event
 // @route   POST /api/sponsorships/checkout   { eventId, spots? | amount?, anonymous?, sponsorName?, message?, name?, email?, phone? }
 // @access  Public (guests give a name and email for the receipt)
 const createSponsorCheckout = async (req, res) => {
@@ -72,9 +71,8 @@ const createSponsorCheckout = async (req, res) => {
    const back = `${base}/events/${encodeURIComponent(event.id)}`;
    const amountInCents = Math.round(charge.amount * 100);
    const label = charge.spots ? `Sponsor ${charge.spots} spot${charge.spots > 1 ? 's' : ''} at ${event.title}` : `Sponsorship for ${event.title}`;
-    const checkoutData = {
-      amount: amountInCents,
-      currency: 'ZAR',
+    const checkout = await payments.createCheckout(req.body?.provider || null, {
+      amountCents: amountInCents,
      metadata: {
        type: 'sponsorship', isDonation: true, eventId: event.id, eventTitle: event.title, userId: payer.id,
        sponsorAnonymous: isAnonymous ? 'true' : 'false',
@@ -85,14 +83,14 @@ const createSponsorCheckout = async (req, res) => {
      successUrl: `${back}?sponsored=1`,
      cancelUrl: back,
      failureUrl: `${back}?sponsored=failed`,
-      lineItems: [{ displayName: label, quantity: 1, pricingDetails: { price: amountInCents } }],
-    };
-    const response = await axios.post('https://payments.yoco.com/api/checkouts', checkoutData, {
-      headers: { 'Content-Type': 'application/json', Authorization: await yocoAuthHeader(), 'Idempotency-Key': `spon_${event.id}_${payer.id}_${amountInCents}_${Date.now()}` },
+      lineItems: [{ name: label, quantity: 1, unitCents: amountInCents }],
+      description: label,
+      payer: { name: payer.name || '', email: payer.email || '' },
+      idempotencyKey: `spon_${event.id}_${payer.id}_${amountInCents}_${Date.now()}`,
    });
-    res.json({ redirectUrl: response.data.redirectUrl, checkoutId: response.data.id, amount: charge.amount });
+    res.json({ redirectUrl: checkout.redirectUrl, checkoutId: checkout.checkoutId, provider: checkout.provider, amount: charge.amount });
  } catch (error) {
-    if (error.response) console.error('Sponsor checkout error:', error.response.data || error.message);
+    if (error.statusCode >= 500) console.error('Sponsor checkout error:', error.message);
    fail(res, error);
  }
 };
@@ -1,21 +1,23 @@
 const prisma = require('../config/db');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { isDonationLeg } = require('../utils/cashupUtils');
+const { campusesEnabled, campusWhere, resolveCampusFilter } = require('../utils/campuses');
+const { scopeFor, eventWhere: scopeEventWhere, withScope } = require('../utils/campusScope');

 // Shared building blocks for the per-dashboard stats endpoints below. Each dashboard
 // (staff/supervisor/admin) gets exactly one endpoint that returns only what it renders,
 // computed with aggregate queries — never a full payments/events list shipped to the
 // client just to be reduced down to a couple of numbers.

-async function computeScanStats(userId) {
+async function computeScanStats(userId, ticketWhere = {}) {
  const startOfDay = new Date();
  startOfDay.setHours(0, 0, 0, 0);
-  const whereBase = { scannedAt: { gte: startOfDay } };
+  const whereBase = { scannedAt: { gte: startOfDay }, ...ticketWhere };

  const [totalToday, myToday, lastHour, byStaffRaw] = await Promise.all([
    prisma.ticketUsage.count({ where: whereBase }),
    prisma.ticketUsage.count({ where: { ...whereBase, scannedById: userId } }),
-    prisma.ticketUsage.count({ where: { scannedAt: { gte: new Date(Date.now() - 60 * 60 * 1000) } } }),
+    prisma.ticketUsage.count({ where: { scannedAt: { gte: new Date(Date.now() - 60 * 60 * 1000) }, ...ticketWhere } }),
    prisma.ticketUsage.groupBy({ by: ['scannedById'], where: whereBase, _count: { _all: true } }),
  ]);

@@ -33,8 +35,9 @@ async function computeScanStats(userId) {
  };
 }

-function getRecentScans(limit = 10) {
+function getRecentScans(limit = 10, ticketWhere = {}) {
  return prisma.ticketUsage.findMany({
+    where: ticketWhere,
    orderBy: { scannedAt: 'desc' },
    take: limit,
    select: {
@@ -53,8 +56,26 @@ function getRecentScans(limit = 10) {
  });
 }

-function getActiveEventsCount() {
-  return prisma.event.count({ where: { isActive: true, endDate: { gte: new Date() } } });
+function getActiveEventsCount(eventWhere = {}) {
+  return prisma.event.count({ where: { isActive: true, endDate: { gte: new Date() }, ...eventWhere } });
+}
+
+/**
+ * `where` pieces for a ?campus= filter (id, slug or 'all') together with the user's campus scope
+ * (1.44.0), or empty for church-wide. A payment belongs to a campus through its event, or its
+ * registration's event — so payments with neither (unlinked donations) aren't counted for a
+ * scoped user. EXCLUDE_DONATION_LEGS uses NOT, so the payment OR never collides with it.
+ */
+async function campusFilters(value, scope = null) {
+  const enabled = await campusesEnabled();
+  const eventWhere = withScope(campusWhere(enabled ? await resolveCampusFilter(value) : '', { enabled }), scopeEventWhere(scope));
+  if (!Object.keys(eventWhere).length) return { eventWhere: {}, byEvent: {}, payment: {}, usage: {} };
+  return {
+    eventWhere,
+    byEvent: { event: eventWhere },
+    payment: { OR: [{ event: eventWhere }, { registration: { event: eventWhere } }] },
+    usage: { ticket: { event: eventWhere } },
+  };
 }

 // A donation-application leg (isDonation:false, originalPaymentId set, amount>0) isn't new
@@ -64,19 +85,19 @@ const EXCLUDE_DONATION_LEGS = {
  NOT: { AND: [{ isDonation: false }, { originalPaymentId: { not: null } }, { amount: { gt: 0 } }] },
 };

-async function computePaymentStats({ includeWeekMonth }) {
+async function computePaymentStats({ includeWeekMonth, paymentWhere = {} }) {
  const startOfDay = new Date(new Date().setHours(0, 0, 0, 0));

  const queries = [
-    prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: startOfDay }, ...EXCLUDE_DONATION_LEGS } }),
-    prisma.payment.count({ where: { isDonation: true, createdAt: { gte: startOfDay } } }),
+    prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: startOfDay }, ...EXCLUDE_DONATION_LEGS, ...paymentWhere } }),
+    prisma.payment.count({ where: { isDonation: true, createdAt: { gte: startOfDay }, ...paymentWhere } }),
  ];
  if (includeWeekMonth) {
    const lastWeek = new Date(startOfDay.getTime() - 7 * 24 * 60 * 60 * 1000);
    const lastMonth = new Date(startOfDay.getTime() - 30 * 24 * 60 * 60 * 1000);
    queries.push(
-      prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: lastWeek }, ...EXCLUDE_DONATION_LEGS } }),
-      prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: lastMonth }, ...EXCLUDE_DONATION_LEGS } }),
+      prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: lastWeek }, ...EXCLUDE_DONATION_LEGS, ...paymentWhere } }),
+      prisma.payment.aggregate({ _sum: { amount: true }, where: { createdAt: { gte: lastMonth }, ...EXCLUDE_DONATION_LEGS, ...paymentWhere } }),
    );
  }

@@ -98,9 +119,10 @@ async function computePaymentStats({ includeWeekMonth }) {
 // @access  Private/Staff+
 const getStaffDashboardStats = async (req, res) => {
  try {
+    const cf = await campusFilters('', await scopeFor(req));
    const [scanStats, recentScans] = await Promise.all([
-      computeScanStats(req.user.id),
-      getRecentScans(10),
+      computeScanStats(req.user.id, cf.usage),
+      getRecentScans(10, cf.usage),
    ]);
    res.json({ scanStats, recentScans });
  } catch (error) {
@@ -113,11 +135,12 @@ const getStaffDashboardStats = async (req, res) => {
 // @access  Private/Supervisor+
 const getSupervisorDashboardStats = async (req, res) => {
  try {
+    const cf = await campusFilters('', await scopeFor(req));
    const [scanStats, recentScans, paymentStats, activeEventsCount] = await Promise.all([
-      computeScanStats(req.user.id),
-      getRecentScans(10),
-      computePaymentStats({ includeWeekMonth: false }),
-      getActiveEventsCount(),
+      computeScanStats(req.user.id, cf.usage),
+      getRecentScans(10, cf.usage),
+      computePaymentStats({ includeWeekMonth: false, paymentWhere: cf.payment }),
+      getActiveEventsCount(cf.eventWhere),
    ]);
    res.json({ scanStats, recentScans, paymentStats, activeEventsCount });
  } catch (error) {
@@ -207,21 +230,22 @@ function classifyAndSum(payments) {
 // @desc    Registrations/tickets/revenue/donations for the trailing month (today back one
 //          month) vs the month before that, a daily revenue trend for the trailing month,
 //          and the top performing events overall.
-// @route   GET /api/stats/overview
+// @route   GET /api/stats/overview?campus=<id|slug|all>   (no campus = church-wide)
 // @access  Private/Supervisor+
 const getOverviewStats = async (req, res) => {
  try {
    const now = new Date();
    const { thisStart, thisEnd, lastStart, lastEnd } = trailingMonthRanges(now);
+    const cf = await campusFilters(req.query.campus, await scopeFor(req));

    const [thisPayments, lastPayments, thisRegistrations, lastRegistrations, thisTickets, lastTickets, activeEvents] = await Promise.all([
-      fetchPaymentsWithOriginal({ createdAt: { gte: thisStart, lt: thisEnd } }),
-      fetchPaymentsWithOriginal({ createdAt: { gte: lastStart, lt: lastEnd } }),
-      prisma.registration.count({ where: { createdAt: { gte: thisStart, lt: thisEnd }, status: { not: 'cancelled' } } }),
-      prisma.registration.count({ where: { createdAt: { gte: lastStart, lt: lastEnd }, status: { not: 'cancelled' } } }),
-      prisma.ticket.aggregate({ _sum: { quantity: true }, where: { createdAt: { gte: thisStart, lt: thisEnd } } }),
-      prisma.ticket.aggregate({ _sum: { quantity: true }, where: { createdAt: { gte: lastStart, lt: lastEnd } } }),
-      getActiveEventsCount(),
+      fetchPaymentsWithOriginal({ createdAt: { gte: thisStart, lt: thisEnd }, ...cf.payment }),
+      fetchPaymentsWithOriginal({ createdAt: { gte: lastStart, lt: lastEnd }, ...cf.payment }),
+      prisma.registration.count({ where: { createdAt: { gte: thisStart, lt: thisEnd }, status: { not: 'cancelled' }, ...cf.byEvent } }),
+      prisma.registration.count({ where: { createdAt: { gte: lastStart, lt: lastEnd }, status: { not: 'cancelled' }, ...cf.byEvent } }),
+      prisma.ticket.aggregate({ _sum: { quantity: true }, where: { createdAt: { gte: thisStart, lt: thisEnd }, ...cf.byEvent } }),
+      prisma.ticket.aggregate({ _sum: { quantity: true }, where: { createdAt: { gte: lastStart, lt: lastEnd }, ...cf.byEvent } }),
+      getActiveEventsCount(cf.eventWhere),
    ]);

    const thisTotals = classifyAndSum(thisPayments);
@@ -245,7 +269,7 @@ const getOverviewStats = async (req, res) => {
    // "real revenue" definition as the KPI above: everything except application legs.
    const revenueByEvent = await prisma.payment.groupBy({
      by: ['eventId'],
-      where: { ...EXCLUDE_DONATION_LEGS, eventId: { not: null } },
+      where: { ...EXCLUDE_DONATION_LEGS, eventId: { not: null }, ...cf.byEvent },
      _sum: { amount: true },
      orderBy: { _sum: { amount: 'desc' } },
      take: 5,
@@ -270,7 +294,7 @@ const getOverviewStats = async (req, res) => {
    // Funnel conversion (event page views → paid) across live events, last 30 days.
    let funnel = null;
    try {
-      const live = await prisma.event.findMany({ where: { isActive: true, endDate: { gte: now } }, select: { id: true } });
+      const live = await prisma.event.findMany({ where: { isActive: true, endDate: { gte: now }, ...cf.eventWhere }, select: { id: true } });
      if (live.length) {
        const { funnelFor } = require('../utils/analytics');
        const f = await funnelFor(live.map(e => e.id), { from: new Date(now.getTime() - 30 * 864e5).toISOString() });
@@ -296,6 +320,7 @@ const getOverviewStats = async (req, res) => {
 };

 module.exports = {
+  campusFilters,
  getStaffDashboardStats,
  getSupervisorDashboardStats,
  getAdminDashboardStats,
@@ -50,6 +50,8 @@ const getTickets = async (req, res) => {
    const page  = Math.max(1, parseInt(req.query.page)  || 1);
    const limit = Math.min(200, Math.max(1, parseInt(req.query.limit) || 100));
    const skip  = (page - 1) * limit;
+    // Campus-scoped supervisors: tickets for events they can see.
+    const scopeW = await require('../utils/campusScope').listWhere(req, 'event');

    const include = {
      registrationOption: {
@@ -66,8 +68,8 @@ const getTickets = async (req, res) => {
    };

    const [tickets, total] = await prisma.$transaction([
-      prisma.ticket.findMany({ include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
-      prisma.ticket.count()
+      prisma.ticket.findMany({ where: scopeW, include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
+      prisma.ticket.count({ where: scopeW })
    ]);

    res.json({ data: tickets, total, page, limit, pages: Math.ceil(total / limit) });
@@ -103,7 +105,7 @@ const getUserTickets = async (req, res) => {
          },
        },
        user: { select: { id: true, name: true } },
-        event: { include: { sessions: { where: { cancelledAt: null }, orderBy: { startsAt: 'asc' } } } },
+        event: { include: { sessions: { where: { cancelledAt: null }, orderBy: { startsAt: 'asc' } }, campus: { select: { name: true, slug: true } } } },
        transferRequests: { where: { status: 'pending' }, select: { id: true, toName: true, expiresAt: true } },
        usages: {
          include: {
@@ -264,6 +266,7 @@ const getScanPreview = async (req, res) => {
        t."eventId",
        ro.id                AS "registrationOptionId",
        ro."sessionId"       AS "pinnedSessionId",
+        ro."sessionIds"      AS "chosenSessionIds",
        eo.id                AS "eventOptionId",
        eo.name              AS "eventOptionName",
        ov.id                AS "variantId",
@@ -316,7 +319,7 @@ const getScanPreview = async (req, res) => {
    if (r.scheduleType === 'sessions') {
      const sessionsUtil = require('../utils/sessions');
      const schedule = await sessionsUtil.eventSchedule(r.eventId);
-      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, req.query.sessionId || null);
+      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, req.query.sessionId || null, new Date(), r.chosenSessionIds);
      sessionError = found.error;
      if (found.session) {
        session = { id: found.session.id, label: sessionsUtil.sessionLabel(found.session, schedule.sessions) };
@@ -364,6 +367,7 @@ const scanTicket = async (req, res) => {
        e.title              AS "eventTitle",
        e."scheduleType"     AS "scheduleType",
        ro."sessionId"       AS "pinnedSessionId",
+        ro."sessionIds"      AS "chosenSessionIds",
        eo.id                AS "eventOptionId",
        eo.name              AS "eventOptionName",
        eo."isMainTicket"    AS "isMainTicket",
@@ -441,7 +445,7 @@ const scanTicket = async (req, res) => {
    if (r.scheduleType === 'sessions') {
      sessionsUtil = require('../utils/sessions');
      schedule = await sessionsUtil.eventSchedule(ticket.eventId);
-      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, String(req.body?.sessionId || req.query?.sessionId || '').trim() || null);
+      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, String(req.body?.sessionId || req.query?.sessionId || '').trim() || null, new Date(), r.chosenSessionIds);
      if (!found.session) return res.status(400).json({ message: found.error, code: 'NO_SESSION', ticket });
      session = found.session;
    }
@@ -630,9 +634,11 @@ const getRecentScans = async (req, res) => {
  try {
    const limit = Math.max(1, Math.min(parseInt(req.query.limit) || 10, 100));
    const eventId = req.query.eventId || undefined;
+    // Campus-scoped staff: scans of tickets for events they can see.
+    const scopeEv = (await require('../utils/campusScope').listWhere(req, 'event')).event;

    const scans = await prisma.ticketUsage.findMany({
-      where: eventId ? { ticket: { eventId } } : undefined,
+      where: eventId || scopeEv ? { ticket: { ...(eventId ? { eventId } : {}), ...(scopeEv ? { event: scopeEv } : {}) } } : undefined,
      orderBy: { scannedAt: 'desc' },
      take: limit,
      select: {
@@ -664,11 +670,14 @@ const getScanStats = async (req, res) => {
    const eventId = req.query.eventId || undefined;
    const startOfDay = new Date();
    startOfDay.setHours(0, 0, 0, 0);
+    // Campus-scoped staff: scans of tickets for events they can see.
+    const scopeEv = (await require('../utils/campusScope').listWhere(req, 'event')).event;
+    const ticketWhere = eventId || scopeEv ? { ticket: { ...(eventId ? { eventId } : {}), ...(scopeEv ? { event: scopeEv } : {}) } } : {};

    // Total scans today (optionally by event)
    const whereBase = {
      scannedAt: { gte: startOfDay },
-      ...(eventId ? { ticket: { eventId } } : {})
+      ...ticketWhere
    };

    const [totalToday, myToday, lastHour] = await Promise.all([
@@ -676,7 +685,7 @@ const getScanStats = async (req, res) => {
      prisma.ticketUsage.count({ where: { ...whereBase, scannedById: req.user.id } }),
      prisma.ticketUsage.count({
        where: {
-          ...(eventId ? { ticket: { eventId } } : {}),
+          ...ticketWhere,
          scannedAt: { gte: new Date(Date.now() - 60 * 60 * 1000) }
        }
      })
@@ -917,7 +926,7 @@ function drawTicketCard(doc, { x, y, w, h }, ticket, qrDataUrl, buyerName) {
  // Event title, with the date on the right of the same line
  let cy = y + pad;
  const eventDate = ticket.event.startDate ? new Date(ticket.event.startDate) : null;
-  const dateStr = require('../utils/sessions').ticketDateText(ticket.event, 'short', ticket.registrationOption.session)
+  const dateStr = require('../utils/sessions').ticketDateText(ticket.event, 'short', ticket.registrationOption.session, null, ticket.registrationOption.sessionIds)
    || (eventDate ? new Intl.DateTimeFormat('en-GB', { day: '2-digit', month: 'long', year: 'numeric' }).format(eventDate) : '');
  doc.font('Helvetica').fontSize(9);
  const dateW = dateStr ? doc.widthOfString(dateStr) : 0;
@@ -927,6 +936,12 @@ function drawTicketCard(doc, { x, y, w, h }, ticket, qrDataUrl, buyerName) {
  doc.text(ticket.event.title, x + pad, cy, { width: titleW });
  cy += doc.heightOfString(ticket.event.title, { width: titleW }) + 4;

+  // Campus (only included while campuses are on)
+  if (ticket.event.campus?.name) {
+    doc.font('Helvetica').fontSize(9).fillColor(gray500).text(ticket.event.campus.name, x + pad, cy, { width: innerW });
+    cy += doc.heightOfString(ticket.event.campus.name, { width: innerW }) + 2;
+  }
+
  // Ticket type
  const variantSuffix = ticket.registrationOption.variant ? ` — ${ticket.registrationOption.variant.name}` : '';
  const type = `${ticket.registrationOption.eventOption.name}${variantSuffix}`;
@@ -981,8 +996,9 @@ async function emailTicketsInternal(req, res, userOverride) {
    return res.json({ message: 'No valid contact details on file — ticket delivery skipped.' });
  }

+  const showCampus = await require('../utils/campuses').campusesEnabled();
  const ticketInclude = {
-    event: { include: { sessions: { where: { cancelledAt: null }, orderBy: { startsAt: 'asc' } } } },
+    event: { include: { sessions: { where: { cancelledAt: null }, orderBy: { startsAt: 'asc' } }, ...(showCampus ? { campus: { select: { name: true } } } : {}) } },
    registrationOption: { include: { eventOption: true, variant: true, session: true, registration: { select: { ticketDelivery: true } } } },
    attendee: { include: { allocations: { where: { set: { showOnTicket: true } }, include: { group: { select: { name: true } }, set: { select: { name: true, order: true } } } } } },
    user: { select: { name: true } },
@@ -1092,7 +1108,10 @@ async function emailTicketsInternal(req, res, userOverride) {

  const eventTitle = tickets[0].event.title;
  const pinnedSessions = tickets.map(t => t.registrationOption?.session).filter(Boolean);
-  const eventDate = require('../utils/sessions').ticketDateText(tickets[0].event, 'long', pinnedSessions.length === tickets.length && pinnedSessions.length === 1 ? pinnedSessions[0] : null, pinnedSessions.length === tickets.length ? pinnedSessions : null) || (tickets[0].event.startDate
+  // All-sessions tickets with the same sessions ticked: those sessions.
+  const chosenKeys = new Set(tickets.map(t => (t.registrationOption?.sessionIds || []).join(',')));
+  const chosenIds = chosenKeys.size === 1 && !pinnedSessions.length ? tickets[0].registrationOption?.sessionIds : null;
+  const eventDate = require('../utils/sessions').ticketDateText(tickets[0].event, 'long', pinnedSessions.length === tickets.length && pinnedSessions.length === 1 ? pinnedSessions[0] : null, pinnedSessions.length === tickets.length ? pinnedSessions : null, chosenIds) || (tickets[0].event.startDate
    ? new Date(tickets[0].event.startDate).toLocaleDateString('en-GB', { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' })
    : '');
  const pdfFilename = `tickets-${eventTitle.replace(/[^a-z0-9]/gi, '_').toLowerCase()}.pdf`;
@@ -139,7 +139,8 @@ async function sendWelcomeEmail(user) {
 // Fields the login flow needs once the password (and any 2FA code) has checked out.
 const LOGIN_USER_SELECT = {
  id: true, name: true, email: true, role: true, tokenVersion: true, isActive: true,
-  phoneNumber: true, notificationPreference: true, twoFactorEnabled: true, twoFactorMethod: true,
+  phoneNumber: true, notificationPreference: true, twoFactorEnabled: true, twoFactorMethod: true, newsAskedAt: true,
+  noticeVersionAccepted: true,
 };

 // Errors from utils/twoFactor carry their own HTTP status; everything else follows
@@ -150,7 +151,11 @@ function errorStatus(error, res) {

 // Final step of a successful login (after the password, and the 2FA code when
 // required): notify, record the activity, and issue the session token.
-function completeLogin(user, req, res, extra = {}) {
+async function completeLogin(user, req, res, extra = {}) {
+  const noticePromptPending = await require('../utils/privacyNotice').noticePromptPending(user).catch(() => false);
+  // Retention: logging in keeps the account (and cancels an inactivity warning).
+  prisma.user.update({ where: { id: user.id }, data: { lastLoginAt: new Date(), inactivityWarnedAt: null } }).catch(() => {});
+
  // Send login notification in the background
  sendLoginNotification(user, req).catch(() => {});
  logSecurityEvent({ userId: user.id, type: 'login', ip: getClientIp(req), userAgent: req.headers['user-agent'] }).catch(() => {});
@@ -161,6 +166,10 @@ function completeLogin(user, req, res, extra = {}) {
    email: user.email,
    role: user.role,
    token: generateToken(user.id, user.role, user.tokenVersion),
+    // POPIA: ask about News & announcements once (see NewsPrompt on the frontend), and to
+    // accept a privacy notice version marked as a significant change (NoticePrompt).
+    newsPromptPending: !user.newsAskedAt,
+    noticePromptPending,
    ...extra
  });
 }
@@ -170,7 +179,7 @@ function completeLogin(user, req, res, extra = {}) {
 // @access  Public
 const registerUser = async (req, res) => {
  try {
-    const { name, email, password, phoneNumber, notificationPreference } = req.body;
+    const { name, email, password, phoneNumber, notificationPreference, newsOptIn } = req.body;

    // Normalize phone using SA-aware normalisation
    const { normalizeZAPhone, isValidZAPhone } = require('../utils/whatsapp');
@@ -215,6 +224,18 @@ const registerUser = async (req, res) => {
    });

    if (user) {
+      // POPIA: the sign-up form's (unticked) "news and announcements" box. Recorded either
+      // way, so they aren't asked again at their first login.
+      await require('../utils/privacy').setNewsPreferences(
+        user.id,
+        { email: newsOptIn === true, whatsapp: newsOptIn === true },
+        { source: 'signup', ip: getClientIp(req), answered: true, logAll: true },
+      ).catch(e => console.warn('[signup] news preference not saved:', e?.message || e));
+      // The sign-up form requires ticking "I agree to the Terms of Use and Privacy Policy".
+      await require('../utils/privacyNotice').acceptNotice(user.id, { source: 'signup', ip: getClientIp(req) })
+        .catch(e => console.warn('[signup] notice acceptance not saved:', e?.message || e));
+
+
      // Send welcome email in the background — don't block the response
      sendWelcomeEmail(user).catch(() => {});

@@ -340,7 +361,7 @@ const loginUser = async (req, res) => {
      }
    }

-    completeLogin(updated, req, res);
+    await completeLogin(updated, req, res);
  } catch (error) {
    res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
  }
@@ -375,7 +396,7 @@ const verifyLoginTwoFactor = async (req, res) => {
    if (rememberDevice === true) {
      extra.deviceToken = await issueTrustedDevice(user.id, req.headers['user-agent']);
    }
-    completeLogin(user, req, res, extra);
+    await completeLogin(user, req, res, extra);
  } catch (error) {
    res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
  }
@@ -515,12 +536,21 @@ const getUserProfile = async (req, res) => {
        twoFactorMethod: true,
        createdAt: true,
        updatedAt: true,
-        isActive: true
+        isActive: true,
+        homeCampusId: true,
+        newsAskedAt: true,
+        noticeVersionAccepted: true
      }
    });

    if (user) {
-      res.json({ ...user, twoFactorRequired: requiresTwoFactor(user) });
+      const { newsAskedAt, noticeVersionAccepted, ...rest } = user;
+      // newsPromptPending: they haven't answered the news opt-in question yet (asked once).
+      // noticePromptPending: a privacy notice version they must accept has been published.
+      const noticePromptPending = !req.impersonation && await require('../utils/privacyNotice').noticePromptPending({ noticeVersionAccepted });
+      // Campus-scoped staff: the campuses they're limited to (null = every campus).
+      const campusScope = (await require('../utils/campusScope').scopeFor(req))?.campusIds || null;
+      res.json({ ...rest, twoFactorRequired: requiresTwoFactor(user), newsPromptPending: !newsAskedAt && !req.impersonation, noticePromptPending, campusScope });
    } else {
      res.status(404);
      throw new Error('User not found');
@@ -544,7 +574,18 @@ const updateUserProfile = async (req, res) => {
      throw new Error('User not found');
    }

-    const { name, email, password, phoneNumber, currentPassword, notificationPreference } = req.body || {};
+    const { name, email, password, phoneNumber, currentPassword, notificationPreference, homeCampusId } = req.body || {};
+
+    // Home campus (only while campuses are on): an active campus, or ''/null for none.
+    let newHomeCampusId = user.homeCampusId;
+    if (homeCampusId !== undefined && await require('../utils/campuses').campusesEnabled()) {
+      if (!homeCampusId) newHomeCampusId = null;
+      else {
+        const campus = await prisma.campus.findFirst({ where: { id: String(homeCampusId), archivedAt: null }, select: { id: true } });
+        if (!campus) { res.status(400); throw new Error('Choose one of the campuses in the list.'); }
+        newHomeCampusId = campus.id;
+      }
+    }

    // If a password change is requested, verify current password for safety
    let newHashedPassword = undefined;
@@ -592,6 +633,7 @@ const updateUserProfile = async (req, res) => {
        phoneNumber: newPhone,
        notificationPreference: newPref,
        twoFactorMethod: newTwoFactorMethod,
+        homeCampusId: newHomeCampusId,
        updatedAt: new Date()
      },
      select: {
@@ -606,6 +648,7 @@ const updateUserProfile = async (req, res) => {
        createdAt: true,
        updatedAt: true,
        isActive: true,
+        homeCampusId: true,
        tokenVersion: true
      }
    });
@@ -742,7 +785,8 @@ const getUserById = async (req, res) => {
        phoneNumber: true,
        createdAt: true,
        updatedAt: true,
-        isActive: true
+        isActive: true,
+        scopedCampuses: { select: { id: true, name: true } }
      }
    });

@@ -771,7 +815,7 @@ const updateUser = async (req, res) => {
      throw new Error('User not found');
    }

-    const { name, email, role, isActive, phoneNumber, password, notificationPreference, twoFactorEnabled } = req.body;
+    const { name, email, role, isActive, phoneNumber, password, notificationPreference, twoFactorEnabled, scopedCampusIds } = req.body;

    const newPhone = phoneNumber !== undefined ? (phoneNumber || null) : user.phoneNumber;
    const { resolveNotificationPreference } = require('../utils/notificationPreference');
@@ -807,6 +851,21 @@ const updateUser = async (req, res) => {
      data.tokenVersion = { increment: 1 };
    }

+    // Campus-scoped staff (utils/campusScope.js): "Limit to campuses" for supervisors and staff.
+    // Admins and users are never limited, so a role change away from staff clears the limit.
+    const before = await prisma.user.findUnique({ where: { id: user.id }, select: { scopedCampuses: { select: { id: true } } } });
+    const beforeIds = before.scopedCampuses.map(c => c.id).sort();
+    let afterIds = beforeIds;
+    if (!['supervisor', 'staff'].includes(data.role)) afterIds = [];
+    else if (Array.isArray(scopedCampusIds)) {
+      const wanted = [...new Set(scopedCampusIds.filter(x => typeof x === 'string' && x))];
+      const found = await prisma.campus.findMany({ where: { id: { in: wanted } }, select: { id: true } });
+      if (found.length !== wanted.length) { res.status(400); throw new Error('One of those campuses doesn\'t exist.'); }
+      afterIds = wanted.sort();
+    }
+    const scopeChanged = afterIds.join(',') !== beforeIds.join(',');
+    if (scopeChanged) data.scopedCampuses = { set: afterIds.map(id => ({ id })) };
+
    const updatedUser = await prisma.user.update({
      where: { id: req.params.id },
      data,
@@ -820,9 +879,13 @@ const updateUser = async (req, res) => {
        twoFactorEnabled: true,
        createdAt: true,
        updatedAt: true,
-        isActive: true
+        isActive: true,
+        scopedCampuses: { select: { id: true, name: true } }
      }
    });
+    if (scopeChanged) {
+      require('../utils/adminAudit').logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'user_campus_scope_changed', targetType: 'User', targetId: updatedUser.id, metadata: { from: beforeIds, to: afterIds }, ip: getClientIp(req) });
+    }

    if (resetTwoFactor || data.password) {
      await clearTrustedDevices(updatedUser.id);
@@ -874,21 +937,22 @@ const anonymizeUser = async (req, res) => {
    const user = await prisma.user.findUnique({ where: { id: req.params.id } });
    if (!user) { res.status(404); throw new Error('User not found'); }

-    await prisma.user.update({
-      where: { id: req.params.id },
-      data: {
-        name: 'Deleted User',
-        email: `deleted-${req.params.id}@deleted.local`,
-        phoneNumber: null,
-        isActive: false,
-        twoFactorEnabled: false,
-        twoFactorMethod: null,
-        tokenVersion: { increment: 1 },
-        updatedAt: new Date()
-      }
+    const { deletionBlockers, anonymiseUser } = require('../utils/privacy');
+    const blockers = await deletionBlockers(user.id);
+    if (blockers.length) {
+      res.status(409);
+      throw new Error(`Cancel (and refund where needed) these registrations first: ${blockers.map(b => b.eventTitle).join(', ')}.`);
+    }
+    const counts = await anonymiseUser(user.id);
+    // An open deletion request from this person is now done.
+    await prisma.dataRequest.updateMany({
+      where: { userId: user.id, type: 'deletion', status: 'open' },
+      data: { status: 'completed', closedAt: new Date(), handledById: req.user.id },
+    });
+    require('../utils/adminAudit').logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'user_anonymised', targetType: 'user', targetId: user.id,
+      metadata: counts, ip: getClientIp(req),
    });
-    await clearTrustedDevices(req.params.id);
-    await require('../utils/consent').clearConsentDataForUser(req.params.id);

    res.json({ message: 'User data deleted' });
  } catch (error) {
@@ -1134,34 +1198,11 @@ const closeAccount = async (req, res) => {
    const realName  = user.name;

    if (deleteData) {
-      // Anonymise: wipe all personal data while keeping the row intact for referential integrity
-      await prisma.user.update({
-        where: { id: req.user.id },
-        data: {
-          name: 'Deleted User',
-          email: `deleted-${uuidv4()}@deleted.invalid`,
-          password: '',
-          phoneNumber: null,
-          isActive: false,
-          twoFactorEnabled: false,
-          twoFactorMethod: null,
-          tokenVersion: { increment: 1 },
-          updatedAt: new Date(),
-        },
-      });
-      await clearTrustedDevices(req.user.id);
-      await require('../utils/consent').clearConsentDataForUser(req.user.id);
-      // Send closure confirmation to the real address (before it was wiped)
-      if (realEmail && !realEmail.endsWith('@deleted.invalid') && !realEmail.endsWith('@guest.local')) {
-        const { sendMail, buildAccountClosedEmail } = require('../utils/email');
-        const { waText } = require('../utils/notify');
-        const { buildWAAccountClosed } = require('../utils/waMessages');
-        const content = buildAccountClosedEmail({ name: realName, dataDeleted: true });
-        sendMail({ to: realEmail, subject: `Your ${getOrgName()} account has been closed`, ...content }).catch(() => {});
-        // WhatsApp while we still have phone (send before data wipe completes in-flight)
-        waText(user, buildWAAccountClosed({ name: realName, dataDeleted: true })).catch(() => {});
-      }
-      return res.json({ message: 'Your account and personal data have been removed.' });
+      // POPIA: deleting personal data is a request an admin approves (see privacyController);
+      // the account is closed straight away.
+      const open = await prisma.dataRequest.findFirst({ where: { userId: user.id, type: 'deletion', status: 'open' } });
+      if (!open) await require('./privacyController').requestAccountDeletion(user);
+      return res.json({ message: 'Your account is closed. Your personal information will be deleted once your request has been processed — we will email you.' });
    } else {
      // Soft-deactivate only
      await prisma.user.update({
@@ -2,8 +2,8 @@ const prisma = require('../config/db');
 const { v4: uuidv4 } = require('uuid');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { findAccountByContact } = require('../utils/accountMatch');
-const { remainingFor } = require('../utils/stock');
-const { ACTIVE, makeOffer, queueWaitlist, findOfferByToken } = require('../utils/waitlist');
+const { ACTIVE, makeOffer, queueWaitlist, findOfferByToken, placesFree, lineName } = require('../utils/waitlist');
+const { activeSessions, isPickOption, sessionLabel } = require('../utils/sessions');

 const fail = (res, error) => res.status(error.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: safeErrorMessage(error) });

@@ -11,19 +11,21 @@ const ENTRY_INCLUDE = {
  event: { select: { id: true, title: true, startDate: true, picture: true } },
  eventOption: { select: { id: true, name: true } },
  variant: { select: { id: true, name: true } },
+  session: { select: { id: true, label: true, startsAt: true, endsAt: true } },
 };

 // @desc    Join the waitlist for a sold-out option
 // @route   POST /api/waitlist
 // @access  Public (login needed when the event requires it)
-// Body: { eventId, eventOptionId, variantId?, quantity, guestName?, guestEmail?, guestPhone? }
+// Body: { eventId, eventOptionId, variantId?, sessionId?, quantity, guestName?, guestEmail?, guestPhone? }
+// sessionId: required for a "pick sessions" option (one session per entry), not allowed otherwise.
 const joinWaitlist = async (req, res) => {
  try {
-    const { eventId, eventOptionId, variantId = null, quantity, guestName, guestEmail, guestPhone } = req.body || {};
+    const { eventId, eventOptionId, variantId = null, sessionId = null, quantity, guestName, guestEmail, guestPhone } = req.body || {};
    const qty = parseInt(quantity, 10);
    if (!eventId || !eventOptionId || !(qty >= 1)) { res.status(400); throw new Error('eventId, eventOptionId and a quantity of at least 1 are required'); }

-    const event = await prisma.event.findUnique({ where: { id: eventId }, include: { eventOptions: { include: { variants: true } } } });
+    const event = await prisma.event.findUnique({ where: { id: eventId }, include: { eventOptions: { include: { variants: true } }, sessions: true } });
    if (!event || !event.isActive) { res.status(404); throw new Error('Event not found'); }
    if (!event.waitlistEnabled) { res.status(400); throw new Error('This event does not have a waitlist.'); }
    if (event.cashupStatus === 'closed' || new Date(event.endDate) < new Date()) { res.status(400); throw new Error('This event is no longer taking registrations.'); }
@@ -32,7 +34,16 @@ const joinWaitlist = async (req, res) => {
    const variant = variantId ? (option.variants || []).find(v => v.id === variantId) : null;
    if (variantId && !variant) { res.status(400); throw new Error('Unknown variant for this option'); }

-    const free = await remainingFor(option, variant);
+    if (isPickOption(event, option)) {
+      if (!sessionId) { res.status(400); throw new Error(`Choose which session of "${option.name}" you want to wait for.`); }
+      const session = activeSessions(event.sessions).find(s => s.id === sessionId);
+      if (!session) { res.status(400); throw new Error('That session isn\'t available.'); }
+      if (new Date(session.startsAt) <= new Date()) { res.status(400); throw new Error(`${sessionLabel(session, event.sessions)} has already started.`); }
+    } else if (sessionId) {
+      res.status(400); throw new Error(`"${option.name}" covers every session — no session to choose.`);
+    }
+
+    const free = await placesFree(event, option, variant, sessionId);
    if (free === null || free >= qty) { res.status(400); throw new Error('There are places available — you can register now.'); }

    // Who's joining
@@ -47,15 +58,15 @@ const joinWaitlist = async (req, res) => {
      })).id;
    }

-    const existing = await prisma.waitlistEntry.findFirst({ where: { userId, eventOptionId, variantId, status: { in: ACTIVE } } });
+    const existing = await prisma.waitlistEntry.findFirst({ where: { userId, eventOptionId, variantId, sessionId, status: { in: ACTIVE } } });
    if (existing) { res.status(409); throw new Error('You\'re already on the waitlist for this.'); }

    const last = await prisma.waitlistEntry.aggregate({ where: { eventId }, _max: { position: true } });
    const entry = await prisma.waitlistEntry.create({
-      data: { eventId, eventOptionId, variantId, userId, quantity: qty, position: (last._max.position || 0) + 1 },
+      data: { eventId, eventOptionId, variantId, sessionId, userId, quantity: qty, position: (last._max.position || 0) + 1 },
      include: ENTRY_INCLUDE,
    });
-    const ahead = await prisma.waitlistEntry.count({ where: { eventId, eventOptionId, variantId, status: 'waiting', position: { lt: entry.position } } });
+    const ahead = await prisma.waitlistEntry.count({ where: { eventId, eventOptionId, variantId, sessionId, status: 'waiting', position: { lt: entry.position } } });
    res.status(201).json({ ...entry, ahead, message: `You're on the waitlist${ahead ? ` — ${ahead} ahead of you` : ''}. We'll email or WhatsApp you if a place opens up.` });
  } catch (error) {
    fail(res, error);
@@ -106,11 +117,15 @@ const claimInfo = async (req, res) => {
      status: expired ? 'expired' : 'offered',
      eventId: entry.eventId,
      eventTitle: entry.event.title,
-      eventStart: entry.event.startDate,
+      eventStart: entry.session?.startsAt || entry.event.startDate,
      eventOptionId: entry.eventOptionId,
      optionName: entry.eventOption.name,
      variantId: entry.variantId,
      variantName: entry.variant?.name || null,
+      sessionId: entry.sessionId,
+      sessionName: entry.session ? sessionLabel(entry.session, entry.event.sessions) : null,
+      sessionStart: entry.session?.startsAt || null,
+      lineName: lineName(entry),
      quantity: entry.offeredQuantity,
      requested: entry.quantity,
      expiresAt: entry.offerExpiresAt,
@@ -142,8 +157,11 @@ const eventWaitlist = async (req, res) => {
 // @access  Private/Supervisor
 const offerManually = async (req, res) => {
  try {
-    const entry = await prisma.waitlistEntry.findUnique({ where: { id: req.params.id } });
+    const entry = await prisma.waitlistEntry.findUnique({ where: { id: req.params.id }, include: { session: true } });
    if (!entry) { res.status(404); throw new Error('Waitlist entry not found'); }
+    if (entry.session && (entry.session.cancelledAt || new Date(entry.session.startsAt) <= new Date())) {
+      res.status(400); throw new Error(`The session they're waiting for has ${entry.session.cancelledAt ? 'been cancelled' : 'already started'}.`);
+    }
    if (!['waiting', 'expired'].includes(entry.status)) { res.status(400); throw new Error(`This person is ${entry.status === 'offered' ? 'already holding an offer' : `no longer waiting (${entry.status})`}.`); }
    const qty = Math.max(1, Math.min(entry.quantity, parseInt(req.body?.quantity, 10) || entry.quantity));
    const updated = await makeOffer(entry.id, qty);
@@ -1,552 +1,9 @@
-const crypto = require('crypto');
-const prisma = require('../config/db');
-const { v4: uuidv4 } = require('uuid');
-const { generateTicketsForRegistration } = require('../utils/ticketUtils');
-const { emailTickets } = require('./ticketController');
-const { computeRegistrationTotalDue, refreshPricingForRegistration } = require('../utils/pricing');
-const { getYocoWebhookSecret } = require('../utils/yoco');
+const { handleProviderWebhook } = require('../payments/webhook');

-// @desc    Handle Yoco webhook events
+// @desc    Handle Yoco webhook events (signature check and processing: src/payments)
 // @route   POST /api/webhooks/yoco
 // @access  Public
-const handleYocoWebhook = async (req, res) => {
-  try {
-    const headers = req.headers;
-    const requestBody = req.rawBody;
-
-    // Log every JSON request body for webhook controller
-    try {
-      const contentType = headers['content-type'] || headers['Content-Type'] || '';
-      let parsedBody = null;
-      if (typeof requestBody === 'string') {
-        try {
-          parsedBody = JSON.parse(requestBody);
-        } catch (e) {
-          // Not valid JSON; keep as raw string
-        }
-      } else if (requestBody && typeof requestBody === 'object') {
-        parsedBody = requestBody;
-      }
-    } catch (logErr) {
-      // Fail-safe: never block webhook processing due to logging issues
-      console.error('Failed to log webhook JSON request:', logErr);
-    }
-
-    // Verify webhook signature
-    const id = headers['webhook-id'];
-    const timestamp = headers['webhook-timestamp'];
-
-    const rawSigHeader = headers['webhook-signature'];
-    if (!id || !timestamp || !rawSigHeader) {
-      const responseObj = {
-        success: false,
-        message: 'Missing webhook headers',
-        details: { missingHeaders: ['webhook-id', 'webhook-timestamp', 'webhook-signature'].filter(h => !headers[h]) }
-      };
-      return res.status(400).json(responseObj);
-    }
-
-    // Reject replayed requests (Yoco recommends a 3-minute tolerance window)
-    const webhookTimeMs = parseInt(timestamp, 10) * 1000;
-    if (isNaN(webhookTimeMs) || Math.abs(Date.now() - webhookTimeMs) > 3 * 60 * 1000) {
-      return res.status(400).json({ success: false, message: 'Webhook timestamp outside acceptable window' });
-    }
-
-    // Construct the signed content
-    const signedContent = `${id}.${timestamp}.${requestBody}`;
-
-    // Webhook secret from Site Settings → Yoco (falls back to .env)
-    const secret = await getYocoWebhookSecret();
-    if (!secret) {
-      console.error('Yoco webhook secret is not configured (Site Settings → Yoco, or YOCO_WEBHOOK_SECRET)');
-      const responseObj = { 
-        success: false, 
-        message: 'Server configuration error',
-        details: { error: 'Missing webhook secret configuration' }
-      };
-      return res.status(500).json(responseObj);
-    }
-
-    const secretBytes = Buffer.from(secret.split('_')[1], "base64");
-
-    // Calculate expected signature
-    const expectedSignature = crypto
-      .createHmac('sha256', secretBytes)
-      .update(signedContent)
-      .digest('base64');
-
-    // Accept if any of the space-separated signatures match (supports key rotation)
-    const signatures = rawSigHeader.split(' ').map(s => s.split(',')[1]).filter(Boolean);
-    const signatureValid = signatures.some(sig => {
-      try {
-        return crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(sig));
-      } catch {
-        return false;
-      }
-    });
-
-    if (!signatureValid) {
-      console.error('Invalid webhook signature');
-      const responseObj = {
-        success: false,
-        message: 'Invalid signature',
-        details: { error: 'Webhook signature verification failed' }
-      };
-      return res.status(403).json(responseObj);
-    }
-
-    // Parse the webhook payload
-    const webhookData = JSON.parse(requestBody);
-
-    // Extract checkoutId from payload or metadata
-    const receivedCheckoutId = webhookData?.payload?.checkoutId || webhookData?.payload?.metadata?.checkoutId || webhookData?.payload?.metadata?.checkout_id;
-
-    // Optional filtering: allow only specific checkoutIds or prefixes for this endpoint
-    try {
-      const idsEnv = process.env.YOCO_ALLOWED_CHECKOUT_IDS || process.env.YOCO_WEBHOOK_ALLOWED_CHECKOUT_IDS || '';
-      const prefixesEnv = process.env.YOCO_ALLOWED_CHECKOUT_PREFIXES || process.env.YOCO_WEBHOOK_ALLOWED_CHECKOUT_PREFIXES || '';
-      const allowedIds = idsEnv.split(',').map(s => s.trim()).filter(Boolean);
-      const allowedPrefixes = prefixesEnv.split(',').map(s => s.trim()).filter(Boolean);
-
-      const hasFilter = allowedIds.length > 0 || allowedPrefixes.length > 0;
-      if (hasFilter) {
-        const idMatches = receivedCheckoutId && (
-          allowedIds.includes(receivedCheckoutId) ||
-          allowedPrefixes.some(pref => receivedCheckoutId.startsWith(pref))
-        );
-        if (!idMatches) {
-          // Store event for audit/unreconciled tracking
-          try { await saveYocoTransaction(webhookData); } catch(e) { console.warn('Failed to store filtered yoco event:', e?.message || e); }
-          // Acknowledge but ignore processing for unrelated checkout flows
-          const responseObj = {
-            success: true,
-            message: 'Webhook acknowledged but ignored due to unmatched checkoutId for this endpoint',
-            data: {
-              filtered: true,
-              receivedCheckoutId,
-              allowedIdsCount: allowedIds.length,
-              allowedPrefixesCount: allowedPrefixes.length
-            }
-          };
-          return res.status(200).json(responseObj);
-        }
-      }
-    } catch (filterErr) {
-      // Never block webhook due to filter parsing errors; log only
-      console.warn('Webhook checkoutId filter parse warning:', filterErr?.message || filterErr);
-    }
-
-    // Automatic filtering by database registration record, with donation allowance
-    try {
-      if (receivedCheckoutId) {
-        const existingRegistration = await prisma.registration.findFirst({
-          where: { checkoutId: receivedCheckoutId },
-          select: { id: true }
-        });
-        if (!existingRegistration) {
-          // Allow donations (no registration) to proceed based on metadata
-          const meta = webhookData?.payload?.metadata || {};
-          const isDonation = meta?.type === 'donation' || !!meta?.isDonation || !!meta?.eventId;
-          if (!isDonation) {
-            try {
-              await saveYocoTransaction(webhookData);
-            } catch (saveErr) {
-              console.warn('Failed to save unreconciled transaction:', saveErr?.message || saveErr);
-            }
-            const responseObj = {
-              success: true,
-              message: 'Webhook acknowledged and stored as unreconciled: no registration found for checkoutId',
-              data: {
-                filtered: true,
-                reason: 'no_registration_for_checkoutId',
-                receivedCheckoutId
-              }
-            };
-            return res.status(200).json(responseObj);
-          }
-        }
-      }
-    } catch (dbFilterErr) {
-      // Do not fail webhook due to DB filter issues
-      console.warn('Webhook DB auto-filter warning:', dbFilterErr?.message || dbFilterErr);
-    }
-
-    let processedData = null;
-    
-    // Process different event types
-    switch (webhookData.type) {
-      case 'payment.succeeded':
-        processedData = await handlePaymentSucceeded(webhookData);
-        break;
-      // Add more event types as needed
-      default:
-        console.log(`Unhandled webhook event type: ${webhookData.type}`);
-        try { await saveYocoTransaction(webhookData); } catch(e) { console.warn('Failed to store unhandled yoco event:', e?.message || e); }
-        const responseObj = { 
-          success: true, 
-          message: 'Webhook received but event type not handled',
-          data: {
-            eventType: webhookData.type,
-            webhookId: id,
-            timestamp: timestamp
-          }
-        };
-        return res.status(200).json(responseObj);
-    }
-
-    // Return detailed success response
-    const responseObj = { 
-      success: true, 
-      message: `Successfully processed ${webhookData.type} webhook`,
-      data: {
-        eventType: webhookData.type,
-        webhookId: id,
-        timestamp: timestamp,
-        processedData
-      }
-    };
-    return res.status(200).json(responseObj);
-  } catch (error) {
-    console.error('Webhook error:', error);
-    const responseObj = {
-      success: false,
-      message: error.message,
-      details: {
-        error: error.stack,
-        timestamp: new Date().toISOString()
-      }
-    };
-    return res.status(500).json(responseObj);
-  }
-};
-
-// Handle payment.succeeded event
-const handlePaymentSucceeded = async (webhookData) => {
-  try {
-    const paymentData = webhookData.payload;
-    
-    // Log the payment data
-    console.log('Payment succeeded:', paymentData);
-    
-    // Extract payment details
-    const {
-      id: yocoPaymentId,
-      amount,
-      currency,
-      status,
-      metadata,
-      paymentMethodDetails: method,
-      checkoutId
-    } = paymentData;
-    
-    // Check if payment already exists to avoid duplicates
-    const existingPayment = await prisma.payment.findFirst({
-      where: {
-        externalId: yocoPaymentId
-      }
-    });
-    
-    if (existingPayment) {
-      console.log(`Payment ${yocoPaymentId} already processed`);
-      try { await saveYocoTransaction(webhookData, { reconciled: true, paymentId: existingPayment.id }); } catch(e) { console.warn('Failed to reconcile YocoTransaction for existing payment:', e?.message || e); }
-      return {
-        status: 'already_processed',
-        paymentId: existingPayment.id,
-        externalId: yocoPaymentId
-      };
-    }
-    
-    // Find the registration by checkoutId
-    let registration = null;
-    if (checkoutId) {
-      registration = await prisma.registration.findFirst({
-        where: {
-          checkoutId: checkoutId
-        },
-        include: {
-          event: {
-            select: {
-              id: true,
-              title: true
-            }
-          },
-          user: {
-            select: {
-              id: true,
-              name: true,
-              email: true
-            }
-          }
-        }
-      });
-    }
-    
-    // If no registration found by checkoutId, try metadata
-    if (!registration && metadata && metadata.registrationId) {
-      registration = await prisma.registration.findUnique({
-        where: {
-          id: metadata.registrationId
-        },
-        include: {
-          event: {
-            select: {
-              id: true,
-              title: true
-            }
-          },
-          user: {
-            select: {
-              id: true,
-              name: true,
-              email: true
-            }
-          }
-        }
-      });
-    }
-    
-    // Resolve userId: registration owner → metadata → first active admin (never use a non-existent UUID)
-    let resolvedUserId = registration?.userId || metadata?.userId || null;
-    if (!resolvedUserId) {
-      try {
-        const adminUser = await prisma.user.findFirst({ where: { role: 'admin', isActive: true }, select: { id: true } });
-        resolvedUserId = adminUser?.id || null;
-      } catch (e) { /* ignore — payment will fail below if still null */ }
-    }
-
-    // A registration checkout can carry a donation on top (metadata.donationAmount). It's
-    // recorded as its own donation payment so it never counts towards the registration.
-    const grossAmount = amount / 100; // Convert cents to your currency unit
-    const donationPart = registration?.id
-      ? Math.min(Math.max(Number(metadata?.donationAmount) || 0, 0), grossAmount)
-      : 0;
-
-    // Create payment record
-    const payment = await prisma.payment.create({
-      data: {
-        id: uuidv4(), // Generate a UUID for the payment
-        amount: Math.round((grossAmount - donationPart) * 100) / 100,
-        method: method.type, // The type of payment from the webhook
-        status: status === 'succeeded' ? 'completed' : status,
-        externalId: yocoPaymentId,
-        registrationId: registration?.id || null,
-        userId: resolvedUserId,
-        recordedById: resolvedUserId, // self-service webhook payment — payer is the recorder
-        eventId: registration?.eventId || metadata?.eventId || null,
-        isDonation: !registration?.id,
-        ...(!registration?.id && metadata?.type === 'sponsorship' ? {
-          isSponsorship: true,
-          sponsorAnonymous: String(metadata.sponsorAnonymous) === 'true',
-          sponsorName: String(metadata.sponsorAnonymous) === 'true' ? null : (metadata.sponsorName ? String(metadata.sponsorName).slice(0, 100) : null),
-          sponsorMessage: metadata.sponsorMessage ? String(metadata.sponsorMessage).slice(0, 300) : null,
-        } : {})
-      },
-      include: {
-        user: {
-          select: {
-            id: true,
-            name: true,
-            email: true
-          }
-        },
-        recordedBy: {
-          select: {
-            id: true,
-            name: true,
-            email: true
-          }
-        },
-        registration: registration ? {
-          include: {
-            event: true
-          }
-        } : undefined,
-        event: (registration?.eventId || metadata?.eventId) ? true : undefined
-      }
-    });
-    
-    let donationPayment = null;
-    if (donationPart > 0) {
-      donationPayment = await prisma.payment.create({
-        data: {
-          id: uuidv4(),
-          amount: donationPart,
-          method: method.type,
-          status: status === 'succeeded' ? 'completed' : status,
-          userId: resolvedUserId,
-          recordedById: resolvedUserId,
-          registrationId: null,
-          eventId: registration.eventId,
-          isDonation: true,
-          originalPaymentId: payment.id,
-        }
-      });
-    }
-
-    // If this payment is for a registration, update the registration status
-    let updatedRegistration = null;
-    let generatedTickets = [];
-    
-    if (registration) {
-      updatedRegistration = await updateRegistrationStatus(registration.id);
-      
-      // If registration status is 'paid', tickets were generated
-      if (updatedRegistration.status === 'paid') {
-        // Find the generated tickets
-        generatedTickets = await prisma.ticket.findMany({
-          where: {
-            registrationOption: {
-              registrationId: registration.id
-            }
-          },
-          select: {
-            id: true,
-            qrCode: true,
-            isUsed: true,
-            registrationOptionId: true,
-            eventId: true
-          }
-        });
-      }
-    }
-    
-    console.log(`Payment ${yocoPaymentId} processed successfully`);
-    
-    // Mark the Yoco transaction as reconciled and link the payment
-    try { await saveYocoTransaction(webhookData, { reconciled: true, paymentId: payment.id }); } catch(e) { console.warn('Failed to reconcile YocoTransaction after payment create:', e?.message || e); }
-
-    // Send emails: payment confirmation first, then tickets (guarantees order)
-    const _whPaymentId = payment.id;
-    const _whDonationId = donationPayment?.id;
-    const _whUserId = registration?.userId;
-    const _whRegId = registration?.id;
-    const _whTicketsGenerated = generatedTickets.length > 0;
-    (async () => {
-      try {
-        const { sendPaymentEmails } = require('../utils/notifications');
-        await sendPaymentEmails(_whPaymentId);
-      } catch (e) {
-        console.error('Failed to send webhook payment emails:', e);
-      }
-      if (_whDonationId) {
-        try {
-          const { sendPaymentEmails } = require('../utils/notifications');
-          await sendPaymentEmails(_whDonationId);
-        } catch (e) {
-          console.error('Failed to send webhook donation emails:', e);
-        }
-      }
-      if (_whTicketsGenerated && _whUserId && _whRegId) {
-        const mockReq = { user: { id: _whUserId }, body: { registrationId: _whRegId } };
-        const mockRes = { status: () => mockRes, json: () => {} };
-        try { await emailTickets(mockReq, mockRes); } catch (e) { console.error('Error emailing tickets from webhook:', e); }
-      }
-    })();
-    
-    // Return processed data
-    return {
-      status: 'success',
-      payment: {
-        id: payment.id,
-        externalId: yocoPaymentId,
-        amount: payment.amount,
-        method: payment.method,
-        status: payment.status,
-        createdAt: payment.createdAt
-      },
-      registration: registration ? {
-        id: registration.id,
-        status: updatedRegistration ? updatedRegistration.status : registration.status,
-        eventId: registration.eventId,
-        eventTitle: registration.event?.title,
-        userId: registration.userId,
-        userName: registration.user?.name
-      } : null,
-      generatedTickets: generatedTickets.length > 0 ? generatedTickets : undefined
-    };
-  } catch (error) {
-    console.error('Error processing payment.succeeded event:', error);
-    throw error;
-  }
-};
-
-// Update registration status based on payments
-const updateRegistrationStatus = async (registrationId) => {
-  try {
-    // Refresh early-bird pricing before computing totalDue — ensures expired/exhausted tiers
-    // are accounted for so we never mark a registration paid based on stale prices.
-    try { await refreshPricingForRegistration(registrationId); } catch (e) {
-      console.warn('[webhook] Price refresh failed:', e?.message);
-    }
-
-    const registration = await prisma.registration.findUnique({
-      where: { id: registrationId },
-      include: {
-        registrationOptions: {
-          include: {
-            eventOption: {
-              include: {
-                earlyBirdTiers: true
-              }
-            },
-            tranches: true
-          }
-        },
-        payments: true
-      }
-    });
-
-    if (!registration) {
-      throw new Error(`Registration ${registrationId} not found`);
-    }
-
-    // Calculate total amount paid
-    const totalPaid = registration.payments.reduce((sum, payment) => sum + payment.amount, 0);
-
-    // Calculate total amount due (uses priceSnapshot — refreshed above)
-    const totalDue = computeRegistrationTotalDue(registration, new Date());
-
-    // Update registration status based on payment
-    let newStatus;
-    if (totalPaid >= totalDue) {
-      newStatus = 'paid';
-    } else if (totalPaid > 0) {
-      newStatus = 'partial_paid';
-    } else {
-      newStatus = 'pending';
-    }
-
-    const updatedRegistration = await prisma.registration.update({
-      where: { id: registrationId },
-      data: {
-        status: newStatus,
-        updatedAt: new Date()
-      }
-    });
-    
-    // Generate tickets if status is "paid" (email handled by caller after payment email)
-    let generatedTickets = [];
-    if (newStatus === 'paid') {
-      try {
-        generatedTickets = await generateTicketsForRegistration(registrationId);
-      } catch (error) {
-        console.error('Error generating tickets:', error);
-        // Don't throw the error, just log it - we still want to update the registration status
-      }
-    }
-    
-    // Return the updated registration
-    return {
-      ...updatedRegistration,
-      totalPaid,
-      totalDue,
-      generatedTickets: generatedTickets.length > 0 ? generatedTickets : undefined
-    };
-  } catch (error) {
-    console.error('Error updating registration status:', error);
-    throw error;
-  }
-};
+const handleYocoWebhook = handleProviderWebhook('yoco');

 const handleWhatsappWebhook = async (req, res) => {
  try {
@@ -561,62 +18,3 @@ module.exports = {
  handleYocoWebhook,
  handleWhatsappWebhook,
 };
-
-// Helper: save or update Yoco transactions for any webhook event
-async function saveYocoTransaction(webhookData, updates = {}) {
-  try {
-    const payload = webhookData?.payload || {};
-    const externalId = payload?.id || webhookData?.id;
-    if (!externalId) {
-      throw new Error('Missing external id in webhook payload');
-    }
-
-    const amount = typeof payload?.amount === 'number' ? payload.amount : null; // cents if provided
-    const currency = payload?.currency || null;
-    const createdDateStr = payload?.createdDate || webhookData?.createdDate;
-    const createdDate = createdDateStr ? new Date(createdDateStr) : null;
-    const checkoutId = payload?.checkoutId || payload?.metadata?.checkoutId || payload?.metadata?.checkout_id || null;
-    const methodType = payload?.paymentMethodDetails?.type || null;
-
-    // Try find existing
-    const existing = await prisma.yocoTransaction.findFirst({ where: { externalId } });
-    if (existing) {
-      // Update with any provided updates
-      if (updates && Object.keys(updates).length > 0) {
-        return await prisma.yocoTransaction.update({
-          where: { id: existing.id },
-          data: { ...updates, updatedAt: new Date() }
-        });
-      }
-      return existing;
-    }
-
-    // Create new
-    const record = await prisma.yocoTransaction.create({
-      data: {
-        externalId,
-        amount,
-        currency,
-        createdDate,
-        checkoutId,
-        methodType,
-        reconciled: false,
-        raw: webhookData,
-        ...updates
-      }
-    });
-    return record;
-  } catch (e) {
-    // Unique constraint race: fetch existing
-    if (e?.code === 'P2002') {
-      const payload = webhookData?.payload || {};
-      const externalId = payload?.id || webhookData?.id;
-      const existing = await prisma.yocoTransaction.findFirst({ where: { externalId } });
-      if (existing && updates && Object.keys(updates).length > 0) {
-        return await prisma.yocoTransaction.update({ where: { id: existing.id }, data: { ...updates, updatedAt: new Date() } });
-      }
-      return existing;
-    }
-    throw e;
-  }
-}
@@ -1,4 +1,5 @@
 const prisma = require('../config/db');
+const { normaliseKind, filterRecipients, whatsAppNewsFooter } = require('../utils/privacy');

 function fmtDate(d) {
  try { return new Date(d).toLocaleString(); } catch { return String(d); }
@@ -82,9 +83,10 @@ const previewWhatsAppBroadcast = async (req, res) => {
      if (!phone) continue;
      if (!map.has(phone)) map.set(phone, { phone, name: r.name || '' });
    }
-    const recipients = Array.from(map.values());
+    const kind = normaliseKind(req.body?.kind) || 'news';
+    const { recipients, skipped } = await filterRecipients(Array.from(map.values()), { channel: 'whatsapp', kind });

-    return res.json({ matched: recipients.length, recipients: recipients.slice(0, 20) });
+    return res.json({ kind, matched: recipients.length, skipped, recipients: recipients.slice(0, 20) });
  } catch (error) {
    return res.status(400).json({ message: error.message });
  }
@@ -123,9 +125,12 @@ const sendWhatsAppBroadcast = async (req, res) => {
      if (!phone) continue;
      if (!map.has(phone)) map.set(phone, { phone, name: r.name || '' });
    }
-    const recipients = Array.from(map.values());
+    // News unless marked as an event update; news skips people who haven't opted in to
+    // WhatsApp news, replied STOP or unsubscribed.
+    const kind = normaliseKind(req.body?.kind) || 'news';
+    const { recipients, skipped } = await filterRecipients(Array.from(map.values()), { channel: 'whatsapp', kind });
    if (recipients.length === 0) {
-      return res.status(400).json({ message: 'No valid recipients with phone numbers' });
+      return res.status(400).json({ message: skipped ? 'Everyone selected has unsubscribed from WhatsApp news.' : 'No valid recipients with phone numbers' });
    }

    let event = null;
@@ -139,7 +144,7 @@ const sendWhatsAppBroadcast = async (req, res) => {
    const results = await Promise.allSettled(recipients.map(async rcpt => {
      const ctx = { name: rcpt.name || '', eventTitle, eventStart, eventLink };
      const finalMessage = replacePlaceholders(message, ctx);
-      await sendText(rcpt.phone, finalMessage);
+      await sendText(rcpt.phone, kind === 'news' ? finalMessage + whatsAppNewsFooter(rcpt) : finalMessage);
    }));

    const sent = results.filter(r => r.status === 'fulfilled').length;
@@ -149,7 +154,7 @@ const sendWhatsAppBroadcast = async (req, res) => {
      }
    });

-    return res.json({ matched: recipients.length, sent });
+    return res.json({ kind, matched: recipients.length, skipped, sent });
  } catch (error) {
    return res.status(400).json({ message: error.message });
  }
@@ -160,13 +165,13 @@ const sendWhatsAppBroadcast = async (req, res) => {
 // @access  Private/Supervisor or Admin
 const scheduleWhatsAppBroadcast = async (req, res) => {
  try {
-    const { scheduledAt, message, userIds, phones, eventId } = req.body || {};
+    const { scheduledAt, message, userIds, phones, eventId, kind } = req.body || {};
    if (!scheduledAt) return res.status(400).json({ message: 'scheduledAt is required' });
    const when = new Date(scheduledAt);
    if (isNaN(when.getTime())) return res.status(400).json({ message: 'scheduledAt must be a valid ISO date-time' });
    if (!message) return res.status(400).json({ message: 'message is required' });

-    const payload = { message, userIds, phones, eventId };
+    const payload = { message, userIds, phones, eventId, kind };

    const recipientSummary = await describeBroadcastRecipients({ userIds, phones });

@@ -25,6 +25,7 @@ const getConfigHandler = async (req, res) => {
      hasToken:    !!token,
      hasInstance: !!instanceId,
      configured:  !!(token && instanceId),
+      webhookUrl:  await require('../utils/whatsapp').webhookUrl(),
    });
  } catch (e) {
    res.status(500).json({ message: e?.message || 'Failed to load config' });
@@ -162,6 +163,7 @@ const handleWebhook = async (req, res) => {

  try {
    const { event, session } = req.body || {};
+    if (event === 'message') return await handleIncomingMessage(req);
    if (event !== 'session.status') return;

    const status = session?.status;
@@ -210,6 +212,42 @@ const handleWebhook = async (req, res) => {
  }
 };

+/**
+ * An incoming WhatsApp message (WAWP `message` event). The only thing we act on is an
+ * opt-out reply — "STOP" — which stops News & announcements on WhatsApp for that number
+ * (event updates still go out). Only trusted when the URL carries our webhook secret,
+ * since WAWP doesn't sign webhooks.
+ */
+async function handleIncomingMessage(req) {
+  const crypto = require('crypto');
+  const { getWebhookSecret, phoneFromChatId, sendText } = require('../utils/whatsapp');
+  const { isStopKeyword, whatsAppStop } = require('../utils/privacy');
+
+  const given = String(req.query?.secret || '');
+  const secret = await getWebhookSecret();
+  if (given.length !== secret.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(secret))) {
+    console.warn('[whatsapp webhook] Ignored a message event without a valid secret');
+    return;
+  }
+
+  // Proof for the POPIA readiness page that WAWP's webhook (and so STOP) is set up.
+  const prisma = require('../config/db');
+  const now = new Date().toISOString();
+  prisma.appSetting.upsert({ where: { key: 'wawp_webhook_last_seen' }, update: { value: now }, create: { key: 'wawp_webhook_last_seen', value: now } }).catch(() => {});
+
+  const payload = req.body?.payload || {};
+  if (payload.fromMe || !isStopKeyword(payload.body)) return;
+  const phone = phoneFromChatId(payload.from);
+  if (!phone) {
+    // Groups, channels, and senders WhatsApp only identifies by a "LID" (no phone number).
+    console.warn('[whatsapp webhook] STOP from a sender without a phone number:', payload.from);
+    return;
+  }
+  const result = await whatsAppStop(phone);
+  if (!result) return;
+  await sendText(phone, "You won't get news and announcements from us on WhatsApp any more. You'll still get messages about events you've registered for.").catch(() => {});
+}
+
 module.exports = {
  getConfigHandler,
  saveConfigHandler,
@@ -1,282 +0,0 @@
-const prisma = require('../config/db');
-const { generateTicketsForRegistration } = require('../utils/ticketUtils');
-const { emailTickets } = require('./ticketController');
-
-function getYocoModel() {
-  // Gracefully handle environments where the Prisma client hasn't been regenerated
-  // and YocoTransaction model is not available yet.
-  return prisma && prisma.yocoTransaction ? prisma.yocoTransaction : null;
-}
-
-// @desc    Get all Yoco transactions (optionally filter by reconciled and ignored)
-// @route   GET /api/yoco-transactions
-// @access  Private/Admin or Supervisor
-const getAllYocoTransactions = async (req, res) => {
-  try {
-    if (!req.user || !['admin', 'supervisor'].includes(req.user.role)) {
-      return res.status(403).json({ success: false, message: 'Forbidden' });
-    }
-
-    const { reconciled, ignored } = req.query;
-    const where = {};
-    if (typeof reconciled !== 'undefined') where.reconciled = String(reconciled) === 'true';
-    if (typeof ignored !== 'undefined') where.ignored = String(ignored) === 'true';
-
-    const Yoco = getYocoModel();
-    if (!Yoco) {
-      console.warn('YocoTransaction model not available on Prisma client. Did you run migrations and `prisma generate`?');
-      return res.status(200).json({ success: true, data: [], message: 'YocoTransaction model not available. Apply DB migration and regenerate Prisma client.' });
-    }
-
-    const items = await Yoco.findMany({
-      where,
-      orderBy: [{ createdDate: 'desc' }, { createdAt: 'desc' }]
-    });
-
-    return res.status(200).json({ success: true, data: items });
-  } catch (error) {
-    console.error('Failed to fetch Yoco transactions:', error);
-    return res.status(500).json({ success: false, message: 'Server error', details: error.message });
-  }
-};
-
-// @desc    Get unreconciled Yoco transactions (not reconciled and not ignored)
-// @route   GET /api/yoco-transactions/unreconciled
-// @access  Private/Admin or Supervisor
-const getUnreconciledYocoTransactions = async (req, res) => {
-  try {
-    // Basic role check if auth middleware sets req.user
-    if (!req.user || !['admin', 'supervisor'].includes(req.user.role)) {
-      return res.status(403).json({ success: false, message: 'Forbidden' });
-    }
-
-    const Yoco = getYocoModel();
-    if (!Yoco) {
-      console.warn('YocoTransaction model not available on Prisma client. Did you run migrations and `prisma generate`?');
-      return res.status(200).json({ success: true, data: [], message: 'YocoTransaction model not available. Apply DB migration and regenerate Prisma client.' });
-    }
-
-    const items = await Yoco.findMany({
-      where: { reconciled: false, ignored: false },
-      orderBy: { createdDate: 'desc' }
-    });
-
-    return res.status(200).json({ success: true, data: items });
-  } catch (error) {
-    console.error('Failed to fetch unreconciled Yoco transactions:', error);
-    return res.status(500).json({ success: false, message: 'Server error', details: error.message });
-  }
-};
-
-// @desc    Reconcile a Yoco transaction to a Registration or Donation (creates Payment)
-// @route   POST /api/yoco-transactions/:id/reconcile
-// @access  Private/Admin or Supervisor
-const reconcileYocoTransaction = async (req, res) => {
-  try {
-    if (!req.user || !['admin', 'supervisor'].includes(req.user.role)) {
-      return res.status(403).json({ success: false, message: 'Forbidden' });
-    }
-
-    const Yoco = getYocoModel();
-    if (!Yoco) {
-      return res.status(400).json({ success: false, message: 'YocoTransaction model not available. Apply DB migration and regenerate Prisma client.' });
-    }
-
-    const { id } = req.params;
-    const { registrationId, eventId, userId: bodyUserId } = req.body || {};
-
-    const ytx = await Yoco.findUnique({ where: { id } });
-    if (!ytx) return res.status(404).json({ success: false, message: 'YocoTransaction not found' });
-    if (ytx.reconciled && ytx.paymentId) {
-      return res.status(409).json({ success: false, message: 'Already reconciled', data: ytx });
-    }
-
-    // Load registration if provided
-    let registration = null;
-    if (registrationId) {
-      registration = await prisma.registration.findUnique({
-        where: { id: registrationId },
-        include: {
-          event: true,
-          user: true,
-          registrationOptions: { include: { eventOption: true } },
-          payments: true
-        }
-      });
-      if (!registration) return res.status(404).json({ success: false, message: 'Registration not found' });
-    }
-
-    // Determine payment fields
-    const amountFloat = typeof ytx.amount === 'number' ? (ytx.amount / 100) : 0;
-    if (!amountFloat || amountFloat <= 0) {
-      return res.status(400).json({ success: false, message: 'Invalid amount on YocoTransaction for reconciliation' });
-    }
-
-    const externalId = ytx.externalId || undefined;
-
-    // Resolve a valid userId for the Payment to satisfy FK constraints
-    let resolvedUserId = null;
-    if (registration?.userId) {
-      resolvedUserId = registration.userId;
-    } else if (bodyUserId) {
-      // Staff explicitly picked the donor while reconciling (e.g. as a donation) — trust that
-      // over metadata guesswork, but still verify the user actually exists.
-      try {
-        const exists = await prisma.user.findUnique({ where: { id: String(bodyUserId) } });
-        if (exists) resolvedUserId = String(bodyUserId);
-      } catch {}
-    }
-    if (!resolvedUserId && ytx?.raw?.payload?.metadata?.userId) {
-      const metaUserId = String(ytx.raw.payload.metadata.userId);
-      try {
-        const exists = await prisma.user.findUnique({ where: { id: metaUserId } });
-        if (exists) resolvedUserId = metaUserId;
-      } catch {}
-    }
-    if (!resolvedUserId && req.user?.id) {
-      // Fallback to the acting supervisor/admin to avoid FK violations
-      resolvedUserId = req.user.id;
-    }
-    if (!resolvedUserId) {
-      return res.status(400).json({ success: false, message: 'Unable to resolve a valid user for this payment' });
-    }
-
-    // Build payment data
-    const paymentData = {
-      amount: amountFloat,
-      method: ytx.methodType || 'card',
-      userId: resolvedUserId,
-      recordedById: req.user?.id || null, // staff who performed the reconciliation
-      registrationId: registration?.id || null,
-      eventId: registration?.eventId || eventId || null,
-      isDonation: !registration?.id,
-      externalId: externalId,
-      status: 'completed'
-    };
-
-    // Ensure donation has an eventId
-    if (!registration && !paymentData.eventId) {
-      return res.status(400).json({ success: false, message: 'eventId is required when reconciling as donation' });
-    }
-
-    // Create payment
-    // Preserve original Yoco creation time to correctly evaluate early-bird pricing
-    const createdAt = ytx.createdDate || ytx.createdAt || new Date();
-    const payment = await prisma.payment.create({ data: { ...paymentData, createdAt } });
-
-    // Optionally update registration status when applicable and generate tickets if paid.
-    // Ticket generation stays synchronous so `generatedTickets` can be included in the response;
-    // emailing/WhatsApp-ing the tickets and payment confirmation are backgrounded below since
-    // they involve slow PDF rendering + SMTP/WAWP round trips that shouldn't block this request.
-    let generatedTickets = [];
-    if (registration) {
-      try {
-        const updatedReg = await updateRegistrationStatus(registration.id);
-        if (updatedReg && updatedReg.status === 'paid') {
-          try {
-            generatedTickets = await generateTicketsForRegistration(registration.id);
-          } catch (genErr) {
-            console.error('Error generating tickets after Yoco reconciliation:', genErr);
-          }
-        }
-      } catch (e) {
-        // log but do not fail reconciliation
-        console.warn('Failed to update registration after reconciliation:', e?.message || e);
-      }
-    }
-
-    // Fire-and-forget: payment confirmation email, then ticket email/WhatsApp (guarantees order)
-    const { sendPaymentEmails } = require('../utils/notifications');
-    const _rxPaymentId = payment.id;
-    const _rxUserId = registration?.userId;
-    const _rxRegId = registration?.id;
-    const _rxShouldEmailTickets = Array.isArray(generatedTickets) && generatedTickets.length > 0;
-    (async () => {
-      try { await sendPaymentEmails(_rxPaymentId); } catch (e) { console.error('Failed to send payment emails after reconciliation:', e); }
-      if (_rxShouldEmailTickets && _rxUserId) {
-        const mockReq = { user: { id: _rxUserId }, body: { registrationId: _rxRegId } };
-        const mockRes = { status: () => mockRes, json: () => {} };
-        try { await emailTickets(mockReq, mockRes); } catch (e) { console.error('Error emailing tickets after Yoco reconciliation:', e); }
-      }
-    })();
-
-    // Update yoco transaction as reconciled
-    const updatedTx = await Yoco.update({
-      where: { id: ytx.id },
-      data: { reconciled: true, paymentId: payment.id }
-    });
-
-    return res.status(200).json({ success: true, data: { yocoTransaction: updatedTx, payment, generatedTickets: (generatedTickets && generatedTickets.length) ? generatedTickets : undefined } });
-  } catch (error) {
-    console.error('Failed to reconcile Yoco transaction:', error);
-    // Handle unique externalId conflicts (if a Payment with same externalId already exists)
-    if (error?.code === 'P2002') {
-      try {
-        const existing = await prisma.payment.findFirst({ where: { externalId: (await getYocoModel()?.findUnique({ where: { id: req.params.id } }))?.externalId } });
-        if (existing) {
-          const updatedTx = await getYocoModel()?.update({ where: { id: req.params.id }, data: { reconciled: true, paymentId: existing.id } });
-          if (updatedTx) {
-            return res.status(200).json({ success: true, data: { yocoTransaction: updatedTx, payment: existing }, message: 'Linked to existing payment' });
-          }
-        }
-      } catch {}
-    }
-    return res.status(500).json({ success: false, message: 'Server error', details: error?.message || String(error) });
-  }
-};
-
-// Minimal registration status update mirroring webhook logic
-async function updateRegistrationStatus(registrationId) {
-  const registration = await prisma.registration.findUnique({
-    where: { id: registrationId },
-    include: {
-      registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } } } },
-      payments: true
-    }
-  });
-  if (!registration) return null;
-  const totalPaid = (registration.payments || []).reduce((s, p) => s + (p.amount || 0), 0);
-  const totalDue = require('../utils/pricing').computeRegistrationTotalDue(registration, new Date());
-  let newStatus = 'pending';
-  if (totalPaid >= totalDue) newStatus = 'paid';
-  else if (totalPaid > 0) newStatus = 'partial_paid';
-  return prisma.registration.update({ where: { id: registrationId }, data: { status: newStatus, updatedAt: new Date() } });
-}
-
-// @desc    Ignore a Yoco transaction (mark as ignored and reconciled without creating a payment)
-// @route   POST /api/yoco-transactions/:id/ignore
-// @access  Private/Admin or Supervisor
-const ignoreYocoTransaction = async (req, res) => {
-  try {
-    if (!req.user || !['admin', 'supervisor'].includes(req.user.role)) {
-      return res.status(403).json({ success: false, message: 'Forbidden' });
-    }
-    const Yoco = getYocoModel();
-    if (!Yoco) {
-      return res.status(400).json({ success: false, message: 'YocoTransaction model not available. Apply DB migration and regenerate Prisma client.' });
-    }
-    const { id } = req.params;
-    const ytx = await Yoco.findUnique({ where: { id } });
-    if (!ytx) return res.status(404).json({ success: false, message: 'YocoTransaction not found' });
-
-    if (ytx.reconciled && ytx.ignored) {
-      return res.status(200).json({ success: true, data: ytx, message: 'Already ignored' });
-    }
-
-    const updated = await Yoco.update({
-      where: { id },
-      data: { ignored: true, reconciled: true }
-    });
-    return res.status(200).json({ success: true, data: updated });
-  } catch (error) {
-    console.error('Failed to ignore Yoco transaction:', error);
-    return res.status(500).json({ success: false, message: 'Server error', details: error?.message || String(error) });
-  }
-};
-
-module.exports = {
-  getAllYocoTransactions,
-  getUnreconciledYocoTransactions,
-  reconcileYocoTransaction,
-  ignoreYocoTransaction
-};
@@ -0,0 +1,167 @@
+/**
+ * Talking to the Cross Events Hub (docs/hub-protocol.md): register with a licence key, then a
+ * signed heartbeat every 15 minutes, and a signed update request when an admin asks for one.
+ * Install → Hub only. Stored in AppSetting:
+ *   hub_install_id, hub_install_secret (encrypted), hub_licence (signed token),
+ *   hub_last_heartbeat_at, hub_last_error, hub_latest_version,
+ *   hub_update_requested_at, hub_update_requested_version.
+ * These keys are kept out of the generic settings endpoints (settingsController).
+ */
+
+const crypto = require('crypto');
+const prisma = require('../config/db');
+const { encrypt, decrypt } = require('../utils/encryption');
+const { verifyToken, clearLicenceCache } = require('./licence');
+const report = require('./report');
+
+const PROTOCOL_VERSION = 1;
+const TIMEOUT_MS = 15000;
+const HUB_KEYS = ['hub_install_id', 'hub_install_secret', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version'];
+
+function hubUrl() {
+  return String(process.env.HUB_URL || 'https://events-hub.crosscode.co.za').replace(/\/$/, '');
+}
+
+class HubError extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.statusCode = status;
+  }
+}
+
+async function save(values) {
+  for (const [key, value] of Object.entries(values)) {
+    if (value === null) await prisma.appSetting.deleteMany({ where: { key } });
+    else await prisma.appSetting.upsert({ where: { key }, update: { value: String(value) }, create: { key, value: String(value) } });
+  }
+  clearLicenceCache();
+}
+
+async function read(keys) {
+  const rows = await prisma.appSetting.findMany({ where: { key: { in: keys } } });
+  return Object.fromEntries(rows.map(r => [r.key, r.value]));
+}
+
+async function post(path, body, headers = {}) {
+  const raw = JSON.stringify(body);
+  let res;
+  try {
+    res = await fetch(`${hubUrl()}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(typeof headers === 'function' ? headers(raw) : headers) },
+      body: raw,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    throw new HubError(`The Hub (${hubUrl()}) could not be reached: ${e?.message || e}`, 'HUB_UNREACHABLE', 502);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new HubError(data.message || `The Hub answered ${res.status}`, data.code || 'HUB_ERROR', res.status);
+  return data;
+}
+
+/** POST signed with the install secret (§3). Throws NOT_CONNECTED when there is no connection. */
+async function signedPost(path, body) {
+  const s = await read(['hub_install_id', 'hub_install_secret']);
+  if (!s.hub_install_id || !s.hub_install_secret) throw new HubError('This site isn\'t connected to the Hub yet.', 'NOT_CONNECTED', 400);
+  const secret = decrypt(s.hub_install_secret);
+  return post(path, body, raw => {
+    const timestamp = new Date().toISOString();
+    return {
+      'X-Hub-Install': s.hub_install_id,
+      'X-Hub-Timestamp': timestamp,
+      'X-Hub-Signature': crypto.createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex'),
+    };
+  });
+}
+
+/** Register this install with a licence key. Returns the licence claims. */
+async function connect(licenceKey, adminContact) {
+  if (!require('./publicKey').hubPublicKey()) {
+    throw new HubError('This version of Cross Events has no Hub key built in, so it can\'t check licences yet.', 'NO_PUBLIC_KEY', 500);
+  }
+  const install = await report.installInfo();
+  if (!/^https?:\/\//.test(install.url)) {
+    throw new HubError('Set the site\'s web address first (FRONTEND_URL on the server, or Site settings → Organisation).', 'NO_SITE_URL', 400);
+  }
+  const data = await post('/api/installs/register', {
+    protocolVersion: PROTOCOL_VERSION,
+    licenceKey: String(licenceKey || '').trim(),
+    install: { ...install, adminContact: adminContact ? { name: adminContact.name || null, email: adminContact.email || null } : null },
+  });
+  const claims = verifyToken(data.licence);
+  if (!claims || claims.installId !== data.installId) {
+    throw new HubError('The Hub answered with a licence this install can\'t verify. Is HUB_URL pointing at the right Hub?', 'BAD_LICENCE', 502);
+  }
+  await save({
+    hub_install_id: data.installId,
+    hub_install_secret: encrypt(data.installSecret),
+    hub_licence: data.licence,
+    hub_last_heartbeat_at: new Date().toISOString(),
+    hub_last_error: null,
+    hub_latest_version: data.latestVersion || null,
+  });
+  return claims;
+}
+
+/** Send a heartbeat (the `hub-heartbeat` job). Skips quietly when not connected. */
+async function heartbeat() {
+  const s = await read(['hub_install_id', 'hub_install_secret']);
+  if (!s.hub_install_id || !s.hub_install_secret) return { skipped: 'not connected' };
+  const body = { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION, health: await report.health(), stats: await report.stats() };
+  try {
+    const data = await signedPost('/api/installs/heartbeat', body);
+    const claims = verifyToken(data.licence);
+    await save({
+      // Keep the old token if the new one doesn't check out (never accept an unverified one).
+      ...(claims && claims.installId === s.hub_install_id ? { hub_licence: data.licence } : {}),
+      hub_last_heartbeat_at: new Date().toISOString(),
+      hub_last_error: null,
+      hub_latest_version: data.latestVersion || null,
+    });
+    return { ok: true, status: claims?.status || null };
+  } catch (e) {
+    await save({ hub_last_error: `${new Date().toISOString()} ${e.code || ''} ${e.message}`.slice(0, 500) });
+    // The Hub doesn't know this install any more (licence released): drop the connection and the
+    // licence, so the site is unlicensed (read-only) and shows "Connect" until a key is entered.
+    if (e.code === 'INSTALL_NOT_FOUND') {
+      await save({ hub_install_id: null, hub_install_secret: null, hub_licence: null });
+      return { ok: false, reconnect: true };
+    }
+    throw e;
+  }
+}
+
+/**
+ * Ask the Hub for this site to be updated (§3a). Joshua is told; the site never updates itself.
+ * Returns { requestedAt, version, alreadyRequested }.
+ */
+async function requestUpdate() {
+  let data;
+  try {
+    data = await signedPost('/api/installs/update-request', { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION });
+  } catch (e) {
+    if (e.code === 'NOT_FOUND') throw new HubError('The Hub doesn\'t take update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
+    throw e;
+  }
+  await save({ hub_update_requested_at: data.requestedAt, hub_update_requested_version: data.version || null });
+  return data;
+}
+
+/**
+ * A heartbeat soon (on startup, and after connecting), so a licence change on the Hub shows
+ * without waiting for the next 15-minute run. Never throws; skipped when the job is switched off.
+ */
+let soonTimer = null;
+function heartbeatSoon(delayMs = 30 * 1000) {
+  if (String(process.env.JOBS_ENABLED || 'true').toLowerCase() === 'false') return;
+  if (String(process.env.HUB_HEARTBEAT_ENABLED || 'true').toLowerCase() === 'false') return;
+  clearTimeout(soonTimer);
+  soonTimer = setTimeout(() => {
+    heartbeat().catch(e => console.warn('[hub] Heartbeat failed:', e?.message || e));
+  }, delayMs);
+  soonTimer.unref?.();
+}
+
+module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, connect, heartbeat, heartbeatSoon, requestUpdate };
@@ -0,0 +1,107 @@
+/**
+ * Licence checks (docs/hub-protocol.md §4). The Hub signs a licence token with its private
+ * key; this install checks it with the public key and works out its state, offline:
+ *
+ *   active      — everything works
+ *   grace       — past the end date for up to graceDays: works, site admins see a banner
+ *   suspended   — suspended by the Hub, or grace ran out: read-only (no new events,
+ *                 registrations or payments); tickets still scan, data can be exported
+ *   revoked     — like suspended, with a permanent banner
+ *   unlicensed  — not connected to the Hub (never, or the Hub released this install): read-only,
+ *                 like suspended, until a licence key is connected
+ *
+ * LICENCE_CHECK_DISABLED=true turns read-only off outside production (the end-to-end tests).
+ */
+
+const crypto = require('crypto');
+const prisma = require('../config/db');
+const { hubPublicKey } = require('./publicKey');
+
+const DAY = 24 * 60 * 60 * 1000;
+const READ_ONLY_STATES = new Set(['suspended', 'revoked', 'unlicensed']);
+const CACHE_MS = 30 * 1000;
+
+let publicKeyObject = null;
+let publicKeyPem = null;
+function publicKey() {
+  const pem = hubPublicKey();
+  if (!pem) return null;
+  if (pem !== publicKeyPem) {
+    try {
+      publicKeyObject = crypto.createPublicKey(pem);
+    } catch {
+      throw new Error("The Hub public key can't be read — check HUB_PUBLIC_KEY in backend/.env (copy it from the Hub's Settings page).");
+    }
+    publicKeyPem = pem;
+  }
+  return publicKeyObject;
+}
+
+/** The token's claims if the Hub signed it, else null. */
+function verifyToken(token, key = publicKey()) {
+  if (!key) return null;
+  const parts = String(token || '').split('.');
+  if (parts.length !== 3 || parts[0] !== 'hel1') return null;
+  try {
+    const ok = crypto.verify(null, Buffer.from(`${parts[0]}.${parts[1]}`), key, Buffer.from(parts[2], 'base64url'));
+    return ok ? JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The state for verified claims (or null = never connected). Pure, for tests.
+ * Returns { state, readOnly, endsAt, graceEndsAt, daysLeft }.
+ */
+function stateFor(claims, installId, now = new Date()) {
+  if (!claims || (installId && claims.installId !== installId)) {
+    return { state: 'unlicensed', readOnly: true, endsAt: null, graceEndsAt: null, daysLeft: null };
+  }
+  const ends = [claims.licenceExpiresAt, claims.validUntil].filter(Boolean).map(d => new Date(d));
+  const endsAt = ends.length ? new Date(Math.min(...ends)) : null;
+  const graceEndsAt = endsAt ? new Date(endsAt.getTime() + (claims.graceDays || 0) * DAY) : null;
+  let state;
+  if (claims.status === 'revoked') state = 'revoked';
+  else if (claims.status === 'suspended') state = 'suspended';
+  else if (!endsAt || now < endsAt) state = 'active';
+  else if (now < graceEndsAt) state = 'grace';
+  else state = 'suspended';
+  const daysLeft = state === 'grace' ? Math.max(0, Math.ceil((graceEndsAt - now) / DAY)) : null;
+  return { state, readOnly: READ_ONLY_STATES.has(state), endsAt, graceEndsAt, daysLeft, expired: state === 'suspended' && claims.status === 'active' };
+}
+
+function checkDisabled() {
+  return process.env.NODE_ENV !== 'production' && String(process.env.LICENCE_CHECK_DISABLED || '').toLowerCase() === 'true';
+}
+
+let cache = null;
+
+/** This install's licence: claims, state and Hub connection details. Cached for 30 s. */
+async function licenceStatus({ fresh = false } = {}) {
+  if (!fresh && cache && Date.now() - cache.at < CACHE_MS) return cache.value;
+  const rows = await prisma.appSetting.findMany({ where: { key: { in: ['hub_install_id', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version'] } } });
+  const s = Object.fromEntries(rows.map(r => [r.key, r.value]));
+  const claims = verifyToken(s.hub_licence);
+  const value = {
+    keyConfigured: !!publicKey(),
+    connected: !!s.hub_install_id,
+    installId: s.hub_install_id || null,
+    claims: claims && claims.installId === s.hub_install_id ? claims : null,
+    ...stateFor(claims, s.hub_install_id || null),
+    ...(checkDisabled() ? { readOnly: false } : {}),
+    lastHeartbeatAt: s.hub_last_heartbeat_at || null,
+    lastError: s.hub_last_error || null,
+    latestVersion: s.hub_latest_version || null,
+    updateRequestedAt: s.hub_update_requested_at || null,
+    updateRequestedVersion: s.hub_update_requested_version || null,
+  };
+  cache = { at: Date.now(), value };
+  return value;
+}
+
+function clearLicenceCache() {
+  cache = null;
+}
+
+module.exports = { verifyToken, stateFor, licenceStatus, clearLicenceCache, READ_ONLY_STATES };
@@ -0,0 +1,32 @@
+/**
+ * The Cross Events Hub's public licence key (Ed25519). Installs check every licence token with
+ * it, so a licence can't be faked by editing the database. The matching private key exists
+ * only on the Hub server (events-hub repo, `npm run generate-keys`).
+ *
+ * PRODUCTION_PUBLIC_KEY is the key the production Hub prints (also served at /api/public-key); if
+ * the Hub key is regenerated, update it here. HUB_PUBLIC_KEY (env) overrides it — for a local Hub.
+ */
+
+const PRODUCTION_PUBLIC_KEY = "MCowBQYDK2VwAyEAcKpEo/JdS96wR3r9yh8uFUxBlzPUd2YKbC60fNRUhoU=";
+
+/**
+ * A public key as proper PEM, however it was pasted: with real line breaks, with "\n", all on
+ * one line ("-----BEGIN PUBLIC KEY-----MCow…-----END PUBLIC KEY-----"), or just the base64.
+ */
+function normalisePem(input) {
+  const text = String(input || '').replace(/\\n/g, '\n').trim();
+  if (!text) return null;
+  const body = text
+    .replace(/-----BEGIN PUBLIC KEY-----/, '')
+    .replace(/-----END PUBLIC KEY-----/, '')
+    .replace(/\s+/g, '');
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) return text; // not base64 — let the caller's parse fail clearly
+  const lines = body.match(/.{1,64}/g).join('\n');
+  return `-----BEGIN PUBLIC KEY-----\n${lines}\n-----END PUBLIC KEY-----\n`;
+}
+
+function hubPublicKey() {
+  return normalisePem(process.env.HUB_PUBLIC_KEY) || normalisePem(PRODUCTION_PUBLIC_KEY);
+}
+
+module.exports = { hubPublicKey, normalisePem, PRODUCTION_PUBLIC_KEY };
@@ -0,0 +1,54 @@
+/**
+ * Read-only mode while the licence is suspended, revoked or missing (not connected to the Hub):
+ * no new or edited events, and no *new* activity — registrations, tickets added, payments started
+ * or recorded, waitlist places, coupons or bundles.
+ * Everything else keeps working on purpose: scanning tickets for events people already paid for,
+ * viewing and exporting data, refunds and cancellations, privacy requests, logging in, and the
+ * settings needed to renew the licence. Payment webhooks for payments already started also still
+ * arrive (they're mounted before this middleware).
+ */
+
+const { licenceStatus } = require('./licence');
+
+const BLOCKED = [
+  ['POST', /^\/api\/events\/?$/],
+  ['PUT', /^\/api\/events\/[^/]+\/?$/],
+  ['POST', /^\/api\/events\/[^/]+\/options\/?$/],
+  ['PUT', /^\/api\/events\/options\/[^/]+\/?$/],
+  ['POST', /^\/api\/events\/options\/[^/]+\/variants\/?$/],
+  ['PUT', /^\/api\/events\/variants\/[^/]+\/?$/],
+  ['POST', /^\/api\/registrations\/?$/],
+  ['POST', /^\/api\/registrations\/manual\/?$/],
+  ['PUT', /^\/api\/registrations\/[^/]+\/options\/?$/],
+  ['POST', /^\/api\/payments\/?$/],
+  ['POST', /^\/api\/payments\/(checkout|yoco-checkout)(\/send)?\/?$/],
+  ['POST', /^\/api\/payments\/pay\/[^/]+\/?$/],
+  ['POST', /^\/api\/waitlist\/?$/],
+  ['POST', /^\/api\/coupons\/?$/],
+  ['POST', /^\/api\/bundles\/event\/[^/]+\/?$/],
+];
+
+function isBlocked(method, path) {
+  return BLOCKED.some(([m, re]) => m === method && re.test(path));
+}
+
+async function licenceReadOnly(req, res, next) {
+  if (!isBlocked(req.method, req.path)) return next();
+  try {
+    const status = await licenceStatus();
+    if (!status.readOnly) return next();
+    return res.status(403).json({
+      code: 'LICENCE_READ_ONLY',
+      message: status.state === 'revoked'
+        ? "This site's licence has been revoked, so nothing new can be added and events can't be changed. Tickets still scan and all data can still be viewed and exported."
+        : status.state === 'unlicensed'
+          ? "This site has no licence, so nothing new can be added and events can't be changed. A site admin can connect a licence key in Site settings → Licence."
+          : "This site's licence is suspended, so nothing new can be added and events can't be changed for now. Tickets still scan and all data can still be viewed and exported. Please contact the site's administrator.",
+    });
+  } catch {
+    // Never let a licence check failure take the site down.
+    return next();
+  }
+}
+
+module.exports = { licenceReadOnly, isBlocked, BLOCKED };
@@ -0,0 +1,153 @@
+/**
+ * What this install tells the Hub (docs/hub-protocol.md §3): health, and aggregate counts —
+ * no personal information. Income goes as a range, never an amount.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const prisma = require('../config/db');
+const errorCounter = require('../utils/errorCounter');
+
+const DAY = 24 * 60 * 60 * 1000;
+const APP_VERSION = require('../../package.json').version;
+const STARTED_AT = Date.now();
+
+const INCOME_BANDS = [
+  [1000, 'R0–R1 000'],
+  [5000, 'R1 001–R5 000'],
+  [20000, 'R5 001–R20 000'],
+  [50000, 'R20 001–R50 000'],
+  [100000, 'R50 001–R100 000'],
+];
+
+/** The range an amount falls in: "R5 001–R20 000", or "over R100 000". */
+function incomeBand(amount) {
+  const rand = Math.max(0, Math.round(Number(amount) || 0));
+  for (const [max, label] of INCOME_BANDS) if (rand <= max) return label;
+  return 'over R100 000';
+}
+
+async function postgresVersion() {
+  try {
+    const rows = await prisma.$queryRawUnsafe('SHOW server_version');
+    return String(rows[0]?.server_version || '').split(' ')[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Migrations in the repo that the database hasn't applied. */
+async function pendingMigrations() {
+  try {
+    const dir = path.join(__dirname, '..', '..', 'prisma', 'migrations');
+    const folders = fs.readdirSync(dir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
+    const rows = await prisma.$queryRawUnsafe('SELECT migration_name FROM "_prisma_migrations" WHERE finished_at IS NOT NULL AND rolled_back_at IS NULL');
+    const applied = new Set(rows.map(r => r.migration_name));
+    return folders.filter(f => !applied.has(f)).length;
+  } catch {
+    return null;
+  }
+}
+
+async function disk() {
+  try {
+    const s = await fs.promises.statfs(path.join(__dirname, '..', '..'));
+    return { freeBytes: s.bavail * s.bsize, totalBytes: s.blocks * s.bsize };
+  } catch {
+    return null;
+  }
+}
+
+async function jobsHealth() {
+  try {
+    const { jobStatus } = require('../jobs');
+    const status = await jobStatus(prisma);
+    const since = Date.now() - DAY;
+    const failed = status.jobs.flatMap(j => j.recent).filter(r => r.state === 'failed' && new Date(r.completedOn || r.startedOn || 0).getTime() > since).length;
+    return { mode: status.mode, failedLast24h: failed };
+  } catch {
+    return null;
+  }
+}
+
+async function lastBackupAt() {
+  try {
+    const backups = await require('../utils/backupUtils').listBackups();
+    return backups[0]?.createdAt ? new Date(backups[0].createdAt).toISOString() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function health() {
+  let db = true;
+  try { await prisma.$queryRawUnsafe('SELECT 1'); } catch { db = false; }
+  const [jobs, backupAt, diskInfo, pending] = await Promise.all([jobsHealth(), lastBackupAt(), disk(), pendingMigrations()]);
+  return {
+    uptimeSeconds: Math.round((Date.now() - STARTED_AT) / 1000),
+    db,
+    jobs,
+    lastBackupAt: backupAt,
+    disk: diskInfo,
+    errorsLast24h: errorCounter.countLast24h(),
+    pendingMigrations: pending,
+  };
+}
+
+async function stats(now = new Date()) {
+  const { campusesEnabled } = require('../utils/campuses');
+  const since = new Date(now.getTime() - 30 * DAY);
+  const realUser = { isActive: true, NOT: [{ email: { endsWith: '@deleted.invalid' } }, { email: { endsWith: '@guest.local' } }] };
+  const [users, activeEvents, upcomingEvents, totalEvents, regs30, regsTotal, tickets30, ticketsTotal, checkIns30, income30, incomeAll, providers] = await Promise.all([
+    prisma.user.count({ where: realUser }),
+    prisma.event.count({ where: { isActive: true, startDate: { lte: now }, endDate: { gte: now } } }),
+    prisma.event.count({ where: { isActive: true, startDate: { gt: now } } }),
+    prisma.event.count(),
+    prisma.registration.count({ where: { createdAt: { gte: since } } }),
+    prisma.registration.count(),
+    prisma.ticket.count({ where: { createdAt: { gte: since } } }),
+    prisma.ticket.count(),
+    prisma.ticketUsage.count({ where: { scannedAt: { gte: since } } }),
+    prisma.payment.aggregate({ where: { createdAt: { gte: since } }, _sum: { amount: true } }),
+    prisma.payment.aggregate({ _sum: { amount: true } }),
+    require('../payments').availableProviders().then(list => list.map(p => p.id)).catch(() => []),
+  ]);
+  const campusesOn = await campusesEnabled().catch(() => false);
+  const campusCount = campusesOn ? await prisma.campus.count({ where: { archivedAt: null } }) : 0;
+  return {
+    users,
+    events: { active: activeEvents, upcoming: upcomingEvents, total: totalEvents },
+    registrations: { last30d: regs30, total: regsTotal },
+    tickets: { last30d: tickets30, total: ticketsTotal },
+    checkIns: { last30d: checkIns30 },
+    // Messages aren't logged one by one, so there's nothing to count yet.
+    messages: null,
+    paymentProviders: providers,
+    campuses: campusesOn,
+    campusCount,
+    income: { last30d: incomeBand(income30._sum.amount), allTime: incomeBand(incomeAll._sum.amount) },
+  };
+}
+
+/** What the install says about itself when registering. */
+async function installInfo() {
+  const { getSetting } = require('../utils/settingsCache');
+  const [name, url, waConfigured, providers, campusesOn] = await Promise.all([
+    getSetting('org_name', ''),
+    getSetting('app_base_url', process.env.FRONTEND_URL || ''),
+    require('../utils/whatsapp').isConfigured().catch(() => false),
+    require('../payments').availableProviders().then(list => list.map(p => p.id)).catch(() => []),
+    require('../utils/campuses').campusesEnabled().catch(() => false),
+  ]);
+  return {
+    name: name || 'Cross Events',
+    url: String(url || process.env.FRONTEND_URL || '').split(',')[0].trim().replace(/\/$/, ''),
+    version: APP_VERSION,
+    timezone: process.env.APP_TIMEZONE || 'Africa/Johannesburg',
+    server: { node: process.versions.node, postgres: await postgresVersion(), os: `${os.platform()} ${os.release()}` },
+    features: { whatsapp: !!waConfigured, paymentProviders: providers, campuses: campusesOn },
+  };
+}
+
+module.exports = { APP_VERSION, incomeBand, health, stats, installInfo };
@@ -131,7 +131,7 @@ const webhookRoutes = require('./routes/webhookRoutes');
 const uploadRoutes = require('./routes/uploadRoutes');
 const reportRoutes = require('./routes/reportRoutes');
 const formRoutes = require('./routes/formRoutes');
-const yocoTransactionRoutes = require('./routes/yocoTransactionRoutes');
+const providerTransactionRoutes = require('./routes/providerTransactionRoutes');
 const automationRoutes = require('./routes/automationRoutes');
 const broadcastRoutes = require('./routes/broadcastRoutes');
 const whatsappBroadcastRoutes = require('./routes/whatsappBroadcastRoutes');
@@ -147,6 +147,8 @@ const statsRoutes     = require('./routes/statsRoutes');
 const adminRoutes     = require('./routes/adminRoutes');
 const backupRoutes    = require('./routes/backupRoutes');
 const yocoRoutes      = require('./routes/yocoRoutes');
+const payfastRoutes   = require('./routes/payfastRoutes');
+const privacyRoutes   = require('./routes/privacyRoutes');

 // Mount webhook routes BEFORE JSON body parser to avoid double-reading the stream
 app.use('/api/webhooks', webhookRoutes);
@@ -154,7 +156,33 @@ app.use('/api/webhooks', webhookRoutes);
 // Apply JSON body parser for all non-webhook routes
 app.use(express.json());

+// Count server errors (any 5xx response) for the Hub heartbeat.
+app.use((req, res, next) => {
+  res.on('finish', () => { if (res.statusCode >= 500) require('./utils/errorCounter').recordError(); });
+  next();
+});
+
+// Licence suspended, revoked or missing: no new or edited events, registrations or payments (src/hub/readOnly.js).
+app.use(require('./hub/readOnly').licenceReadOnly);
+
+// Health for monitoring (and the Hub): no secrets, no personal information.
+app.get('/health', async (req, res) => {
+  const report = require('./hub/report');
+  let db = true;
+  try { await prisma.$queryRaw`SELECT 1`; } catch { db = false; }
+  const health = db ? await report.health().catch(() => null) : null;
+  res.status(db ? 200 : 503).json({
+    status: db ? 'ok' : 'error',
+    version: report.APP_VERSION,
+    db,
+    jobs: health?.jobs || null,
+    lastBackupAt: health?.lastBackupAt || null,
+  });
+});
+
 // Use routes
+app.use('/api/hub', require('./routes/hubRoutes'));
+app.use('/api/campuses', require('./routes/campusRoutes'));
 app.use('/api/users', userRoutes);
 app.use('/api/events', eventRoutes);
 app.use('/api/registrations', registrationRoutes);
@@ -163,7 +191,8 @@ app.use('/api/tickets', ticketRoutes);
 app.use('/api/uploads', uploadRoutes);
 app.use('/api/reports', reportRoutes);
 app.use('/api/forms', formRoutes);
-app.use('/api/yoco-transactions', yocoTransactionRoutes);
+app.use('/api/provider-transactions', providerTransactionRoutes);
+app.use('/api/yoco-transactions', providerTransactionRoutes); // older name
 app.use('/api/automations', automationRoutes);
 app.use('/api/broadcasts', broadcastRoutes);
 app.use('/api/whatsapp-broadcasts', whatsappBroadcastRoutes);
@@ -171,6 +200,7 @@ app.use('/api/scheduled-emails', scheduledEmailRoutes);
 app.use('/api/sections', sectionRoutes);
 app.use('/api/banner',    bannerRoutes);
 app.use('/api/whatsapp', whatsappRoutes);
+app.use('/api/privacy',  privacyRoutes);
 app.use('/api/settings', settingsRoutes);
 app.use('/api/setup',    setupRoutes);
 app.use('/api/stats',    statsRoutes);
@@ -189,6 +219,7 @@ app.use('/api/attendance', require('./routes/attendanceRoutes'));
 app.use('/api/analytics', require('./routes/analyticsRoutes'));
 app.use('/api/backups', backupRoutes);
 app.use('/api/yoco', yocoRoutes);
+app.use('/api/payfast', payfastRoutes);

 // Pre-warm the settings cache so synchronous helpers have DB values from startup
 const { getSettingSync, warmCache } = require('./utils/settingsCache');
@@ -487,13 +518,13 @@ app.get('/docs', async (req, res) => {
        responses:[
          { status:200, desc:'Success', body:{ exists:true, hasEmail:true, hasPhone:false }},
        ]},
-      { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID',
+      { method:'GET', path:'/api/users/:id', auth:'admin', desc:'Get a single user by ID (with scopedCampuses)',
        pathParams:{ ':id':'User UUID' },
        responses:[
          { status:200, desc:'Success', body:{ id:'a1b2c3d4-...', name:'Jane Doe', email:'jane@example.com', role:'user', isActive:true, phoneNumber:'+27821234567', notificationPreference:'email' }},
          { status:404, desc:'Not found', body:{ message:'User not found' }},
        ]},
-      { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role)',
+      { method:'PUT', path:'/api/users/:id', auth:'admin', desc:'Update any user (including role). scopedCampusIds limits a supervisor/staff member to those campuses (empty = every campus; audited)',
        pathParams:{ ':id':'User UUID' },
        request:{ body:{ role:'supervisor', isActive:true, name:'Jane Doe' }},
        responses:[
@@ -508,7 +539,7 @@ app.get('/docs', async (req, res) => {
      { method:'POST', path:'/api/users/:id/revoke-sessions', auth:'admin', desc:'Revoke all sessions for another user',
        pathParams:{ ':id':'User UUID' },
        responses:[{ status:200, desc:'Success', body:{ message:'Sessions revoked for user.' }}]},
-      { method:'POST', path:'/api/users/:id/anonymize', auth:'admin', desc:'Erase personal data for a user — sets name to "Deleted User", email to deleted-{id}@deleted.local, clears phone number, deactivates account, revokes all sessions. Irreversible.',
+      { method:'POST', path:'/api/users/:id/anonymize', auth:'admin', desc:'Erase personal data for a user (POPIA) — the account, the people they registered, form answers, consent details, sponsor names, login history and payer details in provider payloads; payments, registrations and tickets stay as "Deleted User". Refused (409) while they have a registration for an upcoming event. Completes an open deletion request. Irreversible; audited as user_anonymised.',
        pathParams:{ ':id':'User UUID' },
        responses:[
          { status:200, desc:'Anonymised', body:{ message:'User data deleted' }},
@@ -797,12 +828,21 @@ app.get('/docs', async (req, res) => {
    { title: 'Payments', base: '/api/payments', endpoints: [
      { method:'GET', path:'/api/payments/:id', auth:'Bearer', desc:'A payment by id' },
      { method:'GET', path:'/api/payments/registration/:registrationId', auth:'Bearer', desc:'Payments of a registration' },
-      { method:'POST', path:'/api/payments/yoco-checkout/send', auth:'supervisor+', desc:'Send a generated Yoco payment link to the registrant by email or WhatsApp', request:{ body:{ registrationId:'reg-uuid-...', redirectUrl:'https://pay.yoco.com/...', channel:'whatsapp' }}},
+      { method:'POST', path:'/api/payments/checkout/send', auth:'supervisor+', desc:'Send a generated payment link to the registrant by email or WhatsApp (also at /api/payments/yoco-checkout/send)', request:{ body:{ registrationId:'reg-uuid-...', redirectUrl:'https://pay.yoco.com/...', channel:'whatsapp' }}},
+      { method:'GET', path:'/api/payments/providers', auth:'—', desc:'Payment providers people can pay with now (enabled in Site settings → Payments and set up), in display order, plus the online minimum (R15)',
+        responses:[{ status:200, desc:'Success', body:{ providers:[{ id:'yoco', label:'Yoco' }], minimumAmount:15 }}]},
+      { method:'GET', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'The payer\'s page for a checkout: amount, description, providers to choose from, or the PayFast form to post' },
+      { method:'POST', path:'/api/payments/pay/:id', auth:'— (checkout id)', desc:'Start the checkout with the provider the payer picked: { provider } → { redirectUrl } or { form }' },
+      { method:'GET', path:'/api/payments/checkouts/open', auth:'supervisor+', desc:'Online checkouts from the last 14 days with no payment yet, and whether their provider can be asked (canCheck)' },
+      { method:'POST', path:'/api/payments/checkouts/check', auth:'supervisor+', desc:'Ask providers whether checkouts were paid ({ ids? }, default all open) and record what they received. PayFast: transaction history; Yoco: cant_check' },
+      { method:'GET', path:'/api/payments/providers/settings', auth:'admin', desc:'Every provider with enabled, configured and capabilities ({ refund, getTransaction, listTransactions }), in display order' },
+      { method:'PUT', path:'/api/payments/providers/settings', auth:'admin', desc:'Turn providers on/off and set their order (the list order). Audit logged.',
+        request:{ body:{ providers:[{ id:'yoco', enabled:true }] }}},
      { method:'POST', path:'/api/payments/unassign-donation', auth:'supervisor+', desc:'Reverse a donation assignment (removes the leg and reverts the registration status)' },
-      { method:'POST', path:'/api/payments/yoco-checkout', auth:'user+', desc:'Initiate a Yoco checkout session. Before creating the checkout, re-evaluates early-bird tier eligibility (deadline + stock). If any price changed since registration, returns priceUpdated:true instead of creating a checkout — the client must inform the user and retry.',
-        request:{ body:{ registrationId:'reg-uuid-...', amount:450, successUrl:'https://events.example.com/payment/success', cancelUrl:'https://events.example.com/payment/cancel', failureUrl:'https://events.example.com/payment/failure' }},
+      { method:'POST', path:'/api/payments/checkout', auth:'user+', desc:'Start an online checkout (also at /api/payments/yoco-checkout) with body.provider, or the first enabled provider. At least R15 (all providers). Before creating the checkout, re-evaluates early-bird tier eligibility (deadline + stock). If any price changed since registration, returns priceUpdated:true instead of creating a checkout — the client must inform the user and retry.',
+        request:{ body:{ registrationId:'reg-uuid-...', amount:450, provider:'yoco', successUrl:'https://events.example.com/payment/success', cancelUrl:'https://events.example.com/payment/cancel', failureUrl:'https://events.example.com/payment/failure' }},
        responses:[
-          { status:200, desc:'Checkout created — proceed to Yoco', body:{ redirectUrl:'https://pay.yoco.com/checkout/abc123', checkoutId:'yoco-checkout-id', amount:450 }},
+          { status:200, desc:'Checkout created — send the payer to redirectUrl', body:{ redirectUrl:'https://pay.yoco.com/checkout/abc123', checkoutId:'yoco-checkout-id', provider:'yoco', amount:450 }},
          { status:200, desc:'Early-bird price changed — checkout NOT created. Frontend must show warning and let user confirm before retrying.', body:{ priceUpdated:true, newTotal:500, message:'One or more early-bird prices have changed since your registration was created. Please review the updated total before proceeding.' }},
        ]},
      { method:'POST', path:'/api/payments', auth:'supervisor+', desc:'Record a manual payment (cash, EFT, etc.)',
@@ -872,6 +912,97 @@ app.get('/docs', async (req, res) => {
        responses:[{ status:200, desc:'Success', body:[{ eventId:'ev-uuid-...', title:'Camp 2025', totalTickets:50, scanned:38, remaining:12 }]}]},
    ]},

+    { title: 'Hub and licence', base: '/api/hub', endpoints: [
+      { method:'GET', path:'/health', auth:'public', desc:'Status, version, database, background jobs and last backup (503 if the database is down)',
+        responses:[{ status:200, desc:'Healthy', body:{ status:'ok', version:'1.41.0', db:true, jobs:{ mode:'queue', failedLast24h:0 }, lastBackupAt:'2026-10-26T00:00:12.000Z' }}]},
+      { method:'GET', path:'/api/hub/status', auth:'admin', desc:'Licence state (active, grace, suspended, revoked, unlicensed), Hub connection, version and update',
+        responses:[{ status:200, desc:'Success', body:{ state:'grace', readOnly:false, daysLeft:9, connected:true, version:'1.41.0', latestVersion:'1.42.0', updateAvailable:true }}]},
+      { method:'POST', path:'/api/hub/connect', auth:'admin', desc:'Connect to the Cross Events Hub with a licence key (also the /setup licence step)',
+        request:{ body:{ licenceKey:'CEH-7K2M-9QXA-P4RT-WD8C' } },
+        responses:[{ status:200, desc:'Connected (status as above)' }, { status:404, desc:'Unknown key', body:{ code:'LICENCE_NOT_FOUND', message:'That licence key was not found.' }}]},
+      { method:'POST', path:'/api/hub/heartbeat', auth:'admin', desc:'Check in with the Hub now (picks up licence changes)',
+        responses:[{ status:200, desc:'Status' }, { status:502, desc:'Hub unreachable' }]},
+      { method:'POST', path:'/api/hub/update-request', auth:'admin', desc:'Ask the Hub for this site to be updated to the latest version (the provider is told; the site never updates itself)',
+        responses:[{ status:200, desc:'Status, with updateRequest', body:{ updateAvailable:true, updateRequest:{ requestedAt:'2026-10-27T09:00:00.000Z', version:'1.42.0' } }}, { status:409, desc:'Already on the latest version', body:{ code:'UP_TO_DATE', message:'This site already runs the latest version.' }}, { status:502, desc:'Hub unreachable' }]},
+    ]},
+
+    { title: 'Campuses', base: '/api/campuses', endpoints: [
+      { method:'GET', path:'/api/campuses', auth:'Public', desc:'Whether campuses are on, and the active campuses in order (empty while off)',
+        responses:[{ status:200, desc:'Success', body:{ enabled:true, campuses:[{ id:'c_1', name:'Henley Campus', slug:'henley-campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall', order:0 }] }}]},
+      { method:'GET', path:'/api/campuses/by-slug/:slug', auth:'Public', desc:'One active campus, for its /campus/<slug> page (404 when archived or campuses are off)' },
+      { method:'GET', path:'/api/campuses/admin', auth:'admin', desc:'All campuses with archived ones, event and home-campus counts, and daily-summary recipients' },
+      { method:'PUT', path:'/api/campuses/settings', auth:'admin', desc:'Turn campuses on or off (off hides campus fields and filters; nothing is deleted). Audited as campuses_toggled',
+        request:{ body:{ enabled:true } }},
+      { method:'POST', path:'/api/campuses', auth:'admin', desc:'Add a campus (slug made from the name unless given). 409 if the slug is taken',
+        request:{ body:{ name:'Henley Campus', address:'1 Church St', colour:'#1d4ed8', defaultLocation:'Main hall' } }},
+      { method:'PUT', path:'/api/campuses/:id', auth:'admin', desc:'Change a campus, its daily-summary recipients (staff only) and archived state',
+        request:{ body:{ name:'Henley Campus', notifyRecipientIds:['u_1'], archived:false } }},
+      { method:'PUT', path:'/api/campuses/order', auth:'admin', desc:'Put the campuses in this order', request:{ body:{ ids:['c_2','c_1'] } }},
+      { method:'DELETE', path:'/api/campuses/:id', auth:'admin', desc:'Delete a campus with no events (409 CAMPUS_HAS_EVENTS otherwise — archive it)' },
+      { method:'GET', path:'/api/campuses/:id/audience', auth:'supervisor+', desc:'"Everyone at campus X" for broadcasts: home campus X, plus with ?registrants=true people registered for its events in the last 12 months' },
+    ]},
+
+    { title: 'Privacy (POPIA)', base: '/api/privacy', endpoints: [
+      { method:'GET', path:'/api/privacy/me', auth:'user', desc:'My news opt-in, its history, and my privacy requests',
+        responses:[{ status:200, desc:'Success', body:{ news:{ email:true, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z', canWhatsApp:false, notificationPreference:'email', history:[{ channel:'email', granted:true, source:'signup', createdAt:'2026-10-23T08:00:00.000Z' }], requests:[] }}]},
+      { method:'PUT', path:'/api/privacy/me/news', auth:'user', desc:'Change the News & announcements opt-in per channel (source "prompt" for the one-time question after login)',
+        request:{ body:{ email:false, whatsapp:false } },
+        responses:[{ status:200, desc:'Saved', body:{ news:{ email:false, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z' }}]},
+      { method:'GET', path:'/api/privacy/me/export', auth:'user', desc:'Download my data — JSON, or ?format=pdf for a readable PDF. Blocked while impersonating',
+        responses:[{ status:200, desc:'File download' }]},
+      { method:'POST', path:'/api/privacy/me/requests', auth:'user', desc:'Correction request ({ type:"correction", details }) or delete my account ({ type:"deletion", password }) — deletion closes the account at once',
+        request:{ body:{ type:'correction', details:'My son\'s date of birth on the Camp registration is wrong — it should be 3 May 2012.' } },
+        responses:[{ status:201, desc:'Created', body:{ request:{ id:'req-uuid-...', type:'correction', status:'open', dueAt:'2026-11-22T08:00:00.000Z' }, message:'Your request was sent.' }}, { status:409, desc:'Already open', body:{ message:'You already have an open correction request.' }}]},
+      { method:'GET', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'What an unsubscribe link (signed token) is for',
+        responses:[{ status:200, desc:'Success', body:{ kind:'account', email:'jo***@example.com', hasPhone:true, news:{ email:true, whatsapp:true } }}]},
+      { method:'POST', path:'/api/privacy/unsubscribe/:token', auth:'public', desc:'Unsubscribe from news ({ channels?: ["email","whatsapp"] }, default both)',
+        responses:[{ status:200, desc:'Done', body:{ message:'You have been unsubscribed.' }}]},
+      { method:'POST', path:'/api/privacy/unsubscribe/:token/one-click', auth:'public', desc:'RFC 8058 one-click unsubscribe from the List-Unsubscribe email header (email news off)',
+        responses:[{ status:200, desc:'Done' }]},
+      { method:'GET', path:'/api/privacy/requests', auth:'admin', desc:'Data requests inbox (?status=open|closed|all), with due dates and, for deletions, the registrations still blocking it',
+        responses:[{ status:200, desc:'Success', body:{ requests:[{ id:'req-uuid-...', type:'deletion', status:'open', name:'Jane Doe', email:'jane@example.com', dueAt:'2026-11-22T08:00:00.000Z', overdue:false, blockers:[] }], openCount:1 }}]},
+      { method:'POST', path:'/api/privacy/requests/:id/complete', auth:'admin', desc:'Complete a request (emailed to the person). Deletion anonymises the account; 409 while it has a registration for an upcoming event',
+        request:{ body:{ response:'Corrected the date of birth on the Camp 2026 registration.' } },
+        responses:[{ status:200, desc:'Completed', body:{ request:{ status:'completed' }, anonymised:null }}]},
+      { method:'POST', path:'/api/privacy/requests/:id/reject', auth:'admin', desc:'Reject a request, or mark it withdrawn (cancelled:true); a deletion request reopens the account',
+        request:{ body:{ response:'We could not find a registration with that name.', cancelled:false } },
+        responses:[{ status:200, desc:'Closed', body:{ request:{ status:'rejected' } }}]},
+      { method:'GET', path:'/api/privacy/notice', auth:'public', desc:'The privacy notice (current, or ?version=N) with org details and the operator list filled in. Version 0 = built-in, until one is published',
+        responses:[{ status:200, desc:'Success', body:{ version:2, builtIn:false, current:true, effectiveDate:'23 October 2026', changeSummary:'We added WhatsApp news.', sections:[{ id:'introduction', title:'1. Introduction', body:'Hope Church values your privacy…' }], versions:[{ version:2, publishedAt:'2026-10-23T10:00:00.000Z', requiresAcceptance:true }] }}]},
+      { method:'POST', path:'/api/privacy/me/notice/accept', auth:'user', desc:'Accept the current privacy notice version',
+        responses:[{ status:200, desc:'Accepted', body:{ version:2 }}]},
+      { method:'GET', path:'/api/privacy/notice/draft', auth:'admin', desc:'Notice editor: draft (or current) sections, rendered preview, published versions with acceptance counts, built-in text',
+        responses:[{ status:200, desc:'Success', body:{ sections:[], rendered:[], isDraft:false, savedAt:null, versions:[{ version:1, acceptances:12 }] }}]},
+      { method:'PUT', path:'/api/privacy/notice/draft', auth:'admin', desc:'Save the draft ({ sections: [{ id?, title, body }] })',
+        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }] } },
+        responses:[{ status:200, desc:'Saved', body:{ isDraft:true }}]},
+      { method:'DELETE', path:'/api/privacy/notice/draft', auth:'admin', desc:'Discard the draft',
+        responses:[{ status:200, desc:'Discarded', body:{ message:'Draft discarded.' }}]},
+      { method:'POST', path:'/api/privacy/notice/publish', auth:'admin', desc:'Publish the next version; requiresAcceptance asks everyone to accept it after their next login (needs changeSummary)',
+        request:{ body:{ sections:[{ title:'1. Introduction', body:'{org} values your privacy.' }], changeSummary:'We added WhatsApp news.', requiresAcceptance:true } },
+        responses:[{ status:201, desc:'Published', body:{ version:2, requiresAcceptance:true }}]},
+      { method:'GET', path:'/api/privacy/operators', auth:'admin', desc:'The operator register (third parties that process personal information)',
+        responses:[{ status:200, desc:'Success', body:[{ id:'op-uuid-...', name:'PayFast', purpose:'Online payments', dataShared:'Name, email address, payment amount and reference', location:'South Africa', website:'https://payfast.io', active:true }] }]},
+      { method:'POST', path:'/api/privacy/operators', auth:'admin', desc:'Add an operator (PUT/DELETE /api/privacy/operators/:id to change or remove)',
+        request:{ body:{ name:'Mailgun', purpose:'Sending emails', dataShared:'Name, email address, message content', location:'EU' } },
+        responses:[{ status:201, desc:'Created' }]},
+      { method:'GET', path:'/api/privacy/consent-log', auth:'admin', desc:'Consent records: ?type=news|notice|parental, ?q= name/email, ?page=',
+        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', name:'Jane Doe', email:'jane@example.com', channel:'email', granted:false, source:'unsubscribe_link' }] }}]},
+      { method:'GET', path:'/api/privacy/readiness', auth:'admin', desc:'POPIA readiness checklist with a score; each open item has a link to fix it',
+        responses:[{ status:200, desc:'Success', body:{ score:77, passed:10, total:13, checks:[{ key:'notice', label:'Privacy notice published', ok:true, detail:'2 versions published', href:'/dashboard/admin/privacy?tab=notice', applies:true }] }}]},
+      { method:'GET', path:'/api/privacy/retention', auth:'admin', desc:'Retention policies, what the next run would affect, and the last run',
+        responses:[{ status:200, desc:'Success', body:{ policies:{ inactive_accounts:{ enabled:true, months:60 } }, preview:{ inactive_accounts:{ toWarn:3, toAnonymise:0 } }, reviewedAt:null }}]},
+      { method:'PUT', path:'/api/privacy/retention', auth:'admin', desc:'Save the retention policies (all five)',
+        request:{ body:{ policies:{ inactive_accounts:{ enabled:true, months:60 }, form_answers:{ enabled:true, months:12 }, login_history:{ enabled:true, months:24 }, payment_details:{ enabled:true, months:24 }, audit_logs:{ enabled:true, months:60 } } } },
+        responses:[{ status:200, desc:'Saved' }]},
+      { method:'POST', path:'/api/privacy/retention/run', auth:'admin', desc:'Run the retention job now (warn/anonymise inactive accounts, delete expired data)',
+        responses:[{ status:200, desc:'Done', body:{ result:{ inactive_accounts:{ warned:3, anonymised:0, waiting:0 }, login_history:{ deleted:120 } } }}]},
+      { method:'GET', path:'/api/privacy/breaches', auth:'admin', desc:'The breach register (security compromises); POST to record one, PUT /:id to update or mark the Regulator/people told',
+        responses:[{ status:200, desc:'Success', body:[{ id:'br-uuid-...', title:'Phone with the attendee list lost', status:'open', discoveredAt:'2026-10-23T08:00:00.000Z', regulatorNotifiedAt:null }] }]},
+      { method:'GET', path:'/api/privacy/access-log', auth:'admin', desc:'Bulk exports/views of personal information: ?action=, ?actorId=, ?sensitive=true, ?from=, ?to=, ?page=',
+        responses:[{ status:200, desc:'Success', body:{ total:1, pageSize:50, rows:[{ at:'2026-10-23T08:00:00.000Z', actor:'Sam Supervisor', action:'report_pdf', what:'Camp 2026 attendees', records:48 }] }}]},
+    ]},
+
    { title: 'Broadcasts (Email)', base: '/api/broadcasts', endpoints: [
      { method:'POST', path:'/api/broadcasts/preview', auth:'supervisor+', desc:'Dry-run a broadcast — returns resolved recipient list without sending',
        request:{ body:{ userIds:['user-uuid-1','user-uuid-2'], emails:'extra@example.com\nJohn <john@example.com>', eventId:'ev-uuid-...' }},
@@ -1012,19 +1143,20 @@ app.get('/docs', async (req, res) => {
        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'resp-uuid-...', registrationId:'reg-uuid-...', createdAt:'2025-06-01T10:05:00.000Z', answers:[{ field:{ label:'Dietary requirements' }, value:'Vegetarian' }] }], total:1 }}]},
    ]},

-    { title: 'Yoco Transactions', base: '/api/yoco-transactions', endpoints: [
-      { method:'GET', path:'/api/yoco-transactions', auth:'supervisor+', desc:'All Yoco webhook transactions (raw events received from Yoco)',
-        queryParams:{ page:'Page (default 1)', limit:'Per page (default 50)', reconciled:'true|false' },
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'ytx-uuid-...', externalId:'pi_yoco_abc', amount:45000, currency:'ZAR', reconciled:true, paymentId:'pay-uuid-...', createdDate:'2025-06-01T11:00:00.000Z' }], total:1 }}]},
-      { method:'GET', path:'/api/yoco-transactions/unreconciled', auth:'supervisor+', desc:'Transactions not yet matched to a payment record',
-        responses:[{ status:200, desc:'Success', body:{ data:[{ id:'ytx-uuid-...', externalId:'pi_yoco_xyz', amount:45000, currency:'ZAR', reconciled:false }], total:1 }}]},
-      { method:'POST', path:'/api/yoco-transactions/:id/reconcile', auth:'supervisor+', desc:'Manually link a Yoco transaction to an existing payment',
-        pathParams:{ ':id':'YocoTransaction UUID' },
-        request:{ body:{ paymentId:'pay-uuid-...' }},
-        responses:[{ status:200, desc:'Reconciled', body:{ id:'ytx-uuid-...', reconciled:true, paymentId:'pay-uuid-...' }}]},
-      { method:'POST', path:'/api/yoco-transactions/:id/ignore', auth:'supervisor+', desc:'Mark a transaction as intentionally ignored',
-        pathParams:{ ':id':'YocoTransaction UUID' },
-        responses:[{ status:200, desc:'Ignored', body:{ id:'ytx-uuid-...', ignored:true }}]},
+    { title: 'Provider Transactions', base: '/api/provider-transactions', endpoints: [
+      { method:'GET', path:'/api/provider-transactions', auth:'supervisor+', desc:'Transactions payment providers sent by webhook (also at /api/yoco-transactions)',
+        queryParams:{ provider:'yoco', reconciled:'true|false', ignored:'true|false' },
+        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_abc', amount:45000, currency:'ZAR', reconciled:true, paymentId:'pay-uuid-...', createdDate:'2025-06-01T11:00:00.000Z' }] }}]},
+      { method:'GET', path:'/api/provider-transactions/unreconciled', auth:'supervisor+', desc:'Transactions not yet matched to a payment record',
+        queryParams:{ provider:'yoco' },
+        responses:[{ status:200, desc:'Success', body:{ success:true, data:[{ id:'ptx-uuid-...', provider:'yoco', providerLabel:'Yoco', externalId:'pi_yoco_xyz', amount:45000, currency:'ZAR', reconciled:false }] }}]},
+      { method:'POST', path:'/api/provider-transactions/:id/reconcile', auth:'supervisor+', desc:'Record the transaction as a payment on a registration, or as a donation to an event',
+        pathParams:{ ':id':'ProviderTransaction UUID' },
+        request:{ body:{ registrationId:'reg-uuid-...', eventId:'(donation) event-uuid-...', userId:'(donation, optional) user-uuid-...' }},
+        responses:[{ status:200, desc:'Reconciled', body:{ success:true, data:{ transaction:{ id:'ptx-uuid-...', reconciled:true, paymentId:'pay-uuid-...' }, payment:{ id:'pay-uuid-...', provider:'yoco' } } }}]},
+      { method:'POST', path:'/api/provider-transactions/:id/ignore', auth:'supervisor+', desc:'Mark a transaction as intentionally ignored',
+        pathParams:{ ':id':'ProviderTransaction UUID' },
+        responses:[{ status:200, desc:'Ignored', body:{ success:true, data:{ id:'ptx-uuid-...', ignored:true } }}]},
    ]},

    { title: 'WhatsApp Admin', base: '/api/whatsapp', endpoints: [
@@ -1056,7 +1188,7 @@ app.get('/docs', async (req, res) => {
      { method:'GET', path:'/api/stats/staff', auth:'staff+', desc:'Everything the staff dashboard needs, in one call' },
      { method:'GET', path:'/api/stats/supervisor', auth:'supervisor+', desc:'Everything the supervisor dashboard needs, in one call' },
      { method:'GET', path:'/api/stats/admin', auth:'admin', desc:'Everything the admin dashboard needs, in one call' },
-      { method:'GET', path:'/api/stats/overview', auth:'supervisor+', desc:'Trailing-month KPIs (registrations, tickets, revenue, donations), revenue trend, top events, funnel conversion' },
+      { method:'GET', path:'/api/stats/overview', auth:'supervisor+', desc:'Trailing-month KPIs (registrations, tickets, revenue, donations), revenue trend, top events, funnel conversion. ?campus=<id|slug|all> for one campus or church-wide events only' },
    ]},
    { title: 'Backups', base: '/api/backups', endpoints: [
      { method:'GET', path:'/api/backups', auth:'admin', desc:'Local database backups, newest first' },
@@ -1064,6 +1196,7 @@ app.get('/docs', async (req, res) => {
      { method:'GET', path:'/api/backups/:filename/download', auth:'admin', desc:'Download a backup file' },
    ]},
    { title: 'Webhooks', base: '/api/webhooks', endpoints: [
+      { method:'POST', path:'/api/webhooks/payfast', auth:'PayFast ITN', desc:'PayFast payment notification (form-encoded). Checked as PayFast requires: signature, PayFast host, VALID from /eng/query/validate, and amount_gross equal to the checkout (otherwise held for review). COMPLETE records the payment.' },
      { method:'POST', path:'/api/webhooks/yoco', auth:'HMAC', desc:'Yoco payment event webhook. Called by Yoco servers. Verified via HMAC-SHA256 signature in the X-Yoco-Signature header.',
        notes:'This endpoint bypasses the global rate limiter. Raw body is parsed before JSON middleware. Refreshes early-bird pricing before computing totalDue to ensure accurate paid/partial status.',
        request:{ body:{ id:'evt_yoco_abc', type:'payment.succeeded', payload:{ metadata:{ checkoutId:'checkout-id-...' }, amount:45000, currency:'ZAR' }}},
@@ -1072,6 +1205,11 @@ app.get('/docs', async (req, res) => {
        responses:[{ status:200, desc:'Acknowledged', body:{ received:true }}]},
    ]},

+    { title: 'PayFast', base: '/api/payfast', endpoints: [
+      { method:'GET', path:'/api/payfast/config', auth:'admin', desc:'PayFast settings (passphrase masked), mode and the ITN notify URL (with a warning when PayFast can\'t reach it).' },
+      { method:'PUT', path:'/api/payfast/config', auth:'admin', desc:'Save merchantId, merchantKey, passphrase (encrypted) and/or mode (sandbox|live). Audit logged.' },
+      { method:'POST', path:'/api/payfast/test', auth:'admin', desc:'Check the saved merchant ID and passphrase with PayFast (signed API ping).' },
+    ]},
    { title: 'Yoco', base: '/api/yoco', endpoints: [
      { method:'GET', path:'/api/yoco/config', auth:'admin', desc:'Yoco settings with secrets masked (prefix + last 3 characters), where each comes from (db, env or none), test/live mode and the default webhook URL.',
        responses:[{ status:200, desc:'Success', body:{ secretKeyMasked:'sk_test_***************aba', secretKeySource:'db', mode:'test', webhookSecretMasked:'whsec_*****************1Xz', webhookSecretSource:'db', webhookId:'sub_123', webhookUrl:'https://api.example.com/api/webhooks/yoco', configured:true }}]},
@@ -1451,6 +1589,9 @@ app.listen(PORT, () => {
  // backup, temp cleanup) run on the pg-boss job queue — see src/jobs/index.js.
  require('./jobs').startJobs().catch(e => console.warn('[jobs] Not started:', e?.message || e));

+  // Check in with the Hub 30 s after starting, so the licence is fresh without waiting 15 minutes.
+  require('./hub/client').heartbeatSoon();
+
  // Scheduled emails worker (polling)
  try {
    const enabled = String(process.env.SCHEDULED_EMAILS_ENABLED || 'true').toLowerCase() !== 'false';
@@ -29,6 +29,10 @@ const JOBS = [
    name: 'waitlist', label: 'Waitlist: expire offers, offer freed places', cron: '*/10 * * * *', env: 'WAITLIST_JOB_ENABLED',
    run: () => require('../utils/waitlist').runWaitlistJob(),
  },
+  {
+    name: 'payment-status', label: 'Payments: check providers for notifications that never arrived', cron: '*/15 * * * *', env: 'PAYMENT_STATUS_JOB_ENABLED',
+    run: () => require('../payments/status').runPaymentStatusJob(),
+  },
  {
    name: 'feedback', label: 'Post-event feedback forms and reminders', cron: '*/15 * * * *', env: 'FEEDBACK_JOB_ENABLED',
    run: () => require('../utils/feedback').runFeedbackJob(),
@@ -48,6 +52,18 @@ const JOBS = [
      return { reminded: await sendConsentReminders(new Date()), purged: await purgeConsentMedicalData(new Date()) };
    },
  },
+  {
+    name: 'privacy', label: 'Privacy requests: remind admins of requests due soon', cron: '0 8 * * *', env: 'PRIVACY_JOBS_ENABLED',
+    run: () => require('../utils/privacy').remindDueRequests(new Date()),
+  },
+  {
+    name: 'hub-heartbeat', label: 'Cross Events Hub: heartbeat and licence refresh', cron: '*/15 * * * *', env: 'HUB_HEARTBEAT_ENABLED',
+    run: () => require('../hub/client').heartbeat(),
+  },
+  {
+    name: 'retention', label: 'Retention: delete or anonymise personal information past its retention period', cron: '30 3 * * *', env: 'RETENTION_JOBS_ENABLED',
+    run: () => require('../utils/retention').runRetention(new Date()),
+  },
  {
    name: 'analytics-rollup', label: 'Funnel analytics: roll up visits older than 90 days', cron: '15 4 * * *', env: 'ANALYTICS_ROLLUP_ENABLED',
    run: async () => ({ rolledUp: await require('../utils/analytics').rollupOldEvents() }),
@@ -231,8 +247,14 @@ async function runNow(name) {
 async function jobStatus(prisma) {
  const recent = new Map();
  if (mode === 'queue') {
+    // pg-boss columns are timestamptz, and Prisma's pg adapter drops their offset in raw queries
+    // (10:55+02 came back as 10:55Z). As plain UTC timestamps they come back right.
    const rows = await prisma.$queryRawUnsafe(`
-      SELECT name, state, created_on AS "createdOn", started_on AS "startedOn", completed_on AS "completedOn", output
+      SELECT name, state,
+             created_on AT TIME ZONE 'UTC' AS "createdOn",
+             started_on AT TIME ZONE 'UTC' AS "startedOn",
+             completed_on AT TIME ZONE 'UTC' AS "completedOn",
+             output
      FROM (
        SELECT name, state, created_on, started_on, completed_on, output,
               row_number() OVER (PARTITION BY name ORDER BY created_on DESC) AS rn
@@ -0,0 +1,96 @@
+/**
+ * Online checkouts for registrations (the balance, part of it, or the balance plus a
+ * donation). Used by the payment pages, payment links in emails and invoices, and the
+ * self-service kiosk. The provider is the one asked for, the only available one, or the
+ * payer's choice on /pay/<id> (./index.js); the registration remembers the checkout so the
+ * webhook can find it.
+ */
+
+const prisma = require('../config/db');
+const { computeRegistrationTotalDue } = require('../utils/pricing');
+const payments = require('./index');
+
+const CHECKOUT_INCLUDE = {
+  registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, variant: true, tranches: true } },
+  payments: true,
+  couponRedemptions: { where: { releasedAt: null }, include: { coupon: { select: { code: true } } } },
+  bundleApplications: { include: { bundle: { select: { name: true } } } },
+  user: { select: { id: true, name: true, email: true } },
+  event: true,
+};
+
+/**
+ * The checkout's line items for a registration: one per line (with its tranches' prices),
+ * then bundle savings and the coupon discount as deductions. Callers add payment lines.
+ * @returns {{ name: string, quantity: number, unitCents: number }[]}
+ */
+function registrationLineItems(registration) {
+  const { buildLineItems, discountLines } = require('../utils/pdfDocs');
+  const items = buildLineItems(registration.registrationOptions).map(row => ({
+    name: row.label + (row.isEarlyBird ? ' (early bird)' : ''),
+    quantity: row.quantity,
+    unitCents: Math.round(row.unitPrice * 100),
+  }));
+  for (const line of discountLines(registration)) items.push({ name: line.label, quantity: 1, unitCents: -Math.round(line.amount * 100) });
+  return items;
+}
+
+/**
+ * Starts a checkout for a registration. Doesn't check who's asking — callers do.
+ * @param {object} opts
+ * @param {number} [opts.amount] - pay only this much of the balance (at least the online minimum)
+ * @param {number} [opts.donationAmount] - added on top as its own line; the webhook records it
+ *   as a separate donation (it travels in the checkout metadata)
+ * @param {string} [opts.provider] - payment provider id (default: first available)
+ * @returns {Promise<{ checkoutId, redirectUrl, provider, amount, registration }>}
+ */
+async function createRegistrationCheckout(registrationId, userId, { successUrl, cancelUrl, failureUrl, donationAmount = 0, amount = null, provider = null } = {}) {
+  const registration = await prisma.registration.findUnique({ where: { id: registrationId }, include: CHECKOUT_INCLUDE });
+  if (!registration) throw payments.paymentError('Registration not found', 404);
+
+  const totalDue = computeRegistrationTotalDue(registration, new Date());
+  const totalPaid = registration.payments.reduce((sum, p) => sum + p.amount, 0);
+  const remaining = totalDue - totalPaid;
+  if (remaining <= 0) throw payments.paymentError('This registration is already paid in full');
+
+  let charge = remaining;
+  if (amount !== null && amount !== undefined) {
+    const requested = parseFloat(amount);
+    if (!(requested > 0)) throw payments.paymentError('Amount must be greater than 0');
+    charge = Math.min(requested, remaining);
+  }
+
+  const donationCents = Math.round((Number(donationAmount) || 0) * 100);
+  const chargeCents = Math.round(charge * 100);
+  const lineItems = registrationLineItems(registration);
+  if (totalPaid > 0) lineItems.push({ name: 'Previous Payments', quantity: 1, unitCents: -Math.round(totalPaid * 100) });
+  // Paying part of the balance: the rest is deferred to a later payment
+  if (charge < remaining) lineItems.push({ name: 'Partial Payment', quantity: 1, unitCents: -Math.round((remaining - charge) * 100) });
+  if (donationCents > 0) lineItems.push({ name: 'Donation', quantity: 1, unitCents: donationCents });
+
+  const amountCents = chargeCents + donationCents;
+  const checkout = await payments.createCheckout(provider, {
+    amountCents,
+    metadata: {
+      registrationId, userId, eventId: registration.eventId, eventTitle: registration.event.title, type: 'registration_payment',
+      ...(donationCents > 0 ? { donationAmount: (donationCents / 100).toFixed(2) } : {}),
+    },
+    lineItems,
+    successUrl, cancelUrl, failureUrl,
+    payer: { name: registration.user?.name || '', email: registration.user?.email || '' },
+    description: registration.event.title,
+    idempotencyKey: `reg_${registrationId}_${amountCents}_${Date.now()}`,
+  });
+
+  await prisma.registration.update({ where: { id: registrationId }, data: { checkoutId: checkout.checkoutId, updatedAt: new Date() } });
+
+  return {
+    checkoutId: checkout.checkoutId,
+    redirectUrl: checkout.redirectUrl,
+    provider: checkout.provider,
+    amount: amount !== null && amount !== undefined ? charge : amountCents / 100,
+    registration: { id: registration.id, eventId: registration.eventId, eventTitle: registration.event.title },
+  };
+}
+
+module.exports = { createRegistrationCheckout, registrationLineItems };
@@ -0,0 +1,178 @@
+/**
+ * Online payment providers.
+ *
+ * Every provider implements the same interface (see providers/yoco.js, providers/payfast.js):
+ *   id, label
+ *   capabilities          { refund, getTransaction, listTransactions } — what its API supports
+ *   isConfigured()        → Promise<boolean>   credentials are set
+ *   createCheckout(input) → Promise<{ externalId?, redirectUrl? } | { form: { action, fields } }>
+ *                           input: { checkoutId, amountCents, currency, metadata, lineItems,
+ *                           successUrl, cancelUrl, failureUrl, payer?, description,
+ *                           idempotencyKey }; lineItems: [{ name, quantity, unitCents }]
+ *                           (negative unitCents = a deduction). A provider that takes the
+ *                           payer with a signed form (PayFast) returns { form }; the payer's
+ *                           browser posts it from /pay/<checkoutId>.
+ *   verifyWebhook(req)    → Promise<{ ok: true } | { ok: false, status, message, details? }>
+ *   parseWebhook(body)    → { type: 'payment.succeeded' | <other>, transaction }
+ *                           body: the request body as the provider sent it (JSON or form)
+ *                           transaction: { externalId, amountCents, currency, createdDate,
+ *                           checkoutId, methodType, metadata, status }
+ *   readWebhookBody(raw)  → (optional) turns req.rawBody into the body; default JSON.parse
+ *   getTransaction / refund / listTransactions — only when the capability is true
+ *
+ * Every checkout is recorded as a ProviderCheckout (amount, what it's for, return URLs), so
+ * the payment that comes back can be matched and checked, and so the payer can be sent to
+ * /pay/<id>: there they choose a provider when several are enabled, or their browser posts a
+ * provider's form. Admins switch providers on and off and set their order in Site settings →
+ * Payments (AppSetting `payment_providers`). Provider fees are never deducted or added:
+ * payments are recorded at the full amount and fees are handled at cashup.
+ */
+
+const prisma = require('../config/db');
+const { getSetting } = require('../utils/settingsCache');
+
+const PROVIDERS = [require('./providers/yoco'), require('./providers/payfast')];
+const BY_ID = new Map(PROVIDERS.map(p => [p.id, p]));
+
+// One minimum for every provider: online payments must be at least R15.
+const MIN_ONLINE_AMOUNT = 15;
+const SETTINGS_KEY = 'payment_providers';
+
+function paymentError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/** A provider by id, or null. */
+function getProvider(id) {
+  return BY_ID.get(String(id || '')) || null;
+}
+
+/**
+ * Enabled flags and order from the stored setting. Pure. Unknown ids are dropped; providers
+ * not in the setting yet come last — Yoco enabled (it was the only provider before), others off.
+ * @param {string} raw - JSON: { order: string[], enabled: { [id]: boolean } }
+ * @param {string[]} [ids] - known provider ids, in default order
+ * @returns {{ id: string, enabled: boolean }[]}
+ */
+function parseProviderSettings(raw, ids = PROVIDERS.map(p => p.id)) {
+  let stored = {};
+  try { stored = raw ? JSON.parse(raw) : {}; } catch { stored = {}; }
+  const order = Array.isArray(stored.order) ? stored.order.filter(id => ids.includes(id)) : [];
+  const all = [...new Set([...order, ...ids])];
+  const enabled = stored.enabled && typeof stored.enabled === 'object' ? stored.enabled : {};
+  return all.map(id => ({ id, enabled: typeof enabled[id] === 'boolean' ? enabled[id] : id === 'yoco' }));
+}
+
+/** Every provider with its settings and whether it's configured, in display order. */
+async function providerSettings() {
+  const list = parseProviderSettings(await getSetting(SETTINGS_KEY));
+  return Promise.all(list.map(async ({ id, enabled }) => {
+    const p = getProvider(id);
+    return { id, label: p.label, enabled, configured: await p.isConfigured(), capabilities: p.capabilities };
+  }));
+}
+
+/** Providers people can pay with now (enabled and configured), in display order. */
+async function availableProviders() {
+  return (await providerSettings()).filter(p => p.enabled && p.configured);
+}
+
+/** The setting value to store for an ordered list of { id, enabled }. */
+function serializeProviderSettings(list) {
+  const ids = list.map(p => p.id).filter(id => getProvider(id));
+  return JSON.stringify({ order: ids, enabled: Object.fromEntries(list.filter(p => getProvider(p.id)).map(p => [p.id, p.enabled === true])) });
+}
+
+/** The payer's page for a checkout: /pay/<id> on the frontend. */
+function payPageUrl(checkoutId) {
+  const base = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3000').split(',')[0].trim().replace(/\/$/, '');
+  return `${base}/pay/${encodeURIComponent(checkoutId)}`;
+}
+
+/** Throws unless `provider` may take payments now (enabled; and set up, or it explains). */
+async function assertUsable(provider) {
+  const state = (await providerSettings()).find(p => p.id === provider.id);
+  if (!state?.enabled) throw paymentError(`Paying with ${provider.label} is turned off.`);
+}
+
+/**
+ * Starts a recorded checkout with a provider. Idempotent for a provider that was already
+ * started with a redirect (Yoco); form providers rebuild their (deterministic) form.
+ * @returns {Promise<{ provider, redirectUrl, form? }>}
+ */
+async function startCheckout(checkout, provider) {
+  if (checkout.provider === provider.id && checkout.redirectUrl) return { provider: provider.id, redirectUrl: checkout.redirectUrl };
+  const request = checkout.request || {};
+  const started = await provider.createCheckout({
+    ...request,
+    checkoutId: checkout.id,
+    amountCents: checkout.amountCents,
+    currency: checkout.currency,
+    metadata: checkout.metadata,
+  });
+  if (started.form) {
+    if (checkout.provider !== provider.id) await prisma.providerCheckout.update({ where: { id: checkout.id }, data: { provider: provider.id } });
+    return { provider: provider.id, redirectUrl: payPageUrl(checkout.id), form: started.form };
+  }
+  await prisma.providerCheckout.update({
+    where: { id: checkout.id },
+    data: { provider: provider.id, externalId: started.externalId || null, redirectUrl: started.redirectUrl },
+  });
+  return { provider: provider.id, redirectUrl: started.redirectUrl };
+}
+
+/**
+ * Starts a checkout with `providerId`, or the only available provider; with several
+ * available, the payer chooses on /pay/<id>.
+ * @param {object} input - { amountCents, metadata, lineItems, successUrl, cancelUrl, failureUrl,
+ *   payer?: { name, email }, description?, idempotencyKey? }
+ * @returns {Promise<{ checkoutId, redirectUrl, provider: string|null }>}
+ */
+async function createCheckout(providerId, input) {
+  if (!(input.amountCents >= MIN_ONLINE_AMOUNT * 100)) {
+    throw paymentError(`Online payments must be at least R${MIN_ONLINE_AMOUNT}. Please pay at the door or contact the organiser.`);
+  }
+  let provider = null;
+  const available = await availableProviders();
+  if (providerId) {
+    provider = getProvider(providerId);
+    if (!provider) throw paymentError('Unknown payment provider.');
+    await assertUsable(provider);
+  } else if (available.length === 1) {
+    provider = getProvider(available[0].id);
+  } else if (available.length === 0) {
+    // Nothing enabled: say so. Enabled but not set up: the provider explains what's missing.
+    const enabled = (await providerSettings()).find(p => p.enabled);
+    if (!enabled) throw paymentError('Online payments are turned off. Please pay at the door or contact the organiser.', 503);
+    provider = getProvider(enabled.id);
+  }
+
+  const { amountCents, metadata, currency, ...request } = input;
+  const checkout = await prisma.providerCheckout.create({
+    data: { amountCents, currency: currency || 'ZAR', metadata: metadata || {}, request },
+  });
+  if (!provider) return { checkoutId: checkout.id, redirectUrl: payPageUrl(checkout.id), provider: null };
+  try {
+    const started = await startCheckout(checkout, provider);
+    return { checkoutId: checkout.id, redirectUrl: started.redirectUrl, provider: started.provider };
+  } catch (e) {
+    await prisma.providerCheckout.delete({ where: { id: checkout.id } }).catch(() => {});
+    throw e;
+  }
+}
+
+/** The checkout a webhook is about: by our id, or by the provider's own checkout id. */
+async function findCheckout(providerId, ref) {
+  if (!ref) return null;
+  const ours = await prisma.providerCheckout.findUnique({ where: { id: String(ref) } }).catch(() => null);
+  if (ours) return ours;
+  return prisma.providerCheckout.findFirst({ where: { provider: providerId, externalId: String(ref) } });
+}
+
+module.exports = {
+  PROVIDERS, MIN_ONLINE_AMOUNT, SETTINGS_KEY, paymentError,
+  getProvider, parseProviderSettings, serializeProviderSettings, providerSettings, availableProviders,
+  payPageUrl, assertUsable, createCheckout, startCheckout, findCheckout,
+};
@@ -0,0 +1,303 @@
+/**
+ * PayFast as a payment provider (see ../index.js for the interface), using PayFast's
+ * "custom integration" (developers.payfast.co.za/docs → Custom Integration).
+ *
+ * Checkout: the payer's browser posts a signed form to https://<host>/eng/process (from our
+ * /pay/<checkoutId> page). Fields go in the order PayFast lists them; the signature is the MD5
+ * of the non-blank fields as name=value pairs (URL-encoded, upper-case escapes, spaces as '+')
+ * joined with '&', plus &passphrase=… when one is set.
+ *
+ * ITN (Instant Transaction Notification): PayFast posts the result, form-encoded, to
+ * /api/webhooks/payfast. Before trusting it we check, as PayFast requires: the signature, that
+ * it came from a PayFast host, and — by posting it back to /eng/query/validate — that PayFast
+ * says it's VALID. The amount is checked against the checkout in ../webhook.js.
+ *
+ * Status checks: when an ITN never arrives, findPayments looks the checkout up in PayFast's
+ * transaction history (its API, signed differently — see apiSignature). Refunds aren't done
+ * through the API: they're made in the PayFast dashboard and recorded with the manual flow.
+ */
+
+const crypto = require('crypto');
+const dns = require('dns').promises;
+const axios = require('axios');
+const { getPayfastConfig, payfastHost, payfastNotifyUrl } = require('../../utils/payfast');
+
+// getTransaction: payments can be looked up in PayFast's transaction history (findPayments).
+const capabilities = { refund: false, getTransaction: true, listTransactions: false };
+
+// Hosts PayFast sends ITNs from.
+const VALID_HOSTS = ['www.payfast.co.za', 'w1w.payfast.co.za', 'w2w.payfast.co.za', 'sandbox.payfast.co.za'];
+
+async function isConfigured() {
+  const c = await getPayfastConfig();
+  return !!(c.merchantId && c.merchantKey);
+}
+
+/**
+ * URL-encodes a value the way PayFast's signature expects (PHP urlencode): every character
+ * but letters, digits and -_. is %-escaped in upper case, and spaces become '+'. Checked
+ * against the sandbox: PayFast's own Node sample, which leaves ' ( ) ! * ~ as they are, is
+ * rejected for names like "Men's Camp (Youth)"; this is accepted.
+ */
+function pfEncode(value) {
+  return encodeURIComponent(String(value).trim())
+    .replace(/[!'()*~]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+    .replace(/%20/g, '+');
+}
+
+/**
+ * name=value&… of the pairs, in order. Pure. A checkout signs only the non-blank fields; an
+ * ITN is checked over every field PayFast posted, blanks included (`allFields`).
+ */
+function paramString(pairs, { allFields = false } = {}) {
+  const keep = allFields ? pairs : pairs.filter(([, v]) => v !== undefined && v !== null && String(v).trim() !== '');
+  return keep.map(([k, v]) => `${k}=${pfEncode(v ?? '')}`).join('&');
+}
+
+/** PayFast's MD5 signature over ordered pairs (and the passphrase, if any). Pure. */
+function signature(pairs, passphrase = '', opts = {}) {
+  let s = paramString(pairs, opts);
+  if (passphrase) s += `&passphrase=${pfEncode(passphrase)}`;
+  return crypto.createHash('md5').update(s).digest('hex');
+}
+
+/** Text we send PayFast (item and payer names): one line, within PayFast's length limit. Pure. */
+function cleanText(value, max) {
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/** "Camp ticket x2, T-shirt" → the item description (charged lines only). Pure. */
+function describeLines(lineItems) {
+  return (lineItems || []).filter(l => l.unitCents > 0).map(l => `${l.name}${l.quantity > 1 ? ` x${l.quantity}` : ''}`).join(', ');
+}
+
+async function createCheckout({ checkoutId, amountCents, successUrl, cancelUrl, payer, description, lineItems }) {
+  const c = await getPayfastConfig();
+  if (!c.merchantId || !c.merchantKey) {
+    const err = new Error('PayFast isn\'t set up. An admin needs to add the merchant ID and key in Site Settings → Payments → PayFast.');
+    err.statusCode = 503;
+    throw err;
+  }
+  const notifyUrl = payfastNotifyUrl();
+  const [first, ...rest] = String(payer?.name || '').trim().split(/\s+/);
+  const email = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(String(payer?.email || '')) && !String(payer.email).endsWith('.local') && !String(payer.email).endsWith('.invalid') ? payer.email : '';
+  const items = describeLines(lineItems);
+  // In the order PayFast documents them — the signature depends on it.
+  const pairs = [
+    ['merchant_id', c.merchantId],
+    ['merchant_key', c.merchantKey],
+    ['return_url', successUrl],
+    ['cancel_url', cancelUrl],
+    ['notify_url', notifyUrl],
+    ['name_first', cleanText(first, 100)],
+    ['name_last', cleanText(rest.join(' '), 100)],
+    ['email_address', email],
+    ['m_payment_id', checkoutId],
+    ['amount', (amountCents / 100).toFixed(2)],
+    ['item_name', cleanText(description || items || 'Payment', 100)],
+    ['item_description', cleanText(items, 255)],
+  ].filter(([, v]) => v !== undefined && v !== null && String(v).trim() !== '');
+  const fields = Object.fromEntries(pairs.map(([k, v]) => [k, String(v).trim()]));
+  fields.signature = signature(pairs, c.passphrase);
+  return { form: { action: `https://${payfastHost(c.mode)}/eng/process`, fields } };
+}
+
+/** The ITN's name/value pairs, decoded, in the order PayFast sent them. Pure. */
+function parsePairs(rawBody) {
+  return String(rawBody || '').split('&').filter(Boolean).map(kv => {
+    const i = kv.indexOf('=');
+    const dec = (s) => decodeURIComponent(s.replace(/\+/g, ' '));
+    return i < 0 ? [dec(kv), ''] : [dec(kv.slice(0, i)), dec(kv.slice(i + 1))];
+  });
+}
+
+function readWebhookBody(rawBody) {
+  return Object.fromEntries(parsePairs(rawBody));
+}
+
+/** The caller's IP, without IPv4-mapped-IPv6 noise (needs TRUST_PROXY behind a proxy). */
+function requestIp(req) {
+  return String(req.ip || req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
+}
+
+async function payfastIps() {
+  const all = await Promise.all(VALID_HOSTS.map(h => dns.lookup(h, { all: true }).catch(() => [])));
+  return new Set(all.flat().map(a => a.address));
+}
+
+/** PayFast's four ITN checks, less the amount (checked against the checkout in ../webhook.js). */
+async function verifyWebhook(req, { lookupIps = payfastIps, post = axios.post } = {}) {
+  const pairs = parsePairs(req.rawBody);
+  const data = Object.fromEntries(pairs);
+  if (!data.signature || !data.pf_payment_id) return { ok: false, status: 400, message: 'Not a PayFast notification' };
+
+  const c = await getPayfastConfig();
+  if (!c.merchantId) return { ok: false, status: 500, message: 'PayFast isn\'t set up' };
+  if (data.merchant_id && data.merchant_id !== c.merchantId) return { ok: false, status: 403, message: 'Notification for a different PayFast merchant' };
+
+  // 1. Signature: every posted field before the signature, in order, plus our passphrase.
+  const signed = [];
+  for (const pair of pairs) { if (pair[0] === 'signature') break; signed.push(pair); }
+  if (signature(signed, c.passphrase, { allFields: true }) !== data.signature) {
+    console.error('PayFast ITN: invalid signature');
+    return { ok: false, status: 403, message: 'Invalid signature' };
+  }
+
+  // 2. It came from PayFast.
+  if (process.env.PAYFAST_SKIP_IP_CHECK !== 'true') {
+    const ip = requestIp(req);
+    if (!(await lookupIps()).has(ip)) {
+      console.error(`PayFast ITN from ${ip}, which isn't a PayFast address (behind a proxy? set TRUST_PROXY)`);
+      return { ok: false, status: 403, message: 'Notification did not come from PayFast' };
+    }
+  }
+
+  // 3. PayFast confirms the details.
+  let reply = '';
+  try {
+    const res = await post(`https://${payfastHost(c.mode)}/eng/query/validate`, paramString(signed, { allFields: true }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, timeout: 15000 });
+    reply = String(res.data || '').trim();
+  } catch (e) {
+    console.error('PayFast ITN: could not confirm with PayFast:', e.message);
+    return { ok: false, status: 502, message: 'Could not confirm the notification with PayFast' };
+  }
+  if (reply !== 'VALID') {
+    console.error('PayFast ITN: PayFast did not confirm it:', reply.slice(0, 100));
+    return { ok: false, status: 403, message: 'PayFast did not confirm the notification' };
+  }
+
+  return { ok: true, webhookId: data.pf_payment_id, timestamp: null };
+}
+
+/** An ITN body → { type, transaction }. Pure. */
+function parseWebhook(body) {
+  const status = String(body?.payment_status || '').toUpperCase();
+  const gross = parseFloat(body?.amount_gross);
+  return {
+    type: status === 'COMPLETE' ? 'payment.succeeded' : `payment.${status.toLowerCase() || 'unknown'}`,
+    transaction: {
+      externalId: body?.pf_payment_id || null,
+      amountCents: Number.isFinite(gross) ? Math.round(gross * 100) : null,
+      currency: 'ZAR',
+      createdDate: null,
+      checkoutId: body?.m_payment_id || null,
+      // PayFast doesn't say how the payer paid; it settles like a card payment.
+      methodType: null,
+      metadata: {},
+      status: status === 'COMPLETE' ? 'succeeded' : status.toLowerCase(),
+    },
+  };
+}
+
+// ─── PayFast API (developers.payfast.co.za/api) ──────────────────────────────
+
+const API_BASE = 'https://api.payfast.co.za';
+
+/**
+ * The API signature: every header and query variable plus the passphrase, sorted
+ * alphabetically, URL-encoded, joined with '&' (not the payment form's field order). Pure.
+ */
+function apiSignature(vars) {
+  const s = Object.keys(vars).sort()
+    .filter(k => vars[k] !== undefined && vars[k] !== null && String(vars[k]) !== '')
+    .map(k => `${k}=${pfEncode(vars[k])}`).join('&');
+  return crypto.createHash('md5').update(s).digest('hex');
+}
+
+/** A signed GET to the PayFast API; the sandbox adds ?testing=true (left out of the signature). */
+async function apiGet(path, query = {}, { get = axios.get } = {}) {
+  const c = await getPayfastConfig();
+  const headers = { 'merchant-id': c.merchantId, version: 'v1', timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, '+00:00') };
+  const signature = apiSignature({ ...headers, ...query, ...(c.passphrase ? { passphrase: c.passphrase } : {}) });
+  const params = { ...query, ...(c.mode === 'live' ? {} : { testing: 'true' }) };
+  try {
+    const res = await get(`${API_BASE}${path}`, { params, headers: { ...headers, signature }, timeout: 20000, responseType: 'text', transformResponse: r => r });
+    return res.data;
+  } catch (e) {
+    const status = e.response?.status;
+    let detail = '';
+    try { detail = JSON.parse(e.response?.data || '{}')?.data?.response || ''; } catch { /* not JSON */ }
+    const err = new Error(status === 401
+      ? 'PayFast refused the merchant ID or passphrase (check they match your PayFast dashboard, and the mode).'
+      : `Could not reach PayFast${detail ? `: ${detail}` : status ? ` (${status})` : `: ${e.message}`}`);
+    err.statusCode = status === 401 ? 400 : 502;
+    throw err;
+  }
+}
+
+/** Checks the credentials with PayFast (GET /ping, signed). */
+async function testConnection(deps) {
+  await apiGet('/ping', {}, deps);
+  return true;
+}
+
+/** Rows of a CSV with a header line, as objects keyed by the header. Pure. */
+function parseCsv(text) {
+  const rows = [];
+  let row = [], field = '', quoted = false;
+  const s = String(text || '');
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quoted) {
+      if (ch === '"' && s[i + 1] === '"') { field += '"'; i++; }
+      else if (ch === '"') quoted = false;
+      else field += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === ',') { row.push(field); field = ''; }
+    else if (ch === '\n' || ch === '\r') {
+      if (ch === '\r' && s[i + 1] === '\n') i++;
+      row.push(field); field = '';
+      if (row.some(v => v !== '')) rows.push(row);
+      row = [];
+    } else field += ch;
+  }
+  row.push(field);
+  if (row.some(v => v !== '')) rows.push(row);
+  const [header, ...data] = rows;
+  return header ? data.map(r => Object.fromEntries(header.map((h, i) => [h, r[i] ?? '']))) : [];
+}
+
+const day = (d) => new Date(d).toISOString().slice(0, 10);
+
+/**
+ * Payments PayFast received for our checkouts (from its transaction history, matched on
+ * "M Payment ID" = our checkout id). For notifications (ITNs) that never arrived.
+ * @param {object[]} checkouts - ProviderCheckout rows
+ * @returns {Promise<Map<string, object>>} checkout id → transaction (as parseWebhook gives)
+ */
+async function findPayments(checkouts, deps) {
+  const found = new Map();
+  if (!checkouts.length) return found;
+  const ids = new Set(checkouts.map(c => c.id));
+  const from = day(Math.min(...checkouts.map(c => new Date(c.createdAt).getTime())) - 24 * 60 * 60 * 1000);
+  const to = day(Date.now() + 24 * 60 * 60 * 1000);
+  const PAGE = 1000;
+  for (let offset = 0; offset < 20 * PAGE; offset += PAGE) {
+    const rows = parseCsv(await apiGet('/transactions/history', { from, to, limit: PAGE, offset }, deps));
+    for (const r of rows) {
+      const id = r['M Payment ID'];
+      if (!ids.has(id) || r.Type !== 'FUNDS_RECEIVED' || found.has(id)) continue;
+      const gross = parseFloat(String(r.Gross).replace(/,/g, ''));
+      found.set(id, {
+        externalId: r['PF Payment ID'] || null,
+        amountCents: Number.isFinite(gross) ? Math.round(gross * 100) : null,
+        currency: r.Currency || 'ZAR',
+        // PayFast's history times are South African time
+        createdDate: r.Date ? new Date(`${r.Date.replace(' ', 'T')}+02:00`) : null,
+        checkoutId: id,
+        methodType: null,
+        metadata: {},
+        status: 'succeeded',
+      });
+    }
+    if (rows.length < PAGE || found.size === ids.size) break;
+  }
+  return found;
+}
+
+module.exports = {
+  id: 'payfast', label: 'PayFast', capabilities,
+  isConfigured, createCheckout, verifyWebhook, parseWebhook, readWebhookBody, findPayments, testConnection,
+  // for tests
+  pfEncode, paramString, signature, cleanText, parsePairs, VALID_HOSTS, apiSignature, parseCsv,
+};
@@ -0,0 +1,107 @@
+/**
+ * Yoco as a payment provider (see ../index.js for the interface).
+ *
+ * Checkouts: POST /checkouts on the Yoco Checkout API; Yoco redirects the payer back and
+ * posts a `payment.succeeded` webhook to /api/webhooks/yoco. Webhooks are signed with the
+ * webhook secret (Standard Webhooks: HMAC-SHA256 over "id.timestamp.body").
+ * Keys and webhooks are managed in Site settings → Payments → Yoco (utils/yoco.js).
+ * Refunds and transaction lookups aren't done through Yoco's API here: refunds are made in
+ * the Yoco portal and recorded with the manual refund flow.
+ */
+
+const crypto = require('crypto');
+const { getYocoSecretKey, getYocoWebhookSecret, yocoRequest } = require('../../utils/yoco');
+
+// Yoco recommends rejecting webhooks more than 3 minutes old (replays).
+const WEBHOOK_TOLERANCE_MS = 3 * 60 * 1000;
+
+const capabilities = { refund: false, getTransaction: false, listTransactions: false };
+
+async function isConfigured() {
+  return !!(await getYocoSecretKey());
+}
+
+/** Our line items → Yoco's (amounts in cents; a negative price is a deduction line). */
+function toYocoLineItems(lineItems) {
+  return (lineItems || []).map(l => ({ displayName: l.name, quantity: l.quantity, pricingDetails: { price: l.unitCents } }));
+}
+
+async function createCheckout({ amountCents, currency, metadata, lineItems, successUrl, cancelUrl, failureUrl, idempotencyKey }) {
+  const data = await yocoRequest('post', '/checkouts', {
+    amount: amountCents, currency, metadata, successUrl, cancelUrl, failureUrl, lineItems: toYocoLineItems(lineItems),
+  }, undefined, idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {});
+  return { externalId: data.id, redirectUrl: data.redirectUrl };
+}
+
+/**
+ * The signature Yoco sends for a webhook. Pure.
+ * @param {string} secret - whsec_<base64>
+ */
+function webhookSignature(secret, id, timestamp, rawBody) {
+  const secretBytes = Buffer.from(String(secret).split('_')[1] || '', 'base64');
+  return crypto.createHmac('sha256', secretBytes).update(`${id}.${timestamp}.${rawBody}`).digest('base64');
+}
+
+/** Checks the webhook headers, age and signature of an incoming request (req.rawBody). */
+async function verifyWebhook(req, now = Date.now()) {
+  const headers = req.headers || {};
+  const id = headers['webhook-id'];
+  const timestamp = headers['webhook-timestamp'];
+  const rawSigHeader = headers['webhook-signature'];
+  if (!id || !timestamp || !rawSigHeader) {
+    return {
+      ok: false, status: 400, message: 'Missing webhook headers',
+      details: { missingHeaders: ['webhook-id', 'webhook-timestamp', 'webhook-signature'].filter(h => !headers[h]) },
+    };
+  }
+
+  const webhookTimeMs = parseInt(timestamp, 10) * 1000;
+  if (isNaN(webhookTimeMs) || Math.abs(now - webhookTimeMs) > WEBHOOK_TOLERANCE_MS) {
+    return { ok: false, status: 400, message: 'Webhook timestamp outside acceptable window' };
+  }
+
+  const secret = await getYocoWebhookSecret();
+  if (!secret) {
+    console.error('Yoco webhook secret is not configured (Site Settings → Payments → Yoco, or YOCO_WEBHOOK_SECRET)');
+    return { ok: false, status: 500, message: 'Server configuration error', details: { error: 'Missing webhook secret configuration' } };
+  }
+
+  const expected = webhookSignature(secret, id, timestamp, req.rawBody);
+  // Accept if any of the space-separated signatures match (supports key rotation)
+  const signatures = String(rawSigHeader).split(' ').map(s => s.split(',')[1]).filter(Boolean);
+  const valid = signatures.some(sig => {
+    try { return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)); } catch { return false; }
+  });
+  if (!valid) {
+    console.error('Invalid webhook signature');
+    return { ok: false, status: 403, message: 'Invalid signature', details: { error: 'Webhook signature verification failed' } };
+  }
+  return { ok: true, webhookId: id, timestamp };
+}
+
+/** A Yoco webhook body → { type, transaction }. Pure. */
+function parseWebhook(body) {
+  const payload = body?.payload || {};
+  const metadata = payload.metadata || {};
+  const createdDate = payload.createdDate || body?.createdDate;
+  return {
+    type: body?.type,
+    transaction: {
+      externalId: payload.id || body?.id || null,
+      amountCents: typeof payload.amount === 'number' ? payload.amount : null,
+      currency: payload.currency || null,
+      createdDate: createdDate ? new Date(createdDate) : null,
+      checkoutId: payload.checkoutId || metadata.checkoutId || metadata.checkout_id || null,
+      methodType: payload.paymentMethodDetails?.type || null,
+      metadata,
+      status: payload.status || null,
+    },
+  };
+}
+
+module.exports = {
+  id: 'yoco', label: 'Yoco', capabilities,
+  isConfigured, createCheckout, verifyWebhook, parseWebhook,
+  // for tests
+  webhookSignature, toYocoLineItems,
+};
@@ -0,0 +1,99 @@
+/**
+ * Payment status checks — for when a provider's notification (webhook / ITN) never arrives.
+ *
+ * An open checkout is one we started with a provider that has no payment recorded yet. A
+ * provider that can look payments up (capabilities.getTransaction, findPayments) is asked
+ * whether it received one; anything it found is settled exactly as its webhook would have been
+ * (same amount check, same recording, same emails). Run every 15 minutes by the
+ * 'payment-status' job for recent checkouts, and on demand from the Payments page.
+ * Providers that can't be asked (Yoco: its API has no lookup) show as "can't check" — their
+ * payments are found in the provider's portal and recorded with Reconcile.
+ */
+
+const prisma = require('../config/db');
+const { getProvider } = require('./index');
+const { settlePayment } = require('./webhook');
+
+/** Whether a checkout has been paid: a payment came back for it, or its registration is paid. */
+async function checkoutPaid(checkout) {
+  const refs = [checkout.id, checkout.externalId].filter(Boolean);
+  const tx = await prisma.providerTransaction.findFirst({ where: { checkoutId: { in: refs }, paymentId: { not: null } }, select: { id: true } });
+  if (tx) return true;
+  const registrationId = checkout.metadata?.registrationId;
+  if (!registrationId) return false;
+  const reg = await prisma.registration.findUnique({ where: { id: String(registrationId) }, select: { status: true } });
+  return reg?.status === 'paid';
+}
+
+/** A payment held for review on this checkout (paid a different amount), if any. */
+async function heldForReview(checkout) {
+  const refs = [checkout.id, checkout.externalId].filter(Boolean);
+  return prisma.providerTransaction.findFirst({ where: { checkoutId: { in: refs }, paymentId: null, ignored: false, note: { not: null } }, select: { id: true, note: true } });
+}
+
+/**
+ * Asks each checkout's provider whether it was paid and records what it finds.
+ * @returns {Promise<Map<string, { status: 'paid'|'recorded'|'needs_review'|'not_paid'|'cant_check', note? }>>}
+ */
+async function checkCheckouts(checkouts) {
+  const out = new Map();
+  const byProvider = new Map();
+  for (const c of checkouts) {
+    if (await checkoutPaid(c)) { out.set(c.id, { status: 'paid' }); continue; }
+    const provider = getProvider(c.provider);
+    if (!provider?.findPayments) { out.set(c.id, { status: 'cant_check' }); continue; }
+    if (!byProvider.has(provider.id)) byProvider.set(provider.id, []);
+    byProvider.get(provider.id).push(c);
+  }
+  for (const [providerId, list] of byProvider) {
+    const provider = getProvider(providerId);
+    const found = await provider.findPayments(list);
+    for (const c of list) {
+      const tx = found.get(c.id);
+      if (!tx) {
+        const held = await heldForReview(c);
+        out.set(c.id, held ? { status: 'needs_review', note: held.note } : { status: 'not_paid' });
+        continue;
+      }
+      const event = {
+        type: 'payment.succeeded',
+        transaction: { ...tx, metadata: { ...(c.metadata || {}), ...(tx.metadata || {}) } },
+        checkoutRefs: [c.id, c.externalId].filter(Boolean),
+      };
+      const settled = await settlePayment(provider, event, { source: 'status-check', provider: providerId, transaction: tx }, c);
+      out.set(c.id, settled.needsReview ? { status: 'needs_review', note: settled.note } : { status: 'recorded' });
+    }
+  }
+  return out;
+}
+
+/** Recent checkouts started with a provider and not paid yet, newest first. */
+async function openCheckouts({ since, until = new Date() } = {}) {
+  const rows = await prisma.providerCheckout.findMany({
+    where: { provider: { not: null }, createdAt: { gte: since, lte: until } },
+    orderBy: { createdAt: 'desc' },
+    take: 200,
+  });
+  const open = [];
+  for (const c of rows) if (!(await checkoutPaid(c))) open.push(c);
+  return open;
+}
+
+/**
+ * Background job: checks checkouts started between 3 days and 10 minutes ago (giving the
+ * webhook time to arrive first) with providers that can be asked.
+ */
+async function runPaymentStatusJob(now = new Date()) {
+  const since = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000);
+  const until = new Date(now.getTime() - 10 * 60 * 1000);
+  const checkable = (await openCheckouts({ since, until })).filter(c => getProvider(c.provider)?.findPayments);
+  if (!checkable.length) return { checked: 0, recorded: 0, needsReview: 0 };
+  const results = [...(await checkCheckouts(checkable)).values()];
+  return {
+    checked: checkable.length,
+    recorded: results.filter(r => r.status === 'recorded').length,
+    needsReview: results.filter(r => r.status === 'needs_review').length,
+  };
+}
+
+module.exports = { checkoutPaid, checkCheckouts, openCheckouts, runPaymentStatusJob };
@@ -0,0 +1,301 @@
+/**
+ * Payment webhooks, for every provider: the provider checks the signature and reads the
+ * body (providers/*.js); everything after that is shared here.
+ *
+ * - Every event is stored as a ProviderTransaction (by provider + external id, so repeats
+ *   are idempotent). Events that aren't for one of our checkouts stay unreconciled for the
+ *   Payments page.
+ * - The event is matched to the checkout we started (ProviderCheckout, by our id or the
+ *   provider's): that gives who/what it's for, and the amount we asked for. A payment of a
+ *   different amount isn't recorded — it waits on the Payments page with a note.
+ * - payment.succeeded for a registration or donation records a Payment at the full amount
+ *   paid (provider fees are dealt with at cashup), splits off any donation added at checkout,
+ *   updates the registration's status and generates tickets once it's paid, then emails.
+ * - A provider that has been switched off still has its webhooks processed, so checkouts
+ *   started before it was turned off complete.
+ */
+
+const prisma = require('../config/db');
+const { v4: uuidv4 } = require('uuid');
+const { getProvider, findCheckout } = require('./index');
+const { generateTicketsForRegistration } = require('../utils/ticketUtils');
+const { computeRegistrationTotalDue, refreshPricingForRegistration } = require('../utils/pricing');
+
+/** Express handler for POST /api/webhooks/<providerId> (needs req.rawBody). */
+const handleProviderWebhook = (providerId) => async (req, res) => {
+  try {
+    const provider = getProvider(providerId);
+    if (!provider) return res.status(404).json({ success: false, message: 'Unknown payment provider' });
+
+    const verified = await provider.verifyWebhook(req);
+    if (!verified.ok) {
+      return res.status(verified.status).json({ success: false, message: verified.message, ...(verified.details ? { details: verified.details } : {}) });
+    }
+
+    const body = provider.readWebhookBody ? provider.readWebhookBody(req.rawBody) : JSON.parse(req.rawBody);
+    const event = provider.parseWebhook(body);
+    const tx = event.transaction;
+    const receivedCheckoutId = tx.checkoutId;
+
+    // The checkout we started: its metadata says who/what this is for (PayFast sends none back)
+    const checkout = await findCheckout(provider.id, tx.checkoutId).catch(() => null);
+    if (checkout) tx.metadata = { ...(checkout.metadata || {}), ...(tx.metadata || {}) };
+    // A registration remembers our checkout id (older ones: the provider's)
+    event.checkoutRefs = [...new Set([checkout?.id, tx.checkoutId].filter(Boolean))];
+
+    // Optional filtering: only process specific checkoutIds or prefixes on this endpoint
+    try {
+      const idsEnv = process.env.YOCO_ALLOWED_CHECKOUT_IDS || process.env.YOCO_WEBHOOK_ALLOWED_CHECKOUT_IDS || '';
+      const prefixesEnv = process.env.YOCO_ALLOWED_CHECKOUT_PREFIXES || process.env.YOCO_WEBHOOK_ALLOWED_CHECKOUT_PREFIXES || '';
+      const allowedIds = idsEnv.split(',').map(s => s.trim()).filter(Boolean);
+      const allowedPrefixes = prefixesEnv.split(',').map(s => s.trim()).filter(Boolean);
+      if (allowedIds.length > 0 || allowedPrefixes.length > 0) {
+        const idMatches = receivedCheckoutId && (allowedIds.includes(receivedCheckoutId) || allowedPrefixes.some(pref => receivedCheckoutId.startsWith(pref)));
+        if (!idMatches) {
+          try { await saveProviderTransaction(provider.id, event, body); } catch (e) { console.warn('Failed to store filtered webhook event:', e?.message || e); }
+          return res.status(200).json({
+            success: true,
+            message: 'Webhook acknowledged but ignored due to unmatched checkoutId for this endpoint',
+            data: { filtered: true, receivedCheckoutId, allowedIdsCount: allowedIds.length, allowedPrefixesCount: allowedPrefixes.length },
+          });
+        }
+      }
+    } catch (filterErr) {
+      console.warn('Webhook checkoutId filter parse warning:', filterErr?.message || filterErr);
+    }
+
+    // Not one of our registration checkouts and not a donation → keep it for reconciling
+    try {
+      if (receivedCheckoutId) {
+        const existingRegistration = await prisma.registration.findFirst({ where: { checkoutId: { in: event.checkoutRefs } }, select: { id: true } });
+        if (!existingRegistration) {
+          const meta = tx.metadata || {};
+          const isDonation = meta.type === 'donation' || !!meta.isDonation || !!meta.eventId;
+          if (!isDonation) {
+            try { await saveProviderTransaction(provider.id, event, body); } catch (e) { console.warn('Failed to save unreconciled transaction:', e?.message || e); }
+            return res.status(200).json({
+              success: true,
+              message: 'Webhook acknowledged and stored as unreconciled: no registration found for checkoutId',
+              data: { filtered: true, reason: 'no_registration_for_checkoutId', receivedCheckoutId },
+            });
+          }
+        }
+      }
+    } catch (dbFilterErr) {
+      console.warn('Webhook DB auto-filter warning:', dbFilterErr?.message || dbFilterErr);
+    }
+
+    if (event.type !== 'payment.succeeded') {
+      console.log(`Unhandled ${provider.id} webhook event type: ${event.type}`);
+      try { await saveProviderTransaction(provider.id, event, body); } catch (e) { console.warn('Failed to store unhandled webhook event:', e?.message || e); }
+      return res.status(200).json({
+        success: true,
+        message: 'Webhook received but event type not handled',
+        data: { eventType: event.type, webhookId: verified.webhookId, timestamp: verified.timestamp },
+      });
+    }
+
+    const settled = await settlePayment(provider, event, body, checkout);
+    if (settled.needsReview) {
+      return res.status(200).json({ success: true, message: 'Webhook acknowledged; amount differs from the checkout, so it needs review', data: { needsReview: true } });
+    }
+    const processedData = settled.processedData;
+    return res.status(200).json({
+      success: true,
+      message: `Successfully processed ${event.type} webhook`,
+      data: { eventType: event.type, webhookId: verified.webhookId, timestamp: verified.timestamp, processedData },
+    });
+  } catch (error) {
+    console.error('Webhook error:', error);
+    return res.status(500).json({ success: false, message: error.message, details: { error: error.stack, timestamp: new Date().toISOString() } });
+  }
+};
+
+/**
+ * A successful payment for one of our checkouts (from a webhook, or found by a status check):
+ * held for review with a note when the amount differs from the checkout, otherwise recorded.
+ * @returns {Promise<{ needsReview: true, note } | { needsReview: false, processedData }>}
+ */
+async function settlePayment(provider, event, body, checkout) {
+  const tx = event.transaction;
+  if (checkout && tx.amountCents !== checkout.amountCents) {
+    const note = `Paid R${((tx.amountCents || 0) / 100).toFixed(2)}, but the checkout was for R${(checkout.amountCents / 100).toFixed(2)}. Check it with ${provider.label} before recording it.`;
+    console.warn(`[${provider.id}] amount mismatch on checkout ${checkout.id}: ${note}`);
+    try { await saveProviderTransaction(provider.id, event, body, { note }); } catch (e) { console.warn('Failed to store mismatched payment:', e?.message || e); }
+    return { needsReview: true, note };
+  }
+  return { needsReview: false, processedData: await recordSucceededPayment(provider.id, event, body) };
+}
+
+const REG_INCLUDE ={ event: { select: { id: true, title: true } }, user: { select: { id: true, name: true, email: true } } };
+
+/** Records a successful payment from a webhook. Idempotent on the provider's payment id. */
+async function recordSucceededPayment(providerId, event, body) {
+  const { externalId, amountCents, status, metadata = {}, methodType, checkoutId } = event.transaction;
+  console.log(`Payment succeeded (${providerId}):`, externalId);
+
+  const existingPayment = await prisma.payment.findFirst({ where: { externalId } });
+  if (existingPayment) {
+    console.log(`Payment ${externalId} already processed`);
+    try { await saveProviderTransaction(providerId, event, body, { reconciled: true, paymentId: existingPayment.id }); } catch (e) { console.warn('Failed to reconcile transaction for existing payment:', e?.message || e); }
+    return { status: 'already_processed', paymentId: existingPayment.id, externalId };
+  }
+
+  let registration = null;
+  const refs = event.checkoutRefs || [checkoutId].filter(Boolean);
+  if (refs.length) registration = await prisma.registration.findFirst({ where: { checkoutId: { in: refs } }, include: REG_INCLUDE });
+  if (!registration && metadata.registrationId) registration = await prisma.registration.findUnique({ where: { id: metadata.registrationId }, include: REG_INCLUDE });
+
+  // Resolve userId: registration owner → metadata → first active admin (never a non-existent UUID)
+  let resolvedUserId = registration?.userId || metadata.userId || null;
+  if (!resolvedUserId) {
+    try {
+      const adminUser = await prisma.user.findFirst({ where: { role: 'admin', isActive: true }, select: { id: true } });
+      resolvedUserId = adminUser?.id || null;
+    } catch { /* payment will fail below if still null */ }
+  }
+
+  // A registration checkout can carry a donation on top (metadata.donationAmount). It's
+  // recorded as its own donation payment so it never counts towards the registration.
+  const grossAmount = amountCents / 100;
+  const donationPart = registration?.id ? Math.min(Math.max(Number(metadata.donationAmount) || 0, 0), grossAmount) : 0;
+  const method = methodType || 'card';
+  const paymentStatus = status === 'succeeded' ? 'completed' : status;
+
+  const payment = await prisma.payment.create({
+    data: {
+      id: uuidv4(),
+      amount: Math.round((grossAmount - donationPart) * 100) / 100,
+      method,
+      provider: providerId,
+      status: paymentStatus,
+      externalId,
+      registrationId: registration?.id || null,
+      userId: resolvedUserId,
+      recordedById: resolvedUserId, // self-service webhook payment — payer is the recorder
+      eventId: registration?.eventId || metadata.eventId || null,
+      isDonation: !registration?.id,
+      ...(!registration?.id && metadata.type === 'sponsorship' ? {
+        isSponsorship: true,
+        sponsorAnonymous: String(metadata.sponsorAnonymous) === 'true',
+        sponsorName: String(metadata.sponsorAnonymous) === 'true' ? null : (metadata.sponsorName ? String(metadata.sponsorName).slice(0, 100) : null),
+        sponsorMessage: metadata.sponsorMessage ? String(metadata.sponsorMessage).slice(0, 300) : null,
+      } : {}),
+    },
+  });
+
+  let donationPayment = null;
+  if (donationPart > 0) {
+    donationPayment = await prisma.payment.create({
+      data: {
+        id: uuidv4(), amount: donationPart, method, provider: providerId, status: paymentStatus,
+        userId: resolvedUserId, recordedById: resolvedUserId, registrationId: null, eventId: registration.eventId,
+        isDonation: true, originalPaymentId: payment.id,
+      },
+    });
+  }
+
+  let updatedRegistration = null;
+  let generatedTickets = [];
+  if (registration) {
+    updatedRegistration = await updateRegistrationStatus(registration.id);
+    if (updatedRegistration.status === 'paid') {
+      generatedTickets = await prisma.ticket.findMany({
+        where: { registrationOption: { registrationId: registration.id } },
+        select: { id: true, qrCode: true, isUsed: true, registrationOptionId: true, eventId: true },
+      });
+    }
+  }
+
+  console.log(`Payment ${externalId} processed successfully`);
+  try { await saveProviderTransaction(providerId, event, body, { reconciled: true, paymentId: payment.id }); } catch (e) { console.warn('Failed to reconcile transaction after payment create:', e?.message || e); }
+
+  // Emails: payment confirmation first, then tickets (guarantees order)
+  const regUserId = registration?.userId;
+  const regId = registration?.id;
+  const sendTickets = generatedTickets.length > 0;
+  (async () => {
+    const { sendPaymentEmails } = require('../utils/notifications');
+    try { await sendPaymentEmails(payment.id); } catch (e) { console.error('Failed to send webhook payment emails:', e); }
+    if (donationPayment) {
+      try { await sendPaymentEmails(donationPayment.id); } catch (e) { console.error('Failed to send webhook donation emails:', e); }
+    }
+    if (sendTickets && regUserId && regId) {
+      const { emailTickets } = require('../controllers/ticketController');
+      const mockReq = { user: { id: regUserId }, body: { registrationId: regId } };
+      const mockRes = { status: () => mockRes, json: () => {} };
+      try { await emailTickets(mockReq, mockRes); } catch (e) { console.error('Error emailing tickets from webhook:', e); }
+    }
+  })();
+
+  return {
+    status: 'success',
+    payment: { id: payment.id, externalId, amount: payment.amount, method: payment.method, status: payment.status, createdAt: payment.createdAt },
+    registration: registration ? {
+      id: registration.id,
+      status: updatedRegistration ? updatedRegistration.status : registration.status,
+      eventId: registration.eventId,
+      eventTitle: registration.event?.title,
+      userId: registration.userId,
+      userName: registration.user?.name,
+    } : null,
+    generatedTickets: generatedTickets.length > 0 ? generatedTickets : undefined,
+  };
+}
+
+/** Sets a registration's status from its payments; generates tickets once it's paid. */
+async function updateRegistrationStatus(registrationId) {
+  // Refresh early-bird pricing first so a registration is never marked paid on stale prices.
+  try { await refreshPricingForRegistration(registrationId); } catch (e) { console.warn('[webhook] Price refresh failed:', e?.message); }
+
+  const registration = await prisma.registration.findUnique({
+    where: { id: registrationId },
+    include: { registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, tranches: true } }, payments: true },
+  });
+  if (!registration) throw new Error(`Registration ${registrationId} not found`);
+
+  const totalPaid = registration.payments.reduce((sum, p) => sum + p.amount, 0);
+  const totalDue = computeRegistrationTotalDue(registration, new Date());
+  const newStatus = totalPaid >= totalDue ? 'paid' : totalPaid > 0 ? 'partial_paid' : 'pending';
+
+  const updatedRegistration = await prisma.registration.update({ where: { id: registrationId }, data: { status: newStatus, updatedAt: new Date() } });
+
+  // Tickets are generated here; the caller emails them after the payment email.
+  let generatedTickets = [];
+  if (newStatus === 'paid') {
+    try { generatedTickets = await generateTicketsForRegistration(registrationId); } catch (error) { console.error('Error generating tickets:', error); }
+  }
+  return { ...updatedRegistration, totalPaid, totalDue, generatedTickets: generatedTickets.length > 0 ? generatedTickets : undefined };
+}
+
+/** Stores (or updates) the transaction behind a webhook event. Idempotent per provider + id. */
+async function saveProviderTransaction(providerId, event, body, updates = {}) {
+  const tx = event.transaction;
+  const externalId = tx.externalId;
+  if (!externalId) throw new Error('Missing external id in webhook payload');
+  const where = { provider_externalId: { provider: providerId, externalId } };
+  const touch = (existing) => (Object.keys(updates).length
+    ? prisma.providerTransaction.update({ where: { id: existing.id }, data: updates })
+    : existing);
+  try {
+    const existing = await prisma.providerTransaction.findUnique({ where });
+    if (existing) return touch(existing);
+    return await prisma.providerTransaction.create({
+      data: {
+        provider: providerId, externalId,
+        amount: tx.amountCents, currency: tx.currency, createdDate: tx.createdDate,
+        checkoutId: tx.checkoutId, methodType: tx.methodType,
+        reconciled: false, raw: body, ...updates,
+      },
+    });
+  } catch (e) {
+    // Unique constraint race: another request stored it first
+    if (e?.code === 'P2002') {
+      const existing = await prisma.providerTransaction.findUnique({ where });
+      return existing ? touch(existing) : null;
+    }
+    throw e;
+  }
+}
+
+module.exports = { handleProviderWebhook, settlePayment, recordSucceededPayment, updateRegistrationStatus, saveProviderTransaction };
@@ -5,18 +5,19 @@ const {
  assign, autoAssign, clearAssignments, getSetLists, getMyGroups,
 } = require('../controllers/allocationController');
 const { protect, staff, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent, campusIndependent } = require('../utils/campusScope');

-router.get('/my-groups', protect, staff, getMyGroups);
-router.get('/event/:eventId', protect, supervisor, getBoard);
-router.post('/sets', protect, supervisor, createSet);
-router.put('/sets/:id', protect, supervisor, updateSet);
-router.delete('/sets/:id', protect, supervisor, deleteSet);
-router.get('/sets/:id/lists', protect, supervisor, getSetLists);
-router.post('/sets/:id/groups', protect, supervisor, createGroup);
-router.put('/sets/:id/assignments', protect, supervisor, assign);
-router.delete('/sets/:id/assignments', protect, supervisor, clearAssignments);
-router.post('/sets/:id/auto', protect, supervisor, autoAssign);
-router.put('/groups/:id', protect, supervisor, updateGroup);
-router.delete('/groups/:id', protect, supervisor, deleteGroup);
+router.get('/my-groups', protect, staff, campusIndependent('only the groups the signed-in person leads'), getMyGroups);
+router.get('/event/:eventId', protect, supervisor, scopeEvent(), getBoard);
+router.post('/sets', protect, supervisor, scopeEvent({ from: req => req.body?.eventId }), createSet);
+router.put('/sets/:id', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), updateSet);
+router.delete('/sets/:id', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), deleteSet);
+router.get('/sets/:id/lists', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), getSetLists);
+router.post('/sets/:id/groups', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), createGroup);
+router.put('/sets/:id/assignments', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), assign);
+router.delete('/sets/:id/assignments', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), clearAssignments);
+router.post('/sets/:id/auto', protect, supervisor, scopeEvent({ resolve: 'allocationSet' }), autoAssign);
+router.put('/groups/:id', protect, supervisor, scopeEvent({ resolve: 'allocationGroup' }), updateGroup);
+router.delete('/groups/:id', protect, supervisor, scopeEvent({ resolve: 'allocationGroup' }), deleteGroup);

 module.exports = router;
@@ -3,6 +3,7 @@ const rateLimit = require('express-rate-limit');
 const router = express.Router();
 const { trackStage, getFunnel } = require('../controllers/analyticsController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');

 const trackLimiter = rateLimit({
  windowMs: 60 * 1000,
@@ -13,6 +14,6 @@ const trackLimiter = rateLimit({
 });

 router.post('/track', trackLimiter, trackStage);
-router.get('/funnel', protect, supervisor, getFunnel);
+router.get('/funnel', protect, supervisor, scopeList, getFunnel);

 module.exports = router;
@@ -6,20 +6,21 @@ const {
  myCertificates, downloadCertificate, verifyCertificate,
 } = require('../controllers/attendanceController');
 const { protect, staff, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent, campusIndependent } = require('../utils/campusScope');

 // Certificates — fixed paths first so they aren't taken as an :eventId
 router.get('/certificates/verify/:code', verifyCertificate);
 router.get('/certificates/mine', protect, myCertificates);
-router.post('/certificates/preview', protect, supervisor, previewCertificate);
+router.post('/certificates/preview', protect, supervisor, campusIndependent('previews a certificate template from the request body'), previewCertificate);
 router.get('/certificates/:id/pdf', protect, downloadCertificate);
-router.post('/certificates/:id/revoke', protect, supervisor, revokeCertificate);
+router.post('/certificates/:id/revoke', protect, supervisor, scopeEvent({ resolve: 'certificate' }), revokeCertificate);

 // Attendance register
-router.get('/:eventId', protect, staff, getRegister);
-router.get('/:eventId/export', protect, staff, exportRegister);
-router.post('/:eventId/mark', protect, supervisor, markAttendance);
-router.post('/:eventId/certificates', protect, supervisor, issueCertificates);
-router.post('/:eventId/certificates/send', protect, supervisor, sendCertificatesHandler);
-router.get('/:eventId/certificates.pdf', protect, supervisor, downloadEventCertificates);
+router.get('/:eventId', protect, staff, scopeEvent(), getRegister);
+router.get('/:eventId/export', protect, staff, scopeEvent(), exportRegister);
+router.post('/:eventId/mark', protect, supervisor, scopeEvent(), markAttendance);
+router.post('/:eventId/certificates', protect, supervisor, scopeEvent(), issueCertificates);
+router.post('/:eventId/certificates/send', protect, supervisor, scopeEvent(), sendCertificatesHandler);
+router.get('/:eventId/certificates.pdf', protect, supervisor, scopeEvent(), downloadEventCertificates);

 module.exports = router;
@@ -2,8 +2,9 @@ const express = require('express');
 const router = express.Router();
 const { scheduleAutomations } = require('../controllers/automationController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 // Schedule multiple automation emails for an event
-router.post('/schedule', protect, supervisor, scheduleAutomations);
+router.post('/schedule', protect, supervisor, scopeEvent({ from: req => req.body?.eventId }), scheduleAutomations);

 module.exports = router;
@@ -2,8 +2,9 @@ const express = require('express');
 const router = express.Router();
 const { getBanner, setBanner } = require('../controllers/bannerController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { unscopedOnly } = require('../utils/campusScope');

 router.get('/', getBanner);
-router.post('/', protect, supervisor, setBanner);
+router.post('/', protect, supervisor, unscopedOnly, setBanner);

 module.exports = router;
@@ -2,10 +2,11 @@ const express = require('express');
 const router = express.Router();
 const { previewBroadcast, sendBroadcast, scheduleBroadcast } = require('../controllers/broadcastController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { scopeBroadcast } = require('../utils/campusScope');

 // All routes require supervisor (or admin via middleware logic) access
-router.post('/preview', protect, supervisor, previewBroadcast);
-router.post('/send', protect, supervisor, sendBroadcast);
-router.post('/schedule', protect, supervisor, scheduleBroadcast);
+router.post('/preview', protect, supervisor, scopeBroadcast({ freeformField: 'emails' }), previewBroadcast);
+router.post('/send', protect, supervisor, scopeBroadcast({ freeformField: 'emails' }), sendBroadcast);
+router.post('/schedule', protect, supervisor, scopeBroadcast({ freeformField: 'emails' }), scheduleBroadcast);

 module.exports = router;
@@ -2,13 +2,14 @@ const express = require('express');
 const router = express.Router();
 const { listBundles, createBundle, updateBundle, deleteBundle, quoteBundles } = require('../controllers/bundleController');
 const { protect, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 // What a basket gets off before registering (guests included)
 router.post('/quote', optionalAuth, quoteBundles);

-router.get('/event/:eventId', protect, supervisor, listBundles);
-router.post('/event/:eventId', protect, supervisor, createBundle);
-router.put('/:id', protect, supervisor, updateBundle);
-router.delete('/:id', protect, supervisor, deleteBundle);
+router.get('/event/:eventId', protect, supervisor, scopeEvent(), listBundles);
+router.post('/event/:eventId', protect, supervisor, scopeEvent({ need: 'manage' }), createBundle);
+router.put('/:id', protect, supervisor, scopeEvent({ resolve: 'bundle', need: 'manage' }), updateBundle);
+router.delete('/:id', protect, supervisor, scopeEvent({ resolve: 'bundle', need: 'manage' }), deleteBundle);

 module.exports = router;
@@ -0,0 +1,21 @@
+const express = require('express');
+const router = express.Router();
+const {
+  getCampuses, getCampusBySlug, getCampusesAdmin, updateCampusSettings, createCampus, updateCampus, reorderCampuses, deleteCampus,
+  getCampusAudience,
+} = require('../controllers/campusController');
+const { protect, admin, supervisor } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');
+
+// Multi-campus (utils/campuses.js). The public list is empty while campuses are off.
+router.get('/', getCampuses);
+router.get('/by-slug/:slug', getCampusBySlug);
+router.get('/admin', protect, admin, getCampusesAdmin);
+router.put('/settings', protect, admin, updateCampusSettings);
+router.put('/order', protect, admin, reorderCampuses);
+router.post('/', protect, admin, createCampus);
+router.put('/:id', protect, admin, updateCampus);
+router.delete('/:id', protect, admin, deleteCampus);
+router.get('/:id/audience', protect, supervisor, scopeList, getCampusAudience);
+
+module.exports = router;
@@ -2,11 +2,12 @@ const express = require('express');
 const router = express.Router();
 const { getEventCashup, getCashByRecordedUser, savePersonCash, saveEventCashupDraft, closeEvent, reopenEvent, resolvePending, getCashupAudit } = require('../controllers/cashupController');
 const { protect, supervisor, admin } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');

-router.get('/audit', protect, supervisor, getCashupAudit);
-router.get('/event/:eventId', protect, supervisor, getEventCashup);
-router.get('/event/:eventId/cash-by-user', protect, supervisor, getCashByRecordedUser);
-router.put('/event/:eventId/person-cash/:userId', protect, supervisor, savePersonCash);
+router.get('/audit', protect, supervisor, scopeList, getCashupAudit);
+router.get('/event/:eventId', protect, supervisor, scopeEvent({ need: 'manage' }), getEventCashup);
+router.get('/event/:eventId/cash-by-user', protect, supervisor, scopeEvent({ need: 'manage' }), getCashByRecordedUser);
+router.put('/event/:eventId/person-cash/:userId', protect, supervisor, scopeEvent({ need: 'manage' }), savePersonCash);
 router.put('/event/:eventId/draft', protect, admin, saveEventCashupDraft);
 router.post('/event/:eventId/close', protect, admin, closeEvent);
 router.post('/event/:eventId/reopen', protect, admin, reopenEvent);
@@ -3,15 +3,16 @@ const rateLimit = require('express-rate-limit');
 const router = express.Router();
 const { getConsent, answerConsent, listEventConsent, resendRequest, resendPending, rerequestConsent, medicalList } = require('../controllers/consentController');
 const { protect, staff, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 // The token in the link is the parent's only credential, so keep guessing slow.
 const consentLimiter = rateLimit({ windowMs: 60 * 1000, max: 30, message: { message: 'Too many attempts. Please try again in a minute.' } });

-router.get('/events/:eventId', protect, staff, listEventConsent);
-router.post('/events/:eventId/resend-pending', protect, supervisor, resendPending);
-router.post('/events/:eventId/rerequest', protect, supervisor, rerequestConsent);
-router.get('/events/:eventId/medical', protect, supervisor, medicalList);
-router.post('/requests/:id/resend', protect, resendRequest);
+router.get('/events/:eventId', protect, staff, scopeEvent(), listEventConsent);
+router.post('/events/:eventId/resend-pending', protect, supervisor, scopeEvent(), resendPending);
+router.post('/events/:eventId/rerequest', protect, supervisor, scopeEvent(), rerequestConsent);
+router.get('/events/:eventId/medical', protect, supervisor, scopeEvent(), medicalList);
+router.post('/requests/:id/resend', protect, scopeEvent({ resolve: 'consentRequest', ownerOk: true }), resendRequest);

 // Public consent page
 router.get('/:token', consentLimiter, getConsent);
@@ -2,9 +2,10 @@ const express = require('express');
 const router = express.Router();
 const { getEventCosts, createEventCost, updateEventCost, deleteEventCost } = require('../controllers/costController');
 const { protect, supervisor, admin } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 // Mounted at /api — paths below match the documented /api/events/:eventId/costs and /api/costs/:id shape
-router.get('/events/:eventId/costs', protect, supervisor, getEventCosts);
+router.get('/events/:eventId/costs', protect, supervisor, scopeEvent({ need: 'manage' }), getEventCosts);
 router.post('/events/:eventId/costs', protect, admin, createEventCost);
 router.put('/costs/:id', protect, admin, updateEventCost);
 router.delete('/costs/:id', protect, admin, deleteEventCost);
@@ -2,14 +2,15 @@ const express = require('express');
 const router = express.Router();
 const { listCoupons, getCoupon, createCoupon, updateCoupon, validateCode, listRedemptions } = require('../controllers/couponController');
 const { protect, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');

 // Check a code against a basket before registering (guests included)
-router.post('/validate', optionalAuth, validateCode);
+router.post('/validate', optionalAuth, scopeEvent({ from: req => req.body?.eventId }), validateCode);

-router.get('/', protect, supervisor, listCoupons);
-router.post('/', protect, supervisor, createCoupon);
-router.get('/redemptions', protect, supervisor, listRedemptions);
-router.get('/:id', protect, supervisor, getCoupon);
-router.put('/:id', protect, supervisor, updateCoupon);
+router.get('/', protect, supervisor, scopeList, listCoupons);
+router.post('/', protect, supervisor, scopeList, createCoupon);
+router.get('/redemptions', protect, supervisor, scopeList, listRedemptions);
+router.get('/:id', protect, supervisor, scopeList, getCoupon);
+router.put('/:id', protect, supervisor, scopeList, updateCoupon);

 module.exports = router;
@@ -29,6 +29,7 @@ const {
  getEventByAlias
 } = require('../controllers/eventController');
 const { protect, admin, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');

 // Public routes
 router.get('/', getEvents);
@@ -49,40 +50,40 @@ router.get('/:id/ics', optionalAuth, getEventIcs);
 router.get('/by-alias/:redirectUrl', getEventByAlias);

 // Create/Update/Delete event
-router.post('/', protect, supervisor, createEvent);
+router.post('/', protect, supervisor, scopeList, createEvent);
 router.route('/:id')
-  .put(protect, supervisor, updateEvent)
+  .put(protect, supervisor, scopeEvent({ need: 'manage' }), updateEvent)
  .delete(protect, admin, deleteEvent);

 // Notification recipients: who gets registration/payment/daily-summary emails for this event
 router.route('/:id/notify-recipients')
-  .get(protect, supervisor, getEventNotifyRecipients)
-  .put(protect, supervisor, updateEventNotifyRecipients);
+  .get(protect, supervisor, scopeEvent(), getEventNotifyRecipients)
+  .put(protect, supervisor, scopeEvent({ need: 'manage' }), updateEventNotifyRecipients);

 // Attachments routes
 router.get('/:id/attachments', listEventAttachments); // public read (used by event detail page)
-router.post('/:id/attachments', protect, supervisor, ...uploadEventAttachment);
-router.delete('/:eventId/attachments/:attachmentId', protect, supervisor, deleteEventAttachment);
+router.post('/:id/attachments', protect, supervisor, scopeEvent({ need: 'manage' }), ...uploadEventAttachment);
+router.delete('/:eventId/attachments/:attachmentId', protect, supervisor, scopeEvent({ need: 'manage' }), deleteEventAttachment);

 // Bulk email attendees
-router.post('/:id/email-attendees', protect, supervisor, emailEventAttendees);
+router.post('/:id/email-attendees', protect, supervisor, scopeEvent(), emailEventAttendees);
 // Schedule bulk email to attendees
-router.post('/:id/email-attendees/schedule', protect, supervisor, scheduleEmailEventAttendees);
+router.post('/:id/email-attendees/schedule', protect, supervisor, scopeEvent(), scheduleEmailEventAttendees);
 // Bulk WhatsApp message to attendees
-router.post('/:id/whatsapp-attendees', protect, supervisor, whatsappEventAttendees);
+router.post('/:id/whatsapp-attendees', protect, supervisor, scopeEvent(), whatsappEventAttendees);
 // Schedule bulk WhatsApp message to attendees
-router.post('/:id/whatsapp-attendees/schedule', protect, supervisor, scheduleWhatsappEventAttendees);
+router.post('/:id/whatsapp-attendees/schedule', protect, supervisor, scopeEvent(), scheduleWhatsappEventAttendees);

 // Event options routes
-router.post('/:id/options', protect, supervisor, createEventOption);
+router.post('/:id/options', protect, supervisor, scopeEvent({ need: 'manage' }), createEventOption);
 router.route('/options/:id')
-  .put(protect, supervisor, updateEventOption)
+  .put(protect, supervisor, scopeEvent({ resolve: 'eventOption', need: 'manage' }), updateEventOption)
  .delete(protect, admin, deleteEventOption);

 // Option variant routes
-router.post('/options/:id/variants', protect, supervisor, createOptionVariant);
+router.post('/options/:id/variants', protect, supervisor, scopeEvent({ resolve: 'eventOption', need: 'manage' }), createOptionVariant);
 router.route('/variants/:id')
-  .put(protect, supervisor, updateOptionVariant)
+  .put(protect, supervisor, scopeEvent({ resolve: 'optionVariant', need: 'manage' }), updateOptionVariant)
  .delete(protect, admin, deleteOptionVariant);

 module.exports = router;
@@ -2,13 +2,14 @@ const express = require('express');
 const router = express.Router();
 const { getEventFeedback, saveEventFeedback, deleteEventFeedback, sendNow, getPublicForm, submitPublicForm, getSummary } = require('../controllers/feedbackController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');

 router.get('/public/:token', getPublicForm);
 router.post('/public/:token', submitPublicForm);
-router.get('/summary', protect, supervisor, getSummary);
-router.get('/event/:eventId', protect, supervisor, getEventFeedback);
-router.put('/event/:eventId', protect, supervisor, saveEventFeedback);
-router.delete('/event/:eventId', protect, supervisor, deleteEventFeedback);
-router.post('/event/:eventId/send-now', protect, supervisor, sendNow);
+router.get('/summary', protect, supervisor, scopeList, getSummary);
+router.get('/event/:eventId', protect, supervisor, scopeEvent(), getEventFeedback);
+router.put('/event/:eventId', protect, supervisor, scopeEvent({ need: 'manage' }), saveEventFeedback);
+router.delete('/event/:eventId', protect, supervisor, scopeEvent({ need: 'manage' }), deleteEventFeedback);
+router.post('/event/:eventId/send-now', protect, supervisor, scopeEvent({ need: 'manage' }), sendNow);

 module.exports = router;
@@ -2,8 +2,9 @@ const express = require('express');
 const router = express.Router();
 const { listFormResponses } = require('../controllers/formController');
 const { protect, staff } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');

 // Staff or higher can view submitted forms
-router.get('/responses', protect, staff, listFormResponses);
+router.get('/responses', protect, staff, scopeList, listFormResponses);

 module.exports = router;
@@ -0,0 +1,13 @@
+const express = require('express');
+const router = express.Router();
+const { getStatus, connect, heartbeatNow, requestUpdate } = require('../controllers/hubController');
+const { protect, admin } = require('../middleware/authMiddleware');
+
+// Licence and the Cross Events Hub (docs/hub-protocol.md). Admins only; the setup wizard's
+// admin token counts, so the licence step can run during /setup.
+router.get('/status', protect, admin, getStatus);
+router.post('/connect', protect, admin, connect);
+router.post('/heartbeat', protect, admin, heartbeatNow);
+router.post('/update-request', protect, admin, requestUpdate);
+
+module.exports = router;
@@ -0,0 +1,10 @@
+const express = require('express');
+const router = express.Router();
+const { getConfig, updateConfig, testConnection } = require('../controllers/payfastController');
+const { protect, admin } = require('../middleware/authMiddleware');
+
+router.get('/config', protect, admin, getConfig);
+router.put('/config', protect, admin, updateConfig);
+router.post('/test', protect, admin, testConnection);
+
+module.exports = router;
@@ -9,29 +9,46 @@ const {
  getPaymentsByEvent,
  assignDonationToRegistration,
  unassignDonationFromRegistration,
-  createYocoCheckout,
+  createCheckout,
  sendPaymentLink,
  createRefund,
  getPaymentStats,
  sendReceipt,
 } = require('../controllers/paymentController');
+const { listPaymentProviders, getPaymentProviderSettings, updatePaymentProviderSettings, getPayPage, choosePayProvider, listOpenCheckouts, checkCheckoutStatus } = require('../controllers/paymentProvidersController');
 const { protect, supervisor, staff, admin} = require('../middleware/authMiddleware');
+const { scopeEvent, scopeBody, scopeList, unscopedOnly } = require('../utils/campusScope');
+
+// Campus-scoped staff: payments follow their registration's or event's campus. Door payments for
+// church-wide events are allowed; refunds of them aren't (need 'manage'); a payment or donation
+// not linked to any event is for admins and unscoped supervisors (orphan 'deny').
+const paymentTarget = scopeBody([['registrationId', 'registration'], ['eventId', 'event']], { orphan: 'deny' });

 // Protected routes
-router.post('/', protect, supervisor, createPayment);
-router.post('/yoco-checkout', protect, createYocoCheckout);
-router.post('/yoco-checkout/send', protect, supervisor, sendPaymentLink);
+router.post('/', protect, supervisor, paymentTarget, createPayment);
+router.get('/providers', listPaymentProviders);
+router.get('/pay/:id', getPayPage);
+router.post('/pay/:id', choosePayProvider);
+router.get('/checkouts/open', protect, supervisor, unscopedOnly, listOpenCheckouts);
+router.post('/checkouts/check', protect, supervisor, unscopedOnly, checkCheckoutStatus);
+router.get('/providers/settings', protect, admin, getPaymentProviderSettings);
+router.put('/providers/settings', protect, admin, updatePaymentProviderSettings);
+router.post('/checkout', protect, createCheckout);
+router.post('/checkout/send', protect, supervisor, scopeBody([['registrationId', 'registration']]), sendPaymentLink);
+// Older names, kept for existing clients
+router.post('/yoco-checkout', protect, createCheckout);
+router.post('/yoco-checkout/send', protect, supervisor, scopeBody([['registrationId', 'registration']]), sendPaymentLink);
 router.get('/mypayments', protect, getUserPayments);
-router.post('/:id/send-receipt', protect, sendReceipt);
-router.get('/:id', protect, getPaymentById);
-router.get('/registration/:registrationId', protect, getPaymentsByRegistration);
+router.post('/:id/send-receipt', protect, scopeEvent({ resolve: 'payment', ownerOk: true }), sendReceipt);
+router.get('/:id', protect, scopeEvent({ resolve: 'payment', ownerOk: true }), getPaymentById);
+router.get('/registration/:registrationId', protect, scopeEvent({ resolve: 'registration', from: req => req.params.registrationId, ownerOk: true }), getPaymentsByRegistration);

 // Admin/Staff routes
-router.get('/', protect, supervisor, getPayments);
-router.get('/event/:eventId', protect, staff, getPaymentsByEvent);
-router.put('/assign-donation', protect, supervisor, assignDonationToRegistration);
-router.post('/unassign-donation', protect, supervisor, unassignDonationFromRegistration);
-router.post('/refund', protect, supervisor, createRefund);
+router.get('/', protect, supervisor, scopeList, getPayments);
+router.get('/event/:eventId', protect, staff, scopeEvent(), getPaymentsByEvent);
+router.put('/assign-donation', protect, supervisor, scopeBody([['paymentId', 'payment']], { orphan: 'deny' }), scopeBody([['registrationId', 'registration']]), assignDonationToRegistration);
+router.post('/unassign-donation', protect, supervisor, scopeBody([['legId', 'payment']], { orphan: 'deny' }), unassignDonationFromRegistration);
+router.post('/refund', protect, supervisor, scopeBody([['paymentId', 'payment'], ['registrationId', 'registration']], { need: 'manage', orphan: 'deny' }), createRefund);
 router.get('/admin/stats', protect, admin, getPaymentStats);

 module.exports = router;
@@ -0,0 +1,85 @@
+const express = require('express');
+const rateLimit = require('express-rate-limit');
+const router = express.Router();
+const {
+  getMyPrivacy,
+  updateMyNews,
+  exportMyData,
+  createMyRequest,
+  getUnsubscribe,
+  postUnsubscribe,
+  oneClickUnsubscribe,
+  oneClickRedirect,
+  listRequests,
+  completeRequest,
+  rejectRequest,
+} = require('../controllers/privacyController');
+const {
+  getNotice,
+  acceptMyNotice,
+  getNoticeDraft,
+  saveNoticeDraft,
+  discardNoticeDraft,
+  publishNotice,
+  listOperators,
+  createOperator,
+  updateOperator,
+  deleteOperator,
+  consentLog,
+  accessLog,
+  getReadiness,
+  getRetention,
+  saveRetention,
+  runRetentionNow,
+  listBreaches,
+  createBreach,
+  updateBreach,
+} = require('../controllers/privacyAdminController');
+const { protect, admin } = require('../middleware/authMiddleware');
+
+// Exports are heavy-ish (every record the person has) — a few per 10 minutes is plenty.
+const exportLimiter = rateLimit({ windowMs: 10 * 60 * 1000, max: 10, standardHeaders: true, legacyHeaders: false });
+
+// The person themselves
+router.get('/me', protect, getMyPrivacy);
+router.put('/me/news', protect, updateMyNews);
+router.get('/me/export', protect, exportLimiter, exportMyData);
+router.post('/me/requests', protect, createMyRequest);
+
+// Unsubscribe links (signed tokens, no login)
+router.get('/unsubscribe/:token', getUnsubscribe);
+router.post('/unsubscribe/:token', postUnsubscribe);
+router.get('/unsubscribe/:token/one-click', oneClickRedirect);
+router.post('/unsubscribe/:token/one-click', express.urlencoded({ extended: false }), oneClickUnsubscribe);
+
+// Admin: data requests inbox
+router.get('/requests', protect, admin, listRequests);
+router.post('/requests/:id/complete', protect, admin, completeRequest);
+router.post('/requests/:id/reject', protect, admin, rejectRequest);
+
+// Privacy notice: public reading, acceptance, and the admin editor
+router.get('/notice', getNotice);
+router.post('/me/notice/accept', protect, acceptMyNotice);
+router.get('/notice/draft', protect, admin, getNoticeDraft);
+router.put('/notice/draft', protect, admin, saveNoticeDraft);
+router.delete('/notice/draft', protect, admin, discardNoticeDraft);
+router.post('/notice/publish', protect, admin, publishNotice);
+
+// Admin: operator register, consent log, access log
+router.get('/operators', protect, admin, listOperators);
+router.post('/operators', protect, admin, createOperator);
+router.put('/operators/:id', protect, admin, updateOperator);
+router.delete('/operators/:id', protect, admin, deleteOperator);
+router.get('/consent-log', protect, admin, consentLog);
+router.get('/access-log', protect, admin, accessLog);
+
+// Admin: readiness, retention, breach register
+router.get('/readiness', protect, admin, getReadiness);
+router.get('/retention', protect, admin, getRetention);
+router.put('/retention', protect, admin, saveRetention);
+router.post('/retention/run', protect, admin, runRetentionNow);
+router.get('/breaches', protect, admin, listBreaches);
+router.post('/breaches', protect, admin, createBreach);
+router.put('/breaches/:id', protect, admin, updateBreach);
+
+module.exports = router;
@@ -0,0 +1,21 @@
+const express = require('express');
+const router = express.Router();
+const { getAllProviderTransactions, getUnreconciledProviderTransactions, reconcileProviderTransaction, ignoreProviderTransaction } = require('../controllers/providerTransactionsController');
+const { protect, supervisor} = require('../middleware/authMiddleware');
+const { unscopedOnly } = require('../utils/campusScope');
+
+// Mounted at /api/provider-transactions (and /api/yoco-transactions, the older name).
+
+// GET all payment provider transactions (admin/supervisor)
+router.get('/', protect, supervisor, unscopedOnly, getAllProviderTransactions);
+
+// GET all unreconciled transactions (admin/supervisor)
+router.get('/unreconciled', protect, supervisor, unscopedOnly, getUnreconciledProviderTransactions);
+
+// POST reconcile a transaction
+router.post('/:id/reconcile', protect, supervisor, unscopedOnly, reconcileProviderTransaction);
+
+// POST ignore a transaction
+router.post('/:id/ignore', protect, supervisor, unscopedOnly, ignoreProviderTransaction);
+
+module.exports = router;
@@ -17,29 +17,33 @@ const {
  updateAttendees, sendAttendeeFormLink,
 } = require('../controllers/registrationController');
 const { protect, supervisor, staff, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');
+
+// Campus-scoped staff (utils/campusScope.js). Routes open to the registration's owner as well
+// as to staff check staff against the registration's event, and let the owner through (ownerOk).

 // Registration - auth optional when event doesn't require it
 router.post('/', optionalAuth, createRegistration);
 router.get('/myregistrations', protect, getUserRegistrations);
-router.put('/:id/options', protect, updateRegistrationOptions);
-router.delete('/:id', protect, cancelRegistration);
-router.post('/:id/send-invoice', protect, sendInvoice);
-router.post('/:id/coupon', protect, applyCoupon);
-router.delete('/:id/coupon', protect, staff, removeCoupon);
-router.put('/:id/attendees', protect, updateAttendees);
-router.post('/:id/attendees/:attendeeId/send-form-link', protect, sendAttendeeFormLink);
+router.put('/:id/options', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), updateRegistrationOptions);
+router.delete('/:id', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), cancelRegistration);
+router.post('/:id/send-invoice', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), sendInvoice);
+router.post('/:id/coupon', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), applyCoupon);
+router.delete('/:id/coupon', protect, staff, scopeEvent({ resolve: 'registration' }), removeCoupon);
+router.put('/:id/attendees', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), updateAttendees);
+router.post('/:id/attendees/:attendeeId/send-form-link', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), sendAttendeeFormLink);

 // Registration detail + forms — optionalAuth so guests can access with just the registrationId
-router.get('/:id', optionalAuth, getRegistrationById);
-router.get('/:id/forms/draft', optionalAuth, getFormDraft);
-router.put('/:id/forms/draft', optionalAuth, saveFormDraft);
-router.post('/:id/forms/responses', optionalAuth, submitFormResponses);
-router.put('/:id/forms/responses', protect, supervisor, replaceFormResponses);
+router.get('/:id', optionalAuth, scopeEvent({ resolve: 'registration', ownerOk: true }), getRegistrationById);
+router.get('/:id/forms/draft', optionalAuth, scopeEvent({ resolve: 'registration', ownerOk: true }), getFormDraft);
+router.put('/:id/forms/draft', optionalAuth, scopeEvent({ resolve: 'registration', ownerOk: true }), saveFormDraft);
+router.post('/:id/forms/responses', optionalAuth, scopeEvent({ resolve: 'registration', ownerOk: true }), submitFormResponses);
+router.put('/:id/forms/responses', protect, supervisor, scopeEvent({ resolve: 'registration' }), replaceFormResponses);

 // Admin/Staff routes
-router.get('/', protect, staff, getRegistrations);
-router.put('/:id', protect, staff, updateRegistrationStatus);
-router.get('/event/:eventId', protect, staff, getRegistrationsByEvent);
-router.post('/manual', protect, supervisor, createManualRegistration);
+router.get('/', protect, staff, scopeList, getRegistrations);
+router.put('/:id', protect, staff, scopeEvent({ resolve: 'registration' }), updateRegistrationStatus);
+router.get('/event/:eventId', protect, staff, scopeEvent(), getRegistrationsByEvent);
+router.post('/manual', protect, supervisor, scopeEvent({ from: req => req.body?.eventId }), createManualRegistration);

 module.exports = router;
@@ -2,14 +2,15 @@ const express = require('express');
 const router = express.Router();
 const { listLocks, createLock, getSnapshot, syncLock, releaseLock, forceRelease, listReports, reviewReport } = require('../controllers/scanLockController');
 const { protect, staff, supervisor } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

-router.get('/', protect, staff, listLocks);
-router.post('/', protect, staff, createLock);
-router.get('/reports', protect, supervisor, listReports);
-router.post('/reports/:id/review', protect, supervisor, reviewReport);
-router.get('/:id/snapshot', protect, staff, getSnapshot);
-router.post('/:id/sync', protect, staff, syncLock);
-router.post('/:id/force-release', protect, supervisor, forceRelease);
-router.delete('/:id', protect, staff, releaseLock);
+router.get('/', protect, staff, scopeEvent({ from: req => req.query.eventId }), listLocks);
+router.post('/', protect, staff, scopeEvent({ from: req => req.body?.eventId }), createLock);
+router.get('/reports', protect, supervisor, scopeEvent({ from: req => req.query.eventId }), listReports);
+router.post('/reports/:id/review', protect, supervisor, scopeEvent({ resolve: 'syncReport' }), reviewReport);
+router.get('/:id/snapshot', protect, staff, scopeEvent({ resolve: 'scanLock' }), getSnapshot);
+router.post('/:id/sync', protect, staff, scopeEvent({ resolve: 'scanLock' }), syncLock);
+router.post('/:id/force-release', protect, supervisor, scopeEvent({ resolve: 'scanLock' }), forceRelease);
+router.delete('/:id', protect, staff, scopeEvent({ resolve: 'scanLock' }), releaseLock);

 module.exports = router;
@@ -2,10 +2,11 @@ const express = require('express');
 const router = express.Router();
 const { listScheduledEmails, updateScheduledEmail, deleteScheduledEmail } = require('../controllers/scheduledEmailsController');
 const { protect, supervisor } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');

 // All routes require supervisor (or admin via middleware logic) access
-router.get('/', protect, supervisor, listScheduledEmails);
-router.patch('/:id', protect, supervisor, updateScheduledEmail);
-router.delete('/:id', protect, supervisor, deleteScheduledEmail);
+router.get('/', protect, supervisor, scopeList, listScheduledEmails);
+router.patch('/:id', protect, supervisor, scopeList, updateScheduledEmail);
+router.delete('/:id', protect, supervisor, scopeList, deleteScheduledEmail);

 module.exports = router;
@@ -7,10 +7,11 @@ const {
    updateSection
 } = require('../controllers/sectionController');
 const { protect, admin, supervisor, staff } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeList } = require('../utils/campusScope');

-router.get('/', protect, staff, getSections);
-router.post('/', protect, supervisor, createSection);
+router.get('/', protect, staff, scopeList, getSections);
+router.post('/', protect, supervisor, scopeEvent({ from: req => req.body?.eventId, need: 'manage' }), createSection);
 router.delete('/:id', protect, admin, deleteSection);
-router.put('/:id', protect, supervisor, updateSection);
+router.put('/:id', protect, supervisor, scopeEvent({ resolve: 'section', need: 'manage' }), updateSection);

 module.exports = router;
@@ -2,9 +2,10 @@ const express = require('express');
 const router = express.Router();
 const { getEventSponsorship, createSponsorCheckout, getPool } = require('../controllers/sponsorshipController');
 const { protect, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 router.get('/event/:eventId', getEventSponsorship);
-router.get('/event/:eventId/pool', protect, supervisor, getPool);
+router.get('/event/:eventId/pool', protect, supervisor, scopeEvent(), getPool);
 router.post('/checkout', optionalAuth, createSponsorCheckout);

 module.exports = router;
@@ -2,16 +2,17 @@ const express = require('express');
 const router = express.Router();
 const { getStaffDashboardStats, getSupervisorDashboardStats, getAdminDashboardStats, getOverviewStats } = require('../controllers/statsController');
 const { protect, staff, supervisor, admin } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');

 // One endpoint per dashboard — each returns exactly what that dashboard renders in a
 // single response instead of the dashboard making several separate calls (and, previously,
 // pulling full payments/events lists just to reduce them to a couple of numbers).
-router.get('/staff', protect, staff, getStaffDashboardStats);
-router.get('/supervisor', protect, supervisor, getSupervisorDashboardStats);
+router.get('/staff', protect, staff, scopeList, getStaffDashboardStats);
+router.get('/supervisor', protect, supervisor, scopeList, getSupervisorDashboardStats);
 router.get('/admin', protect, admin, getAdminDashboardStats);

 // Month-over-month KPIs + trend + top events, shared by the Admin and Supervisor dashboards.
 // Staff never sees financial data, so this has no staff-accessible route.
-router.get('/overview', protect, supervisor, getOverviewStats);
+router.get('/overview', protect, supervisor, scopeList, getOverviewStats);

 module.exports = router;
@@ -22,31 +22,34 @@ const {
  getTicketTransfers
 } = require('../controllers/ticketController');
 const { protect, admin, supervisor, staff } = require('../middleware/authMiddleware');
+const { scopeEvent, scopeBody, scopeList } = require('../utils/campusScope');
+
+// Campus-scoped staff (utils/campusScope.js). The scanner names the campus of another campus's ticket.

 // Protected routes
 router.get('/mytickets', protect, getUserTickets);
-router.get('/:id', protect, getTicketById);
+router.get('/:id', protect, scopeEvent({ resolve: 'ticket', ownerOk: true }), getTicketById);
 router.post('/email', protect, emailTickets);
-router.post('/:id/transfer', protect, transferTicketHandler);
-router.delete('/:id/transfer', protect, cancelTransferHandler);
+router.post('/:id/transfer', protect, scopeEvent({ resolve: 'ticket', ownerOk: true }), transferTicketHandler);
+router.delete('/:id/transfer', protect, scopeEvent({ resolve: 'ticket', ownerOk: true }), cancelTransferHandler);
 // Transfer links (public: the person the ticket is offered to)
 router.get('/transfer-offer/:token', getTransferOffer);
 router.post('/transfer-offer/:token/accept', acceptTransferOffer);
 router.post('/transfer-offer/:token/decline', declineTransferOffer);
-router.get('/:id/transfers', protect, getTicketTransfers);
+router.get('/:id/transfers', protect, scopeEvent({ resolve: 'ticket', ownerOk: true }), getTicketTransfers);

 // Staff routes
-router.post('/send-to', protect, staff, sendTicketsTo);
-router.get('/scan-preview/:qrCode', protect, staff, getScanPreview);
-router.get('/qr/:qrCode', protect, staff, getTicketByQrCode);
-router.post('/scan/:qrCode', protect, staff, scanTicket);
-router.get('/event/:eventId', protect, staff, getTicketsByEvent);
-router.get('/scans/recent', protect, staff, getRecentScans);
-router.get('/scans/stats', protect, staff, getScanStats);
+router.post('/send-to', protect, staff, scopeBody([['registrationId', 'registration'], ['ticketIds', 'ticket']]), sendTicketsTo);
+router.get('/scan-preview/:qrCode', protect, staff, scopeEvent({ resolve: 'ticketQr', from: req => req.params.qrCode, nameCampus: true }), getScanPreview);
+router.get('/qr/:qrCode', protect, staff, scopeEvent({ resolve: 'ticketQr', from: req => req.params.qrCode, nameCampus: true }), getTicketByQrCode);
+router.post('/scan/:qrCode', protect, staff, scopeEvent({ resolve: 'ticketQr', from: req => req.params.qrCode, nameCampus: true }), scanTicket);
+router.get('/event/:eventId', protect, staff, scopeEvent(), getTicketsByEvent);
+router.get('/scans/recent', protect, staff, scopeList, getRecentScans);
+router.get('/scans/stats', protect, staff, scopeList, getScanStats);

 // Admin routes
-router.post('/generate', protect, supervisor, generateTickets);
-router.get('/', protect, supervisor, getTickets);
+router.post('/generate', protect, supervisor, scopeBody([['registrationId', 'registration']]), generateTickets);
+router.get('/', protect, supervisor, scopeList, getTickets);
 router.put('/email-sent', protect, admin, markTicketsAsEmailSent);

 module.exports = router;
@@ -3,12 +3,13 @@ const router = express.Router();

 const { upload, uploadEventImage, uploadLogo, uploadLogoImage, uploadFavicon, uploadFaviconImage } = require('../controllers/uploadController');
 const { protect, supervisor, admin } = require('../middleware/authMiddleware');
+const { campusIndependent } = require('../utils/campusScope');
 const prisma = require('../config/db');

 // @route POST /api/uploads/event-image
 // @desc Upload an image for an event
 // @access Private (Supervisor+ recommended)
-router.post('/event-image', protect, supervisor, (req, res, next) => {
+router.post('/event-image', protect, supervisor, campusIndependent('stores an image file; the event it goes on is checked when the event is saved'), (req, res, next) => {
    upload.single('image')(req, res, (err) => {
        if (err) {
            req.multerError = err;
@@ -26,6 +26,7 @@ const {
  getMyActivity,
 } = require('../controllers/userController');
 const { protect, admin, supervisor, loginLimiter} = require('../middleware/authMiddleware');
+const { campusIndependent } = require('../utils/campusScope');

 // Public routes
 router.post('/', registerUser);
@@ -51,9 +52,9 @@ router.post('/2fa/disable', protect, loginLimiter, disableTwoFactor);

 // Admin routes
 router.route('/')
-  .get(protect, supervisor, getUsers);
+  .get(protect, supervisor, campusIndependent('accounts are shared across campuses'), getUsers);

-router.get('/check-exists', protect, supervisor, checkUserExists);
+router.get('/check-exists', protect, supervisor, campusIndependent('accounts are shared across campuses'), checkUserExists);

 router.route('/:id')
  .get(protect, admin, getUserById)
@@ -3,6 +3,7 @@ const rateLimit = require('express-rate-limit');
 const router = express.Router();
 const { joinWaitlist, myWaitlist, leaveWaitlist, claimInfo, eventWaitlist, offerManually, moveEntry, removeEntry } = require('../controllers/waitlistController');
 const { protect, staff, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { scopeEvent } = require('../utils/campusScope');

 // Claim links are credentials, so keep guessing slow.
 const claimLimiter = rateLimit({ windowMs: 60 * 1000, max: 30, message: { message: 'Too many attempts. Please try again in a minute.' } });
@@ -10,10 +11,10 @@ const claimLimiter = rateLimit({ windowMs: 60 * 1000, max: 30, message: { messag
 router.post('/', optionalAuth, joinWaitlist);
 router.get('/mine', protect, myWaitlist);
 router.get('/claim/:token', claimLimiter, claimInfo);
-router.get('/events/:eventId', protect, staff, eventWaitlist);
-router.post('/:id/offer', protect, supervisor, offerManually);
-router.post('/:id/move', protect, supervisor, moveEntry);
-router.post('/:id/remove', protect, supervisor, removeEntry);
+router.get('/events/:eventId', protect, staff, scopeEvent(), eventWaitlist);
+router.post('/:id/offer', protect, supervisor, scopeEvent({ resolve: 'waitlistEntry' }), offerManually);
+router.post('/:id/move', protect, supervisor, scopeEvent({ resolve: 'waitlistEntry' }), moveEntry);
+router.post('/:id/remove', protect, supervisor, scopeEvent({ resolve: 'waitlistEntry' }), removeEntry);
 router.delete('/:id', protect, leaveWaitlist);

 module.exports = router;
@@ -1,9 +1,11 @@
 const express = require('express');
 const router = express.Router();
 const { handleYocoWebhook, handleWhatsappWebhook } = require('../controllers/webhookController');
+const { handleProviderWebhook } = require('../payments/webhook');

-// Yoco webhook endpoint
+// Payment provider webhooks (src/payments)
 router.post('/yoco', handleYocoWebhook);
+router.post('/payfast', handleProviderWebhook('payfast'));
 router.post('/whatsapp', handleWhatsappWebhook);

 module.exports = router;
--- a/Show More
+++ b/Show More