Merge branch 'docs/ai-roadmap'

- §15 AI helpers (2.0): one-button helpers (draft an event, summarise
  reports and feedback, draft messages, improve text) on Claude Haiku 5.5,
  called through the Hub, which holds the key, meters usage in rand and
  enforces a monthly cap per licence; admin usage view; POPIA notes
- §16 AI later stages (unversioned): Ask AI, help/navigation assistant,
  actions with confirmation, more helpers, long-term self-hosted AI
- Hub: AI cap as the first per-licence limit, AiUsage model; decisions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mt6TCv85T9VKRq3cV7rXq

.gitignore

@@ -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/

CHANGELOG.md

@@ -7,6 +7,126 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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

FEATURES.md

@@ -30,10 +30,11 @@ WhatsApp · PM2 for process management · optional Sentry for error monitoring.
 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)
+17. [Privacy (POPIA)](#privacy-popia)
+18. [Help system](#help-system)
+19. [Background jobs](#background-jobs)
+20. [Operations](#operations)
+21. [Page map](#page-map)
 
 ---
 
@@ -104,7 +105,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 +175,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 +201,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 +262,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 +344,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 +447,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).
@@ -495,7 +516,7 @@ applied without a restart. Secrets are encrypted with AES-256-GCM.
 | 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.
@@ -520,13 +541,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 +636,12 @@ 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`) |
 | `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 |
@@ -590,7 +679,8 @@ can't start, the same jobs run on in-process timers.
 | `/[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 +688,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 |

README.md

@@ -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,18 @@ 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).
+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 +166,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.

SETTINGS.md

@@ -57,12 +57,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,7 +79,7 @@ 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. |
@@ -85,6 +89,21 @@ Managed in the Yoco tab (through `/api/yoco`, not the generic settings endpoints
 | 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
 

backend/.env.example

@@ -39,6 +39,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 +69,13 @@ 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
 # 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

backend/API_DOCUMENTATION.md

@@ -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,7 +42,7 @@ 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)
 - [Webhooks](#webhooks)
 - [Settings](#settings)
@@ -465,7 +466,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 +509,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 +524,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 +551,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 +625,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 +653,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 +706,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 +804,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 +823,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 |
@@ -775,8 +840,10 @@ Manages the WAWP WhatsApp API instance. Credentials are stored in `AppSetting` (
 
 | 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 +863,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 |
 |--------|------|------|-------------|

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "event-management-backend",
-  "version": "1.35.0",
+  "version": "1.40.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "event-management-backend",
-      "version": "1.35.0",
+      "version": "1.40.0",
       "hasInstallScript": true,
       "dependencies": {
         "@prisma/adapter-pg": "^7.10.1",

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "event-management-backend",
-  "version": "1.35.0",
+  "version": "1.40.0",
   "description": "Event Management System Backend",
   "main": "src/index.js",
   "scripts": {

backend/prisma/migrations/20261023083152_add_waitlist_session/migration.sql

@@ -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;

backend/prisma/migrations/20261023091312_add_chosen_sessions/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "RegistrationOption" ADD COLUMN     "sessionIds" TEXT[] DEFAULT ARRAY[]::TEXT[];

backend/prisma/migrations/20261023094434_payment_providers/migration.sql

@@ -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);

backend/prisma/migrations/20261023103212_payfast/migration.sql

@@ -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");

backend/prisma/migrations/20261023154520_popia_privacy_centre/migration.sql

@@ -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;

backend/prisma/migrations/20261023165845_popia_notice_operators_access_log/migration.sql

@@ -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);

backend/prisma/migrations/20261023181344_popia_retention_breaches/migration.sql

@@ -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";

backend/prisma/schema.prisma

@@ -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,13 @@ 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[]
 }
 
 model Event {
@@ -344,6 +364,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 +413,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 +423,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 +583,25 @@ 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
 }
 
 // Append-only audit trail for admin/supervisor-initiated actions with money or
@@ -677,9 +716,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 +732,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 +1431,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 +1448,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 +1554,7 @@ model EventSession {
   usages      TicketUsage[]
   reminders   SessionReminderLog[]
   registrationOptions RegistrationOption[]
+  waitlistEntries     WaitlistEntry[]
 
   @@index([eventId, startsAt])
 }
@@ -1526,3 +1598,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])
+}

backend/src/controllers/allocationController.js

@@ -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) });
     }

backend/src/controllers/attendanceController.js

@@ -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);

backend/src/controllers/backupController.js

@@ -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) });

backend/src/controllers/broadcastController.js

@@ -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) });
 

backend/src/controllers/consentController.js

@@ -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);

backend/src/controllers/couponController.js

@@ -250,8 +250,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);

backend/src/controllers/eventController.js

@@ -1586,8 +1586,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 +1621,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 +1632,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 +1738,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 +1833,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 +1869,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 +1879,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 +1941,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 +1969,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 +1987,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 +2010,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 +2024,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({

backend/src/controllers/formController.js

@@ -43,6 +43,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 });

backend/src/controllers/impersonationController.js

@@ -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');

backend/src/controllers/payfastController.js

@@ -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 };

backend/src/controllers/paymentController.js

@@ -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');
@@ -914,122 +914,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 +943,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 +962,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 +973,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 +1319,7 @@ module.exports = {
   getPaymentsByEvent,
   assignDonationToRegistration,
   unassignDonationFromRegistration,
-  createYocoCheckout,
-  createRegistrationCheckoutInternal,
+  createCheckout,
   sendPaymentLink,
   createRefund,
   getPaymentStats,

backend/src/controllers/paymentProvidersController.js

@@ -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,
+};

backend/src/controllers/privacyAdminController.js

@@ -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,
+};

backend/src/controllers/privacyController.js

@@ -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,
+};

backend/src/controllers/providerTransactionsController.js

@@ -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
+};

backend/src/controllers/registrationController.js

@@ -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: {
@@ -1193,6 +1196,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 +1210,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 +1280,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 +1365,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);
       }
     }
 

backend/src/controllers/reportController.js

@@ -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 });

backend/src/controllers/settingsController.js

@@ -8,9 +8,12 @@ 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',
+]);
 
 const PUBLIC_KEYS = [
   'org_name', 'org_tagline', 'org_email', 'org_phone', 'org_address',
@@ -50,7 +53,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 (PAYMENT_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 +89,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 && !PAYMENT_PRIVATE_KEYS.has(k))
       .map(([key, value]) => {
         let storedValue = String(value);
 
@@ -125,7 +128,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 && !PAYMENT_PRIVATE_KEYS.has(k)) },
         ip: getClientIp(req),
       });
     }
@@ -202,7 +205,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() !== '' && !PAYMENT_PRIVATE_KEYS.has(k))
       .map(([key, value]) => {
         let storedValue = String(value);
         if (ENCRYPTED_KEYS.has(key)) storedValue = encrypt(storedValue);

backend/src/controllers/sponsorshipController.js

@@ -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);
   }
 };

backend/src/controllers/ticketController.js

@@ -264,6 +264,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 +317,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 +365,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 +443,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;
     }
@@ -917,7 +919,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;
@@ -1092,7 +1094,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`;

backend/src/controllers/userController.js

@@ -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,18 @@ const getUserProfile = async (req, res) => {
         twoFactorMethod: true,
         createdAt: true,
         updatedAt: true,
-        isActive: true
+        isActive: 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 });
+      res.json({ ...rest, twoFactorRequired: requiresTwoFactor(user), newsPromptPending: !newsAskedAt && !req.impersonation, noticePromptPending });
     } else {
       res.status(404);
       throw new Error('User not found');
@@ -874,21 +901,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 +1162,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({

backend/src/controllers/waitlistController.js

@@ -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);

backend/src/controllers/webhookController.js

@@ -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;
-  }
-}

backend/src/controllers/whatsappBroadcastController.js

@@ -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 });
 

backend/src/controllers/whatsappController.js

@@ -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,

backend/src/controllers/yocoTransactionsController.js

@@ -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
-};

backend/src/index.js

@@ -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);
@@ -163,7 +165,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 +174,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 +193,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');
@@ -508,7 +513,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 +802,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 +886,67 @@ 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: '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 +1087,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: [
@@ -1064,6 +1140,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 +1149,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 }}]},

backend/src/jobs/index.js

@@ -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,14 @@ 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: '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() }),

backend/src/payments/checkouts.js

@@ -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 };

backend/src/payments/index.js

@@ -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,
+};

backend/src/payments/providers/payfast.js

@@ -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,
+};

backend/src/payments/providers/yoco.js

@@ -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,
+};

backend/src/payments/status.js

@@ -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 };

backend/src/payments/webhook.js

@@ -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 };

backend/src/routes/payfastRoutes.js

@@ -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;

backend/src/routes/paymentRoutes.js

@@ -9,17 +9,28 @@ 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');
 
 // Protected routes
 router.post('/', protect, supervisor, createPayment);
-router.post('/yoco-checkout', protect, createYocoCheckout);
+router.get('/providers', listPaymentProviders);
+router.get('/pay/:id', getPayPage);
+router.post('/pay/:id', choosePayProvider);
+router.get('/checkouts/open', protect, supervisor, listOpenCheckouts);
+router.post('/checkouts/check', protect, supervisor, 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, sendPaymentLink);
+// Older names, kept for existing clients
+router.post('/yoco-checkout', protect, createCheckout);
 router.post('/yoco-checkout/send', protect, supervisor, sendPaymentLink);
 router.get('/mypayments', protect, getUserPayments);
 router.post('/:id/send-receipt', protect, sendReceipt);

backend/src/routes/privacyRoutes.js

@@ -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;

backend/src/routes/providerTransactionRoutes.js

@@ -0,0 +1,20 @@
+const express = require('express');
+const router = express.Router();
+const { getAllProviderTransactions, getUnreconciledProviderTransactions, reconcileProviderTransaction, ignoreProviderTransaction } = require('../controllers/providerTransactionsController');
+const { protect, supervisor} = require('../middleware/authMiddleware');
+
+// Mounted at /api/provider-transactions (and /api/yoco-transactions, the older name).
+
+// GET all payment provider transactions (admin/supervisor)
+router.get('/', protect, supervisor, getAllProviderTransactions);
+
+// GET all unreconciled transactions (admin/supervisor)
+router.get('/unreconciled', protect, supervisor, getUnreconciledProviderTransactions);
+
+// POST reconcile a transaction
+router.post('/:id/reconcile', protect, supervisor, reconcileProviderTransaction);
+
+// POST ignore a transaction
+router.post('/:id/ignore', protect, supervisor, ignoreProviderTransaction);
+
+module.exports = router;

backend/src/routes/webhookRoutes.js

@@ -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;

backend/src/routes/yocoTransactionRoutes.js

@@ -1,18 +0,0 @@
-const express = require('express');
-const router = express.Router();
-const { getAllYocoTransactions, getUnreconciledYocoTransactions, reconcileYocoTransaction, ignoreYocoTransaction } = require('../controllers/yocoTransactionsController');
-const { protect, supervisor} = require('../middleware/authMiddleware');
-
-// GET all Yoco transactions (admin/supervisor)
-router.get('/', protect, supervisor, getAllYocoTransactions);
-
-// GET all unreconciled Yoco transactions (admin/supervisor)
-router.get('/unreconciled', protect, supervisor, getUnreconciledYocoTransactions);
-
-// POST reconcile a Yoco transaction
-router.post('/:id/reconcile', protect, supervisor, reconcileYocoTransaction);
-
-// POST ignore a Yoco transaction
-router.post('/:id/ignore', protect, supervisor, ignoreYocoTransaction);
-
-module.exports = router;

backend/src/utils/accessLog.js

@@ -0,0 +1,59 @@
+const prisma = require('../config/db');
+const { getClientIp } = require('./requestUtils');
+
+// What each DataAccessLog action means, for the admin page.
+const ACCESS_ACTIONS = {
+  report_pdf: 'Report downloaded (PDF)',
+  report_excel: 'Report downloaded (Excel)',
+  report_email: 'Report emailed',
+  report_whatsapp: 'Report sent by WhatsApp',
+  attendance_export: 'Attendance register exported',
+  certificates_download: 'Certificates downloaded',
+  group_lists: 'Room/group lists opened',
+  form_responses: 'Attendee form answers viewed',
+  consent_list: 'Parental consent list viewed',
+  medical_list: 'Medical list viewed',
+  backup_download: 'Database backup downloaded',
+  impersonation: 'Viewed the site as another user',
+};
+
+/**
+ * POPIA access log: someone exported or viewed personal information in bulk. Fire-and-
+ * forget like logAdminAction — a logging failure never blocks the export itself.
+ */
+async function logDataAccess(req, { action, what, eventId = null, records = null, sensitive }) {
+  try {
+    // Children's or special information: medical lists always; otherwise anything about a
+    // youth event (one that asks for parental consent).
+    let isSensitive = sensitive ?? (action === 'medical_list');
+    if (!isSensitive && eventId) {
+      const event = await prisma.event.findUnique({ where: { id: eventId }, select: { requiresParentalConsent: true } });
+      isSensitive = !!event?.requiresParentalConsent;
+    }
+    await prisma.dataAccessLog.create({
+      data: {
+        actorId: req.user?.id || null,
+        actorRole: req.user?.role || 'unknown',
+        action,
+        what: String(what || ACCESS_ACTIONS[action] || action).slice(0, 500),
+        eventId: eventId || null,
+        records: Number.isFinite(records) ? records : null,
+        sensitive: isSensitive,
+        ip: getClientIp(req),
+      },
+    });
+  } catch (e) {
+    console.error('Failed to log data access:', e?.message);
+  }
+}
+
+/** Rows in a report payload (main table or layered sections, plus extra tables). */
+function reportRowCount(payload) {
+  const p = payload || {};
+  let n = Array.isArray(p.table?.rows) ? p.table.rows.length : 0;
+  if (Array.isArray(p.layered?.sections)) n += p.layered.sections.reduce((s, sec) => s + (Array.isArray(sec.items) ? sec.items.length : 0), 0);
+  if (Array.isArray(p.extraTables)) n += p.extraTables.reduce((s, t) => s + (Array.isArray(t.rows) ? t.rows.length : 0), 0);
+  return n;
+}
+
+module.exports = { ACCESS_ACTIONS, logDataAccess, reportRowCount };

backend/src/utils/certificates.js

@@ -57,7 +57,7 @@ async function attendanceForCertificates(eventId) {
       holder: { select: { id: true, name: true } },
       user: { select: { id: true, name: true } },
       usages: { select: { quantityRedeemed: true, sessionId: true } },
-      registrationOption: { select: { registrationId: true, eventOptionId: true, variantId: true, sessionId: true } },
+      registrationOption: { select: { registrationId: true, eventOptionId: true, variantId: true, sessionId: true, sessionIds: true } },
     },
     orderBy: { createdAt: 'asc' },
   });

backend/src/utils/email.js

@@ -54,7 +54,7 @@ function isSmtpConfigured() {
   return !!_smtpConfig().host;
 }
 
-async function sendMail({ to, subject, html, text, attachments }) {
+async function sendMail({ to, subject, html, text, attachments, headers }) {
   // Never send to anonymised/deleted accounts
   if (!to || String(to).endsWith('@deleted.invalid')) {
     console.info('[email] Skipping send to deleted account:', to);
@@ -62,7 +62,7 @@ async function sendMail({ to, subject, html, text, attachments }) {
   }
   const { transporter, cfg } = _getTransporter();
   const from = cfg.from || 'no-reply@crosscode.local';
-  const info = await transporter.sendMail({ from, to, subject, html, text, ...(attachments ? { attachments } : {}) });
+  const info = await transporter.sendMail({ from, to, subject, html, text, ...(attachments ? { attachments } : {}), ...(headers ? { headers } : {}) });
 
   if (transporter.options && transporter.options.jsonTransport) {
     try {
@@ -420,7 +420,24 @@ function buildAccountClosedEmail({ name, dataDeleted }) {
   return { text, html: emailWrapper(body, { preheader }) };
 }
 
+/**
+ * A plain message about a privacy (POPIA) request: a heading and paragraphs. Paragraphs
+ * are text (escaped here), so an admin's typed answer can go straight in.
+ */
+function buildPrivacyEmail({ name, heading, paragraphs }) {
+  const org = getOrg();
+  const esc = s => String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '<br/>');
+  const body = `
+    <p style="font-size:22px;font-weight:800;color:#0f172a;margin:0 0 24px 0;letter-spacing:-0.3px">${esc(heading)}</p>
+    <p style="margin:0 0 16px 0;color:#374151">Hi <strong>${esc(name || 'there')}</strong>,</p>
+    ${paragraphs.map(p => `<p style="margin:0 0 16px 0;color:#374151">${esc(p)}</p>`).join('')}
+    <p style="margin:0;color:#374151">Questions? Contact us at <a href="mailto:${org.email}" style="color:#2563eb">${org.email}</a>.</p>`;
+  const text = `Hi ${name || 'there'},\n\n${paragraphs.join('\n\n')}\n\nQuestions? Contact us at ${org.email}.\n\n${org.name}`;
+  return { text, html: emailWrapper(body, { preheader: heading }) };
+}
+
 module.exports = {
+  buildPrivacyEmail,
   sendMail,
   isSmtpConfigured,
   getOrg,

backend/src/utils/notifications.js

@@ -955,12 +955,12 @@ function buildDailySummary(ev, registrations, payments, now, waitlistCount = 0)
 
 /**
  * Generates an invoice PDF for a registration when it still has an outstanding balance,
- * reusing (or, if none was supplied, creating) a Yoco checkout link so the invoice can carry
+ * reusing (or, if none was supplied, creating) a checkout link so the invoice can carry
  * a clickable "pay now" link and a scannable QR code. Returns null when nothing is owed or
  * PDF generation fails — callers fall back to the existing text-only notification either way.
  */
 /**
- * Resolves a Yoco checkout link for an invoice's "pay now" link/QR code. Returns the given
+ * Resolves a checkout link for an invoice's "pay now" link/QR code. Returns the given
  * hint as-is when supplied; otherwise creates a fresh checkout, or null if nothing is owed
  * (no point paying) or checkout creation fails (invoice still generates, just without a link).
  */
@@ -968,16 +968,16 @@ async function resolveInvoicePaymentUrl(reg, { totalDue, totalPaid, paymentUrlHi
   if (paymentUrlHint) return paymentUrlHint;
   if (totalDue - totalPaid <= 0.01) return null;
   try {
-    const { createRegistrationCheckoutInternal } = require('../controllers/paymentController');
+    const { createRegistrationCheckout } = require('../payments/checkouts');
     const baseUrl = process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001';
-    const checkout = await createRegistrationCheckoutInternal(reg.id, reg.userId, {
+    const checkout = await createRegistrationCheckout(reg.id, reg.userId, {
       successUrl: `${baseUrl}/payment/success`,
       cancelUrl: `${baseUrl}/payment/cancel`,
       failureUrl: `${baseUrl}/payment/failure`,
     });
     return checkout.redirectUrl || null;
   } catch (e) {
-    console.warn('Could not create Yoco checkout for invoice PDF:', e?.message || e);
+    console.warn('Could not create a checkout for the invoice PDF:', e?.message || e);
     return null;
   }
 }

backend/src/utils/payfast.js

@@ -0,0 +1,57 @@
+/**
+ * PayFast configuration (Admin → Site Settings → Payments → PayFast).
+ *
+ * Stored in AppSetting: payfast_merchant_id, payfast_merchant_key, payfast_passphrase
+ * (AES-256-GCM encrypted — it signs every payment) and payfast_mode ('sandbox' | 'live',
+ * default sandbox). PAYFAST_MERCHANT_ID / PAYFAST_MERCHANT_KEY / PAYFAST_PASSPHRASE /
+ * PAYFAST_MODE in .env are fallbacks when the database has no value. The merchant key isn't
+ * secret: it travels in the payment form the payer's browser posts to PayFast.
+ */
+
+const { getSetting } = require('./settingsCache');
+
+const KEY_MERCHANT_ID = 'payfast_merchant_id';
+const KEY_MERCHANT_KEY = 'payfast_merchant_key';
+const KEY_PASSPHRASE = 'payfast_passphrase';
+const KEY_MODE = 'payfast_mode';
+
+const HOSTS = { live: 'www.payfast.co.za', sandbox: 'sandbox.payfast.co.za' };
+
+async function getPayfastConfig() {
+  const [merchantId, merchantKey, passphrase, mode] = await Promise.all([
+    getSetting(KEY_MERCHANT_ID, process.env.PAYFAST_MERCHANT_ID),
+    getSetting(KEY_MERCHANT_KEY, process.env.PAYFAST_MERCHANT_KEY),
+    getSetting(KEY_PASSPHRASE, process.env.PAYFAST_PASSPHRASE),
+    getSetting(KEY_MODE, process.env.PAYFAST_MODE),
+  ]);
+  return {
+    merchantId: String(merchantId || '').trim(),
+    merchantKey: String(merchantKey || '').trim(),
+    passphrase: String(passphrase || ''),
+    mode: mode === 'live' ? 'live' : 'sandbox',
+  };
+}
+
+/** PayFast's host for a mode: where payers are sent and where ITNs are confirmed. */
+const payfastHost = (mode) => HOSTS[mode === 'live' ? 'live' : 'sandbox'];
+
+/** Where PayFast should post ITNs: BACKEND_URL (or the request's origin) + /api/webhooks/payfast. */
+function payfastNotifyUrl(req) {
+  const base = (process.env.BACKEND_URL || (req ? `${req.protocol}://${req.get('host')}` : '')).replace(/\/$/, '');
+  return base ? `${base}/api/webhooks/payfast` : '';
+}
+
+/** Why PayFast can't reach the notify URL (null when it can). */
+function notifyUrlProblem(url) {
+  let u;
+  try { u = new URL(url); } catch { return 'Set BACKEND_URL on the server so PayFast knows where to send payment notifications.'; }
+  if (['localhost', '127.0.0.1', '::1', '[::1]'].includes(u.hostname)) {
+    return 'PayFast can\'t reach localhost, so payments won\'t be confirmed automatically. Use a public BACKEND_URL (or a tunnel) to test notifications.';
+  }
+  return null;
+}
+
+module.exports = {
+  KEY_MERCHANT_ID, KEY_MERCHANT_KEY, KEY_PASSPHRASE, KEY_MODE,
+  getPayfastConfig, payfastHost, payfastNotifyUrl, notifyUrlProblem,
+};

backend/src/utils/placeholders.js

@@ -1,5 +1,5 @@
 // Shared template placeholder substitution for bulk emails/WhatsApp messages and broadcasts.
-// Async because {{payment.link}} needs to create a live Yoco checkout session per recipient —
+// Async because {{payment.link}} needs to create a live checkout session per recipient —
 // every other placeholder is a plain synchronous string replace.
 async function replacePlaceholders(str, ctx = {}) {
   if (!str) return str;

backend/src/utils/privacy.js

@@ -0,0 +1,641 @@
+/**
+ * POPIA toolkit, the data subject side: news opt-in and its consent log, unsubscribe
+ * links, the opt-out filter every bulk send goes through, anonymising an account, and
+ * "Download my data".
+ *
+ * Bulk messages come in two kinds:
+ *   - 'update' — about an event the person registered for (venue change, reminder). Sent
+ *     regardless of the news opt-in; the email links to the preferences.
+ *   - 'news'   — News & announcements (marketing). Only to people who opted in on that
+ *     channel, never to an address that unsubscribed, with a one-click unsubscribe.
+ */
+
+const crypto = require('crypto');
+const prisma = require('../config/db');
+
+const CHANNELS = ['email', 'whatsapp'];
+const MESSAGE_KINDS = ['update', 'news'];
+// POPIA gives a responsible party 30 days to respond to a request.
+const REQUEST_DUE_DAYS = 30;
+
+const DELETED_NAME = 'Deleted User';
+const DELETED_ATTENDEE_NAME = 'Deleted attendee';
+
+function frontendUrl() {
+  return String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+}
+
+function backendUrl() {
+  return String(process.env.BACKEND_URL || process.env.API_URL || 'http://localhost:5000').replace(/\/$/, '');
+}
+
+function normaliseKind(kind) {
+  return MESSAGE_KINDS.includes(kind) ? kind : null;
+}
+
+function normaliseEmail(email) {
+  return String(email || '').trim().toLowerCase();
+}
+
+function addressFor(channel, raw) {
+  if (channel === 'whatsapp') return require('./whatsapp').normalizeZAPhone(raw) || null;
+  return normaliseEmail(raw) || null;
+}
+
+// ─── News opt-in ──────────────────────────────────────────────────────────────
+
+const NEWS_FIELD = { email: 'newsEmail', whatsapp: 'newsWhatsApp' };
+
+/**
+ * Set someone's news opt-in. `prefs` is { email?, whatsapp? } (booleans; missing = leave).
+ * Logs one CommunicationConsent row per channel that actually changed — or every channel
+ * given when `logAll` (the first answer to the opt-in question is worth recording even
+ * when it keeps the current value). WhatsApp can't be switched on without a valid phone.
+ */
+async function setNewsPreferences(userId, prefs, { source, ip = null, answered = false, logAll = false } = {}, db = prisma) {
+  const user = await db.user.findUnique({ where: { id: userId }, select: { id: true, phoneNumber: true, newsEmail: true, newsWhatsApp: true } });
+  if (!user) return null;
+  const { isValidZAPhone } = require('./whatsapp');
+
+  const data = {};
+  const log = [];
+  for (const channel of CHANNELS) {
+    if (typeof prefs?.[channel] !== 'boolean') continue;
+    let value = prefs[channel];
+    if (channel === 'whatsapp' && value && !isValidZAPhone(user.phoneNumber)) value = false;
+    const field = NEWS_FIELD[channel];
+    if (value !== user[field]) data[field] = value;
+    if (value !== user[field] || logAll) log.push({ userId, channel, granted: value, source, ip });
+  }
+  if (answered) data.newsAskedAt = new Date();
+
+  const updated = Object.keys(data).length
+    ? await db.user.update({ where: { id: userId }, data, select: { newsEmail: true, newsWhatsApp: true, newsAskedAt: true } })
+    : await db.user.findUnique({ where: { id: userId }, select: { newsEmail: true, newsWhatsApp: true, newsAskedAt: true } });
+  if (log.length) await db.communicationConsent.createMany({ data: log });
+  return updated;
+}
+
+/** The consent history for one person, newest first. */
+function consentHistory(userId, db = prisma) {
+  return db.communicationConsent.findMany({
+    where: { userId },
+    orderBy: { createdAt: 'desc' },
+    select: { id: true, channel: true, granted: true, source: true, createdAt: true },
+  });
+}
+
+// ─── Unsubscribe links ────────────────────────────────────────────────────────
+// A token names an account (u) or, for people without one, an address on a channel (a, c).
+// Signed with JWT_SECRET and never expires: an unsubscribe link must keep working.
+
+function sign(payload) {
+  return crypto.createHmac('sha256', process.env.JWT_SECRET || '').update(`unsubscribe:${payload}`).digest('base64url').slice(0, 32);
+}
+
+function unsubscribeToken(target) {
+  const body = target.userId ? { u: target.userId } : { a: target.address, c: target.channel };
+  const payload = Buffer.from(JSON.stringify(body)).toString('base64url');
+  return `${payload}.${sign(payload)}`;
+}
+
+/** { userId } or { address, channel } for a valid token, else null. */
+function readUnsubscribeToken(token) {
+  const [payload, sig] = String(token || '').split('.');
+  if (!payload || !sig) return null;
+  const expected = sign(payload);
+  if (sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null;
+  try {
+    const body = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    if (typeof body.u === 'string' && body.u) return { userId: body.u };
+    if (typeof body.a === 'string' && body.a && CHANNELS.includes(body.c)) return { address: body.a, channel: body.c };
+  } catch { /* fall through */ }
+  return null;
+}
+
+/** The page people land on from an unsubscribe link. */
+function unsubscribePageUrl(target) {
+  return `${frontendUrl()}/unsubscribe?t=${encodeURIComponent(unsubscribeToken(target))}`;
+}
+
+/** RFC 8058 one-click endpoint, for the List-Unsubscribe header (mail apps POST to it). */
+function oneClickUrl(target) {
+  return `${backendUrl()}/api/privacy/unsubscribe/${encodeURIComponent(unsubscribeToken(target))}/one-click`;
+}
+
+/** What an unsubscribe link refers to, for the landing page. */
+async function describeUnsubscribe(token) {
+  const target = readUnsubscribeToken(token);
+  if (!target) return null;
+  if (target.userId) {
+    const user = await prisma.user.findUnique({ where: { id: target.userId }, select: { email: true, phoneNumber: true, newsEmail: true, newsWhatsApp: true, isActive: true } });
+    if (!user) return null;
+    return {
+      kind: 'account',
+      email: maskEmail(user.email),
+      hasPhone: !!user.phoneNumber,
+      news: { email: user.newsEmail, whatsapp: user.newsWhatsApp },
+    };
+  }
+  const optedOut = !!(await prisma.messagingOptOut.findUnique({ where: { channel_address: { channel: target.channel, address: target.address } } }));
+  return {
+    kind: 'address',
+    channel: target.channel,
+    address: target.channel === 'email' ? maskEmail(target.address) : maskPhone(target.address),
+    optedOut,
+  };
+}
+
+/**
+ * Unsubscribe from news. For an account: the given channels (default both). For an
+ * address: that address on its channel. Returns the new state, or null for a bad token.
+ */
+async function unsubscribe(token, { channels = CHANNELS, source = 'unsubscribe_link', ip = null } = {}) {
+  const target = readUnsubscribeToken(token);
+  if (!target) return null;
+  if (target.userId) {
+    const prefs = {};
+    for (const c of channels) if (CHANNELS.includes(c)) prefs[c] = false;
+    return setNewsPreferences(target.userId, prefs, { source, ip });
+  }
+  await optOutAddress(target.channel, target.address, { source, ip });
+  return { optedOut: true };
+}
+
+/** Record that an address without an account wants no more news on a channel. */
+async function optOutAddress(channel, rawAddress, { source, ip = null } = {}, db = prisma) {
+  const address = addressFor(channel, rawAddress);
+  if (!address) return false;
+  const existing = await db.messagingOptOut.findUnique({ where: { channel_address: { channel, address } } });
+  if (existing) return true;
+  await db.messagingOptOut.create({ data: { channel, address, source } });
+  await db.communicationConsent.create({ data: { address, channel, granted: false, source, ip } });
+  return true;
+}
+
+function maskEmail(email) {
+  const [local, domain] = String(email || '').split('@');
+  if (!domain) return '';
+  return `${local.slice(0, 2)}${'*'.repeat(Math.max(1, local.length - 2))}@${domain}`;
+}
+
+function maskPhone(phone) {
+  const s = String(phone || '');
+  return s.length > 4 ? `${'*'.repeat(s.length - 4)}${s.slice(-4)}` : s;
+}
+
+// ─── Bulk sends ───────────────────────────────────────────────────────────────
+
+/**
+ * Drop recipients a news message mustn't go to. `recipients` are { email } (channel
+ * 'email') or { phone } (channel 'whatsapp'), optionally with userId. Removed: accounts on
+ * that address without the news opt-in for the channel, and addresses that unsubscribed.
+ * Each kept recipient gets `userId` filled in when the address belongs to an account, so
+ * the email footer can link to the account's preferences. Update messages pass through
+ * untouched (apart from the userId lookup). Returns { recipients, skipped }.
+ */
+async function filterRecipients(recipients, { channel, kind }, db = prisma) {
+  const key = channel === 'whatsapp' ? 'phone' : 'email';
+  const addressOf = r => addressFor(channel, r[key]);
+  const addresses = [...new Set(recipients.map(addressOf).filter(Boolean))];
+  if (!addresses.length) return { recipients: [], skipped: recipients.length };
+
+  const users = await db.user.findMany({
+    where: channel === 'whatsapp'
+      ? { phoneNumber: { in: addresses } }
+      : { OR: addresses.map(a => ({ email: { equals: a, mode: 'insensitive' } })) },
+    select: { id: true, email: true, phoneNumber: true, newsEmail: true, newsWhatsApp: true },
+  });
+  const byAddress = new Map(users.map(u => [addressFor(channel, channel === 'whatsapp' ? u.phoneNumber : u.email), u]));
+
+  let optedOut = new Set();
+  if (kind === 'news') {
+    const rows = await db.messagingOptOut.findMany({ where: { channel, address: { in: addresses } }, select: { address: true } });
+    optedOut = new Set(rows.map(r => r.address));
+  }
+
+  const kept = [];
+  for (const r of recipients) {
+    const address = addressOf(r);
+    const user = address ? byAddress.get(address) : null;
+    if (kind === 'news') {
+      if (!address || optedOut.has(address)) continue;
+      if (user && !user[NEWS_FIELD[channel]]) continue;
+    }
+    kept.push({ ...r, userId: r.userId || user?.id || null });
+  }
+  return { recipients: kept, skipped: recipients.length - kept.length };
+}
+
+function escapeHtml(s) {
+  return String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/**
+ * The footer and headers a bulk email gets. News: unsubscribe link + List-Unsubscribe
+ * (one click in Gmail/Apple Mail). Updates: why they got it, and where to manage
+ * preferences. Returns { html, text, headers }.
+ */
+function bulkEmailFooter({ kind, recipient, eventTitle = '' }) {
+  const prefsUrl = `${frontendUrl()}/dashboard/user/privacy`;
+  const style = 'color:#94a3b8;font-size:12px;line-height:1.6;margin:24px 0 0 0;border-top:1px solid #e2e8f0;padding-top:12px';
+  if (kind === 'news') {
+    const target = recipient.userId ? { userId: recipient.userId } : { address: normaliseEmail(recipient.email), channel: 'email' };
+    const url = unsubscribePageUrl(target);
+    return {
+      html: `<p style="${style}">You're receiving this because you chose to get news and announcements from us. <a href="${url}" style="color:#64748b">Unsubscribe</a>${recipient.userId ? ` &middot; <a href="${prefsUrl}" style="color:#64748b">Manage preferences</a>` : ''}</p>`,
+      text: `\n\n—\nYou're receiving this because you chose to get news and announcements from us.\nUnsubscribe: ${url}`,
+      headers: {
+        'List-Unsubscribe': `<${oneClickUrl(target)}>`,
+        'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+      },
+    };
+  }
+  const why = eventTitle ? `you registered for ${eventTitle}` : 'you have a registration or account with us';
+  return {
+    html: `<p style="${style}">You're receiving this because ${escapeHtml(why)}. <a href="${prefsUrl}" style="color:#64748b">Manage your communication preferences</a></p>`,
+    text: `\n\n—\nYou're receiving this because ${why}.\nManage your communication preferences: ${prefsUrl}`,
+    headers: {},
+  };
+}
+
+/** The line a bulk news WhatsApp ends with. */
+function whatsAppNewsFooter(recipient) {
+  const target = recipient.userId ? { userId: recipient.userId } : { address: addressFor('whatsapp', recipient.phone), channel: 'whatsapp' };
+  return `\n\n_Reply STOP to stop news messages, or unsubscribe: ${unsubscribePageUrl(target)}_`;
+}
+
+/** Recognises an opt-out reply ("STOP", "stop.", "Unsubscribe"). */
+function isStopKeyword(text) {
+  return /^\s*(stop|unsubscribe|stop all|opt out|optout)\s*[.!]?\s*$/i.test(String(text || ''));
+}
+
+/**
+ * Someone replied STOP on WhatsApp: no more news on WhatsApp for that number — the
+ * account's opt-in if the number belongs to one, otherwise the number itself.
+ * Returns 'account' | 'address' | null (number not usable).
+ */
+async function whatsAppStop(rawPhone) {
+  const phone = addressFor('whatsapp', rawPhone);
+  if (!phone) return null;
+  const user = await prisma.user.findFirst({ where: { phoneNumber: phone }, select: { id: true } });
+  if (user) {
+    await setNewsPreferences(user.id, { whatsapp: false }, { source: 'whatsapp_stop' });
+    return 'account';
+  }
+  await optOutAddress('whatsapp', phone, { source: 'whatsapp_stop' });
+  return 'address';
+}
+
+// ─── Data requests ────────────────────────────────────────────────────────────
+
+function dueDate(from = new Date()) {
+  return new Date(from.getTime() + REQUEST_DUE_DAYS * 24 * 60 * 60 * 1000);
+}
+
+async function createDataRequest({ user, type, details = null, selfService = false }, db = prisma) {
+  const now = new Date();
+  return db.dataRequest.create({
+    data: {
+      type,
+      userId: user.id,
+      name: user.name,
+      email: user.email,
+      details: details ? String(details).slice(0, 5000) : null,
+      selfService,
+      status: selfService ? 'completed' : 'open',
+      closedAt: selfService ? now : null,
+      dueAt: dueDate(now),
+    },
+  });
+}
+
+/** Who hears about privacy requests: the Information Officer (when set) and every admin. */
+async function privacyContacts(db = prisma) {
+  const { getSettingSync } = require('./settingsCache');
+  const admins = await db.user.findMany({ where: { role: 'admin', isActive: true }, select: { email: true } });
+  const io = getSettingSync('legal_io_email', '');
+  return [...new Set([...(io && !io.endsWith('@example.com') ? [io] : []), ...admins.map(a => a.email)])];
+}
+
+/**
+ * Daily: email the Information Officer and admins a list of open requests due within 7 days
+ * or overdue. Nothing is sent when there are none.
+ */
+async function remindDueRequests(now = new Date(), db = prisma) {
+  const soon = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+  const due = await db.dataRequest.findMany({
+    where: { status: 'open', selfService: false, dueAt: { lte: soon } },
+    orderBy: { dueAt: 'asc' },
+    select: { type: true, name: true, dueAt: true },
+  });
+  if (!due.length) return { due: 0, notified: 0 };
+
+  const { sendMail, buildPrivacyEmail } = require('./email');
+  const to = await privacyContacts(db);
+  const fmt = d => d.toLocaleDateString('en-ZA', { timeZone: 'Africa/Johannesburg' });
+  const content = buildPrivacyEmail({
+    name: '',
+    heading: 'Privacy requests need an answer',
+    paragraphs: [
+      `${due.length} privacy request${due.length === 1 ? ' is' : 's are'} due within a week or overdue. POPIA asks for an answer within 30 days.`,
+      due.map(r => `${r.dueAt < now ? 'OVERDUE' : `Due ${fmt(r.dueAt)}`} — ${r.type} request from ${r.name}`).join('\n'),
+      `Handle them on the Data requests page: ${frontendUrl()}/dashboard/admin/data-requests`,
+    ],
+  });
+  await Promise.allSettled(to.map(email => sendMail({ to: email, subject: 'Privacy requests need an answer', ...content })));
+  return { due: due.length, notified: to.length };
+}
+
+/**
+ * Why an account can't be anonymised yet: registrations (not cancelled) for events that
+ * haven't ended. The person may still need the ticket, or be owed or owe money.
+ */
+async function deletionBlockers(userId, db = prisma) {
+  const regs = await db.registration.findMany({
+    where: { userId, status: { not: 'cancelled' }, event: { endDate: { gte: new Date() } } },
+    select: { id: true, status: true, event: { select: { id: true, title: true, endDate: true } } },
+    orderBy: { createdAt: 'asc' },
+  });
+  return regs.map(r => ({ registrationId: r.id, status: r.status, eventId: r.event.id, eventTitle: r.event.title, endDate: r.event.endDate }));
+}
+
+// ─── Anonymising ──────────────────────────────────────────────────────────────
+
+// Keys in a provider's raw webhook payload that can hold the payer's details (PayFast:
+// name_first, name_last, email_address, cell_number; Yoco: customer metadata).
+const PERSONAL_KEY = /(^|_)(name|first|last|email|phone|cell|mobile|address|customer|surname)/i;
+
+function scrubPersonal(value) {
+  if (Array.isArray(value)) return value.map(scrubPersonal);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = PERSONAL_KEY.test(k) && (typeof v === 'string' || typeof v === 'number') ? '[deleted]' : scrubPersonal(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Remove a person's personal information while keeping the records the church must keep
+ * (payments, registrations, tickets, check-ins — amounts and dates) for its accounts and
+ * historic reports, where they show as "Deleted User". Also covers the attendees on their
+ * registrations (people they booked for) and their place on other people's bookings.
+ * Irreversible. Returns counts for the audit log.
+ */
+async function anonymiseUser(userId, db = prisma) {
+  const user = await db.user.findUnique({ where: { id: userId }, select: { id: true } });
+  if (!user) return null;
+  const { clearTrustedDevices } = require('./twoFactor');
+
+  const counts = await db.$transaction(async tx => {
+    await tx.user.update({
+      where: { id: userId },
+      data: {
+        name: DELETED_NAME,
+        email: `deleted-${crypto.randomUUID()}@deleted.invalid`,
+        password: '',
+        phoneNumber: null,
+        isActive: false,
+        twoFactorEnabled: false,
+        twoFactorMethod: null,
+        tokenVersion: { increment: 1 },
+        newsEmail: false,
+        newsWhatsApp: false,
+      },
+    });
+
+    const attendees = await tx.attendee.findMany({ where: { OR: [{ userId }, { registration: { userId } }] }, select: { id: true } });
+    const attendeeIds = attendees.map(a => a.id);
+    if (attendeeIds.length) {
+      await tx.attendee.updateMany({
+        where: { id: { in: attendeeIds } },
+        data: { name: DELETED_ATTENDEE_NAME, email: null, phone: null, dateOfBirth: null, gender: null, parentName: null, parentEmail: null, parentPhone: null },
+      });
+      await tx.consentRequest.updateMany({
+        where: { attendeeId: { in: attendeeIds } },
+        data: { medical: null, emergency: null, parentName: null, parentEmail: null, parentPhone: null, signedName: null, ip: null, device: null, medicalPurgedAt: new Date() },
+      });
+    }
+
+    // Form answers on their registrations (and for their attendees elsewhere) hold
+    // whatever the form asked — delete the answers, keep that a form was filled in.
+    const answers = await tx.formAnswer.deleteMany({
+      where: { response: { OR: [{ registration: { userId } }, ...(attendeeIds.length ? [{ attendeeId: { in: attendeeIds } }] : [])] } },
+    });
+    await tx.formDraft.deleteMany({ where: { userId } });
+
+    // Feedback stays (it's about the event) but no longer says who gave it.
+    await tx.feedbackResponse.updateMany({ where: { userId }, data: { userId: null } });
+    await tx.feedbackInvite.deleteMany({ where: { userId } });
+
+    await tx.waitlistEntry.updateMany({ where: { userId, status: { in: ['waiting', 'offered'] } }, data: { status: 'left', offerTokenHash: null } });
+    await tx.ticketTransferRequest.deleteMany({ where: { requestedById: userId } });
+    await tx.ticketTransfer.updateMany({ where: { fromUserId: userId }, data: { fromHolderName: DELETED_NAME } });
+    await tx.ticketTransfer.updateMany({ where: { toUserId: userId }, data: { toName: DELETED_NAME } });
+    await tx.certificate.updateMany({ where: { userId }, data: { name: DELETED_NAME } });
+
+    await tx.payment.updateMany({ where: { userId }, data: { sponsorName: null, sponsorMessage: null } });
+    const payments = await tx.payment.findMany({ where: { userId }, select: { id: true } });
+    const txns = payments.length
+      ? await tx.providerTransaction.findMany({ where: { paymentId: { in: payments.map(p => p.id) }, raw: { not: null } }, select: { id: true, raw: true } })
+      : [];
+    for (const t of txns) await tx.providerTransaction.update({ where: { id: t.id }, data: { raw: scrubPersonal(t.raw) } });
+    const checkouts = await tx.providerCheckout.findMany({ where: { metadata: { path: ['userId'], equals: userId } }, select: { id: true, request: true } });
+    for (const c of checkouts) await tx.providerCheckout.update({ where: { id: c.id }, data: { request: scrubPersonal(c.request) } });
+
+    // Consent and notice records stay as proof, without the IP address they came from.
+    await tx.communicationConsent.updateMany({ where: { userId }, data: { ip: null } });
+    await tx.noticeAcceptance.updateMany({ where: { userId }, data: { ip: null } });
+
+    await tx.securityEvent.deleteMany({ where: { userId } });
+    await tx.passwordReset.deleteMany({ where: { userId } });
+    await tx.twoFactorChallenge.deleteMany({ where: { userId } });
+
+    return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length };
+  });
+
+  await clearTrustedDevices(userId);
+  return counts;
+}
+
+// ─── Download my data ─────────────────────────────────────────────────────────
+
+/** Everything held about a person, as plain JSON. */
+async function exportUserData(userId, db = prisma) {
+  const { openJson } = require('./consent');
+  const user = await db.user.findUnique({
+    where: { id: userId },
+    select: {
+      id: true, name: true, email: true, phoneNumber: true, role: true, createdAt: true, updatedAt: true,
+      notificationPreference: true, twoFactorEnabled: true, twoFactorMethod: true,
+      newsEmail: true, newsWhatsApp: true, newsAskedAt: true,
+    },
+  });
+  if (!user) return null;
+
+  const [registrations, payments, tickets, waitlist, certificates, feedback, consents, security, requests, notices] = await Promise.all([
+    db.registration.findMany({
+      where: { userId },
+      orderBy: { createdAt: 'asc' },
+      include: {
+        event: { select: { title: true, startDate: true, endDate: true } },
+        registrationOptions: { include: { eventOption: { select: { name: true } }, variant: { select: { name: true } } } },
+        attendees: { include: { consentRequests: { orderBy: { createdAt: 'desc' }, take: 1 } } },
+        formResponses: { include: { answers: { include: { field: { select: { label: true } } } } } },
+      },
+    }),
+    db.payment.findMany({ where: { userId }, orderBy: { createdAt: 'asc' }, include: { event: { select: { title: true } } } }),
+    db.ticket.findMany({
+      where: { OR: [{ userId }, { holderUserId: userId }] },
+      orderBy: { createdAt: 'asc' },
+      include: { event: { select: { title: true } }, usages: { select: { scannedAt: true, sessionId: true } } },
+    }),
+    db.waitlistEntry.findMany({ where: { userId }, include: { event: { select: { title: true } } } }),
+    db.certificate.findMany({ where: { userId }, include: { event: { select: { title: true } } } }),
+    db.feedbackResponse.findMany({ where: { userId }, include: { form: { include: { event: { select: { title: true } } } }, answers: { include: { field: { select: { label: true } } } } } }),
+    consentHistory(userId, db),
+    db.securityEvent.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, take: 100, select: { type: true, ip: true, device: true, createdAt: true } }),
+    db.dataRequest.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { type: true, status: true, details: true, response: true, createdAt: true, closedAt: true } }),
+    db.noticeAcceptance.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { version: true, source: true, createdAt: true } }),
+  ]);
+
+  return {
+    exportedAt: new Date().toISOString(),
+    account: user,
+    communication: {
+      notificationChannel: user.notificationPreference,
+      news: { email: user.newsEmail, whatsapp: user.newsWhatsApp, answeredAt: user.newsAskedAt },
+      history: consents.map(c => ({ channel: c.channel, granted: c.granted, source: c.source, at: c.createdAt })),
+    },
+    privacyNoticeAccepted: notices.map(n => ({ version: n.version, how: n.source, at: n.createdAt })),
+    registrations: registrations.map(r => ({
+      id: r.id,
+      event: r.event?.title,
+      eventStart: r.event?.startDate,
+      status: r.status,
+      createdAt: r.createdAt,
+      options: r.registrationOptions.map(o => ({ option: o.eventOption?.name, variant: o.variant?.name || null, quantity: o.quantity, price: o.priceSnapshot })),
+      attendees: r.attendees.map(a => {
+        const consent = a.consentRequests[0];
+        return {
+          name: a.name, email: a.email, phone: a.phone, dateOfBirth: a.dateOfBirth, gender: a.gender,
+          parentName: a.parentName, parentEmail: a.parentEmail, parentPhone: a.parentPhone,
+          parentalConsent: consent ? {
+            status: consent.status, signedName: consent.signedName, respondedAt: consent.respondedAt,
+            photoConsent: consent.photoConsent, medical: openJson(consent.medical), emergency: openJson(consent.emergency),
+          } : null,
+        };
+      }),
+      formAnswers: r.formResponses.flatMap(f => f.answers.map(a => ({ question: a.field?.label, answer: a.value }))),
+    })),
+    payments: payments.map(p => ({
+      amount: p.amount, method: p.method, provider: p.provider, status: p.status, event: p.event?.title || null,
+      donation: p.isDonation, sponsorName: p.sponsorName, sponsorMessage: p.sponsorMessage, at: p.createdAt,
+    })),
+    tickets: tickets.map(t => ({ event: t.event?.title, quantity: t.quantity, checkIns: t.usages.map(u => u.scannedAt), createdAt: t.createdAt })),
+    waitlist: waitlist.map(w => ({ event: w.event?.title, quantity: w.quantity, status: w.status, joinedAt: w.createdAt })),
+    certificates: certificates.map(c => ({ event: c.event?.title, name: c.name, code: c.code, issuedAt: c.issuedAt, revoked: !!c.revokedAt })),
+    feedback: feedback.map(f => ({ event: f.form?.event?.title, at: f.createdAt, answers: f.answers.map(a => ({ question: a.field?.label, answer: a.value })) })),
+    accountActivity: security.map(s => ({ type: s.type, ip: s.ip, device: s.device, at: s.createdAt })),
+    dataRequests: requests,
+  };
+}
+
+/** A readable PDF of the export (the JSON is the complete copy). Resolves to a Buffer. */
+async function dataExportPdf(data) {
+  const PDFDocument = require('pdfkit');
+  const { getBranding } = require('./pdfDocs');
+  const org = await getBranding();
+  const doc = new PDFDocument({ size: 'A4', margin: 48 });
+  const chunks = [];
+  doc.on('data', c => chunks.push(c));
+  const done = new Promise(resolve => doc.on('end', () => resolve(Buffer.concat(chunks))));
+
+  const fmt = d => (d ? new Date(d).toLocaleString('en-ZA', { timeZone: 'Africa/Johannesburg' }) : '—');
+  const heading = text => {
+    if (doc.y > doc.page.height - 120) doc.addPage();
+    doc.moveDown(0.8).fillColor(org.brandColor).font('Helvetica-Bold').fontSize(13).text(text).moveDown(0.3).fillColor('#1e293b');
+  };
+  const line = (label, value) => doc.font('Helvetica-Bold').fontSize(10).text(`${label}: `, { continued: true }).font('Helvetica').text(value == null || value === '' ? '—' : String(value));
+  const para = text => doc.font('Helvetica').fontSize(10).text(text);
+
+  doc.fillColor(org.brandColor).font('Helvetica-Bold').fontSize(20).text('Your personal information');
+  doc.fillColor('#64748b').font('Helvetica').fontSize(10).text(`${org.name} · exported ${fmt(data.exportedAt)}`);
+  doc.moveDown(0.4).text('This is a readable summary. The JSON file you can download alongside it is the complete copy.');
+  doc.fillColor('#1e293b');
+
+  const a = data.account;
+  heading('Account');
+  line('Name', a.name); line('Email', a.email); line('Phone', a.phoneNumber); line('Role', a.role);
+  line('Created', fmt(a.createdAt)); line('Two-factor', a.twoFactorEnabled ? `on (${a.twoFactorMethod})` : 'off');
+
+  heading('Communication');
+  line('Notifications by', a.notificationPreference);
+  line('News by email', data.communication.news.email ? 'yes' : 'no');
+  line('News by WhatsApp', data.communication.news.whatsapp ? 'yes' : 'no');
+  for (const h of data.communication.history) para(`${fmt(h.at)} — ${h.channel} news ${h.granted ? 'on' : 'off'} (${h.source.replace(/_/g, ' ')})`);
+
+  heading(`Registrations (${data.registrations.length})`);
+  for (const r of data.registrations) {
+    doc.font('Helvetica-Bold').fontSize(10).text(`${r.event} — ${r.status}`).font('Helvetica');
+    para(`Registered ${fmt(r.createdAt)}; ${r.options.map(o => `${o.quantity} × ${o.option}${o.variant ? ` (${o.variant})` : ''}`).join(', ')}`);
+    for (const p of r.attendees) para(`Attendee: ${p.name}${p.dateOfBirth ? `, born ${new Date(p.dateOfBirth).toLocaleDateString('en-ZA')}` : ''}${p.parentalConsent ? `, parental consent ${p.parentalConsent.status}` : ''}`);
+    for (const f of r.formAnswers) para(`${f.question}: ${f.answer}`);
+    doc.moveDown(0.3);
+  }
+
+  heading(`Payments (${data.payments.length})`);
+  for (const p of data.payments) para(`${fmt(p.at)} — R${Number(p.amount).toFixed(2)} ${p.method}${p.event ? `, ${p.event}` : ''}${p.donation ? ' (donation)' : ''}`);
+
+  heading(`Tickets (${data.tickets.length})`);
+  for (const t of data.tickets) para(`${t.event} — ${t.quantity} place${t.quantity === 1 ? '' : 's'}, ${t.checkIns.length} check-in${t.checkIns.length === 1 ? '' : 's'}`);
+
+  if (data.certificates.length) {
+    heading('Certificates');
+    for (const c of data.certificates) para(`${c.event} — ${c.code}${c.revoked ? ' (withdrawn)' : ''}`);
+  }
+  if (data.feedback.length) {
+    heading('Feedback you gave');
+    for (const f of data.feedback) {
+      doc.font('Helvetica-Bold').fontSize(10).text(f.event || 'Event').font('Helvetica');
+      for (const ans of f.answers) para(`${ans.question}: ${ans.answer}`);
+    }
+  }
+  heading('Recent account activity');
+  for (const s of data.accountActivity.slice(0, 20)) para(`${fmt(s.at)} — ${s.type.replace(/_/g, ' ')}${s.device ? `, ${s.device}` : ''}`);
+
+  doc.end();
+  return done;
+}
+
+module.exports = {
+  CHANNELS,
+  MESSAGE_KINDS,
+  REQUEST_DUE_DAYS,
+  DELETED_NAME,
+  normaliseKind,
+  setNewsPreferences,
+  consentHistory,
+  unsubscribeToken,
+  readUnsubscribeToken,
+  unsubscribePageUrl,
+  describeUnsubscribe,
+  unsubscribe,
+  optOutAddress,
+  filterRecipients,
+  bulkEmailFooter,
+  whatsAppNewsFooter,
+  isStopKeyword,
+  whatsAppStop,
+  createDataRequest,
+  privacyContacts,
+  remindDueRequests,
+  deletionBlockers,
+  scrubPersonal,
+  anonymiseUser,
+  exportUserData,
+  dataExportPdf,
+};

backend/src/utils/privacyNotice.js

@@ -0,0 +1,443 @@
+/**
+ * The privacy notice: the built-in text (version 0), published versions (PrivacyNotice),
+ * the admin's draft, and who has accepted which version.
+ *
+ * A notice is a list of sections { id, title, body }. A body is plain text, one paragraph
+ * per line; a line starting with "• " is a bullet. Placeholders are filled in when the
+ * notice is shown, so it follows Site settings and the operator register:
+ *   {org} {orgEmail} {website} {ioName} {ioEmail} {medicalRetentionDays}
+ *   {operators} — on a line of its own: one bullet per active operator.
+ *   {retention} — on a line of its own: one bullet per retention period (utils/retention.js).
+ */
+
+const prisma = require('../config/db');
+
+const PLACEHOLDERS = ['org', 'orgEmail', 'website', 'ioName', 'ioEmail', 'medicalRetentionDays', 'operators', 'retention'];
+const MAX_SECTIONS = 40;
+const MAX_TITLE = 200;
+const MAX_BODY = 20000;
+const DRAFT_KEY = 'privacy_notice_draft';
+
+const DEFAULT_SECTIONS = [
+  {
+    id: 'summary',
+    title: 'Plain English Summary',
+    body: [
+      "We respect your privacy — here's what you need to know:",
+      '• We only collect info needed to run events: registrations, payments, tickets and check-in.',
+      '• We store your info safely on South African servers.',
+      "• We don't sell your data, and only share it with the services listed in section 9, which process payments and deliver messages for us.",
+      '• If you register other people or pass a ticket on, we only use the email or phone number you type to contact them. We never show you whether someone has an account with us.',
+      '• For youth events, a parent or guardian gives consent. Medical details are encrypted, seen only by the event leaders who need them, and deleted shortly after the event.',
+      '• Online payments go through Yoco or PayFast; we never see your card details.',
+      '• We send tickets, updates and security alerts by email and/or WhatsApp. News and announcements are sent only if you ask for them, and you can unsubscribe at any time.',
+      '• Visit statistics are only collected if you click "Allow" on the cookie notice — no third-party analytics.',
+      '• On the Privacy page in your account you can download your data, ask for corrections, and delete your account.',
+    ].join('\n'),
+  },
+  {
+    id: 'introduction',
+    title: '1. Introduction',
+    body: [
+      "{org} ('we', 'us', 'our') values your privacy and is committed to protecting your personal information in accordance with the Protection of Personal Information Act (POPIA).",
+      'This notice explains what data we collect, how we use it, and your rights.',
+    ].join('\n'),
+  },
+  {
+    id: 'information',
+    title: '2. Information We Collect',
+    body: [
+      'We collect the following information when you interact with our platform:',
+      '• Account information: name, email address, phone number, notification preference and password (stored only as an encrypted hash). If you use two-factor authentication, we keep which method you use; codes are short-lived and never stored in readable form.',
+      '• Security records: sign-ins, password changes and similar account events, with the time, IP address and device type, so we can alert you and investigate misuse.',
+      '• Event information: events you register for, ticket selections, discount codes used, attendee form answers, waitlist requests, ticket check-ins (when your ticket was scanned), and room or group allocations.',
+      '• Details about other people you register (see section 3), and parental consent details for youth events (see section 8).',
+      '• Payment information: processed by our payment provider (Yoco or PayFast); we receive only payment status, amount and reference numbers. If you sponsor a spot, we record the amount and, unless you give anonymously, the name and message you choose to add.',
+      "• Feedback: answers you give to post-event feedback forms. If an event's feedback is anonymous, your answers are not linked to your name.",
+      '• Your choices: whether you want news and announcements, which version of this notice you accepted, and when you made each choice.',
+      '• Communication data: emails or messages exchanged with our team.',
+      '• Visit statistics: only if you allow them on the cookie notice (see section 11).',
+      'We do not collect or store credit card numbers or bank details.',
+      'Accounts may be created by an administrator, or when someone registers you or transfers a ticket to you, with a mobile number or email address only. You can activate such an account at any time.',
+    ].join('\n'),
+  },
+  {
+    id: 'others',
+    title: '3. People You Register or Transfer Tickets To',
+    body: [
+      'You can register other people (for example family members) and give each one their own ticket, or pass your ticket on to someone else.',
+      '• You type their name and, optionally, their email address or phone number. There is no search or list of existing users to choose from, and we never tell you whether the details you enter belong to an account.',
+      '• We use those details only to send that person their ticket, their attendee form, a parental consent request (youth events), or — for a transfer — a link to accept the ticket. A transfer only happens once they accept it; they can also decline.',
+      "• If the email or phone number matches an existing account, the ticket also appears in that person's own account. Otherwise an account may be created for them, which they can activate if they wish.",
+      "• Some events ask for each person's date of birth or gender (for example, to allocate rooms at a camp).",
+      'By entering someone else\'s details, you confirm that you are allowed to share them with us for this purpose (for a child, that you are their parent or guardian or have their permission).',
+    ].join('\n'),
+  },
+  {
+    id: 'use',
+    title: '4. How We Use Your Information',
+    body: [
+      'We use your information to:',
+      '• Process event registrations, payments, discounts and refunds.',
+      '• Send updates about events you registered for — confirmations, reminders and changes — by email and/or WhatsApp (based on your preference).',
+      '• Send news and announcements about upcoming events, only if you asked for them. Every such email has an unsubscribe link, and you can reply STOP on WhatsApp.',
+      '• Send security notifications for new logins, password changes, and account actions on your account.',
+      '• Deliver your event tickets via email attachment and/or WhatsApp PDF (based on your preference).',
+      '• Check tickets in at the door, including with scanners that keep working without an internet connection.',
+      '• Offer places from a waitlist, arrange rooms and groups, and ask for parental consent on youth events.',
+      '• Send you an optional feedback form after an event, with one reminder.',
+      '• Manage user accounts and event attendance records, and give support when you ask for help.',
+      '• Improve our events and website (using anonymous statistics, and only with your permission).',
+      '• Comply with legal obligations.',
+    ].join('\n'),
+  },
+  {
+    id: 'whatsapp',
+    title: '5. WhatsApp Communications',
+    body: [
+      "If you choose 'WhatsApp' or 'Both' as your notification preference, we will use your South African mobile number to send you messages via WhatsApp. These messages may include:",
+      '• Event registration confirmations and updates.',
+      '• Payment receipts.',
+      '• Your event tickets (as a PDF document).',
+      '• Security alerts such as new login notifications, password changes, and account closure confirmations.',
+      '• News and announcements, only if you asked for them on WhatsApp. Reply STOP to any of these to stop them.',
+      'WhatsApp communications are delivered through WAWP (wawp.net), a third-party WhatsApp Business API provider. Your mobile number is transmitted to WAWP solely for the purpose of delivering your messages.',
+      'Security-critical messages (login alerts, password resets, account closures) are always sent via email regardless of your preference, and additionally sent via WhatsApp if your preference includes it.',
+      "You may change your notification preference at any time from the Profile & Security page in your account. Selecting 'Email only' will stop WhatsApp messages from being sent to you.",
+      'For accounts registered without a valid email address (e.g. walk-in or at-the-door registrations), WhatsApp will be used as the primary delivery channel for payment confirmations and ticket delivery, regardless of notification preference, since email is unavailable.',
+      'If your account requires activation and no email address is on file, the activation link will be sent to your WhatsApp number instead.',
+      "WhatsApp is a product of Meta Platforms, Inc. By receiving WhatsApp messages from us, you are subject to WhatsApp's own Terms of Service and Privacy Policy.",
+    ].join('\n'),
+  },
+  {
+    id: 'storage',
+    title: '6. Where We Store Your Data',
+    body: [
+      'All data is securely stored on cloud servers hosted in South Africa.',
+      'We use appropriate technical and organisational measures to protect your information from unauthorised access, alteration, or disclosure.',
+    ].join('\n'),
+  },
+  {
+    id: 'retention',
+    title: '7. Data Retention',
+    body: [
+      'We keep personal information only as long as we need it:',
+      '{retention}',
+      "• Ticket lists downloaded to a staff member's scanner for offline check-in are deleted from that device when offline mode is ended.",
+      'You can ask for your account to be deleted at any time from the Privacy page in your account. Your account is closed straight away, and your personal information — your name and contact details, the people you registered, your form answers — is deleted within 30 days (after any upcoming event you registered for). Payment and registration records are kept without your name, because the law requires us to keep financial records.',
+    ].join('\n'),
+  },
+  {
+    id: 'children',
+    title: '8. Children, Parental Consent and Health Information',
+    body: [
+      'Users under 18 may only create an account or register for events with the consent and supervision of a parent or guardian.',
+      'We do not knowingly collect or process personal information of minors without such consent.',
+      "For youth events, each attendee's date of birth is required. For anyone under 18, the parent or guardian named at registration is sent a consent request by email and WhatsApp, where they review the event details and give or decline consent. Their typed name, the time, the wording agreed to, and the IP address and device type used are recorded as proof of consent. A young person can't be checked in until consent is given.",
+      "The consent form may ask for medical information (such as allergies, medication and conditions) and an emergency contact. This is special personal information under POPIA. We collect it only with the parent's or guardian's consent, for the young person's safety at the event. It is stored encrypted and shown only to supervisors who need it, and each time the medical list is viewed this is recorded. It is deleted after the event as described in section 7.",
+      'A parent or guardian may also say whether photos of the young person may be used.',
+    ].join('\n'),
+  },
+  {
+    id: 'sharing',
+    title: '9. Who Can See Your Information',
+    body: [
+      'We do not sell or rent your personal information. Outside our organisation, it is shared only with these service providers ("operators"), each only for its purpose:',
+      '{operators}',
+      '• Anyone we are required to share it with under South African law.',
+      'Within our organisation, people see only what they need:',
+      "• Door staff see a ticket's holder name, ticket type and check-in status when scanning.",
+      '• Group, room or bus leaders see the names, ages and contact numbers of the people in their group. Medical details are shown to supervisors only.',
+      '• Supervisors and administrators manage registrations, payments and communication for events. Every export of personal information (reports, attendance registers, lists) is recorded.',
+      '• Support access: to help with a problem (for example, a ticket not showing), an administrator may view the site as you see it for up to 30 minutes. This is strictly read-only — nothing can be changed, paid, registered or sent on your behalf. A reason must be given, and the session and every page viewed are recorded. The organisation may choose to email you whenever this happens.',
+      '• Sponsors never see who was helped by a sponsorship; the public only sees how many spots were sponsored.',
+      '• Nobody else can see whether you have an account.',
+    ].join('\n'),
+  },
+  {
+    id: 'rights',
+    title: '10. Your Rights (under POPIA)',
+    body: [
+      'Under POPIA, you have the right to:',
+      '• Access your personal information.',
+      '• Request correction or deletion of your data.',
+      '• Withdraw consent for processing, including for news and announcements.',
+      '• Object to direct marketing.',
+      '• Lodge a complaint with the Information Regulator of South Africa.',
+      'The Privacy page in your account lets you download your data, ask for a correction, delete your account and choose which messages you receive. We answer requests within 30 days.',
+      'To contact the Information Regulator:',
+      '• Website: www.inforeg.org.za',
+      '• Email: enquiries@inforeg.org.za',
+      'To exercise your rights directly with us, contact our Information Officer using the details in section 14 below.',
+    ].join('\n'),
+  },
+  {
+    id: 'cookies',
+    title: '11. Cookie Policy (Cookies and Browser Storage)',
+    body: [
+      "Our own site does not set tracking cookies. It keeps a few small items in your browser's storage (localStorage, and on staff scanners IndexedDB and an offline page cache). These work much like cookies, so this policy covers them. We do not use third-party analytics, advertising or tracking pixels.",
+      "Strictly necessary — always used, because the site can't work without them:",
+      '• hope_events_token — keeps you signed in.',
+      '• hope_events_user_cache — your last loaded profile, so pages keep working if your connection drops.',
+      '• hope_events_device — only if you tick "Trust this device" when entering a two-factor code, so you aren\'t asked for a code every time.',
+      '• hope_events_cookie_consent — remembers your choice on the cookie notice.',
+      '• banner_dismissed_… — remembers notices you have closed.',
+      'Staff and administrators only:',
+      '• hope_events_scan_device, hope_events_offline_lock and the "hope-events-offline-scan" database — on a staff member\'s scanner in offline mode: the device\'s id, the ticket list for the section being scanned, and scans waiting to upload. They are deleted when offline mode is ended. A copy of the scanner page is also cached so it opens without a connection.',
+      '• hope_events_admin_token, hope_events_admin_user_cache and hope_events_impersonation — only while an administrator is using read-only support access (section 9), and removed when it ends.',
+      'Optional — only if you click "Allow" on the cookie notice:',
+      '• hope_events_analytics_sid — a random, anonymous visit id. With it we count, in our own statistics, how many visitors view an event, start registering, and complete a registration. We record only that step, where the visit came from (for example a short link or campaign link) and the type of device — never your name, IP address or browsing history. Detailed records become anonymous daily totals after 90 days. If you choose "No thanks", nothing is counted and no visit id is created.',
+      'Third parties:',
+      "• Event pages with a location show an embedded Google Maps map. Google may set its own cookies when the map loads (see Google's privacy policy).",
+      "• Payments open the payment provider's secure checkout page (Yoco or PayFast), which uses its own cookies on the provider's site.",
+      'You can change your cookie choice at any time with "Cookie settings" at the bottom of every page, or with the button above. You can also clear your browser\'s storage in your browser settings; this signs you out.',
+    ].join('\n'),
+  },
+  {
+    id: 'security',
+    title: '12. Security',
+    body: [
+      'Your personal data is encrypted during transmission and stored using industry-standard security protocols. Medical and emergency details are additionally encrypted in our database.',
+      'Passwords are encrypted and cannot be viewed by anyone, including administrators.',
+      'Two-factor authentication is available to everyone and is required for supervisors and administrators.',
+      'Links we send for consent, feedback, ticket transfers and unsubscribing are personal. Only a secure fingerprint of most links is stored, not the link itself.',
+      'In the event of a data breach that poses a risk to your rights, we will notify you and the Information Regulator of South Africa as required under POPIA section 22, without unreasonable delay.',
+    ].join('\n'),
+  },
+  {
+    id: 'changes',
+    title: '13. Changes to This Notice',
+    body: [
+      'We may update this notice from time to time. Each update is published as a new version with its date, and earlier versions stay available on this page.',
+      'If a change is significant, we ask you to accept the new version the next time you log in.',
+    ].join('\n'),
+  },
+  {
+    id: 'officer',
+    title: '14. Information Officer',
+    body: [
+      'The Information Officer responsible for overseeing compliance with POPIA on behalf of {org} is:',
+      '• Name: {ioName}',
+      '• Email: {ioEmail}',
+      'You may contact the Information Officer for any POPIA-related requests, including access to your personal data, requests for correction or deletion, and formal complaints.',
+    ].join('\n'),
+  },
+  {
+    id: 'contact',
+    title: '15. Contact',
+    body: [
+      'For general privacy-related questions or requests, you can also contact us at:',
+      '📧 {orgEmail}',
+    ].join('\n'),
+  },
+];
+
+function defaultSections() {
+  return DEFAULT_SECTIONS.map(s => ({ ...s }));
+}
+
+function slugify(text) {
+  return String(text || '').toLowerCase().replace(/^\d+\.\s*/, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'section';
+}
+
+/** Checks and tidies sections from the editor. Throws a message fit for the admin. */
+function cleanSections(input) {
+  if (!Array.isArray(input) || input.length === 0) throw new Error('The notice needs at least one section.');
+  if (input.length > MAX_SECTIONS) throw new Error(`At most ${MAX_SECTIONS} sections.`);
+  const seen = new Set();
+  return input.map((s, i) => {
+    const title = String(s?.title || '').trim();
+    const body = String(s?.body || '').replace(/\r\n/g, '\n').trim();
+    if (!title) throw new Error(`Section ${i + 1} needs a title.`);
+    if (title.length > MAX_TITLE) throw new Error(`The title of "${title.slice(0, 40)}…" is too long.`);
+    if (body.length > MAX_BODY) throw new Error(`"${title}" is too long.`);
+    let id = slugify(s?.id || title);
+    while (seen.has(id)) id = `${id}-${i + 1}`;
+    seen.add(id);
+    return { id, title, body };
+  });
+}
+
+/** Settings and operators the placeholders are filled from. */
+async function noticeContext(db = prisma) {
+  const { getSetting } = require('./settingsCache');
+  const [org, orgEmail, website, ioName, ioEmail, medicalDays, operators, retention] = await Promise.all([
+    getSetting('org_name', process.env.ORG_NAME || 'Cross Code'),
+    getSetting('org_email', ''),
+    getSetting('legal_website_url', ''),
+    getSetting('legal_io_name', ''),
+    getSetting('legal_io_email', ''),
+    getSetting('consent_medical_retention_days', ''),
+    db.operator.findMany({ where: { active: true }, orderBy: [{ order: 'asc' }, { name: 'asc' }] }),
+    require('./retention').noticeLines(db),
+  ]);
+  // Unset legal fields show an obviously-unfinished placeholder, never someone's real details.
+  return {
+    org,
+    orgEmail: orgEmail || 'privacy@example.com',
+    website: website || 'example.com',
+    ioName: ioName || '[not yet configured]',
+    ioEmail: ioEmail || 'io@example.com',
+    medicalRetentionDays: String(parseInt(medicalDays, 10) || 30),
+    operators,
+    retention,
+  };
+}
+
+// Placeholders that stand on a line of their own and become several bullet lines.
+const LIST_PLACEHOLDERS = {
+  operators: ctx => (ctx.operators.length ? ctx.operators.map(operatorLine) : ['• (No service providers listed.)']),
+  retention: ctx => ctx.retention || [],
+};
+
+function operatorLine(o) {
+  return `• ${o.name}${o.location ? ` (${o.location})` : ''} — ${o.purpose}. ${o.dataShared ? `Receives: ${o.dataShared}.` : ''}`.trim();
+}
+
+/** Sections with their placeholders filled in. */
+function renderSections(sections, ctx) {
+  return sections.map(s => {
+    const body = String(s.body || '')
+      .split('\n')
+      .flatMap(line => {
+        const list = line.trim().match(/^\{(\w+)\}$/)?.[1];
+        return list && LIST_PLACEHOLDERS[list] ? LIST_PLACEHOLDERS[list](ctx) : [line];
+      })
+      .map(line => line.replace(/\{(\w+)\}/g, (m, key) => (!LIST_PLACEHOLDERS[key] && PLACEHOLDERS.includes(key) ? ctx[key] : m)))
+      .join('\n');
+    return { id: s.id, title: s.title, body };
+  });
+}
+
+async function latestNotice(db = prisma) {
+  return db.privacyNotice.findFirst({ orderBy: { version: 'desc' } });
+}
+
+/** The newest version people must have accepted, or null when none asks for it. */
+async function requiredVersion(db = prisma) {
+  const row = await db.privacyNotice.findFirst({ where: { requiresAcceptance: true }, orderBy: { version: 'desc' }, select: { version: true } });
+  return row ? row.version : null;
+}
+
+/** Whether someone must (re-)accept the notice before carrying on. */
+async function noticePromptPending(user, db = prisma) {
+  const required = await requiredVersion(db);
+  if (required == null) return false;
+  return (user.noticeVersionAccepted ?? -1) < required;
+}
+
+/**
+ * A notice for the public page: the given version (or the current one), rendered, with
+ * the list of versions. Version 0 is the built-in notice.
+ */
+async function publicNotice(version, db = prisma) {
+  const versions = await db.privacyNotice.findMany({
+    orderBy: { version: 'desc' },
+    select: { version: true, publishedAt: true, changeSummary: true, requiresAcceptance: true },
+  });
+  const ctx = await noticeContext(db);
+  const wanted = version == null ? versions[0]?.version ?? 0 : version;
+
+  if (wanted === 0) {
+    if (version != null && versions.length) return null; // the built-in text isn't a past version
+    const { getSetting } = require('./settingsCache');
+    return {
+      version: 0,
+      builtIn: true,
+      current: true,
+      publishedAt: null,
+      effectiveDate: (await getSetting('legal_effective_date', '')) || '[not yet set]',
+      changeSummary: null,
+      sections: renderSections(DEFAULT_SECTIONS, ctx),
+      versions,
+    };
+  }
+  const notice = await db.privacyNotice.findUnique({ where: { version: wanted } });
+  if (!notice) return null;
+  return {
+    version: notice.version,
+    builtIn: false,
+    current: notice.version === versions[0]?.version,
+    publishedAt: notice.publishedAt,
+    effectiveDate: notice.publishedAt.toLocaleDateString('en-ZA', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'Africa/Johannesburg' }),
+    changeSummary: notice.changeSummary,
+    sections: renderSections(notice.sections, ctx),
+    versions,
+  };
+}
+
+/** The version a new acceptance is for: the latest published, or 0 (built-in). */
+async function currentVersion(db = prisma) {
+  return (await latestNotice(db))?.version ?? 0;
+}
+
+/** Record that someone accepted the current notice. */
+async function acceptNotice(userId, { source, ip = null } = {}, db = prisma) {
+  const version = await currentVersion(db);
+  await db.user.update({ where: { id: userId }, data: { noticeVersionAccepted: version } });
+  await db.noticeAcceptance.create({ data: { userId, version, source, ip } });
+  return version;
+}
+
+// ─── Draft (admin) ────────────────────────────────────────────────────────────
+
+/** The draft being edited, or — when there is none — the current notice's sections. */
+async function getDraft(db = prisma) {
+  const row = await db.appSetting.findUnique({ where: { key: DRAFT_KEY } });
+  if (row?.value) {
+    try {
+      const draft = JSON.parse(row.value);
+      if (Array.isArray(draft.sections)) return { sections: draft.sections, savedAt: draft.savedAt || null, isDraft: true };
+    } catch { /* fall through to the current notice */ }
+  }
+  const latest = await latestNotice(db);
+  return { sections: latest ? latest.sections : defaultSections(), savedAt: null, isDraft: false };
+}
+
+async function saveDraft(sections, db = prisma) {
+  const clean = cleanSections(sections);
+  const value = JSON.stringify({ sections: clean, savedAt: new Date().toISOString() });
+  await db.appSetting.upsert({ where: { key: DRAFT_KEY }, update: { value }, create: { key: DRAFT_KEY, value } });
+  return clean;
+}
+
+async function discardDraft(db = prisma) {
+  await db.appSetting.deleteMany({ where: { key: DRAFT_KEY } });
+}
+
+/** Publish the given sections as the next version, and clear the draft. */
+async function publish({ sections, changeSummary, requiresAcceptance, publishedById }, db = prisma) {
+  const clean = cleanSections(sections);
+  const notice = await db.$transaction(async tx => {
+    const latest = await tx.privacyNotice.findFirst({ orderBy: { version: 'desc' }, select: { version: true } });
+    return tx.privacyNotice.create({
+      data: {
+        version: (latest?.version ?? 0) + 1,
+        sections: clean,
+        changeSummary: changeSummary ? String(changeSummary).trim().slice(0, 2000) : null,
+        requiresAcceptance: !!requiresAcceptance,
+        publishedById: publishedById || null,
+      },
+    });
+  });
+  await discardDraft(db);
+  return notice;
+}
+
+module.exports = {
+  PLACEHOLDERS,
+  defaultSections,
+  cleanSections,
+  noticeContext,
+  renderSections,
+  operatorLine,
+  requiredVersion,
+  noticePromptPending,
+  publicNotice,
+  currentVersion,
+  acceptNotice,
+  getDraft,
+  saveDraft,
+  discardDraft,
+  publish,
+};

backend/src/utils/readiness.js

@@ -0,0 +1,95 @@
+/**
+ * The POPIA readiness checklist for Admin → Privacy: what's set up, what isn't, and where to
+ * fix it. Checks that don't apply to this install (e.g. WhatsApp STOP without WhatsApp) are
+ * left out of the score.
+ */
+
+const prisma = require('../config/db');
+
+const DAY = 24 * 60 * 60 * 1000;
+// Generic names the operator register starts with, which should be replaced with the real provider.
+const GENERIC_OPERATORS = ['Email delivery provider', 'Hosting provider'];
+
+async function readiness(now = new Date(), db = prisma) {
+  const { getSetting } = require('./settingsCache');
+  const setting = key => getSetting(key, '');
+  const [ioName, ioEmail, operatorName, website, smtpHost] = await Promise.all([
+    setting('legal_io_name'), setting('legal_io_email'), setting('legal_operator_name'), setting('legal_website_url'), setting('smtp_host'),
+  ]);
+
+  const retention = require('./retention');
+  const { isEnabled, JOBS } = require('../jobs');
+  const [notices, operators, policies, lastRun, overdue, openBreaches, webhookSeen, whatsappConfigured, backups] = await Promise.all([
+    db.privacyNotice.count(),
+    db.operator.findMany({ where: { active: true }, select: { name: true, location: true } }),
+    retention.getPolicies(db),
+    retention.lastRun(db),
+    db.dataRequest.count({ where: { status: 'open', selfService: false, dueAt: { lt: now } } }),
+    db.securityBreach.findMany({ where: { status: { not: 'closed' } }, select: { title: true, discoveredAt: true, regulatorNotifiedAt: true } }),
+    db.appSetting.findUnique({ where: { key: 'wawp_webhook_last_seen' } }),
+    require('./whatsapp').isConfigured().catch(() => false),
+    require('./backupUtils').listBackups().catch(() => []),
+  ]);
+
+  const checks = [];
+  const add = (key, label, ok, detail, href, applies = true) => checks.push({ key, label, ok: !!ok, detail, href, applies });
+
+  add('io', 'Information Officer named', ioName && ioEmail,
+    ioName && ioEmail ? `${ioName} (${ioEmail})` : 'Set the Information Officer\'s name and email address — they appear on the privacy notice and contact page.',
+    '/dashboard/admin/settings?tab=legal');
+  add('legal', 'Responsible party and website filled in', operatorName && website,
+    operatorName && website ? `${operatorName} · ${website}` : 'Fill in the operator/responsible party and website for the legal pages.',
+    '/dashboard/admin/settings?tab=legal');
+  add('notice', 'Privacy notice published', notices > 0,
+    notices > 0 ? `${notices} version${notices === 1 ? '' : 's'} published` : 'Review the privacy notice and publish your own version (the built-in text is a starting point).',
+    '/dashboard/admin/privacy?tab=notice');
+
+  const vague = operators.filter(o => !o.location || GENERIC_OPERATORS.includes(o.name)).map(o => o.name);
+  add('operators', 'Operators listed with their details', operators.length && !vague.length,
+    !operators.length ? 'List the services that process personal information for you.' : vague.length ? `Check: ${vague.join(', ')} (name the real provider and where it processes data).` : `${operators.length} operator${operators.length === 1 ? '' : 's'} listed`,
+    '/dashboard/admin/privacy?tab=operators');
+
+  add('retention_reviewed', 'Retention periods reviewed', policies.reviewedAt,
+    policies.reviewedAt ? `Saved ${new Date(policies.reviewedAt).toLocaleDateString('en-ZA')}` : 'Check the retention periods suit your organisation, and save them.',
+    '/dashboard/admin/privacy?tab=retention');
+  const retentionJob = JOBS.find(j => j.name === 'retention');
+  const ranRecently = lastRun?.at && now - new Date(lastRun.at) < 2 * DAY;
+  add('retention_running', 'Retention job running', isEnabled(retentionJob) && ranRecently,
+    !isEnabled(retentionJob) ? 'The retention job is switched off (RETENTION_JOBS_ENABLED or JOBS_ENABLED).' : ranRecently ? `Last ran ${new Date(lastRun.at).toLocaleString('en-ZA')}` : 'It hasn\'t run in the last two days — check Background jobs.',
+    '/dashboard/admin/settings?tab=jobs');
+
+  add('requests', 'Privacy requests answered on time', overdue === 0,
+    overdue ? `${overdue} request${overdue === 1 ? ' is' : 's are'} overdue.` : 'None overdue',
+    '/dashboard/admin/data-requests');
+  const unreported = openBreaches.filter(b => !b.regulatorNotifiedAt && now - new Date(b.discoveredAt) > 3 * DAY);
+  add('breaches', 'Security compromises reported', unreported.length === 0,
+    unreported.length ? `Not yet reported to the Information Regulator: ${unreported.map(b => b.title).join(', ')}.` : openBreaches.length ? `${openBreaches.length} open, all reported` : 'Nothing open',
+    '/dashboard/admin/privacy?tab=breaches');
+
+  const backendUrl = process.env.BACKEND_URL || '';
+  // The .env.example value ("https://your-backend-domain.com") doesn't count.
+  const realHttps = /^https:\/\//i.test(backendUrl) && !/your-|example\./i.test(backendUrl);
+  add('https', 'Unsubscribe links work in mail apps', realHttps,
+    realHttps ? backendUrl : 'Set BACKEND_URL on the server to the site\'s public https:// address (used by one-click unsubscribe and the WhatsApp webhook).',
+    null);
+  add('smtp', 'Email sending set up', smtpHost || process.env.SMTP_HOST || process.env.EMAIL_HOST,
+    smtpHost || process.env.SMTP_HOST || process.env.EMAIL_HOST ? 'SMTP configured' : 'Without email, people don\'t get unsubscribe links, request confirmations or inactivity warnings.',
+    '/dashboard/admin/settings?tab=email');
+  const seen = webhookSeen?.value ? new Date(webhookSeen.value) : null;
+  add('whatsapp_stop', 'WhatsApp STOP replies reach the site', seen && now - seen < 30 * DAY,
+    seen ? `Last message from WAWP ${seen.toLocaleString('en-ZA')}${now - seen >= 30 * DAY ? ' — over a month ago, check the webhook' : ''}` : 'Paste the webhook URL from Site settings → WhatsApp into WAWP (events: message, session.status).',
+    '/dashboard/admin/settings?tab=whatsapp', whatsappConfigured);
+  const twoFactorOn = String(process.env.TWO_FACTOR_REQUIRED_ROLES || 'true').toLowerCase() !== 'false';
+  add('two_factor', 'Two-factor login required for admins and supervisors', twoFactorOn,
+    twoFactorOn ? 'Required' : 'TWO_FACTOR_REQUIRED_ROLES=false on the server — only for emergencies.', null);
+  const lastBackup = backups[0]?.createdAt;
+  add('backups', 'Backups running', lastBackup && now - new Date(lastBackup) < 2 * DAY,
+    lastBackup ? `Last backup ${new Date(lastBackup).toLocaleString('en-ZA')}` : 'No backups found on this server.',
+    '/dashboard/admin/settings?tab=backups');
+
+  const applicable = checks.filter(c => c.applies);
+  const passed = applicable.filter(c => c.ok).length;
+  return { score: applicable.length ? Math.round((passed / applicable.length) * 100) : 0, passed, total: applicable.length, checks };
+}
+
+module.exports = { readiness, GENERIC_OPERATORS };

backend/src/utils/retention.js

@@ -0,0 +1,319 @@
+/**
+ * POPIA retention: how long each kind of personal information is kept, and the nightly
+ * `retention` job that deletes or anonymises what's past its time.
+ *
+ * Policies live in AppSetting `retention_policies` (JSON) on top of the defaults below.
+ * Medical details (consent_medical_retention_days), visit statistics (90 days, fixed) and
+ * backups (backup_retain_count) have their own settings and jobs; they're shown alongside.
+ */
+
+const prisma = require('../config/db');
+
+const SETTING_KEY = 'retention_policies';
+const LAST_RUN_KEY = 'retention_last_run';
+const WARNING_DAYS = 30;
+const DAY = 24 * 60 * 60 * 1000;
+// Spread a first big run over several nights instead of emailing everyone at once.
+const MAX_WARNINGS_PER_RUN = 300;
+const MAX_ANONYMISED_PER_RUN = 200;
+const BATCH = 500;
+
+const POLICIES = {
+  inactive_accounts: {
+    label: 'Inactive accounts',
+    description: 'Accounts with no login, registration or payment in this time are anonymised, after a warning 30 days before. Staff, supervisor and admin accounts are never touched, nor anyone with a registration for an upcoming event.',
+    defaults: { enabled: true, months: 60 },
+    minMonths: 12,
+  },
+  form_answers: {
+    label: 'Attendee form answers',
+    description: 'Answers to event forms are deleted this long after the event ends.',
+    defaults: { enabled: true, months: 12 },
+    minMonths: 1,
+  },
+  login_history: {
+    label: 'Login history',
+    description: 'Logins, password changes and similar account events (with IP address and device).',
+    defaults: { enabled: true, months: 24 },
+    minMonths: 3,
+  },
+  payment_details: {
+    label: 'Payer details in payment notifications',
+    description: 'Names and email addresses that Yoco and PayFast send with a payment are removed. The payment itself (amount, date, method) is always kept for the accounts.',
+    defaults: { enabled: true, months: 24 },
+    minMonths: 3,
+  },
+  audit_logs: {
+    label: 'Audit and access logs',
+    description: 'The audit log, the access log and "view as" sessions.',
+    defaults: { enabled: true, months: 60 },
+    minMonths: 12,
+  },
+};
+
+const MAX_MONTHS = 240;
+
+function monthsAgo(months, now = new Date()) {
+  const d = new Date(now);
+  d.setMonth(d.getMonth() - months);
+  return d;
+}
+
+function describeMonths(months) {
+  return months % 12 === 0 ? `${months / 12} year${months === 12 ? '' : 's'}` : `${months} month${months === 1 ? '' : 's'}`;
+}
+
+/** The policies in force (defaults overlaid with what the admin saved), and when they were last reviewed. */
+async function getPolicies(db = prisma) {
+  const row = await db.appSetting.findUnique({ where: { key: SETTING_KEY } });
+  let saved = {};
+  try { saved = row?.value ? JSON.parse(row.value) : {}; } catch { saved = {}; }
+  const policies = {};
+  for (const [key, def] of Object.entries(POLICIES)) {
+    const s = saved.policies?.[key] || {};
+    policies[key] = {
+      enabled: typeof s.enabled === 'boolean' ? s.enabled : def.defaults.enabled,
+      months: Number.isInteger(s.months) ? s.months : def.defaults.months,
+    };
+  }
+  return { policies, reviewedAt: saved.reviewedAt || null, reviewedBy: saved.reviewedBy || null };
+}
+
+/** Save the admin's policies (validated). Throws a message fit for the admin. */
+async function savePolicies(input, { reviewedBy } = {}, db = prisma) {
+  const policies = {};
+  for (const [key, def] of Object.entries(POLICIES)) {
+    const p = input?.[key] || {};
+    const months = parseInt(p.months, 10);
+    if (!Number.isInteger(months) || months < def.minMonths || months > MAX_MONTHS) {
+      throw new Error(`${def.label}: choose between ${def.minMonths} and ${MAX_MONTHS} months.`);
+    }
+    policies[key] = { enabled: p.enabled !== false, months };
+  }
+  const value = JSON.stringify({ policies, reviewedAt: new Date().toISOString(), reviewedBy: reviewedBy || null });
+  await db.appSetting.upsert({ where: { key: SETTING_KEY }, update: { value }, create: { key: SETTING_KEY, value } });
+  return getPolicies(db);
+}
+
+// ─── Inactive accounts ────────────────────────────────────────────────────────
+
+/**
+ * Ordinary accounts (role user, not already anonymised) whose last sign of life — account
+ * created, last login, a registration (or the end of the event it was for), being named as
+ * an attendee, a payment — is before `before`.
+ *   warned: false — not warned since that last activity (a warning before it no longer counts);
+ *   otherwise    — warned since their last activity, on or before `warnedBefore`.
+ */
+async function inactiveAccounts(before, { warned, warnedBefore, limit }, db = prisma) {
+  const rows = await db.$queryRawUnsafe(`
+    SELECT "id" FROM (
+      SELECT u."id", u."createdAt", u."inactivityWarnedAt" AS warned_at, GREATEST(
+        u."createdAt",
+        COALESCE(u."lastLoginAt", 'epoch'),
+        COALESCE((SELECT MAX(GREATEST(r."createdAt", e."endDate")) FROM "Registration" r JOIN "Event" e ON e."id" = r."eventId" WHERE r."userId" = u."id"), 'epoch'),
+        COALESCE((SELECT MAX(a."createdAt") FROM "Attendee" a WHERE a."userId" = u."id"), 'epoch'),
+        COALESCE((SELECT MAX(p."createdAt") FROM "Payment" p WHERE p."userId" = u."id"), 'epoch')
+      ) AS last_active
+      FROM "User" u
+      WHERE u."role" = 'user'
+        AND u."email" NOT LIKE '%@deleted.invalid' AND u."email" NOT LIKE '%@deleted.local'
+    ) x
+    WHERE last_active < $1
+      AND ${warned === false ? '(warned_at IS NULL OR warned_at < last_active)' : 'warned_at >= last_active AND warned_at <= $2'}
+    ORDER BY "createdAt"
+    LIMIT ${Math.max(1, Math.min(limit || BATCH, 5000))}`,
+  before, ...(warned === false ? [] : [warnedBefore]));
+  return rows.map(r => r.id);
+}
+
+async function warnInactive(userId, deleteOn, months, db = prisma) {
+  const user = await db.user.findUnique({ where: { id: userId }, select: { id: true, name: true, email: true, phoneNumber: true } });
+  if (!user) return false;
+  const { getSettingSync } = require('./settingsCache');
+  const org = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
+  const url = String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+  const when = deleteOn.toLocaleDateString('en-ZA', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'Africa/Johannesburg' });
+  const text = `Your ${org} account hasn't been used for ${describeMonths(months)}. To protect your personal information, we'll delete it on ${when}. If you'd like to keep your account, just log in before then: ${url}/login`;
+
+  const realEmail = user.email && !/@(guest\.local|deleted\.invalid|deleted\.local)$/.test(user.email);
+  if (realEmail) {
+    const { sendMail, buildPrivacyEmail } = require('./email');
+    await sendMail({
+      to: user.email,
+      subject: `Your ${org} account will be deleted on ${when}`,
+      ...buildPrivacyEmail({ name: user.name, heading: 'Your account will be deleted', paragraphs: [text, 'If you do nothing, your account is closed and your personal information deleted. Payment records are kept without your name, as the law requires.'] }),
+    }).catch(() => {});
+  } else {
+    const { waTextAny } = require('./notify');
+    await waTextAny(user, text);
+  }
+  await db.user.update({ where: { id: userId }, data: { inactivityWarnedAt: new Date() } });
+  return true;
+}
+
+async function runInactiveAccounts(policy, now, db = prisma) {
+  const cutoff = monthsAgo(policy.months, now);
+  const deleteOn = new Date(now.getTime() + WARNING_DAYS * DAY);
+  const { anonymiseUser, deletionBlockers } = require('./privacy');
+
+  // Warn those who'll pass the limit within the warning period.
+  const toWarn = await inactiveAccounts(new Date(cutoff.getTime() + WARNING_DAYS * DAY), { warned: false, limit: MAX_WARNINGS_PER_RUN }, db);
+  let warned = 0;
+  for (const id of toWarn) if (await warnInactive(id, deleteOn, policy.months, db)) warned++;
+
+  // Anonymise those past the limit who were warned at least 30 days ago and still haven't come back.
+  const due = await inactiveAccounts(cutoff, { warnedBefore: new Date(now.getTime() - WARNING_DAYS * DAY), limit: MAX_ANONYMISED_PER_RUN }, db);
+  let anonymised = 0;
+  let waiting = 0;
+  for (const id of due) {
+    if ((await deletionBlockers(id, db)).length) { waiting++; continue; }
+    await anonymiseUser(id, db);
+    await db.dataRequest.updateMany({ where: { userId: id, type: 'deletion', status: 'open' }, data: { status: 'completed', closedAt: now, response: 'Deleted after a long period without use.' } });
+    anonymised++;
+  }
+  return { warned, anonymised, waiting };
+}
+
+// ─── The other policies ───────────────────────────────────────────────────────
+
+async function runFormAnswers(policy, now, db = prisma) {
+  const cutoff = monthsAgo(policy.months, now);
+  const where = { response: { registration: { event: { endDate: { lt: cutoff } } } } };
+  const answers = await db.formAnswer.deleteMany({ where });
+  const drafts = await db.formDraft.deleteMany({ where: { registration: { event: { endDate: { lt: cutoff } } } } });
+  return { answers: answers.count, drafts: drafts.count };
+}
+
+async function runLoginHistory(policy, now, db = prisma) {
+  const res = await db.securityEvent.deleteMany({ where: { createdAt: { lt: monthsAgo(policy.months, now) } } });
+  return { deleted: res.count };
+}
+
+// Rows not scrubbed yet carry no "_scrubbed" key; scrubbed ones get it so they're skipped next time.
+async function scrubJsonColumn(table, column, cutoff, db) {
+  const { scrubPersonal } = require('./privacy');
+  let total = 0;
+  for (;;) {
+    const rows = await db.$queryRawUnsafe(
+      `SELECT "id", "${column}" AS data FROM "${table}" WHERE "createdAt" < $1 AND "${column}" IS NOT NULL AND jsonb_typeof("${column}") = 'object' AND NOT ("${column}" ? '_scrubbed') LIMIT ${BATCH}`,
+      cutoff,
+    );
+    if (!rows.length) break;
+    for (const r of rows) {
+      const model = table === 'ProviderTransaction' ? db.providerTransaction : db.providerCheckout;
+      await model.update({ where: { id: r.id }, data: { [column]: { ...scrubPersonal(r.data), _scrubbed: true } } });
+    }
+    total += rows.length;
+    if (rows.length < BATCH) break;
+  }
+  return total;
+}
+
+async function runPaymentDetails(policy, now, db = prisma) {
+  const cutoff = monthsAgo(policy.months, now);
+  return {
+    notifications: await scrubJsonColumn('ProviderTransaction', 'raw', cutoff, db),
+    checkouts: await scrubJsonColumn('ProviderCheckout', 'request', cutoff, db),
+  };
+}
+
+async function runAuditLogs(policy, now, db = prisma) {
+  const cutoff = monthsAgo(policy.months, now);
+  const [audit, access, sessions] = await Promise.all([
+    db.adminAuditLog.deleteMany({ where: { createdAt: { lt: cutoff } } }),
+    db.dataAccessLog.deleteMany({ where: { createdAt: { lt: cutoff } } }),
+    db.impersonationSession.deleteMany({ where: { startedAt: { lt: cutoff } } }),
+  ]);
+  return { audit: audit.count, access: access.count, viewAsSessions: sessions.count };
+}
+
+const RUNNERS = {
+  inactive_accounts: runInactiveAccounts,
+  form_answers: runFormAnswers,
+  login_history: runLoginHistory,
+  payment_details: runPaymentDetails,
+  audit_logs: runAuditLogs,
+};
+
+/** The nightly job: apply every switched-on policy. */
+async function runRetention(now = new Date(), db = prisma) {
+  const { policies } = await getPolicies(db);
+  const result = {};
+  for (const [key, policy] of Object.entries(policies)) {
+    if (!policy.enabled) continue;
+    try {
+      result[key] = await RUNNERS[key](policy, now, db);
+    } catch (e) {
+      result[key] = { error: e?.message || String(e) };
+      console.warn(`[retention] ${key} failed:`, e?.message || e);
+    }
+  }
+  const value = JSON.stringify({ at: now.toISOString(), result });
+  await db.appSetting.upsert({ where: { key: LAST_RUN_KEY }, update: { value }, create: { key: LAST_RUN_KEY, value } });
+  const { isNoop } = require('../jobs');
+  if (!isNoop(result)) {
+    require('./adminAudit').logAdminAction({ actorId: null, actorRole: 'system', action: 'retention_run', targetType: 'retention', metadata: result });
+  }
+  return result;
+}
+
+async function lastRun(db = prisma) {
+  const row = await db.appSetting.findUnique({ where: { key: LAST_RUN_KEY } });
+  try { return row?.value ? JSON.parse(row.value) : null; } catch { return null; }
+}
+
+/** How much each policy would affect if the job ran now — for the admin page. */
+async function preview(policies, now = new Date(), db = prisma) {
+  const out = {};
+  const p = policies;
+  const inactiveCutoff = monthsAgo(p.inactive_accounts.months, now);
+  const [toWarn, warnedDue, formAnswers, logins, audit] = await Promise.all([
+    inactiveAccounts(new Date(inactiveCutoff.getTime() + WARNING_DAYS * DAY), { warned: false, limit: 5000 }, db),
+    inactiveAccounts(inactiveCutoff, { warnedBefore: new Date(now.getTime() - WARNING_DAYS * DAY), limit: 5000 }, db),
+    db.formAnswer.count({ where: { response: { registration: { event: { endDate: { lt: monthsAgo(p.form_answers.months, now) } } } } } }),
+    db.securityEvent.count({ where: { createdAt: { lt: monthsAgo(p.login_history.months, now) } } }),
+    db.adminAuditLog.count({ where: { createdAt: { lt: monthsAgo(p.audit_logs.months, now) } } }),
+  ]);
+  const payments = await db.$queryRawUnsafe(
+    `SELECT COUNT(*)::int AS n FROM "ProviderTransaction" WHERE "createdAt" < $1 AND "raw" IS NOT NULL AND jsonb_typeof("raw") = 'object' AND NOT ("raw" ? '_scrubbed')`,
+    monthsAgo(p.payment_details.months, now),
+  );
+  out.inactive_accounts = { toWarn: toWarn.length, toAnonymise: warnedDue.length };
+  out.form_answers = { count: formAnswers };
+  out.login_history = { count: logins };
+  out.payment_details = { count: payments[0]?.n || 0 };
+  out.audit_logs = { count: audit };
+  return out;
+}
+
+/** One line per policy for the privacy notice's {retention} placeholder. */
+async function noticeLines(db = prisma) {
+  const { policies } = await getPolicies(db);
+  const { getSetting } = require('./settingsCache');
+  const [medical, backups] = await Promise.all([getSetting('consent_medical_retention_days', ''), getSetting('backup_retain_count', '')]);
+  const line = (key, on, off) => (policies[key].enabled ? on(describeMonths(policies[key].months)) : off);
+  return [
+    line('inactive_accounts', t => `• Accounts with no login, registration or payment for ${t} are deleted, after a warning 30 days before.`, '• Accounts are kept until you ask us to delete them.'),
+    line('form_answers', t => `• Answers to event forms are deleted ${t} after the event.`, '• Answers to event forms are kept until you ask us to delete them.'),
+    `• Medical and emergency-contact details from parental consent forms are deleted ${parseInt(medical, 10) || 30} days after the event. The record of who gave consent, when and to which wording is kept.`,
+    line('login_history', t => `• Login history (time, IP address, device) is kept for ${t}.`, '• Login history is kept until you ask us to delete it.'),
+    line('payment_details', t => `• Payer names and email addresses received with payments are removed after ${t}. Payment records themselves (amount, date, method) are kept as tax law requires.`, '• Payment records are kept as tax law requires.'),
+    line('audit_logs', t => `• Audit and access records (who did what in the system) are kept for ${t}.`, '• Audit and access records are kept for accountability.'),
+    '• Detailed visit statistics become anonymous daily totals after 90 days.',
+    `• Database backups are kept for about ${parseInt(backups, 10) || 14} days, so deleted information stays in them until they are replaced.`,
+  ];
+}
+
+module.exports = {
+  POLICIES,
+  WARNING_DAYS,
+  getPolicies,
+  savePolicies,
+  inactiveAccounts,
+  runRetention,
+  lastRun,
+  preview,
+  noticeLines,
+  describeMonths,
+  monthsAgo,
+};

backend/src/utils/scanLocks.js

@@ -147,8 +147,8 @@ async function snapshotFor(lock) {
     session: session ? { id: session.id, label: sessionsUtil.sessionLabel(session, schedule.sessions) } : null,
     noSessionToday: schedule?.scheduleType === 'sessions' && !session,
     tickets: tickets.map(t => {
-      // A picked-session ticket for another session has nothing left today.
-      const otherSession = !!(t.registrationOption.sessionId && t.registrationOption.sessionId !== session?.id);
+      // A ticket for other sessions (picked, or ticked on an all-sessions ticket) has nothing left today.
+      const otherSession = !!(session ? !sessionsUtil.lineCovers(t.registrationOption, session.id) : t.registrationOption.sessionId);
       const redeemed = schedule?.scheduleType === 'sessions'
         ? (session && !otherSession ? sessionsUtil.redeemedForSession(t.usages, session.id) : t.quantity || 1)
         : t.usages.reduce((s, u) => s + (u.quantityRedeemed || 1), 0);
@@ -204,7 +204,7 @@ async function syncScans(lock, scans) {
       state = {
         sessionId: session?.id || null,
         noSession: hasSessions && !session,
-        wrongSession: !!(session && ticket.registrationOption.sessionId && ticket.registrationOption.sessionId !== session.id),
+        wrongSession: !!(session && !sessionsUtil.lineCovers(ticket.registrationOption, session.id)),
         remaining: (ticket.quantity || 1) - redeemed,
         cancelled: ticket.registrationOption.registration.status === 'cancelled',
         inScope: !optionIds || optionIds.has(ticket.registrationOption.eventOptionId),

backend/src/utils/sessionReminders.js

@@ -21,10 +21,10 @@ function fmtWhen(d) {
   return new Date(d).toLocaleString('en-GB', { timeZone: TIMEZONE, weekday: 'long', day: 'numeric', month: 'long', hour: '2-digit', minute: '2-digit' });
 }
 
-/** People to remind about a session: whole-course tickets plus picked places on it. Map userId → user. */
+/** People to remind about a session: whole-course tickets (all sessions, or this one ticked) plus picked places on it. Map userId → user. */
 async function recipientsFor(eventId, sessionId) {
   const tickets = await prisma.ticket.findMany({
-    where: { eventId, registrationOption: { registration: { status: { not: 'cancelled' } }, OR: [{ sessionId: null }, { sessionId }] } },
+    where: { eventId, registrationOption: { registration: { status: { not: 'cancelled' } }, OR: [{ sessionId: null, sessionIds: { isEmpty: true } }, { sessionId: null, sessionIds: { has: sessionId } }, { sessionId }] } },
     select: {
       user: { select: { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true, isActive: true } },
       holder: { select: { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true, isActive: true } },

backend/src/utils/sessions.js

@@ -17,7 +17,12 @@
  *   bought per session — one registration line (and ticket) per session, priced per
  *   session, bookable until that session starts. `all` options cover every session and
  *   follow the whole-course rules above. A session's capacity counts picked places plus
- *   whole-course main tickets; a pick option's stock limit is places per session.
+ *   whole-course main tickets (and places held for waitlist offers); a pick option's stock
+ *   limit is places per session. The waitlist for a pick option is per session.
+ *   `all` options on such an event also let people tick the sessions they'll come to
+ *   (RegistrationOption.sessionIds): one line, one ticket and one price, but the ticket
+ *   scans, counts towards capacity and gets reminders for those sessions only. No
+ *   sessions ticked = every session (the whole-course rules).
  *   Not available on youth (parental consent) events, and picked lines take no names.
  */
 
@@ -138,6 +143,11 @@ function registrationClosesAt(event, sessions) {
   return deadline && deadline < closes ? deadline : closes;
 }
 
+/** Whether people choose sessions on this event (attendance mode "pick sessions"). */
+function choosesSessions(event) {
+  return event?.scheduleType === 'sessions' && event?.attendanceMode === 'pick';
+}
+
 /** Whether an option is bought per session (only in "pick sessions" events). */
 function isPickOption(event, option) {
   return event?.scheduleType === 'sessions' && event?.attendanceMode === 'pick' && option?.sessionMode === 'pick';
@@ -145,68 +155,125 @@ function isPickOption(event, option) {
 
 /**
  * Turns requested lines into registration lines: a pick option with sessionIds becomes
- * one line per session (same quantity); other options stay as they are. Checks the
- * sessions can still be booked: public — before the session starts; staff — until it ends.
+ * one line per session (same quantity); an all-sessions option on a pick-sessions event
+ * keeps its sessionIds (the sessions ticked, empty = every session) on one line. Checks
+ * the sessions can still be booked: public — before the session starts; staff — until it ends.
  * @param {object} event - with eventOptions and sessions
  * @param {object[]} lines - [{ eventOptionId, variantId?, quantity, sessionIds? }]
  */
 function expandPickLines(event, lines, { now = new Date(), staff = false } = {}) {
   const out = [];
+  const bookable = (option, id) => {
+    const session = (event.sessions || []).find(s => s.id === id);
+    if (!session || session.cancelledAt) throw sessionError(`A chosen session for "${option.name}" isn't available.`);
+    const cutoff = staff ? new Date(session.endsAt) : new Date(session.startsAt);
+    if (cutoff <= now) throw sessionError(`${sessionLabel(session, event.sessions)} has ${staff ? 'ended' : 'already started'} — it can't be booked any more.`);
+  };
   for (const line of lines || []) {
     const option = (event.eventOptions || []).find(o => o.id === line.eventOptionId);
     const pick = isPickOption(event, option);
     const ids = Array.isArray(line.sessionIds) ? [...new Set(line.sessionIds.map(String))] : [];
+    const { sessionIds, ...rest } = line;
+    void sessionIds;
     if (!pick) {
-      if (ids.length) throw sessionError(`"${option?.name || 'This ticket'}" covers every session — no sessions to choose.`);
-      out.push({ ...line, sessionId: null });
+      if (ids.length && !choosesSessions(event)) throw sessionError(`"${option?.name || 'This ticket'}" covers every session — no sessions to choose.`);
+      for (const id of ids) bookable(option, id);
+      out.push({ ...rest, sessionId: null, sessionIds: ids });
       continue;
     }
     if (event.requiresParentalConsent) throw sessionError('Choosing sessions isn\'t available on youth events.');
     if (ids.length === 0) throw sessionError(`Choose the sessions for "${option.name}".`);
     for (const id of ids) {
-      const session = (event.sessions || []).find(s => s.id === id);
-      if (!session || session.cancelledAt) throw sessionError(`A chosen session for "${option.name}" isn't available.`);
-      const cutoff = staff ? new Date(session.endsAt) : new Date(session.startsAt);
-      if (cutoff <= now) throw sessionError(`${sessionLabel(session, event.sessions)} has ${staff ? 'ended' : 'already started'} — it can't be booked any more.`);
-      const { sessionIds, ...rest } = line;
-      void sessionIds;
+      bookable(option, id);
       out.push({ ...rest, sessionId: id });
     }
   }
   return out;
 }
 
+/**
+ * The sessions a line attends: its picked session, the sessions ticked on an
+ * all-sessions ticket, or null for every session.
+ * @param {{ sessionId?: string|null, sessionIds?: string[] }} line
+ * @returns {string[]|null}
+ */
+function lineSessions(line) {
+  if (line?.sessionId) return [line.sessionId];
+  return line?.sessionIds?.length ? line.sessionIds : null;
+}
+
+/** Whether a ticket's line covers `sessionId` (picked session, ticked sessions, or every session). */
+function lineCovers(line, sessionId) {
+  const ids = lineSessions(line);
+  return !ids || ids.includes(sessionId);
+}
+
+/** Merges the ticked sessions of two all-sessions lines (empty = every session wins). */
+function mergeSessionIds(a, b) {
+  if (!a?.length || !b?.length) return [];
+  return [...new Set([...a, ...b])];
+}
+
 /**
  * People booked per session: picked places on that session plus whole-course main
- * tickets (which attend every session). Cancelled registrations don't count.
+ * tickets (which attend every session). Cancelled registrations don't count; places
+ * held for a live waitlist offer do (except `excludeEntryId`, the offer being claimed).
  * @returns {Promise<Map<string, number>>}
  */
-async function sessionBookings(eventId, db = prisma) {
-  const lines = await db.registrationOption.findMany({
-    where: { registration: { eventId, status: { not: 'cancelled' } }, eventOption: { isMainTicket: true } },
-    select: { quantity: true, sessionId: true },
-  });
+async function sessionBookings(eventId, db = prisma, { excludeEntryId = null } = {}) {
+  const [booked, held] = await Promise.all([
+    db.registrationOption.findMany({
+      where: { registration: { eventId, status: { not: 'cancelled' } }, eventOption: { isMainTicket: true } },
+      select: { quantity: true, sessionId: true, sessionIds: true },
+    }),
+    db.waitlistEntry.findMany({
+      where: {
+        eventId, status: 'offered', offerExpiresAt: { gt: new Date() }, eventOption: { isMainTicket: true },
+        ...(excludeEntryId ? { id: { not: excludeEntryId } } : {}),
+      },
+      select: { offeredQuantity: true, sessionId: true },
+    }),
+  ]);
+  const lines = [...booked, ...held.map(h => ({ quantity: h.offeredQuantity, sessionId: h.sessionId }))];
   const sessions = await db.eventSession.findMany({ where: { eventId, cancelledAt: null }, select: { id: true } });
-  const whole = lines.filter(l => !l.sessionId).reduce((s, l) => s + (l.quantity || 0), 0);
-  const out = new Map(sessions.map(s => [s.id, whole]));
-  for (const l of lines) if (l.sessionId && out.has(l.sessionId)) out.set(l.sessionId, out.get(l.sessionId) + (l.quantity || 0));
+  const out = new Map(sessions.map(s => [s.id, 0]));
+  for (const l of lines) {
+    for (const id of lineSessions(l) || out.keys()) if (out.has(id)) out.set(id, out.get(id) + (l.quantity || 0));
+  }
   return out;
 }
 
+/**
+ * Session places free for a main-ticket line: its own session (picked) or, for a
+ * whole-course ticket, the fullest session with a capacity. Pure.
+ * @param {object[]} sessions - the event's sessions (with capacity)
+ * @param {Map<string, number>} booked - from sessionBookings
+ * @param {string|null} sessionId - the picked session, or null for whole-course
+ * @returns {number|null} null when no session limits it
+ */
+function sessionPlacesFree(sessions, booked, sessionId = null) {
+  const limited = activeSessions(sessions).filter(s => s.capacity > 0 && (!sessionId || s.id === sessionId));
+  if (limited.length === 0) return null;
+  return Math.max(0, Math.min(...limited.map(s => s.capacity - (booked.get(s.id) || 0))));
+}
+
 /**
  * Checks requested lines fit each session's capacity. Whole-course main tickets count
  * against every session; picked main tickets against their own.
+ * @param {{ excludeEntryId?: string }} [opts] - the waitlist offer being claimed
  */
-async function assertSessionCapacity(event, lines, db = prisma) {
+async function assertSessionCapacity(event, lines, db = prisma, { excludeEntryId = null } = {}) {
   const limited = activeSessions(event.sessions).filter(s => s.capacity > 0);
   if (limited.length === 0) return;
   const mains = new Set((event.eventOptions || []).filter(o => o.isMainTicket).map(o => o.id));
   const wanted = new Map();
-  const whole = lines.filter(l => !l.sessionId && mains.has(l.eventOptionId)).reduce((s, l) => s + (Number(l.quantity) || 0), 0);
-  for (const s of limited) wanted.set(s.id, whole);
-  for (const l of lines) if (l.sessionId && mains.has(l.eventOptionId) && wanted.has(l.sessionId)) wanted.set(l.sessionId, wanted.get(l.sessionId) + (Number(l.quantity) || 0));
+  for (const s of limited) wanted.set(s.id, 0);
+  for (const l of lines) {
+    if (!mains.has(l.eventOptionId)) continue;
+    for (const id of lineSessions(l) || wanted.keys()) if (wanted.has(id)) wanted.set(id, wanted.get(id) + (Number(l.quantity) || 0));
+  }
   if ([...wanted.values()].every(n => n === 0)) return;
-  const booked = await sessionBookings(event.id, db);
+  const booked = await sessionBookings(event.id, db, { excludeEntryId });
   for (const s of limited) {
     const left = s.capacity - (booked.get(s.id) || 0);
     if ((wanted.get(s.id) || 0) > left) {
@@ -384,9 +451,17 @@ function scanSession(event, sessions, requestedId = null, now = new Date()) {
  * (short) or "Wednesday 4 November 2026 (first of 5 sessions — one ticket for all)" (long).
  * Returns null for single-date events (callers keep their own date format).
  */
-function ticketDateText(event, style = 'short', session = null, sessions = null) {
+function ticketDateText(event, style = 'short', session = null, sessions = null, chosenIds = null) {
   if (event?.scheduleType !== 'sessions') return null;
   const fmt = (d, opts) => new Date(d).toLocaleDateString('en-GB', { timeZone: TIMEZONE, ...opts });
+  // An all-sessions ticket with sessions ticked: those sessions.
+  const chosen = chosenIds?.length ? activeSessions(event.sessions).filter(s => chosenIds.includes(s.id)) : [];
+  if (!session && chosen.length === 1) session = chosen[0];
+  else if (!session && chosen.length > 1) {
+    return style === 'long'
+      ? `${chosen.map(s => fmt(s.startsAt, { weekday: 'short', day: 'numeric', month: 'short' })).join(', ')} (${chosen.length} sessions — one ticket for all)`
+      : `${chosen.length} sessions · ${chosen.map(s => fmt(s.startsAt, { day: '2-digit', month: 'short' })).join(', ')}`;
+  }
   // A picked-session ticket is for its own session only.
   if (session) {
     const label = sessionLabel(session, event.sessions);
@@ -412,9 +487,18 @@ function ticketDateText(event, style = 'short', session = null, sessions = null)
 
 /**
  * scanSession for a ticket: a picked-session ticket only checks in on its own session
- * (whatever the scanner has selected).
+ * (whatever the scanner has selected); an all-sessions ticket with sessions ticked
+ * (`chosenIds`) only on those.
  */
-function ticketScanSession(event, sessions, pinnedSessionId, requestedId = null, now = new Date()) {
+function ticketScanSession(event, sessions, pinnedSessionId, requestedId = null, now = new Date(), chosenIds = null) {
+  if (!pinnedSessionId && chosenIds?.length) {
+    const found = scanSession(event, sessions, requestedId, now);
+    if (!found.session || chosenIds.includes(found.session.id)) return found;
+    // Another of their sessions may be open today (a day with more than one session).
+    const own = requestedId ? null : currentSession(activeSessions(sessions).filter(s => chosenIds.includes(s.id)), now, event.checkInWindow || 'whole_day');
+    if (own) return { session: own, error: null };
+    return { session: null, error: `This ticket isn't booked for ${sessionLabel(found.session, sessions)} (${dayKey(found.session.startsAt)})` };
+  }
   if (!pinnedSessionId) return scanSession(event, sessions, requestedId, now);
   const pinned = (sessions || []).find(s => s.id === pinnedSessionId);
   if (!pinned) return { session: null, error: 'This ticket\'s session no longer exists' };
@@ -430,7 +514,8 @@ function ticketScanSession(event, sessions, pinnedSessionId, requestedId = null,
  * Groups an event's tickets into people for the register and certificates: a
  * picked-session booking has one ticket per session, so its tickets (same registration,
  * option and variant) form one group. Every other ticket is its own group.
- * Each ticket needs registrationOption: { registrationId, eventOptionId, variantId, sessionId }.
+ * Each ticket needs registrationOption: { registrationId, eventOptionId, variantId, sessionId, sessionIds }.
+ * An all-sessions ticket with sessions ticked is its own group, limited to those sessions.
  * @returns {{ key: string, tickets: object[], sessionIds: string[]|null }[]} sessionIds null = all sessions
  */
 function groupTickets(tickets) {
@@ -438,7 +523,7 @@ function groupTickets(tickets) {
   for (const t of tickets) {
     const ro = t.registrationOption || {};
     if (!ro.sessionId) {
-      groups.set(t.id, { key: t.id, tickets: [t], sessionIds: null });
+      groups.set(t.id, { key: t.id, tickets: [t], sessionIds: ro.sessionIds?.length ? [...ro.sessionIds] : null });
       continue;
     }
     const key = `pick:${ro.registrationId}:${ro.eventOptionId}:${ro.variantId || ''}`;
@@ -487,7 +572,7 @@ module.exports = {
   TIMEZONE, MAX_SESSIONS, REMINDER_OFFSETS, CERTIFICATE_TEMPLATES, sessionError,
   dayKey, activeSessions, scheduleBounds, normalizeSessionsInput, sessionAcceptsCheckIn, currentSession,
   sessionLabel, scanSession, ticketScanSession, redeemedForSession, ticketDateText, groupTickets,
-  registrationClosesAt, wholeCourseClosesAt, isPickOption, expandPickLines, sessionBookings, assertSessionCapacity,
+  registrationClosesAt, wholeCourseClosesAt, choosesSessions, isPickOption, expandPickLines, lineSessions, lineCovers, mergeSessionIds, sessionBookings, sessionPlacesFree, assertSessionCapacity,
   lateInfo, latePrice, completionMet, normalizeReminders, normalizeCertificateConfig,
   syncEventSessions, eventSchedule, forgetSchedule, withLatePrice, attendanceBySession,
 };

backend/src/utils/settingsCache.js

@@ -11,7 +11,7 @@ const prisma = require('../config/db');
 const { decrypt, isEncrypted } = require('./encryption');
 
 // Keys stored encrypted in the DB — decrypted transparently on read.
-const ENCRYPTED_KEYS = new Set(['smtp_user', 'smtp_pass', 'yoco_secret_key', 'yoco_webhook_secret']);
+const ENCRYPTED_KEYS = new Set(['smtp_user', 'smtp_pass', 'yoco_secret_key', 'yoco_webhook_secret', 'payfast_passphrase']);
 
 let _cache = {};
 let _lastFetch = 0;

backend/src/utils/stock.js

@@ -37,15 +37,17 @@ async function takenCount({ eventOptionId, variantId = null, sessionId = null },
 
 /**
  * Places still free on a line: the tighter of the option and variant limits.
+ * @param {{ sessionId?: string|null, excludeEntryId?: string, db?: object }} [opts] -
+ *   sessionId: a "pick sessions" line (the limits are places per session)
  * @returns {Promise<number|null>} null when unlimited
  */
-async function remainingFor(option, variant, opts = {}) {
+async function remainingFor(option, variant, { sessionId = null, ...opts } = {}) {
   const limits = [];
   if (option?.stockLimit > 0) {
-    limits.push(option.stockLimit - await takenCount({ eventOptionId: option.id }, opts));
+    limits.push(option.stockLimit - await takenCount({ eventOptionId: option.id, sessionId }, opts));
   }
   if (variant?.stockLimit > 0) {
-    limits.push(variant.stockLimit - await takenCount({ eventOptionId: option.id, variantId: variant.id }, opts));
+    limits.push(variant.stockLimit - await takenCount({ eventOptionId: option.id, variantId: variant.id, sessionId }, opts));
   }
   if (limits.length === 0) return null;
   return Math.max(0, Math.min(...limits));

backend/src/utils/waitlist.js

@@ -11,11 +11,16 @@
  *   offered what's free; otherwise they're skipped for the next person who fits.
  * - Claiming = registering with the link (createRegistration's waitlistToken). Early-bird
  *   and coupon rules apply as usual. An unclaimed offer expires and moves on.
+ * - "Pick sessions" options are waited for per session (entry.sessionId): free places are
+ *   that session's, an offer never runs past the session's start, and nobody is offered a
+ *   session that has started or was cancelled. Main tickets also need room in the
+ *   session(s) they cover when sessions have a capacity (utils/sessions.js).
  */
 
 const crypto = require('crypto');
 const prisma = require('../config/db');
 const { remainingFor } = require('./stock');
+const { activeSessions, isPickOption, sessionBookings, sessionPlacesFree, sessionLabel, wholeCourseClosesAt } = require('./sessions');
 
 const ACTIVE = ['waiting', 'offered'];
 
@@ -27,6 +32,42 @@ function waitlistError(message, statusCode = 400) {
 
 const hashToken = (token) => crypto.createHmac('sha256', process.env.JWT_SECRET || '').update(`waitlist:${token}`).digest('hex');
 
+/**
+ * Places free on a waitlist line: option/variant stock (per session for a picked line)
+ * and, for main tickets on events with session capacities, room in the session(s).
+ * @param {object} event - with sessions
+ * @returns {Promise<number|null>} null when unlimited
+ */
+async function placesFree(event, option, variant, sessionId = null, { db = prisma, excludeEntryId = null } = {}) {
+  const limits = [await remainingFor(option, variant, { sessionId, db, excludeEntryId })];
+  if (event.scheduleType === 'sessions' && option.isMainTicket && (event.sessions || []).some(s => s.capacity > 0)) {
+    limits.push(sessionPlacesFree(event.sessions, await sessionBookings(event.id, db, { excludeEntryId }), sessionId));
+  }
+  const known = limits.filter(n => n !== null);
+  return known.length ? Math.min(...known) : null;
+}
+
+/** Whether a waitlist line can still be offered at `now` (its session hasn't started, etc.). */
+function lineOpen(event, sessionId, now = new Date()) {
+  if (!sessionId) return event.scheduleType !== 'sessions' || now < wholeCourseClosesAt(event, event.sessions);
+  const session = activeSessions(event.sessions).find(s => s.id === sessionId);
+  return !!session && new Date(session.startsAt) > now;
+}
+
+/** When an offer made now lapses: the event's offer hours, but never after its session starts. */
+function offerExpiry(hours, session = null, now = new Date()) {
+  const expires = new Date(now.getTime() + (hours || 24) * 60 * 60 * 1000);
+  return session && new Date(session.startsAt) < expires ? new Date(session.startsAt) : expires;
+}
+
+/** "Drop-in (Large)" or "Drop-in — Class 2, Wed 4 Nov" for messages. */
+function lineName(entry, sessions = entry.event?.sessions) {
+  const base = `${entry.eventOption.name}${entry.variant ? ` (${entry.variant.name})` : ''}`;
+  if (!entry.session) return base;
+  const when = new Date(entry.session.startsAt).toLocaleDateString('en-GB', { timeZone: process.env.APP_TIMEZONE || 'Africa/Johannesburg', weekday: 'short', day: 'numeric', month: 'short' });
+  return `${base} — ${sessionLabel(entry.session, sessions || [entry.session])}, ${when}`;
+}
+
 function claimLink(token) {
   const base = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').split(',')[0].trim().replace(/\/$/, '');
   return `${base}/waitlist/claim/${token}`;
@@ -63,7 +104,7 @@ async function notifyOffer(entry, token) {
   const ff = `-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif`;
   const user = entry.user;
   const link = claimLink(token);
-  const item = `${entry.eventOption.name}${entry.variant ? ` (${entry.variant.name})` : ''}`;
+  const item = lineName(entry);
   const until = new Date(entry.offerExpiresAt).toLocaleString('en-GB', { day: 'numeric', month: 'long', hour: '2-digit', minute: '2-digit' });
   const partialNote = entry.offeredQuantity < entry.quantity
     ? ` You asked for ${entry.quantity}; ${entry.offeredQuantity} came free, and you can take those now.` : '';
@@ -86,10 +127,10 @@ async function notifyOffer(entry, token) {
   await Promise.allSettled(sends);
 }
 
-const OFFER_INCLUDE = { event: true, eventOption: true, variant: true, user: { select: { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true } } };
+const OFFER_INCLUDE = { event: { include: { sessions: true } }, eventOption: true, variant: true, session: true, user: { select: { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true } } };
 
-/** Puts an entry on offer (inside the caller's transaction); returns the raw token. */
-async function writeOffer(db, entry, quantity, hours) {
+/** Puts an entry on offer until `expiresAt` (inside the caller's transaction); returns the raw token. */
+async function writeOffer(db, entry, quantity, expiresAt) {
   const token = crypto.randomBytes(24).toString('hex');
   await db.waitlistEntry.update({
     where: { id: entry.id },
@@ -98,7 +139,7 @@ async function writeOffer(db, entry, quantity, hours) {
       offeredQuantity: quantity,
       offerTokenHash: hashToken(token),
       offeredAt: new Date(),
-      offerExpiresAt: new Date(Date.now() + (hours || 24) * 60 * 60 * 1000),
+      offerExpiresAt: expiresAt,
     },
   });
   return token;
@@ -113,8 +154,8 @@ async function notifyOffers(offers) {
 
 /** Offers `quantity` places to one entry (e.g. a supervisor's manual offer) and notifies. */
 async function makeOffer(entryId, quantity) {
-  const entry = await prisma.waitlistEntry.findUnique({ where: { id: entryId }, include: { event: true } });
-  const token = await writeOffer(prisma, entry, quantity, entry.event.waitlistOfferHours);
+  const entry = await prisma.waitlistEntry.findUnique({ where: { id: entryId }, include: { event: true, session: true } });
+  const token = await writeOffer(prisma, entry, quantity, offerExpiry(entry.event.waitlistOfferHours, entry.session));
   await notifyOffers([{ entryId, token }]);
   return prisma.waitlistEntry.findUnique({ where: { id: entryId } });
 }
@@ -127,7 +168,7 @@ async function makeOffer(entryId, quantity) {
 async function processWaitlist(eventId) {
   const event = await prisma.event.findUnique({
     where: { id: eventId },
-    include: { eventOptions: { include: { variants: true } } },
+    include: { eventOptions: { include: { variants: true } }, sessions: true },
   });
   if (!event || !event.waitlistEnabled || !event.isActive || event.cashupStatus === 'closed') return 0;
   if (new Date(event.endDate) < new Date()) return 0;
@@ -136,16 +177,20 @@ async function processWaitlist(eventId) {
   await prisma.$transaction(async (tx) => {
     await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${'waitlist:' + eventId}))`;
     const waiting = await tx.waitlistEntry.findMany({ where: { eventId, status: 'waiting' }, orderBy: { position: 'asc' } });
-    const lines = [...new Map(waiting.map(w => [`${w.eventOptionId}::${w.variantId || ''}`, w])).values()];
+    const lineKey = (w) => `${w.eventOptionId}::${w.variantId || ''}::${w.sessionId || ''}`;
+    const lines = [...new Map(waiting.map(w => [lineKey(w), w])).values()];
     for (const sample of lines) {
       const option = event.eventOptions.find(o => o.id === sample.eventOptionId);
       const variant = sample.variantId ? (option?.variants || []).find(v => v.id === sample.variantId) : null;
-      if (!option) continue;
-      const free = await remainingFor(option, variant, { db: tx });
+      if (!option || !lineOpen(event, sample.sessionId)) continue;
+      // An option switched between per-session and whole-course after people joined.
+      if (!!sample.sessionId !== isPickOption(event, option)) continue;
+      const free = await placesFree(event, option, variant, sample.sessionId, { db: tx });
       if (free === null || free <= 0) continue;
-      const queue = waiting.filter(w => w.eventOptionId === sample.eventOptionId && (w.variantId || null) === (sample.variantId || null));
+      const session = sample.sessionId ? event.sessions.find(s => s.id === sample.sessionId) : null;
+      const queue = waiting.filter(w => lineKey(w) === lineKey(sample));
       for (const offer of pickOffers(queue, free, event.waitlistPartialOffers)) {
-        const token = await writeOffer(tx, { id: offer.entryId }, offer.quantity, event.waitlistOfferHours);
+        const token = await writeOffer(tx, { id: offer.entryId }, offer.quantity, offerExpiry(event.waitlistOfferHours, session));
         made.push({ entryId: offer.entryId, token });
       }
     }
@@ -183,7 +228,7 @@ async function findOfferByToken(token) {
   if (!token || typeof token !== 'string' || token.length > 100) return null;
   return prisma.waitlistEntry.findUnique({
     where: { offerTokenHash: hashToken(token) },
-    include: { event: true, eventOption: true, variant: true, user: { select: { id: true, name: true } } },
+    include: { event: { include: { sessions: true } }, eventOption: true, variant: true, session: true, user: { select: { id: true, name: true } } },
   });
 }
 
@@ -192,6 +237,10 @@ module.exports = {
   waitlistError,
   hashToken,
   pickOffers,
+  placesFree,
+  lineOpen,
+  offerExpiry,
+  lineName,
   makeOffer,
   processWaitlist,
   expireOffers,

backend/src/utils/whatsapp.js

@@ -297,7 +297,36 @@ async function sendPdf(toPhone, localPdfPath, filename, caption) {
   setTimeout(() => { try { fs.unlinkSync(tempPath); } catch {} }, 5 * 60 * 1000);
 }
 
+/**
+ * WAWP doesn't sign webhooks, so the webhook URL carries a secret (?secret=…) and incoming
+ * messages are only acted on when it matches. Made on first use and kept in AppSetting.
+ */
+async function getWebhookSecret() {
+  const prisma = require('../config/db');
+  const row = await prisma.appSetting.findUnique({ where: { key: 'WAWP_WEBHOOK_SECRET' } });
+  if (row?.value) return row.value;
+  const secret = require('crypto').randomBytes(24).toString('base64url');
+  await prisma.appSetting.upsert({ where: { key: 'WAWP_WEBHOOK_SECRET' }, update: {}, create: { key: 'WAWP_WEBHOOK_SECRET', value: secret } });
+  const saved = await prisma.appSetting.findUnique({ where: { key: 'WAWP_WEBHOOK_SECRET' } });
+  return saved.value;
+}
+
+/** The URL to paste into WAWP's webhook settings (events: message, session.status). */
+async function webhookUrl() {
+  const base = String(process.env.BACKEND_URL || process.env.API_URL || 'http://localhost:5000').replace(/\/$/, '');
+  return `${base}/api/whatsapp/webhook?secret=${encodeURIComponent(await getWebhookSecret())}`;
+}
+
+/** The sender's phone (27…) from a WAWP chat id, or null for groups, channels and LIDs. */
+function phoneFromChatId(chatId) {
+  const m = String(chatId || '').match(/^(\d+)@c\.us$/);
+  return m ? normalizeZAPhone(m[1]) : null;
+}
+
 module.exports = {
+  getWebhookSecret,
+  webhookUrl,
+  phoneFromChatId,
   getConfig,
   setConfig,
   normalizeZAPhone,

backend/src/utils/yoco.js

@@ -80,15 +80,18 @@ function friendlyYocoError(e) {
   return err;
 }
 
-/** Call the Yoco API. `key` overrides the stored key (used to verify a key before saving it). */
-async function yocoRequest(method, path, body, key) {
+/**
+ * Call the Yoco API. `key` overrides the stored key (used to verify a key before saving it);
+ * `headers` adds request headers (e.g. Idempotency-Key).
+ */
+async function yocoRequest(method, path, body, key, headers = {}) {
   const auth = key ? `Bearer ${key}` : await yocoAuthHeader();
   try {
     const res = await axios({
       method,
       url: `${YOCO_API}${path}`,
       data: body,
-      headers: { 'Content-Type': 'application/json', Authorization: auth },
+      headers: { 'Content-Type': 'application/json', Authorization: auth, ...headers },
       timeout: 15000,
     });
     return res.data;

backend/tests/paymentStatus.test.js

@@ -0,0 +1,136 @@
+jest.mock('../src/config/db', () => ({
+  appSetting: { findMany: jest.fn() },
+  registration: { findFirst: jest.fn(), findUnique: jest.fn(), update: jest.fn() },
+  payment: { findFirst: jest.fn(), create: jest.fn() },
+  providerTransaction: { findUnique: jest.fn(), findFirst: jest.fn(), create: jest.fn(), update: jest.fn() },
+  providerCheckout: { findMany: jest.fn(), findUnique: jest.fn(), findFirst: jest.fn() },
+  ticket: { findMany: jest.fn() },
+  user: { findFirst: jest.fn() },
+}));
+jest.mock('../src/utils/pricing', () => ({ computeRegistrationTotalDue: jest.fn(), refreshPricingForRegistration: jest.fn() }));
+jest.mock('../src/utils/ticketUtils', () => ({ generateTicketsForRegistration: jest.fn().mockResolvedValue([]) }));
+jest.mock('../src/utils/notifications', () => ({ sendPaymentEmails: jest.fn() }));
+jest.mock('../src/controllers/ticketController', () => ({ emailTickets: jest.fn() }));
+
+const crypto = require('crypto');
+const prisma = require('../src/config/db');
+const settingsCache = require('../src/utils/settingsCache');
+const { computeRegistrationTotalDue } = require('../src/utils/pricing');
+const payfast = require('../src/payments/providers/payfast');
+const status = require('../src/payments/status');
+
+const PF = { payfast_merchant_id: '10000100', payfast_merchant_key: 'abcdefghij123', payfast_passphrase: 'Salt pass', payfast_mode: 'sandbox' };
+function settings(values) {
+  prisma.appSetting.findMany.mockResolvedValue(Object.entries(values).map(([key, value]) => ({ key, value })));
+  settingsCache.invalidate();
+}
+
+// As PayFast's sandbox returned it (CRLF lines, quoted amounts with thousands separators)
+const CSV = [
+  'Date,Type,Sign,Party,Name,Description,Currency,"Funding Type",Gross,Fee,Net,Balance,"M Payment ID","PF Payment ID","custom str1"',
+  '"2026-10-23 14:19:24",FUNDS_RECEIVED,CREDIT,"Test User 01","Family Fun Day",Adult,ZAR,WALLET,80.00,-2.30,77.70,"22,574.02",chk_a,3471967,',
+  '"2026-10-23 15:00:00",FUNDS_RECEIVED,CREDIT,"Test User 01","Big ""Camp""",,ZAR,CC,"1,250.00",-20.00,"1,230.00",,chk_b,3471999,',
+  '"2026-10-23 16:00:00",REFUND,DEBIT,"Test User 01",x,,ZAR,CC,-80.00,0,-80.00,,chk_c,3472000,',
+].join('\r\n');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  settings(PF);
+});
+
+describe('PayFast API', () => {
+  test('requests are signed over the alphabetically sorted variables and passphrase', () => {
+    const md5 = (s) => crypto.createHash('md5').update(s).digest('hex');
+    expect(payfast.apiSignature({ version: 'v1', 'merchant-id': '10000100', timestamp: '2026-10-23T10:00:00+00:00', passphrase: 'Salt pass', from: '' }))
+      .toBe(md5('merchant-id=10000100&passphrase=Salt+pass&timestamp=2026-10-23T10%3A00%3A00%2B00%3A00&version=v1'));
+  });
+
+  test('reads PayFast CSV, quoted commas and quotes included', () => {
+    const rows = payfast.parseCsv(CSV);
+    expect(rows).toHaveLength(3);
+    expect(rows[0]).toMatchObject({ Type: 'FUNDS_RECEIVED', Gross: '80.00', Balance: '22,574.02', 'M Payment ID': 'chk_a', 'PF Payment ID': '3471967' });
+    expect(rows[1]).toMatchObject({ Name: 'Big "Camp"', Gross: '1,250.00' });
+  });
+
+  test('findPayments matches history rows on our checkout id (money received only)', async () => {
+    const get = jest.fn().mockResolvedValue({ data: CSV });
+    const list = ['chk_a', 'chk_b', 'chk_c'].map(id => ({ id, createdAt: new Date() }));
+    const found = await payfast.findPayments(list, { get });
+    expect([...found.keys()]).toEqual(['chk_a', 'chk_b']);
+    expect(found.get('chk_a')).toMatchObject({ externalId: '3471967', amountCents: 8000, checkoutId: 'chk_a', status: 'succeeded' });
+    expect(found.get('chk_a').createdDate.toISOString()).toBe('2026-10-23T12:19:24.000Z');
+    expect(found.get('chk_b').amountCents).toBe(125000);
+    const [url, opts] = get.mock.calls[0];
+    expect(url).toBe('https://api.payfast.co.za/transactions/history');
+    expect(opts.params).toMatchObject({ testing: 'true', limit: 1000, offset: 0 });
+    expect(opts.headers).toMatchObject({ 'merchant-id': '10000100', version: 'v1', signature: expect.any(String) });
+  });
+
+  test('live mode leaves out testing=true', async () => {
+    settings({ ...PF, payfast_mode: 'live' });
+    const get = jest.fn().mockResolvedValue({ data: CSV });
+    await payfast.findPayments([{ id: 'chk_a', createdAt: new Date() }], { get });
+    expect(get.mock.calls[0][1].params.testing).toBeUndefined();
+  });
+
+  test('a refused passphrase reads clearly', async () => {
+    const get = jest.fn().mockRejectedValue({ response: { status: 401, data: '{"data":{"response":"Merchant authorization failed."}}' } });
+    await expect(payfast.testConnection({ get })).rejects.toThrow(/refused the merchant ID or passphrase/);
+  });
+});
+
+describe('checkCheckouts', () => {
+  const checkout = (id, provider, cents) => ({ id, provider, externalId: null, amountCents: cents, metadata: { registrationId: 'r9', userId: 'u9' }, createdAt: new Date() });
+  let spy;
+  beforeEach(() => {
+    prisma.providerTransaction.findFirst.mockResolvedValue(null);
+    prisma.registration.findUnique.mockResolvedValue({ id: 'r9', status: 'pending', registrationOptions: [], payments: [{ amount: 80 }] });
+    prisma.registration.findFirst.mockResolvedValue({ id: 'r9', userId: 'u9', eventId: 'e9', status: 'pending', event: { id: 'e9', title: 'Fun Day' }, user: { id: 'u9', name: 'T' } });
+    prisma.registration.update.mockImplementation(({ data }) => Promise.resolve({ id: 'r9', ...data }));
+    computeRegistrationTotalDue.mockReturnValue(80);
+    prisma.payment.findFirst.mockResolvedValue(null);
+    prisma.payment.create.mockImplementation(({ data }) => Promise.resolve({ createdAt: new Date(), ...data }));
+    prisma.providerTransaction.findUnique.mockResolvedValue(null);
+    prisma.providerTransaction.create.mockImplementation(({ data }) => Promise.resolve({ id: 'ptx', ...data }));
+    prisma.ticket.findMany.mockResolvedValue([]);
+    spy = jest.spyOn(payfast, 'findPayments');
+  });
+  afterEach(() => spy.mockRestore());
+
+  test('a payment PayFast received is recorded as its ITN would have been', async () => {
+    spy.mockResolvedValue(new Map([['chk_a', { externalId: '3471967', amountCents: 8000, currency: 'ZAR', createdDate: new Date(), checkoutId: 'chk_a', methodType: null, metadata: {}, status: 'succeeded' }]]));
+    const out = await status.checkCheckouts([checkout('chk_a', 'payfast', 8000)]);
+    expect(out.get('chk_a')).toEqual({ status: 'recorded' });
+    expect(prisma.payment.create.mock.calls[0][0].data).toMatchObject({ amount: 80, provider: 'payfast', externalId: '3471967', registrationId: 'r9', status: 'completed' });
+    expect(prisma.registration.findFirst).toHaveBeenCalledWith(expect.objectContaining({ where: { checkoutId: { in: ['chk_a'] } } }));
+    expect(prisma.providerTransaction.create).toHaveBeenCalledWith({ data: expect.objectContaining({ provider: 'payfast', externalId: '3471967', reconciled: true }) });
+  });
+
+  test('a different amount is held for review; nothing found is not paid', async () => {
+    spy.mockResolvedValue(new Map([['chk_a', { externalId: '1', amountCents: 2000, checkoutId: 'chk_a', metadata: {}, status: 'succeeded' }]]));
+    const out = await status.checkCheckouts([checkout('chk_a', 'payfast', 8000), checkout('chk_n', 'payfast', 5000)]);
+    expect(out.get('chk_a')).toMatchObject({ status: 'needs_review', note: expect.stringMatching(/Paid R20.00/) });
+    expect(out.get('chk_n')).toEqual({ status: 'not_paid' });
+    expect(prisma.payment.create).not.toHaveBeenCalled();
+  });
+
+  test('already paid checkouts are skipped; Yoco can\'t be asked', async () => {
+    prisma.providerTransaction.findFirst.mockImplementation(({ where }) => Promise.resolve(where.checkoutId.in.includes('chk_paid') && where.paymentId ? { id: 'x' } : null));
+    spy.mockResolvedValue(new Map());
+    const out = await status.checkCheckouts([checkout('chk_paid', 'payfast', 8000), checkout('chk_y', 'yoco', 8000)]);
+    expect(out.get('chk_paid')).toEqual({ status: 'paid' });
+    expect(out.get('chk_y')).toEqual({ status: 'cant_check' });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  test('the job checks checkouts between 3 days and 10 minutes old, with providers that can be asked', async () => {
+    const now = new Date('2026-10-23T12:00:00Z');
+    prisma.providerCheckout.findMany.mockResolvedValue([checkout('chk_a', 'payfast', 8000), checkout('chk_y', 'yoco', 8000)]);
+    spy.mockResolvedValue(new Map());
+    await expect(status.runPaymentStatusJob(now)).resolves.toEqual({ checked: 1, recorded: 0, needsReview: 0 });
+    expect(prisma.providerCheckout.findMany).toHaveBeenCalledWith(expect.objectContaining({
+      where: { provider: { not: null }, createdAt: { gte: new Date('2026-10-20T12:00:00Z'), lte: new Date('2026-10-23T11:50:00Z') } },
+    }));
+    expect(spy).toHaveBeenCalledWith([expect.objectContaining({ id: 'chk_a' })]);
+  });
+});

backend/tests/payments.test.js

@@ -0,0 +1,375 @@
+jest.mock('../src/config/db', () => ({
+  appSetting: { findMany: jest.fn() },
+  registration: { findFirst: jest.fn(), findUnique: jest.fn(), update: jest.fn() },
+  payment: { findFirst: jest.fn(), create: jest.fn() },
+  providerTransaction: { findUnique: jest.fn(), findFirst: jest.fn(), create: jest.fn(), update: jest.fn() },
+  providerCheckout: { create: jest.fn(), update: jest.fn(), delete: jest.fn(), findUnique: jest.fn(), findFirst: jest.fn(), findMany: jest.fn() },
+  ticket: { findMany: jest.fn() },
+  user: { findFirst: jest.fn() },
+}));
+jest.mock('axios', () => { const fn = jest.fn(); fn.post = jest.fn(); fn.get = jest.fn(); return fn; });
+jest.mock('../src/utils/pricing', () => ({ computeRegistrationTotalDue: jest.fn(), refreshPricingForRegistration: jest.fn() }));
+jest.mock('../src/utils/ticketUtils', () => ({ generateTicketsForRegistration: jest.fn().mockResolvedValue([]) }));
+jest.mock('../src/utils/notifications', () => ({ sendPaymentEmails: jest.fn() }));
+jest.mock('../src/controllers/ticketController', () => ({ emailTickets: jest.fn() }));
+
+const axios = require('axios');
+const prisma = require('../src/config/db');
+const settingsCache = require('../src/utils/settingsCache');
+const { computeRegistrationTotalDue } = require('../src/utils/pricing');
+const payments = require('../src/payments');
+const yoco = require('../src/payments/providers/yoco');
+const payfast = require('../src/payments/providers/payfast');
+const { handleProviderWebhook } = require('../src/payments/webhook');
+
+const SECRET = 'whsec_' + Buffer.from('test-webhook-secret').toString('base64');
+const PF = { payfast_merchant_id: '10000100', payfast_merchant_key: 'abcdefghij123', payfast_passphrase: 'Salt pass', payfast_mode: 'sandbox' };
+
+function settings(values) {
+  prisma.appSetting.findMany.mockResolvedValue(Object.entries(values).map(([key, value]) => ({ key, value })));
+  settingsCache.invalidate();
+}
+
+const ENV = { ...process.env };
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ENV };
+  delete process.env.YOCO_SECRET_KEY;
+  delete process.env.YOCO_WEBHOOK_SECRET;
+  for (const k of ['PAYFAST_MERCHANT_ID', 'PAYFAST_MERCHANT_KEY', 'PAYFAST_PASSPHRASE', 'PAYFAST_MODE', 'PAYFAST_SKIP_IP_CHECK']) delete process.env[k];
+  process.env.FRONTEND_URL = 'https://events.example.org';
+  process.env.BACKEND_URL = 'https://api.example.org';
+  prisma.providerCheckout.create.mockImplementation(({ data }) => Promise.resolve({ id: 'chk_1', provider: null, externalId: null, redirectUrl: null, ...data }));
+  prisma.providerCheckout.update.mockResolvedValue({});
+  prisma.providerCheckout.delete.mockResolvedValue({});
+});
+
+describe('provider settings', () => {
+  test('Yoco is on by default (it was the only provider)', () => {
+    expect(payments.parseProviderSettings('', ['yoco', 'payfast'])).toEqual([
+      { id: 'yoco', enabled: true }, { id: 'payfast', enabled: false },
+    ]);
+  });
+
+  test('stored order and flags win; unknown ids are dropped, new ones come last', () => {
+    const raw = JSON.stringify({ order: ['payfast', 'gone', 'yoco'], enabled: { yoco: false, payfast: true } });
+    expect(payments.parseProviderSettings(raw, ['yoco', 'payfast', 'snapscan'])).toEqual([
+      { id: 'payfast', enabled: true }, { id: 'yoco', enabled: false }, { id: 'snapscan', enabled: false },
+    ]);
+  });
+
+  test('bad JSON falls back to the defaults', () => {
+    expect(payments.parseProviderSettings('{nope', ['yoco'])).toEqual([{ id: 'yoco', enabled: true }]);
+  });
+
+  test('serialising keeps the order and drops unknown providers', () => {
+    expect(JSON.parse(payments.serializeProviderSettings([{ id: 'yoco', enabled: false }, { id: 'zzz', enabled: true }])))
+      .toEqual({ order: ['yoco'], enabled: { yoco: false } });
+  });
+});
+
+describe('createCheckout', () => {
+  test('online payments must be at least R15', async () => {
+    await expect(payments.createCheckout(null, { amountCents: 1499 })).rejects.toThrow(/at least R15/);
+    expect(prisma.providerCheckout.create).not.toHaveBeenCalled();
+  });
+
+  test('nothing enabled: online payments are off', async () => {
+    settings({ payment_providers: JSON.stringify({ order: ['yoco'], enabled: { yoco: false } }) });
+    await expect(payments.createCheckout(null, { amountCents: 5000 })).rejects.toMatchObject({ statusCode: 503, message: expect.stringMatching(/turned off/) });
+  });
+
+  test('asking for a provider that is switched off is refused', async () => {
+    settings({ payment_providers: JSON.stringify({ order: ['yoco'], enabled: { yoco: false } }) });
+    await expect(payments.createCheckout('yoco', { amountCents: 5000 })).rejects.toThrow(/Yoco is turned off/);
+  });
+
+  test('enabled but no key: the provider explains, and the checkout record is removed', async () => {
+    settings({});
+    axios.mockRejectedValue(new Error('should not be called'));
+    await expect(payments.createCheckout(null, { amountCents: 5000 })).rejects.toThrow(/Yoco secret key/);
+    expect(prisma.providerCheckout.delete).toHaveBeenCalledWith({ where: { id: 'chk_1' } });
+  });
+
+  test('one provider available: starts it straight away and records the checkout', async () => {
+    settings({ yoco_secret_key: 'sk_test_abc' });
+    const spy = jest.spyOn(yoco, 'createCheckout').mockResolvedValue({ externalId: 'ch_1', redirectUrl: 'https://pay/1' });
+    const out = await payments.createCheckout(null, { amountCents: 5000, metadata: { a: 1 }, description: 'Camp' });
+    expect(out).toEqual({ checkoutId: 'chk_1', provider: 'yoco', redirectUrl: 'https://pay/1' });
+    expect(prisma.providerCheckout.create).toHaveBeenCalledWith({ data: { amountCents: 5000, currency: 'ZAR', metadata: { a: 1 }, request: { description: 'Camp' } } });
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ checkoutId: 'chk_1', amountCents: 5000, currency: 'ZAR', metadata: { a: 1 } }));
+    expect(prisma.providerCheckout.update).toHaveBeenCalledWith({ where: { id: 'chk_1' }, data: { provider: 'yoco', externalId: 'ch_1', redirectUrl: 'https://pay/1' } });
+    spy.mockRestore();
+  });
+
+  test('several available: the payer chooses on /pay/<id>', async () => {
+    settings({ yoco_secret_key: 'sk_test_abc', ...PF, payment_providers: JSON.stringify({ order: ['payfast', 'yoco'], enabled: { yoco: true, payfast: true } }) });
+    const out = await payments.createCheckout(null, { amountCents: 5000 });
+    expect(out).toEqual({ checkoutId: 'chk_1', provider: null, redirectUrl: 'https://events.example.org/pay/chk_1' });
+  });
+
+  test('a form provider (PayFast) sends the payer to /pay/<id>, which posts the form', async () => {
+    settings({ ...PF, payment_providers: JSON.stringify({ order: ['payfast'], enabled: { yoco: false, payfast: true } }) });
+    const out = await payments.createCheckout(null, { amountCents: 5000 });
+    expect(out).toEqual({ checkoutId: 'chk_1', provider: 'payfast', redirectUrl: 'https://events.example.org/pay/chk_1' });
+    expect(prisma.providerCheckout.update).toHaveBeenCalledWith({ where: { id: 'chk_1' }, data: { provider: 'payfast' } });
+  });
+});
+
+describe('Yoco provider', () => {
+  const now = 1_800_000_000_000;
+  const body = JSON.stringify({ type: 'payment.succeeded', payload: { id: 'p_1', amount: 12000, currency: 'ZAR', status: 'succeeded', checkoutId: 'ch_1', paymentMethodDetails: { type: 'card' }, metadata: { registrationId: 'r1' } } });
+  const signed = (overrides = {}) => {
+    const ts = String(Math.floor(now / 1000));
+    return { headers: { 'webhook-id': 'msg_1', 'webhook-timestamp': ts, 'webhook-signature': `v1,${yoco.webhookSignature(SECRET, 'msg_1', ts, body)}`, ...overrides }, rawBody: body };
+  };
+
+  test('line items map to Yoco cents, deductions stay negative', () => {
+    expect(yoco.toYocoLineItems([{ name: 'Ticket', quantity: 2, unitCents: 5000 }, { name: 'Coupon', quantity: 1, unitCents: -1000 }])).toEqual([
+      { displayName: 'Ticket', quantity: 2, pricingDetails: { price: 5000 } },
+      { displayName: 'Coupon', quantity: 1, pricingDetails: { price: -1000 } },
+    ]);
+  });
+
+  test('a correctly signed webhook verifies', async () => {
+    process.env.YOCO_WEBHOOK_SECRET = SECRET;
+    settings({});
+    await expect(yoco.verifyWebhook(signed(), now)).resolves.toMatchObject({ ok: true, webhookId: 'msg_1' });
+  });
+
+  test('any of several signatures may match (key rotation)', async () => {
+    process.env.YOCO_WEBHOOK_SECRET = SECRET;
+    settings({});
+    const req = signed();
+    req.headers['webhook-signature'] = `v1,bm9wZQ== ${req.headers['webhook-signature']}`;
+    await expect(yoco.verifyWebhook(req, now)).resolves.toMatchObject({ ok: true });
+  });
+
+  test('bad signature, old timestamp, missing headers, no secret', async () => {
+    process.env.YOCO_WEBHOOK_SECRET = SECRET;
+    settings({});
+    await expect(yoco.verifyWebhook(signed({ 'webhook-signature': 'v1,bm9wZQ==' }), now)).resolves.toMatchObject({ ok: false, status: 403 });
+    await expect(yoco.verifyWebhook(signed(), now + 4 * 60 * 1000)).resolves.toMatchObject({ ok: false, status: 400, message: expect.stringMatching(/timestamp/) });
+    await expect(yoco.verifyWebhook({ headers: {}, rawBody: body }, now)).resolves.toMatchObject({ ok: false, status: 400, details: { missingHeaders: ['webhook-id', 'webhook-timestamp', 'webhook-signature'] } });
+    delete process.env.YOCO_WEBHOOK_SECRET;
+    settings({});
+    await expect(yoco.verifyWebhook(signed(), now)).resolves.toMatchObject({ ok: false, status: 500 });
+  });
+
+  test('parses a payment.succeeded body', () => {
+    expect(yoco.parseWebhook(JSON.parse(body))).toEqual({
+      type: 'payment.succeeded',
+      transaction: {
+        externalId: 'p_1', amountCents: 12000, currency: 'ZAR', createdDate: null, checkoutId: 'ch_1',
+        methodType: 'card', metadata: { registrationId: 'r1' }, status: 'succeeded',
+      },
+    });
+  });
+});
+
+describe('PayFast provider', () => {
+  test('encodes like PHP urlencode: upper-case escapes, + for spaces, and \' ( ) ! * ~ escaped', () => {
+    expect(payfast.pfEncode("Men's Camp (Youth)! *~")).toBe('Men%27s+Camp+%28Youth%29%21+%2A%7E');
+    expect(payfast.pfEncode('https://x.org/a?b=1&c=2')).toBe('https%3A%2F%2Fx.org%2Fa%3Fb%3D1%26c%3D2');
+    expect(payfast.pfEncode('  padded  ')).toBe('padded');
+  });
+
+  test('a checkout signs the non-blank fields in order; an ITN signs every field', () => {
+    const pairs = [['a', '1'], ['b', ''], ['c', 'x y']];
+    expect(payfast.paramString(pairs)).toBe('a=1&c=x+y');
+    expect(payfast.paramString(pairs, { allFields: true })).toBe('a=1&b=&c=x+y');
+    const md5 = (s) => require('crypto').createHash('md5').update(s).digest('hex');
+    expect(payfast.signature(pairs, 'my pass')).toBe(md5('a=1&c=x+y&passphrase=my+pass'));
+    expect(payfast.signature(pairs)).toBe(md5('a=1&c=x+y'));
+  });
+
+  test('builds the signed form in PayFast\'s field order', async () => {
+    settings(PF);
+    const { form } = await payfast.createCheckout({
+      checkoutId: 'chk_9', amountCents: 12550, successUrl: 'https://e.org/ok', cancelUrl: 'https://e.org/no',
+      payer: { name: "Thandi O'Neil Mokoena", email: 'thandi@example.org' }, description: "Men's Camp (Youth)",
+      lineItems: [{ name: 'Ticket', quantity: 2, unitCents: 5000 }, { name: 'Coupon', quantity: 1, unitCents: -1000 }],
+    });
+    expect(form.action).toBe('https://sandbox.payfast.co.za/eng/process');
+    expect(Object.keys(form.fields)).toEqual(['merchant_id', 'merchant_key', 'return_url', 'cancel_url', 'notify_url', 'name_first', 'name_last', 'email_address', 'm_payment_id', 'amount', 'item_name', 'item_description', 'signature']);
+    expect(form.fields).toMatchObject({
+      notify_url: 'https://api.example.org/api/webhooks/payfast', name_first: 'Thandi', name_last: "O'Neil Mokoena",
+      m_payment_id: 'chk_9', amount: '125.50', item_name: "Men's Camp (Youth)", item_description: 'Ticket x2',
+    });
+    const { signature, ...rest } = form.fields;
+    expect(signature).toBe(payfast.signature(Object.entries(rest), 'Salt pass'));
+  });
+
+  test('live mode posts to www.payfast.co.za; test emails are left out', async () => {
+    settings({ ...PF, payfast_mode: 'live' });
+    const { form } = await payfast.createCheckout({ checkoutId: 'c', amountCents: 2000, payer: { name: 'A', email: 'walkin@guest.local' } });
+    expect(form.action).toBe('https://www.payfast.co.za/eng/process');
+    expect(form.fields.email_address).toBeUndefined();
+  });
+
+  test('not set up: says what is missing', async () => {
+    settings({});
+    await expect(payfast.createCheckout({ checkoutId: 'c', amountCents: 2000 })).rejects.toMatchObject({ statusCode: 503, message: expect.stringMatching(/merchant ID and key/) });
+  });
+
+  describe('ITN checks', () => {
+    // An ITN as PayFast posts it: every field, blanks included, signature last
+    const itn = (overrides = {}, passphrase = 'Salt pass') => {
+      const pairs = Object.entries({
+        m_payment_id: 'chk_9', pf_payment_id: '1089250', payment_status: 'COMPLETE', item_name: "Men's Camp (Youth)", item_description: '',
+        amount_gross: '125.50', amount_fee: '-4.60', amount_net: '120.90', custom_str1: '', name_first: 'Thandi', name_last: '', email_address: 'thandi@example.org',
+        merchant_id: '10000100', ...overrides,
+      });
+      const sig = payfast.signature(pairs, passphrase, { allFields: true });
+      return pairs.map(([k, v]) => `${k}=${payfast.pfEncode(v)}`).join('&') + `&signature=${sig}`;
+    };
+    const req = (rawBody, ip = '197.97.145.144') => ({ rawBody, ip, headers: {} });
+    const deps = (reply = 'VALID', ips = ['197.97.145.144']) => ({ lookupIps: async () => new Set(ips), post: jest.fn().mockResolvedValue({ data: reply }) });
+
+    beforeEach(() => settings(PF));
+
+    test('a genuine ITN passes, and is confirmed with PayFast over every field', async () => {
+      const d = deps();
+      await expect(payfast.verifyWebhook(req(itn()), d)).resolves.toMatchObject({ ok: true, webhookId: '1089250' });
+      const [url, sent] = d.post.mock.calls[0];
+      expect(url).toBe('https://sandbox.payfast.co.za/eng/query/validate');
+      expect(sent).toContain('item_description=&');
+      expect(sent).not.toContain('signature=');
+    });
+
+    test('a forged or wrongly signed ITN is refused', async () => {
+      await expect(payfast.verifyWebhook(req(itn({}, 'wrong passphrase')), deps())).resolves.toMatchObject({ ok: false, status: 403, message: 'Invalid signature' });
+      const tampered = itn().replace('amount_gross=125.50', 'amount_gross=1.00');
+      await expect(payfast.verifyWebhook(req(tampered), deps())).resolves.toMatchObject({ ok: false, status: 403 });
+    });
+
+    test('not from a PayFast address: refused (unless the check is switched off)', async () => {
+      await expect(payfast.verifyWebhook(req(itn(), '10.0.0.5'), deps())).resolves.toMatchObject({ ok: false, status: 403, message: expect.stringMatching(/did not come from PayFast/) });
+      process.env.PAYFAST_SKIP_IP_CHECK = 'true';
+      await expect(payfast.verifyWebhook(req(itn(), '10.0.0.5'), deps())).resolves.toMatchObject({ ok: true });
+    });
+
+    test('PayFast doesn\'t confirm it, or is unreachable', async () => {
+      await expect(payfast.verifyWebhook(req(itn()), deps('INVALID'))).resolves.toMatchObject({ ok: false, status: 403 });
+      const down = { lookupIps: async () => new Set(['197.97.145.144']), post: jest.fn().mockRejectedValue(new Error('timeout')) };
+      await expect(payfast.verifyWebhook(req(itn()), down)).resolves.toMatchObject({ ok: false, status: 502 });
+    });
+
+    test('another merchant\'s ITN is refused', async () => {
+      await expect(payfast.verifyWebhook(req(itn({ merchant_id: '99999999' })), deps())).resolves.toMatchObject({ ok: false, status: 403 });
+    });
+
+    test('parses COMPLETE as a successful payment', () => {
+      expect(payfast.parseWebhook(payfast.readWebhookBody(itn()))).toEqual({
+        type: 'payment.succeeded',
+        transaction: { externalId: '1089250', amountCents: 12550, currency: 'ZAR', createdDate: null, checkoutId: 'chk_9', methodType: null, metadata: {}, status: 'succeeded' },
+      });
+      expect(payfast.parseWebhook({ payment_status: 'CANCELLED' }).type).toBe('payment.cancelled');
+    });
+  });
+});
+
+describe('webhook flow', () => {
+  const response = () => {
+    const res = { statusCode: 200, body: null };
+    res.status = (c) => { res.statusCode = c; return res; };
+    res.json = (b) => { res.body = b; return res; };
+    return res;
+  };
+
+  beforeEach(() => {
+    prisma.registration.findFirst.mockResolvedValue({ id: 'r9', userId: 'u9', eventId: 'e9', status: 'pending', event: { id: 'e9', title: 'Camp' }, user: { id: 'u9', name: 'T' } });
+    prisma.registration.findUnique.mockResolvedValue({ id: 'r9', registrationOptions: [], payments: [{ amount: 100 }] });
+    prisma.registration.update.mockImplementation(({ data }) => Promise.resolve({ id: 'r9', userId: 'u9', eventId: 'e9', ...data }));
+    computeRegistrationTotalDue.mockReturnValue(100);
+    prisma.payment.create.mockImplementation(({ data }) => Promise.resolve({ createdAt: new Date(), ...data }));
+    prisma.providerTransaction.findUnique.mockResolvedValue(null);
+    prisma.providerTransaction.create.mockImplementation(({ data }) => Promise.resolve({ id: 'ptx', ...data }));
+    prisma.providerCheckout.findUnique.mockResolvedValue(null);
+    prisma.providerCheckout.findFirst.mockResolvedValue(null);
+    prisma.ticket.findMany.mockResolvedValue([]);
+  });
+
+  describe('Yoco', () => {
+    const body = JSON.stringify({ type: 'payment.succeeded', payload: { id: 'p_9', amount: 15000, currency: 'ZAR', status: 'succeeded', checkoutId: 'ch_9', paymentMethodDetails: { type: 'card' }, metadata: { registrationId: 'r9', userId: 'u9', donationAmount: '50.00' } } });
+    const request = () => {
+      const ts = String(Math.floor(Date.now() / 1000));
+      return { headers: { 'webhook-id': 'msg_9', 'webhook-timestamp': ts, 'webhook-signature': `v1,${yoco.webhookSignature(SECRET, 'msg_9', ts, body)}` }, rawBody: body };
+    };
+    beforeEach(() => { process.env.YOCO_WEBHOOK_SECRET = SECRET; settings({}); });
+
+    test('records the payment (donation split off), tagged with the provider, and a reconciled transaction', async () => {
+      prisma.payment.findFirst.mockResolvedValue(null);
+      const res = response();
+      await handleProviderWebhook('yoco')(request(), res);
+
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data.processedData.registration).toMatchObject({ id: 'r9', status: 'paid' });
+      const [main, donation] = prisma.payment.create.mock.calls.map(c => c[0].data);
+      expect(main).toMatchObject({ amount: 100, method: 'card', provider: 'yoco', externalId: 'p_9', registrationId: 'r9', isDonation: false, status: 'completed' });
+      expect(donation).toMatchObject({ amount: 50, provider: 'yoco', isDonation: true, originalPaymentId: main.id });
+      expect(prisma.providerTransaction.create).toHaveBeenCalledWith({ data: expect.objectContaining({ provider: 'yoco', externalId: 'p_9', amount: 15000, reconciled: true, paymentId: main.id }) });
+    });
+
+    test('found through our checkout record: the registration is looked up by our id too', async () => {
+      prisma.payment.findFirst.mockResolvedValue(null);
+      prisma.providerCheckout.findFirst.mockResolvedValue({ id: 'chk_ours', provider: 'yoco', externalId: 'ch_9', amountCents: 15000, metadata: { registrationId: 'r9' } });
+      await handleProviderWebhook('yoco')(request(), response());
+      expect(prisma.registration.findFirst).toHaveBeenCalledWith(expect.objectContaining({ where: { checkoutId: { in: ['chk_ours', 'ch_9'] } } }));
+      expect(prisma.payment.create).toHaveBeenCalled();
+    });
+
+    test('a repeated webhook records nothing new', async () => {
+      prisma.payment.findFirst.mockResolvedValue({ id: 'existing' });
+      prisma.providerTransaction.findUnique.mockResolvedValue({ id: 'ptx' });
+      prisma.providerTransaction.update.mockResolvedValue({ id: 'ptx' });
+      const res = response();
+      await handleProviderWebhook('yoco')(request(), res);
+
+      expect(res.body.data.processedData).toMatchObject({ status: 'already_processed', paymentId: 'existing' });
+      expect(prisma.payment.create).not.toHaveBeenCalled();
+      expect(prisma.providerTransaction.update).toHaveBeenCalledWith({ where: { id: 'ptx' }, data: { reconciled: true, paymentId: 'existing' } });
+    });
+
+    test('a bad signature is refused before anything is stored', async () => {
+      const req = request();
+      req.headers['webhook-signature'] = 'v1,bm9wZQ==';
+      const res = response();
+      await handleProviderWebhook('yoco')(req, res);
+      expect(res.statusCode).toBe(403);
+      expect(prisma.payment.create).not.toHaveBeenCalled();
+      expect(prisma.providerTransaction.create).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('PayFast', () => {
+    const itn = (amount = '100.00') => {
+      const pairs = Object.entries({ m_payment_id: 'chk_pf', pf_payment_id: '555', payment_status: 'COMPLETE', item_name: 'Camp', amount_gross: amount, merchant_id: '10000100' });
+      return pairs.map(([k, v]) => `${k}=${payfast.pfEncode(v)}`).join('&') + `&signature=${payfast.signature(pairs, 'Salt pass', { allFields: true })}`;
+    };
+    beforeEach(() => {
+      settings(PF);
+      process.env.PAYFAST_SKIP_IP_CHECK = 'true';
+      axios.post.mockResolvedValue({ data: 'VALID' });
+      prisma.payment.findFirst.mockResolvedValue(null);
+      prisma.providerCheckout.findUnique.mockResolvedValue({ id: 'chk_pf', provider: 'payfast', amountCents: 10000, metadata: { registrationId: 'r9', userId: 'u9', eventId: 'e9', type: 'registration_payment' } });
+    });
+
+    test('a confirmed ITN records the payment against the checkout\'s registration', async () => {
+      const res = response();
+      await handleProviderWebhook('payfast')({ rawBody: itn(), ip: '1.2.3.4', headers: {} }, res);
+      expect(res.statusCode).toBe(200);
+      expect(prisma.payment.create.mock.calls[0][0].data).toMatchObject({ amount: 100, provider: 'payfast', method: 'card', externalId: '555', registrationId: 'r9', status: 'completed' });
+      expect(prisma.providerTransaction.create).toHaveBeenCalledWith({ data: expect.objectContaining({ provider: 'payfast', externalId: '555', checkoutId: 'chk_pf', reconciled: true }) });
+    });
+
+    test('paid a different amount from the checkout: held for review, not recorded', async () => {
+      const res = response();
+      await handleProviderWebhook('payfast')({ rawBody: itn('20.00'), ip: '1.2.3.4', headers: {} }, res);
+      expect(res.statusCode).toBe(200);
+      expect(res.body.data).toEqual({ needsReview: true });
+      expect(prisma.payment.create).not.toHaveBeenCalled();
+      expect(prisma.providerTransaction.create).toHaveBeenCalledWith({ data: expect.objectContaining({ provider: 'payfast', reconciled: false, note: expect.stringMatching(/Paid R20.00, but the checkout was for R100.00/) }) });
+    });
+  });
+});

backend/tests/privacy.test.js

@@ -0,0 +1,161 @@
+jest.mock('../src/config/db', () => ({
+  user: { findUnique: jest.fn(), findMany: jest.fn(), findFirst: jest.fn(), update: jest.fn() },
+  communicationConsent: { createMany: jest.fn(), create: jest.fn() },
+  messagingOptOut: { findMany: jest.fn(), findUnique: jest.fn(), create: jest.fn() },
+  registration: { findMany: jest.fn() },
+}));
+
+process.env.JWT_SECRET = 'test-secret';
+process.env.FRONTEND_URL = 'https://events.example.org';
+process.env.BACKEND_URL = 'https://api.example.org';
+
+const prisma = require('../src/config/db');
+const privacy = require('../src/utils/privacy');
+const { phoneFromChatId } = require('../src/utils/whatsapp');
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  prisma.messagingOptOut.findMany.mockResolvedValue([]);
+});
+
+describe('unsubscribe tokens', () => {
+  test('round-trip an account and an address', () => {
+    expect(privacy.readUnsubscribeToken(privacy.unsubscribeToken({ userId: 'u1' }))).toEqual({ userId: 'u1' });
+    const t = privacy.unsubscribeToken({ address: 'a@b.co', channel: 'email' });
+    expect(privacy.readUnsubscribeToken(t)).toEqual({ address: 'a@b.co', channel: 'email' });
+  });
+
+  test('a tampered token is refused', () => {
+    const [, sig] = privacy.unsubscribeToken({ userId: 'u1' }).split('.');
+    const forged = `${Buffer.from(JSON.stringify({ u: 'someone-else' })).toString('base64url')}.${sig}`;
+    expect(privacy.readUnsubscribeToken(forged)).toBeNull();
+    expect(privacy.readUnsubscribeToken('garbage')).toBeNull();
+    expect(privacy.readUnsubscribeToken('')).toBeNull();
+  });
+
+  test('an address token needs a known channel', () => {
+    const payload = Buffer.from(JSON.stringify({ a: 'x@y.z', c: 'sms' })).toString('base64url');
+    const real = privacy.unsubscribeToken({ address: 'x@y.z', channel: 'email' });
+    expect(privacy.readUnsubscribeToken(`${payload}.${real.split('.')[1]}`)).toBeNull();
+  });
+});
+
+describe('filterRecipients', () => {
+  const users = [
+    { id: 'in', email: 'in@x.co', phoneNumber: '27820000001', newsEmail: true, newsWhatsApp: true },
+    { id: 'out', email: 'Out@x.co', phoneNumber: '27820000002', newsEmail: false, newsWhatsApp: false },
+  ];
+
+  test('updates go to everyone, with the account filled in', async () => {
+    prisma.user.findMany.mockResolvedValue(users);
+    const res = await privacy.filterRecipients([{ email: 'in@x.co' }, { email: 'out@x.co' }, { email: 'guest@x.co' }], { channel: 'email', kind: 'update' });
+    expect(res.skipped).toBe(0);
+    expect(res.recipients.map(r => r.userId)).toEqual(['in', 'out', null]);
+    expect(prisma.messagingOptOut.findMany).not.toHaveBeenCalled();
+  });
+
+  test('news skips accounts without the opt-in (any letter case) and unsubscribed addresses', async () => {
+    prisma.user.findMany.mockResolvedValue(users);
+    prisma.messagingOptOut.findMany.mockResolvedValue([{ address: 'gone@x.co' }]);
+    const res = await privacy.filterRecipients(
+      [{ email: 'in@x.co' }, { email: 'OUT@x.co' }, { email: 'gone@x.co' }, { email: 'new@x.co' }],
+      { channel: 'email', kind: 'news' },
+    );
+    expect(res.recipients.map(r => r.email)).toEqual(['in@x.co', 'new@x.co']);
+    expect(res.skipped).toBe(2);
+  });
+
+  test('WhatsApp news uses the WhatsApp opt-in and normalised numbers', async () => {
+    prisma.user.findMany.mockResolvedValue(users);
+    const res = await privacy.filterRecipients([{ phone: '082 000 0001' }, { phone: '0820000002' }], { channel: 'whatsapp', kind: 'news' });
+    expect(res.recipients).toHaveLength(1);
+    expect(res.recipients[0].userId).toBe('in');
+  });
+});
+
+describe('setNewsPreferences', () => {
+  test('logs only the channels that changed, and WhatsApp needs a phone', async () => {
+    prisma.user.findUnique.mockResolvedValueOnce({ id: 'u1', phoneNumber: null, newsEmail: true, newsWhatsApp: false });
+    prisma.user.update.mockResolvedValue({ newsEmail: false, newsWhatsApp: false, newsAskedAt: null });
+    await privacy.setNewsPreferences('u1', { email: false, whatsapp: true }, { source: 'privacy_centre' });
+    expect(prisma.user.update).toHaveBeenCalledWith(expect.objectContaining({ data: { newsEmail: false } }));
+    expect(prisma.communicationConsent.createMany).toHaveBeenCalledWith({
+      data: [{ userId: 'u1', channel: 'email', granted: false, source: 'privacy_centre', ip: null }],
+    });
+  });
+
+  test('the first answer is logged even when nothing changes', async () => {
+    prisma.user.findUnique.mockResolvedValueOnce({ id: 'u1', phoneNumber: '27820000001', newsEmail: true, newsWhatsApp: true });
+    prisma.user.update.mockResolvedValue({ newsEmail: true, newsWhatsApp: true, newsAskedAt: new Date() });
+    await privacy.setNewsPreferences('u1', { email: true, whatsapp: true }, { source: 'prompt', answered: true, logAll: true });
+    expect(prisma.user.update.mock.calls[0][0].data.newsAskedAt).toBeInstanceOf(Date);
+    expect(prisma.communicationConsent.createMany.mock.calls[0][0].data).toHaveLength(2);
+  });
+});
+
+describe('footers', () => {
+  test('news emails carry an unsubscribe link and one-click headers', () => {
+    const f = privacy.bulkEmailFooter({ kind: 'news', recipient: { email: 'a@b.co', userId: 'u1' } });
+    expect(f.html).toContain('https://events.example.org/unsubscribe?t=');
+    expect(f.headers['List-Unsubscribe']).toMatch(/^<https:\/\/api\.example\.org\/api\/privacy\/unsubscribe\/.+\/one-click>$/);
+    expect(f.headers['List-Unsubscribe-Post']).toBe('List-Unsubscribe=One-Click');
+  });
+
+  test('update emails explain why and link to the preferences, without unsubscribe headers', () => {
+    const f = privacy.bulkEmailFooter({ kind: 'update', recipient: { email: 'a@b.co' }, eventTitle: 'Camp <2026>' });
+    expect(f.html).toContain('you registered for Camp &lt;2026&gt;');
+    expect(f.html).toContain('/dashboard/user/privacy');
+    expect(f.headers).toEqual({});
+  });
+
+  test('news WhatsApps mention STOP', () => {
+    expect(privacy.whatsAppNewsFooter({ phone: '0820000001' })).toMatch(/Reply STOP/);
+  });
+});
+
+describe('WhatsApp STOP', () => {
+  test.each(['STOP', 'stop', ' Stop. ', 'unsubscribe', 'Opt out'])('%p is an opt-out', text => {
+    expect(privacy.isStopKeyword(text)).toBe(true);
+  });
+  test.each(['please stop by the office', 'STOPPED', '', null])('%p is not', text => {
+    expect(privacy.isStopKeyword(text)).toBe(false);
+  });
+
+  test('phone numbers only from personal chats', () => {
+    expect(phoneFromChatId('27821234567@c.us')).toBe('27821234567');
+    expect(phoneFromChatId('1203630@g.us')).toBeNull();
+    expect(phoneFromChatId('99887766@lid')).toBeNull();
+  });
+
+  test('an account number turns off WhatsApp news; an unknown number is opted out', async () => {
+    prisma.user.findFirst.mockResolvedValueOnce({ id: 'u1' });
+    prisma.user.findUnique.mockResolvedValueOnce({ id: 'u1', phoneNumber: '27821234567', newsEmail: true, newsWhatsApp: true });
+    prisma.user.update.mockResolvedValue({});
+    expect(await privacy.whatsAppStop('27821234567')).toBe('account');
+    expect(prisma.user.update.mock.calls[0][0].data).toEqual({ newsWhatsApp: false });
+
+    prisma.user.findFirst.mockResolvedValueOnce(null);
+    prisma.messagingOptOut.findUnique.mockResolvedValueOnce(null);
+    expect(await privacy.whatsAppStop('0829999999')).toBe('address');
+    expect(prisma.messagingOptOut.create).toHaveBeenCalledWith({ data: { channel: 'whatsapp', address: '27829999999', source: 'whatsapp_stop' } });
+  });
+});
+
+describe('anonymising helpers', () => {
+  test('scrubPersonal removes payer details from provider payloads, keeps amounts and ids', () => {
+    const raw = { m_payment_id: 'chk_1', pf_payment_id: '123', amount_gross: '80.00', name_first: 'Ann', name_last: 'Lee', email_address: 'ann@x.co', nested: { customer: 'Ann Lee', id: 'x' } };
+    expect(privacy.scrubPersonal(raw)).toEqual({
+      m_payment_id: 'chk_1', pf_payment_id: '123', amount_gross: '80.00',
+      name_first: '[deleted]', name_last: '[deleted]', email_address: '[deleted]', nested: { customer: '[deleted]', id: 'x' },
+    });
+  });
+
+  test('deletion is blocked by registrations for events that have not ended', async () => {
+    prisma.registration.findMany.mockResolvedValue([{ id: 'r1', status: 'paid', event: { id: 'e1', title: 'Camp', endDate: new Date('2099-01-01') } }]);
+    const blockers = await privacy.deletionBlockers('u1');
+    expect(blockers).toEqual([{ registrationId: 'r1', status: 'paid', eventId: 'e1', eventTitle: 'Camp', endDate: new Date('2099-01-01') }]);
+    const where = prisma.registration.findMany.mock.calls[0][0].where;
+    expect(where.status).toEqual({ not: 'cancelled' });
+    expect(where.event.endDate.gte).toBeInstanceOf(Date);
+  });
+});

backend/tests/privacyNotice.test.js

@@ -0,0 +1,109 @@
+jest.mock('../src/config/db', () => ({
+  privacyNotice: { findFirst: jest.fn(), findMany: jest.fn(), findUnique: jest.fn() },
+  operator: { findMany: jest.fn() },
+  appSetting: { findMany: jest.fn().mockResolvedValue([]), findUnique: jest.fn() },
+}));
+
+const prisma = require('../src/config/db');
+const notice = require('../src/utils/privacyNotice');
+const { reportRowCount } = require('../src/utils/accessLog');
+
+const ctx = {
+  org: 'Hope Church', orgEmail: 'office@hope.test', website: 'hope.test', ioName: 'Ann IO', ioEmail: 'io@hope.test', medicalRetentionDays: '30',
+  operators: [
+    { name: 'PayFast', location: 'South Africa', purpose: 'Online payments', dataShared: 'Name, email address' },
+    { name: 'WAWP', location: null, purpose: 'Delivering WhatsApp messages', dataShared: 'Mobile number' },
+  ],
+};
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('renderSections', () => {
+  test('fills placeholders and expands {operators} into one bullet each', () => {
+    const [s] = notice.renderSections([{ id: 'a', title: 'A', body: 'Run by {org} — ask {ioName} ({ioEmail}).\n{operators}\nUnknown {nope} stays.' }], ctx);
+    expect(s.body.split('\n')).toEqual([
+      'Run by Hope Church — ask Ann IO (io@hope.test).',
+      '• PayFast (South Africa) — Online payments. Receives: Name, email address.',
+      '• WAWP — Delivering WhatsApp messages. Receives: Mobile number.',
+      'Unknown {nope} stays.',
+    ]);
+  });
+
+  test('{operators} inside a sentence is left alone', () => {
+    const [s] = notice.renderSections([{ id: 'a', title: 'A', body: 'See {operators} below' }], ctx);
+    expect(s.body).toBe('See {operators} below');
+  });
+
+  test('the built-in notice has no unfilled placeholders', () => {
+    const rendered = notice.renderSections(notice.defaultSections(), ctx);
+    for (const s of rendered) expect(s.body).not.toMatch(/\{\w+\}/);
+    expect(rendered.find(s => s.id === 'sharing').body).toContain('• PayFast (South Africa)');
+  });
+});
+
+describe('cleanSections', () => {
+  test('trims, makes ids from titles and keeps them unique', () => {
+    const out = notice.cleanSections([
+      { title: ' 1. Introduction ', body: 'Hi\r\nthere ' },
+      { title: 'Introduction', body: '' },
+    ]);
+    expect(out).toEqual([
+      { id: 'introduction', title: '1. Introduction', body: 'Hi\nthere' },
+      { id: 'introduction-2', title: 'Introduction', body: '' },
+    ]);
+  });
+
+  test('refuses an empty notice or a section without a title', () => {
+    expect(() => notice.cleanSections([])).toThrow(/at least one section/);
+    expect(() => notice.cleanSections([{ title: '  ', body: 'x' }])).toThrow(/needs a title/);
+  });
+});
+
+describe('noticePromptPending', () => {
+  test('nobody is asked while no version needs re-acceptance', async () => {
+    prisma.privacyNotice.findFirst.mockResolvedValue(null);
+    expect(await notice.noticePromptPending({ noticeVersionAccepted: null })).toBe(false);
+  });
+
+  test('asked when they accepted an older version than the newest one that needs it', async () => {
+    prisma.privacyNotice.findFirst.mockResolvedValue({ version: 3 });
+    expect(await notice.noticePromptPending({ noticeVersionAccepted: 2 })).toBe(true);
+    expect(await notice.noticePromptPending({ noticeVersionAccepted: null })).toBe(true);
+    expect(await notice.noticePromptPending({ noticeVersionAccepted: 3 })).toBe(false);
+    expect(await notice.noticePromptPending({ noticeVersionAccepted: 5 })).toBe(false);
+    expect(prisma.privacyNotice.findFirst.mock.calls[0][0].where).toEqual({ requiresAcceptance: true });
+  });
+});
+
+describe('publicNotice', () => {
+  beforeEach(() => prisma.operator.findMany.mockResolvedValue([]));
+
+  test('the built-in notice is version 0 while nothing is published', async () => {
+    prisma.privacyNotice.findMany.mockResolvedValue([]);
+    const n = await notice.publicNotice(null);
+    expect(n.version).toBe(0);
+    expect(n.builtIn).toBe(true);
+    expect(n.sections.length).toBeGreaterThan(10);
+  });
+
+  test('once published, version 0 is no longer available as a past version', async () => {
+    prisma.privacyNotice.findMany.mockResolvedValue([{ version: 1, publishedAt: new Date() }]);
+    expect(await notice.publicNotice(0)).toBeNull();
+  });
+
+  test('a published version, marked current only when it is the newest', async () => {
+    prisma.privacyNotice.findMany.mockResolvedValue([{ version: 2 }, { version: 1 }]);
+    prisma.privacyNotice.findUnique.mockResolvedValue({ version: 1, publishedAt: new Date('2026-10-01T10:00:00Z'), changeSummary: 'x', sections: [{ id: 'a', title: 'A', body: 'Hello' }] });
+    const n = await notice.publicNotice(1);
+    expect(n).toMatchObject({ version: 1, builtIn: false, current: false, changeSummary: 'x' });
+    expect(n.sections[0].body).toBe('Hello');
+  });
+});
+
+describe('reportRowCount', () => {
+  test('counts table rows, layered items and extra tables', () => {
+    expect(reportRowCount({ table: { rows: [[1], [2]] }, extraTables: [{ rows: [[1]] }] })).toBe(3);
+    expect(reportRowCount({ layered: { sections: [{ items: ['a', 'b'] }, { items: ['c'] }] } })).toBe(3);
+    expect(reportRowCount(null)).toBe(0);
+  });
+});

backend/tests/retention.test.js

@@ -0,0 +1,85 @@
+jest.mock('../src/config/db', () => ({
+  appSetting: { findUnique: jest.fn(), upsert: jest.fn(), findMany: jest.fn().mockResolvedValue([]) },
+  $queryRawUnsafe: jest.fn(),
+}));
+
+const prisma = require('../src/config/db');
+const retention = require('../src/utils/retention');
+
+function saved(value) {
+  prisma.appSetting.findUnique.mockResolvedValue(value === undefined ? null : { value: JSON.stringify(value) });
+}
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('policies', () => {
+  test('defaults: inactive accounts after 5 years, on', async () => {
+    saved(undefined);
+    const { policies, reviewedAt } = await retention.getPolicies();
+    expect(policies.inactive_accounts).toEqual({ enabled: true, months: 60 });
+    expect(policies.form_answers).toEqual({ enabled: true, months: 12 });
+    expect(reviewedAt).toBeNull();
+  });
+
+  test('saved values override the defaults, one policy at a time', async () => {
+    saved({ policies: { form_answers: { enabled: false, months: 6 } }, reviewedAt: '2026-10-23T00:00:00.000Z' });
+    const { policies, reviewedAt } = await retention.getPolicies();
+    expect(policies.form_answers).toEqual({ enabled: false, months: 6 });
+    expect(policies.login_history).toEqual({ enabled: true, months: 24 });
+    expect(reviewedAt).toBe('2026-10-23T00:00:00.000Z');
+  });
+
+  test('saving refuses periods below the minimum or silly ones', async () => {
+    const ok = Object.fromEntries(Object.entries(retention.POLICIES).map(([k, d]) => [k, { ...d.defaults }]));
+    await expect(retention.savePolicies({ ...ok, inactive_accounts: { enabled: true, months: 6 } })).rejects.toThrow(/Inactive accounts: choose between 12 and 240/);
+    await expect(retention.savePolicies({ ...ok, form_answers: { enabled: true, months: 'x' } })).rejects.toThrow(/Attendee form answers/);
+    saved(undefined);
+    await retention.savePolicies(ok, { reviewedBy: 'Ada' });
+    const value = JSON.parse(prisma.appSetting.upsert.mock.calls[0][0].create.value);
+    expect(value.reviewedBy).toBe('Ada');
+    expect(value.policies.audit_logs).toEqual({ enabled: true, months: 60 });
+  });
+});
+
+describe('describing periods', () => {
+  test('whole years read as years', () => {
+    expect(retention.describeMonths(60)).toBe('5 years');
+    expect(retention.describeMonths(12)).toBe('1 year');
+    expect(retention.describeMonths(18)).toBe('18 months');
+    expect(retention.describeMonths(1)).toBe('1 month');
+  });
+
+  test('monthsAgo goes back calendar months', () => {
+    expect(retention.monthsAgo(24, new Date('2026-10-23T12:00:00Z')).toISOString()).toBe('2024-10-23T12:00:00.000Z');
+  });
+
+  test('the notice lines follow the policies, and say so when one is off', async () => {
+    saved({ policies: { inactive_accounts: { enabled: false, months: 60 }, form_answers: { enabled: true, months: 24 } } });
+    const lines = await retention.noticeLines();
+    expect(lines[0]).toBe('• Accounts are kept until you ask us to delete them.');
+    expect(lines[1]).toBe('• Answers to event forms are deleted 2 years after the event.');
+    expect(lines.every(l => l.startsWith('• '))).toBe(true);
+  });
+});
+
+describe('inactive accounts query', () => {
+  test('not-yet-warned: a warning older than the last activity no longer counts', async () => {
+    prisma.$queryRawUnsafe.mockResolvedValue([{ id: 'u1' }]);
+    const before = new Date('2021-10-23');
+    expect(await retention.inactiveAccounts(before, { warned: false, limit: 10 })).toEqual(['u1']);
+    const [sql, ...params] = prisma.$queryRawUnsafe.mock.calls[0];
+    expect(sql).toMatch(/warned_at IS NULL OR warned_at < last_active/);
+    expect(sql).toMatch(/u\."role" = 'user'/);
+    expect(params).toEqual([before]);
+  });
+
+  test('due for deletion: warned since the last activity, long enough ago', async () => {
+    prisma.$queryRawUnsafe.mockResolvedValue([]);
+    const before = new Date('2021-10-23');
+    const warnedBefore = new Date('2026-09-23');
+    await retention.inactiveAccounts(before, { warnedBefore });
+    const [sql, ...params] = prisma.$queryRawUnsafe.mock.calls[0];
+    expect(sql).toMatch(/warned_at >= last_active AND warned_at <= \$2/);
+    expect(params).toEqual([before, warnedBefore]);
+  });
+});

backend/tests/sessions.test.js

@@ -19,6 +19,10 @@ const {
   ticketScanSession,
   groupTickets,
   wholeCourseClosesAt,
+  choosesSessions,
+  lineSessions,
+  mergeSessionIds,
+  ticketDateText,
 } = require('../src/utils/sessions');
 
 // Africa/Johannesburg is UTC+2 all year, so 16:30Z is 18:30 local.
@@ -281,28 +285,59 @@ describe('pick sessions', () => {
     eventOptions: [{ id: 'drop', name: 'Drop-in', sessionMode: 'pick' }, { id: 'full', name: 'Full course', sessionMode: 'all' }],
   };
 
+  test('choosesSessions: pick-mode multi-day events only', () => {
+    expect(choosesSessions(pickEvent)).toBe(true);
+    expect(choosesSessions({ ...pickEvent, attendanceMode: 'whole' })).toBe(false);
+    expect(choosesSessions({ ...pickEvent, scheduleType: 'single' })).toBe(false);
+  });
+
+  test('lineSessions / mergeSessionIds', () => {
+    expect(lineSessions({ sessionId: 's2', sessionIds: [] })).toEqual(['s2']);
+    expect(lineSessions({ sessionId: null, sessionIds: ['s1', 's3'] })).toEqual(['s1', 's3']);
+    expect(lineSessions({ sessionId: null, sessionIds: [] })).toBeNull();
+    expect(mergeSessionIds(['s1'], ['s3', 's1'])).toEqual(['s1', 's3']);
+    expect(mergeSessionIds(['s1'], [])).toEqual([]);
+  });
+
+  test('an all-sessions ticket with sessions ticked only scans on those', () => {
+    const ev = { checkInWindow: 'whole_day' };
+    const onDay2 = new Date(wed(11).getTime() + 30 * 60000);
+    expect(ticketScanSession(ev, COURSE, null, null, onDay2, ['s2', 's4']).session.id).toBe('s2');
+    expect(ticketScanSession(ev, COURSE, null, null, onDay2, ['s1', 's4']).error).toMatch(/isn't booked for Session 2/);
+    expect(ticketScanSession(ev, COURSE, null, null, onDay2, []).session.id).toBe('s2');
+  });
+
+  test('ticket dates list the ticked sessions', () => {
+    const ev = { ...pickEvent, sessions: COURSE };
+    expect(ticketDateText(ev, 'short', null, null, ['s2', 's4'])).toBe('2 sessions · 11 Nov, 25 Nov');
+    expect(ticketDateText(ev, 'long', null, null, ['s2'])).toBe('Wednesday, 11 November 2026 (Session 2)');
+  });
+
   test('isPickOption needs a pick-mode multi-day event and a pick option', () => {
     expect(isPickOption(pickEvent, pickEvent.eventOptions[0])).toBe(true);
     expect(isPickOption(pickEvent, pickEvent.eventOptions[1])).toBe(false);
     expect(isPickOption({ ...pickEvent, attendanceMode: 'whole' }, pickEvent.eventOptions[0])).toBe(false);
   });
 
-  test('a pick line becomes one line per session; others stay as they are', () => {
+  test('a pick line becomes one line per session; an all-sessions line keeps its ticked sessions', () => {
     const out = expandPickLines(pickEvent, [
       { eventOptionId: 'drop', quantity: 2, sessionIds: ['s3', 's4', 's3'] },
       { eventOptionId: 'full', quantity: 1 },
+      { eventOptionId: 'full', quantity: 1, sessionIds: ['s2', 's5'] },
     ], { now: wed(5) });
     expect(out).toEqual([
       { eventOptionId: 'drop', quantity: 2, sessionId: 's3' },
       { eventOptionId: 'drop', quantity: 2, sessionId: 's4' },
-      { eventOptionId: 'full', quantity: 1, sessionId: null },
+      { eventOptionId: 'full', quantity: 1, sessionId: null, sessionIds: [] },
+      { eventOptionId: 'full', quantity: 1, sessionId: null, sessionIds: ['s2', 's5'] },
     ]);
   });
 
-  test('sessions must be chosen, upcoming, and not on whole-course tickets', () => {
+  test('sessions must be chosen, upcoming, and only on events where people choose them', () => {
     expect(() => expandPickLines(pickEvent, [{ eventOptionId: 'drop', quantity: 1 }])).toThrow(/Choose the sessions/);
     expect(() => expandPickLines(pickEvent, [{ eventOptionId: 'drop', quantity: 1, sessionIds: ['s1'] }], { now: wed(5) })).toThrow(/already started/);
-    expect(() => expandPickLines(pickEvent, [{ eventOptionId: 'full', quantity: 1, sessionIds: ['s3'] }])).toThrow(/covers every session/);
+    expect(() => expandPickLines(pickEvent, [{ eventOptionId: 'full', quantity: 1, sessionIds: ['s1'] }], { now: wed(5) })).toThrow(/already started/);
+    expect(() => expandPickLines({ ...pickEvent, attendanceMode: 'whole' }, [{ eventOptionId: 'full', quantity: 1, sessionIds: ['s3'] }])).toThrow(/covers every session/);
     expect(() => expandPickLines({ ...pickEvent, requiresParentalConsent: true }, [{ eventOptionId: 'drop', quantity: 1, sessionIds: ['s3'] }], { now: wed(5) })).toThrow(/youth/);
   });
 

backend/tests/waitlist.test.js

@@ -29,3 +29,63 @@ describe('pickOffers', () => {
     expect(pickOffers(q(3, 4), 2, false)).toEqual([]);
   });
 });
+
+const { lineOpen, offerExpiry, lineName } = require('../src/utils/waitlist');
+const { sessionPlacesFree } = require('../src/utils/sessions');
+
+const at = (h) => new Date(Date.UTC(2026, 10, 4, h));
+const sessions = [
+  { id: 's1', startsAt: at(8), endsAt: at(9), capacity: 10, cancelledAt: null },
+  { id: 's2', startsAt: at(10), endsAt: at(11), capacity: 4, cancelledAt: null },
+  { id: 's3', startsAt: at(12), endsAt: at(13), capacity: null, cancelledAt: null },
+  { id: 's4', startsAt: at(14), endsAt: at(15), capacity: 1, cancelledAt: at(1) },
+];
+
+describe('sessionPlacesFree', () => {
+  const booked = new Map([['s1', 7], ['s2', 4], ['s3', 50]]);
+  test('a picked session: its own capacity', () => {
+    expect(sessionPlacesFree(sessions, booked, 's1')).toBe(3);
+    expect(sessionPlacesFree(sessions, booked, 's2')).toBe(0);
+  });
+  test('a session without a capacity is unlimited', () => {
+    expect(sessionPlacesFree(sessions, booked, 's3')).toBeNull();
+  });
+  test('whole-course: the fullest limited session, cancelled ones ignored', () => {
+    expect(sessionPlacesFree(sessions, booked, null)).toBe(0);
+    expect(sessionPlacesFree(sessions, new Map([['s1', 2], ['s2', 1]]), null)).toBe(3);
+  });
+});
+
+describe('lineOpen', () => {
+  const event = { scheduleType: 'sessions', attendanceMode: 'pick', endDate: at(13), sessions };
+  test('a session can be offered until it starts', () => {
+    expect(lineOpen(event, 's2', at(9))).toBe(true);
+    expect(lineOpen(event, 's2', at(10))).toBe(false);
+  });
+  test('cancelled or unknown sessions are not offered', () => {
+    expect(lineOpen(event, 's4', at(1))).toBe(false);
+    expect(lineOpen(event, 'nope', at(1))).toBe(false);
+  });
+  test('whole-course lines close when the course does', () => {
+    expect(lineOpen(event, null, at(7))).toBe(true);
+    expect(lineOpen(event, null, at(8))).toBe(false);
+    expect(lineOpen({ scheduleType: 'single' }, null, at(20))).toBe(true);
+  });
+});
+
+describe('offerExpiry', () => {
+  test('the offer hours, but never after the session starts', () => {
+    expect(offerExpiry(24, null, at(0))).toEqual(new Date(at(0).getTime() + 24 * 3600 * 1000));
+    expect(offerExpiry(24, sessions[1], at(0))).toEqual(at(10));
+    expect(offerExpiry(2, sessions[1], at(0))).toEqual(at(2));
+  });
+});
+
+describe('lineName', () => {
+  test('names the session for picked lines', () => {
+    expect(lineName({ eventOption: { name: 'Drop-in' }, variant: null, session: null })).toBe('Drop-in');
+    expect(lineName({ eventOption: { name: 'Drop-in' }, variant: { name: 'Adult' }, session: { ...sessions[1], label: 'Class 2' } }, sessions))
+      .toBe('Drop-in (Adult) — Class 2, Wed 4 Nov');
+    expect(lineName({ eventOption: { name: 'Drop-in' }, session: sessions[1] }, sessions)).toBe('Drop-in — Session 2, Wed 4 Nov');
+  });
+});

docs/HANDOVER.md

@@ -1,6 +1,6 @@
 # Handover — where things stand and how to carry on
 
-Last updated: 2026-10-23, after **1.35.0**. The plan itself is in
+Last updated: 2026-10-23, after **1.40.0**. The plan itself is in
 [ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of
 features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 
@@ -8,24 +8,24 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 
 | Version | What |
 |---------|------|
+| 1.40.0 | POPIA toolkit part 3 — readiness checklist with score, retention policies + nightly `retention` job (inactive accounts anonymised after 5 years with a 30-day warning, on by default), breach register with notification drafts, children's/medical flag in the access log, `{retention}` in the notice |
+| 1.39.0 | POPIA toolkit part 2 — Admin → Privacy: privacy notice editor (built-in text as the start, placeholders, drafts, numbered versions, re-acceptance after login), operator register, consent log, access log; Information Officer on the contact page |
+| 1.38.0 | POPIA toolkit part 1 — Privacy page (news opt-in + history, download my data, correction and deletion requests), Event update vs News & announcements on every bulk send, unsubscribe links + one-click headers, WhatsApp STOP, one-time news question, Admin → Data requests, thorough anonymising |
 | 1.32.0 | Early-bird ribbon on event cards |
 | 1.33.0 | Multi-day events phase A — sessions, late joining + late pricing, per-session check-in, attendance register, session reminders, certificates (4 templates, verify page) |
 | 1.34.0 | Background jobs on pg-boss (admin Background jobs page), Playwright e2e tests, Gitea CI workflow, `scripts/deploy.sh` |
 | 1.35.0 | Multi-day events phase B — "pick sessions" (per-session tickets and prices, session capacity) |
+| 1.37.4 | Deploy script: no tag = latest main; per-install `ecosystem.config.js` out of git (`ecosystem.config.example.js`) |
+| 1.37.3 | Fix: the production build failed on unescaped quotes in a help text |
+| 1.37.2 | Payment status checks (PayFast transaction history; job every 15 min; Payments → Reconcile → Waiting for payment), PayFast Test connection |
+| 1.37.1 | "Pay online" hidden when no provider is on or under R15; SnapScan/Zapper dropped from the roadmap |
+| 1.37.0 | PayFast (signed form, ITN checks), `ProviderCheckout` with amount checks, the "Pay online" page (`/pay/<id>`) where payers choose a provider |
+| 1.36.0 | Payment provider interface (`backend/src/payments`) with Yoco behind it, `ProviderTransaction`, `Payment.provider`, Site settings → Payments (on/off and order per provider), R15 minimum |
+| 1.35.1 | Waitlist per session, session picker at the door, "All sessions" tickets let people tick sessions at one price; fixes (per-session stock limits, offline service worker serving stale scripts) |
 
 ## Next up
 
-1. **1.36.0 — payment provider interface.** Move Yoco behind a `PaymentProvider`
-   interface (`createCheckout`, `handleWebhook`, `getTransaction`, `refund`,
-   `listTransactions`) with no behaviour change; generalise `YocoTransaction` to a
-   provider transaction table; Site settings → Payments with an Enabled toggle per
-   provider and display order. Decisions: fees are **never** deducted or passed on
-   (people handle fees at cashup); minimum online payment **R15** for all providers.
-2. **1.37.0 PayFast → 1.38.0 SnapScan → 1.39.0 Zapper** (one release each). Get the
-   current API documentation links from Joshua before building each one, and don't
-   guess at an API — sandbox/test credentials needed for SnapScan and Zapper.
-3. **1.40.0–1.41.0 — POPIA toolkit** (spec §3 in the roadmap).
-4. **1.42.0 + Hub v1** — install/update tooling and the Hope Events Hub (separate repo
+1. **1.41.0 + Hub v1** — install/update tooling and the Hope Events Hub (separate repo
    `joshua/hope-events-hub`).
 
 ## Working on this repo
@@ -35,6 +35,7 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
   `## [X.Y.Z] - date` heading under `[Unreleased]` in CHANGELOG.md → `git merge --no-ff`
   into `main` → `git tag vX.Y.Z` → `git push origin main <branch> vX.Y.Z`. One minor
   version per feature.
+- **Before tagging:** run `npx eslint src` in `frontend` over the **whole** app (the deploy runs `next build`, which fails on any lint error, e.g. an unescaped ' or " in JSX text). If a dev server is running, a full check build needs its own folder: `NEXT_DIST_DIR=.next-buildcheck npx next build` (then delete it and `git checkout frontend/tsconfig.json`).
 - **Changelog:** add entries to `[Unreleased]` as you go, in plain language.
 - **Docs to keep in step:** CHANGELOG.md, FEATURES.md, README.md, SETTINGS.md,
   backend/API_DOCUMENTATION.md, the `/docs` route list in `backend/src/index.js`, and
@@ -46,12 +47,23 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
   need a migration.
 - **Server Node version:** the deployment notes install Node 20, so dependencies must
   support Node 20 (that's why pg-boss is pinned to 10.x).
+- **Deploying:** `bash scripts/deploy.sh [tag]` on the server (no tag = latest main). Each install
+  keeps its own `ecosystem.config.js` (PM2 app names, port), which is not in git. The script
+  runs from a temp copy of itself and rolls back on failure before the PM2 reload. It was
+  tested by running it against a throwaway clone with npm/pm2 stubbed: across the tracked →
+  untracked change for the PM2 file, deploying main, failed builds and a bad tag.
 - **Pushing:** pushing from some shells fails with "Failed to authenticate user" (a stale
   saved credential); pushing from your own terminal works.
 
 ## Tests
 
 - Backend unit tests: `cd backend && npm test` (Jest).
+- PayFast e2e (`e2e/payfast.spec.ts`) pays into a real PayFast sandbox account and is skipped
+  unless `E2E_PAYFAST_MERCHANT_ID`, `E2E_PAYFAST_MERCHANT_KEY` and `E2E_PAYFAST_PASSPHRASE` are
+  set (from the Sandbox dashboard). PayFast's documented public test merchant (10000100) no
+  longer accepts payments. ITNs can't reach localhost; they're covered by unit tests
+  (`backend/tests/payments.test.js`) — to try one for real, use a tunnel, a public
+  `BACKEND_URL` and `PAYFAST_SKIP_IP_CHECK=true`.
 - End-to-end: `npm run test:e2e` from the repo root (first time: `npm install` and
   `npx playwright install chromium`). They start their own backend (5100) and
   frontend (3100) against `<your DATABASE_URL database>_e2e`, which is dropped and
@@ -81,10 +93,78 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 - Frontend: `src/lib/sessions.ts`, `src/components/events/ScheduleEditor.tsx`,
   `SessionPicker.tsx`, `SessionSchedule.tsx`, `src/app/dashboard/supervisor/attendance/`.
 
+## Where the payment code lives
+
+- `backend/src/payments/index.js` — the provider registry and the `PaymentProvider` interface
+  (documented at the top), provider on/off and order (AppSetting `payment_providers`), the R15
+  minimum, and `createCheckout`. Tests: `backend/tests/payments.test.js`.
+- `backend/src/payments/providers/yoco.js` — Yoco: checkouts, webhook signature check, webhook
+  parsing. Keys/webhook admin stays in `utils/yoco.js` + `controllers/yocoController.js`.
+- `backend/src/payments/webhook.js` — shared webhook processing (Payment with `provider`,
+  donation split, registration status, tickets, emails, `ProviderTransaction`).
+- `backend/src/payments/checkouts.js` — registration checkouts (balance, part, + donation).
+- `backend/src/payments/status.js` — status checks for notifications that never arrived
+  (`payment-status` job, Payments → Reconcile → "Waiting for payment"). PayFast looks payments
+  up in its transaction history (`findPayments`); Yoco's Checkout API documents no lookup, so
+  Yoco checkouts are "can't check". Tests: `backend/tests/paymentStatus.test.js`.
+- **Adding a provider:** write `providers/<id>.js` with the same interface, add it to
+  `PROVIDERS` in `index.js`, mount `handleProviderWebhook('<id>')` at `/api/webhooks/<id>`
+  (`routes/webhookRoutes.js`), and give it a settings card in
+  `frontend/src/components/admin/PaymentsTab.tsx`. New providers start switched off.
+- `Payment.method` stays the wallet type (card, apple_pay…) because cashups bucket on it;
+  the provider is `Payment.provider`.
+
+## Where the privacy (POPIA) code lives
+
+- `backend/src/utils/privacy.js` — news opt-in (`setNewsPreferences`, logged in
+  `CommunicationConsent`), unsubscribe tokens (HMAC with `JWT_SECRET`, never expire),
+  `filterRecipients` (every bulk send goes through it: `kind` 'update' passes, 'news' only to
+  opted-in accounts and not to `MessagingOptOut` addresses), email/WhatsApp footers, STOP
+  handling, data requests, `deletionBlockers`, `anonymiseUser`, `exportUserData` + PDF.
+  Tests: `backend/tests/privacy.test.js`; e2e: `e2e/privacy.spec.ts`.
+- `controllers/privacyController.js` + `routes/privacyRoutes.js` (`/api/privacy`).
+- Bulk sends: `broadcastController`, `whatsappBroadcastController`, and `emailEventAttendees` /
+  `whatsappEventAttendees` in `eventController` take `kind`; scheduled payloads carry it.
+- WhatsApp STOP: `handleIncomingMessage` in `whatsappController.js` (WAWP `message` event on
+  `/api/whatsapp/webhook?secret=…`; secret in AppSetting `WAWP_WEBHOOK_SECRET`).
+- Frontend: `app/dashboard/user/privacy`, `app/unsubscribe`, `app/dashboard/admin/data-requests`,
+  `components/shared/NewsPrompt.tsx` (dashboard layout), `MessageKindPicker.tsx`.
+- **Anything new that stores personal data** must be added to `anonymiseUser` and
+  `exportUserData`.
+- Privacy notice: `utils/privacyNotice.js` (built-in sections, placeholders, versions, draft in
+  AppSetting `privacy_notice_draft`, `noticePromptPending`); public page `app/legal/privacy`
+  (renders whatever `/api/privacy/notice` returns), admin `app/dashboard/admin/privacy` +
+  `components/admin/privacy/*`, prompt `components/shared/NoticePrompt.tsx` (via
+  `PrivacyPrompts.tsx`: notice first, then the news question). **Changing the built-in text
+  changes the live notice only for installs that haven't published a version yet.**
+- Access log: `utils/accessLog.js` (`logDataAccess(req, { action, what, eventId, records })`).
+  **Any new bulk export or list of personal data should call it** and get a label in
+  `ACCESS_ACTIONS`. Operators: `Operator` table, seeded in the 1.39.0 migration.
+- Retention: `utils/retention.js` (policies in AppSetting `retention_policies`, `runRetention`,
+  `preview`, `noticeLines` for `{retention}`), job `retention` (03:30). **Anything new that
+  stores personal data should get a retention rule** (a new entry in `POLICIES` + runner).
+  Inactive = latest of `User.createdAt`, `lastLoginAt` (set on login), registrations/event end,
+  attendee rows, payments. Readiness: `utils/readiness.js`. Breaches: `SecurityBreach`.
+  Admin panels: `components/admin/privacy/{Readiness,Retention,Breaches}Panel.tsx`.
+- e2e: `privacy-retention.spec.ts` runs the retention job on seeded six-year-old accounts
+  (`prepare-db.js` → `retention`); `privacy-notice.spec.ts` publishes a version that needs accepting, then accepts it for all
+  seeded users in `afterAll` so later spec files don't meet the prompt.
+
 ## Known gaps / follow-ups
 
-- The at-the-door booking pop-up doesn't have the session picker; per-session tickets
-  are booked from Manual registration (the page says so).
-- The waitlist works per ticket option, not per session.
+- WhatsApp STOP only works once someone pastes the webhook URL from Site settings → WhatsApp
+  into WAWP (events `message` + `session.status`), and only for senders WhatsApp identifies by
+  phone number — a sender known only by a "LID" is logged and ignored (they can still use the
+  link in the message).
+- `/api/webhooks/whatsapp` (`webhookController.handleWhatsappWebhook`) is an old empty stub; the
+  real WAWP webhook is `/api/whatsapp/webhook`. Remove the stub in a later release.
+- There's no log of individual messages sent, so "Download my data" can't include "messages
+  sent to you" yet.
+- The audit-log page's action filter list was already missing newer actions before 1.38.0
+  (only the three privacy ones were added).
+
+- At the door, per-session tickets are booked on new registrations only; editing an
+  existing registration leaves its booked sessions as they are (the backend refuses
+  changes to picked lines). "Add & charge" for a session at the scanner isn't built.
 - Ticket scanning by camera isn't covered by the e2e tests (headless browsers have no
   camera); scans are tested through the API.

docs/ROADMAP-v2.md

@@ -8,15 +8,21 @@ previous round (1.12.0 – 1.23.0). Where to pick up: [HANDOVER.md](./HANDOVER.m
 
 **Theme for 2.0:** turn a feature-rich church app into a product that can be
 sold — trustworthy (POPIA), flexible (multi-day events, several payment
-providers), and maintainable (tests, CI, typed backend, versioned API).
+providers), maintainable (tests, CI, typed backend, versioned API), and with
+**AI helpers** as the headline feature (§15).
 
 **Status (2026-10-23):** all features in this document are approved. Shipped
 so far: 1.32.0 early-bird ribbon on event cards; 1.33.0 multi-day events
 phase A (sessions, late joining, per-session check-in, attendance register,
 reminders, certificates); 1.34.0 job queue (pg-boss), Playwright E2E tests, Gitea CI
 workflow (waiting for a runner) and deploy script; 1.35.0 multi-day events phase B
-(pick sessions, per-session capacity). **Next: 1.36.0 payment provider interface (Yoco
-moved behind it), then PayFast, SnapScan, Zapper.**
+(pick sessions, per-session capacity), with 1.35.1 adding the per-session waitlist, the session
+picker at the door and session choice on "All sessions" tickets; 1.36.0 payment provider interface
+(Yoco moved behind it, Site settings → Payments); 1.37.0 PayFast and the "Pay online" page;
+1.37.1 "Pay online" hidden when it can't be used; 1.37.2 payment status checks for missing
+notifications. SnapScan and Zapper are dropped — Yoco and PayFast are enough (2026-10-23);
+1.38.0 POPIA toolkit part 1 (privacy page, unsubscribe, WhatsApp STOP, data requests); 1.39.0 part 2 (privacy notice editor and versions, operator register, consent and access logs); 1.40.0 part 3 (retention policies and job, breach register, children’s-data flags, readiness page).
+**Next: 1.41.0 install/update tooling + the Hope Events Hub (§13).**
 
 **Repositories:**
 
@@ -30,7 +36,7 @@ moved behind it), then PayFast, SnapScan, Zapper.**
 ## Contents
 
 1. [Multi-day events (sessions)](#1-multi-day-events-sessions) ← **first**
-2. [Payment providers: PayFast, SnapScan, Zapper](#2-payment-providers-payfast-snapscan-zapper)
+2. [Payment providers: PayFast](#2-payment-providers-payfast)
 3. [POPIA toolkit](#3-popia-toolkit)
 4. [Kids check-in with security labels](#4-kids-check-in-with-security-labels)
 5. [Volunteer / serving rosters](#5-volunteer--serving-rosters)
@@ -43,8 +49,10 @@ moved behind it), then PayFast, SnapScan, Zapper.**
 12. [Multi-campus (one install per church)](#12-multi-campus-one-install-per-church)
 13. [Central management platform (Hope Events Hub)](#13-central-management-platform-hope-events-hub)
 14. [Foundations (platform work)](#14-foundations-platform-work)
-15. [Suggested build order](#suggested-build-order)
-16. [Decisions](#decisions-2026-10-22)
+15. [AI helpers (2.0 headline)](#15-ai-helpers-20-headline)
+16. [AI: later stages](#16-ai-later-stages)
+17. [Suggested build order](#suggested-build-order)
+18. [Decisions](#decisions-2026-10-22)
 
 ---
 
@@ -265,11 +273,12 @@ it's not used for check-in decisions; "checked in" is per session
 
 ---
 
-## 2. Payment providers: PayFast, SnapScan, Zapper
+## 2. Payment providers: PayFast
 
-Today Yoco is the only online provider. Add **PayFast**, **SnapScan** and
-**Zapper**, and let the admin **enable one or more** in Site settings. At
-checkout the user picks from the enabled ones.
+Add **PayFast** next to Yoco, and let the admin **enable one or both** in Site
+settings. At checkout the user picks from the enabled ones. (Shipped in
+1.36.0–1.37.2. SnapScan and Zapper were planned too, but dropped on 2026-10-23:
+two providers are enough.)
 
 **Who:** Admins configure providers. Users choose at payment. Supervisors
 reconcile.
@@ -278,10 +287,10 @@ reconcile.
 
 | Setting | Options |
 |---------|---------|
-| Providers | Yoco · PayFast · SnapScan · Zapper — each with an **Enabled** toggle |
+| Providers | Yoco · PayFast — each with an **Enabled** toggle |
 | Credentials | Per provider (merchant id/key, API key, passphrase, webhook secret…), stored encrypted (`utils/encryption.js`, same as WhatsApp) |
 | Mode | Live / Sandbox per provider (where supported) |
-| Display order / default | Which one is shown first. Default order: Yoco · PayFast · SnapScan · Zapper |
+| Display order / default | Which one is shown first. Default order: Yoco · PayFast |
 | Minimum amount | **R15 for all providers** (one site-wide minimum for online payments) |
 
 **Fees are not handled automatically.** Payments are recorded at the full
@@ -298,10 +307,7 @@ total. Fees are dealt with by people during **cashup**, as today. There is no
   `getTransaction`, `refund` (if the provider supports it via API),
   `listTransactions` (for reconciliation).
 - Yoco is moved behind the same interface first (no behaviour change), then
-  PayFast, SnapScan and Zapper are added one release each.
-- SnapScan and Zapper are QR/app-based: on desktop show the QR, on mobile
-  deep-link into the app; the page polls/waits for the webhook and moves on
-  automatically when payment lands.
+  PayFast is added.
 - `Payment.method` gets the provider name; `YocoTransaction` is generalised to
   `ProviderTransaction` (`provider` column) so the existing reconciliation page
   works for all providers.
@@ -604,8 +610,10 @@ whether they're healthy, basic usage stats, and their **licence** status.
   repos (`docs/hub-protocol.md`). The Hub accepts the current and previous
   protocol version, so churches on older versions keep reporting while they
   wait to update.
-- Runs on its own server/domain (e.g. `hub.<your-domain>`). If the Hub is
+- Runs on its own server at **`events-hub.crosscode.co.za`**. If the Hub is
   down, **no church install is affected**.
+- **Licence keys are generated by the Hub:** Joshua clicks "Generate" on a
+  customer and the Hub creates the key (not typed by hand).
 - Hope Family Church's own site is the first registered install.
 
 ### Registration (setup → Hub)
@@ -632,7 +640,10 @@ All later calls are signed with the install secret (HMAC) and go over HTTPS.
   - **Basic stats (aggregate counts only):** users, active/upcoming events,
     registrations and tickets (30 days / all time), check-ins, WhatsApp/email
     sent, enabled payment providers, campuses on/off.
-  - **Optional (off by default, customer chooses):** payment totals.
+  - **Income in ranges, never exact amounts:** total payments received (30
+    days / all time) reported as a band — R0–R1 000, R1 001–R5 000,
+    R5 001–R20 000, R20 001–R50 000, R50 001–R100 000, over R100 000. The
+    band is worked out on the install; the exact figure never leaves it.
 - **Install → Hub only.** The install pushes; the Hub never needs to reach
   into the install, so it works behind firewalls and the Hub has no access
   to church data.
@@ -670,8 +681,9 @@ All later calls are signed with the install secret (HMAC) and go over HTTPS.
 - **Never a hard kill:** a church must always be able to scan tickets for
   events people already paid for, and get its own data out (POPIA access
   rights). Suspension blocks *new* activity only.
-- Optional plan limits later (e.g. number of campuses, WhatsApp) carried in
-  the token.
+- **One plan for now.** Plan limits (e.g. number of campuses, WhatsApp) can
+  be carried in the token later. The first per-licence limit comes with 2.0: the
+  **monthly AI cap in rand** (§15), kept and enforced on the Hub, since the Hub meters AI.
 
 ### Things to be aware of
 
@@ -695,6 +707,8 @@ model Install  { id, customerId, licenceId, name, url, secretHash, version,
 model Heartbeat { id, installId, receivedAt, version, health Json, stats Json }
                  // rolled up to daily after 30 days
 model InstallEvent { id, installId, type, message, createdAt } // alerts, version changes
+// 2.0, AI (§15): Licence gets aiMonthlyCapCents; usage per call, no prompt/response text
+model AiUsage   { id, installId, helper, model, inputTokens, outputTokens, costCents, createdAt }
 ```
 
 ---
@@ -716,6 +730,134 @@ keep adding to.
 
 ---
 
+## 15. AI helpers (2.0 headline)
+
+Small, one-button AI helpers in the places people already work. **No chat** in 2.0:
+each helper is one request with a predictable cost, and a person always reviews
+the result before anything is saved or sent.
+
+**Who:** Supervisors and admins (the people who create events and read reports).
+
+### The helpers
+
+| Helper | Where | What it does |
+|--------|-------|--------------|
+| **Draft an event** | Event wizard, first step: "Describe your event" | *"Youth camp 14–16 March at Camp Wartburg, R450, 60 places, kids need consent"* → fills in title, description, dates/sessions, location, ticket options and prices, capacity, consent settings. The supervisor checks every field and saves as usual |
+| **Summarise this report** | Every report (Reports page) | A few plain-language insights under the report: trends, outliers, comparisons with the previous period |
+| **Draft a message** | Email / WhatsApp attendees, broadcasts | Turns a short note (*"remind them to bring a sleeping bag, bus leaves 7:30"*) into a friendly message in the right tone and length (shorter for WhatsApp), with placeholders like `{{name}}` |
+| **Summarise feedback** | Post-event feedback results | Themes, what people liked, what to improve, notable comments |
+| **Improve this text** | Event description, banner, message boxes | Rewrite for clarity, fix spelling, shorten |
+
+Every helper shows **"AI suggestion — check before saving"**, can be undone, and
+never saves, sends or publishes by itself.
+
+### Provider and model
+
+- **One provider: Claude (Anthropic), model Claude Haiku 5.5** — the cheapest
+  current model ($0.10 per million input tokens, $0.50 per million output, for
+  prompts under 100K tokens; prices as of 2026-10). Good enough for drafting and
+  summarising; a helper can move to a bigger model later if quality needs it.
+- **Rough cost:** a helper call is ~2,000–10,000 tokens in and ~500 out, so well under
+  US$0.002 per click — about R1.50–R3 per thousand clicks. Fixed instructions are
+  prompt-cached, which makes repeat calls cheaper still.
+- Structured output (a JSON schema) for "Draft an event", so the reply maps straight
+  onto the event form and is validated before it's shown.
+
+### Key, caps and billing — through the Hub
+
+Joshua provides the API key; churches don't need their own. The key must never sit on
+an install (one leaked install would leak it for everyone), so:
+
+- **Installs call AI through the Hub:** `POST /api/ai/complete` on the Hub, signed with
+  the install secret like the heartbeat. The Hub adds the key, calls Claude, and returns
+  the result. Still **install → Hub only** — the Hub never reaches into an install.
+- **The Hub meters every call** in rand: tokens used × the model's price × an exchange rate
+  Joshua sets in the Hub (with an optional margin). Usage is kept per install per month.
+- **Monthly rand cap per licence**, set by Joshua in the Hub to match what the church pays
+  (e.g. R0 = AI off, R50, R200). The licence's cap is the first per-plan limit. At 80% the
+  install's admins get a warning email; at 100% the helpers are switched off until the next
+  month (or until Joshua raises the cap). Optional per-user daily limit against runaway use.
+- **Admins see their usage** in Site settings → AI: used this month (R and number of uses),
+  the cap, a daily chart, use per helper and per person, and an on/off switch per helper.
+- If the Hub or Claude is unavailable, the buttons say so; nothing else in the app is affected.
+
+### POPIA
+
+- Anthropic is added to the **operator register** (and Joshua's Hub, which relays the
+  requests) and to the privacy notice: processing outside South Africa (POPIA s72),
+  for drafting and summarising only.
+- **Send as little personal information as possible:** reports and feedback are sent as
+  counts, totals and anonymised comments — no names, contact details, medical or
+  children's information. Drafting an event or a message needs none.
+- The Hub stores **no prompt or response text** — only the install, helper, tokens, cost
+  and time. Check Anthropic's commercial terms on retention and training before launch.
+- Uses that include personal information (e.g. feedback comments) go in the access log.
+
+### Plumbing
+
+- Install: `backend/src/ai/` — one client for the Hub's AI endpoint, one prompt + schema
+  per helper, usage shown from the Hub. Feature flag per helper, all off when the licence
+  has no AI or the Hub isn't connected.
+- Hub: the AI proxy, metering, caps, warnings, an exchange-rate setting, and a per-install
+  usage view for Joshua (alongside the existing install detail page).
+- A small **eval set** (example event descriptions, reports, notes, with what a good answer
+  looks like) to check quality when changing the prompt or model.
+- Help content, audit log entries (AI settings changed), CHANGELOG, FEATURES.md, SETTINGS.md.
+
+---
+
+## 16. AI: later stages
+
+Ideas for after 2.0, in rough order. **Not tied to versions** — each is decided when it's
+picked up, and all of them reuse the Hub proxy, metering and caps from §15.
+
+### Ask AI (read-only assistant)
+
+A chat panel for supervisors and admins: *"How many paid for Camp compared with last
+year?"*, *"Which events this month are under half full?"*, *"Who hasn't paid yet for
+Men's Breakfast?"*.
+
+- The AI can only call **tools the app defines** — the existing stats and report queries,
+  "find an event", "registrations by week" — never its own SQL. It runs with the
+  logged-in person's permissions, so it sees nothing they couldn't.
+- Answers show the numbers they're based on and link to the matching report.
+- Costs more per question than a button (several tool calls), so it counts against the same
+  cap; may need a bigger model for harder questions.
+
+### Help and navigation assistant
+
+*"How do I add a coupon?"*, *"Where do I see who checked in?"* → a short answer from the
+in-app help content (`frontend/src/content/help/`) with a link straight to the right page.
+No personal information involved, so it's cheap and simple — could also be offered to
+ordinary users.
+
+### Actions with confirmation
+
+The Ask assistant can also *do* things — create an event draft, schedule a reminder, offer
+waitlist places, record a cash payment — always as **"here's what I'll do → Confirm"**, with
+each confirmed action in the audit log.
+
+### More helpers
+
+Smaller one-button additions as they come up: suggest an event's price tiers from past
+events, write a post-event thank-you, draft certificate wording, translate a message into
+Afrikaans (ties in with §10), flag unusual payments for the cashup.
+
+### Self-hosted AI (long term)
+
+Run an open-weight model on Joshua's own GPU server instead of a paid API, once usage and
+income justify the hardware:
+
+- Because every install already talks to the **Hub's** AI endpoint, moving to self-hosting
+  is a change on the Hub only — the Hub gets a provider adapter (Claude now, self-hosted
+  later, or both: simple helpers self-hosted, harder questions on Claude).
+- **POPIA bonus:** the data can stay in South Africa — no cross-border transfer.
+- **When it makes sense:** compare the monthly API bill with the cost of a GPU server
+  (hardware or cloud rental, power, upkeep), and check the self-hosted model against the
+  eval set from §15 before switching any helper over.
+
+---
+
 ## Suggested build order
 
 | Phase | Version | Features | Why |
@@ -724,15 +866,15 @@ keep adding to.
 | 1 | 1.33.0 ✅ | **Multi-day events — phase A** (sessions, whole-course tickets, late joining + late pricing, per-session check-in with whole-day window, attendance register, optional reminders, certificates) | Requested first; touches registration/tickets/scanning, so it shapes later work |
 | 2 | 1.34.0 ✅ | CI + Playwright E2E + job queue | Safety net before the riskiest work (payments). Session reminders move to the queue |
 | 3 | 1.35.0 ✅ | Multi-day events — phase B (pick sessions, per-session capacity) | Builds on phase A, now with E2E coverage |
-| 4 | 1.36.0 – 1.39.0 | Payment provider interface (Yoco moved behind it) → PayFast → SnapScan → Zapper, one release each | Payment code gets split out of the big controller as part of this |
-| 5 | 1.40.0 – 1.41.0 | **POPIA toolkit** (user privacy centre + unsubscribe first, then admin tools, retention jobs, readiness page) | Main selling point; retention jobs use the job queue |
-| 6 | 1.42.0 + Hub v1 | Install/update scripts, `/health`, licence step in `/setup`, "Connect to Hub", heartbeat, licence states — plus the **Hub** app (separate repo) | Must exist before the first church is sold; Hope Family Church registers as install #1 |
-| 7 | 1.43.0 | **Multi-campus** | Kids rooms and volunteer roles are per campus, so campuses come first |
-| 8 | 1.44.0 – 1.45.0 | Kids check-in, Volunteer rosters | Depend on sessions and campuses |
-| 9 | 1.46.0 – 1.48.0 | Event series & cloning, Wallet passes, Outbound webhooks | Smaller, independent wins |
-| 10 | 1.49.0 – 1.51.0 | Admin dashboard/Ctrl+K/bulk actions, Afrikaans, Accessibility pass | Polish before the big release |
-| 11 | 1.52.0 | TypeScript backend + OpenAPI + `/api/v2` alongside v1 | The breaking-change groundwork |
-| 12 | **2.0.0** | v1 API removed, migration guide, marketing site/docs for selling | The release |
+| 4 | 1.36.0 ✅ – 1.37.2 | Payment provider interface (Yoco moved behind it) → PayFast, then hiding "Pay online" when it can't be used and payment status checks (SnapScan and Zapper dropped) | Payment code gets split out of the big controller as part of this |
+| 5 | 1.38.0 ✅ 1.39.0 ✅ 1.40.0 ✅ | **POPIA toolkit** (1.38.0: user privacy centre, unsubscribe, WhatsApp STOP, data requests inbox; 1.39.0: privacy notice editor + versions, operator register, consent log, access log; 1.40.0: retention jobs, breach register, children’s-data flags, readiness page) | Main selling point; retention jobs use the job queue |
+| 6 | 1.41.0 + Hub v1 | Install/update scripts, `/health`, licence step in `/setup`, "Connect to Hub", heartbeat, licence states — plus the **Hub** app (separate repo) | Must exist before the first church is sold; Hope Family Church registers as install #1 |
+| 7 | 1.42.0 | **Multi-campus** | Kids rooms and volunteer roles are per campus, so campuses come first |
+| 8 | 1.43.0 – 1.44.0 | Kids check-in, Volunteer rosters | Depend on sessions and campuses |
+| 9 | 1.45.0 – 1.47.0 | Event series & cloning, Wallet passes, Outbound webhooks | Smaller, independent wins |
+| 10 | 1.48.0 – 1.50.0 | Admin dashboard/Ctrl+K/bulk actions, Afrikaans, Accessibility pass | Polish before the big release |
+| 11 | 1.51.0 | TypeScript backend + OpenAPI + `/api/v2` alongside v1 | The breaking-change groundwork |
+| 12 | **2.0.0** | **AI helpers** (§15 — headline feature: draft an event, summarise reports and feedback, draft messages, improve text; through the Hub with a rand cap per licence), v1 API removed, migration guide, marketing site/docs for selling | The release. AI needs the Hub (phase 6) for the key, metering and caps |
 
 Each phase should add matching help content (`frontend/src/content/help/`),
 audit log entries, Jest tests, a CHANGELOG entry, and updates to FEATURES.md
@@ -754,21 +896,30 @@ feature.
 | — | Pro-rata rounding | Nearest R10 |
 | — | Multi-campus | In scope (§12), inside one install |
 | — | Central management | **Hope Events Hub** in its **own git repo** (`joshua/hope-events-hub`): installs register on setup, send heartbeats (health, version, aggregate stats), licences switched on/off centrally |
-| 7 | Payment provider order | Yoco · PayFast · SnapScan · Zapper. Joshua can supply documentation links |
+| 7 | Payment provider order | Yoco · PayFast. Joshua can supply documentation links |
+| — | SnapScan, Zapper | Dropped (2026-10-23): Yoco and PayFast are enough. Later versions moved up by two |
 | — | Provider fees | Not deducted or estimated automatically; handled by people during cashup. No "pass fee to payer" |
 | — | Minimum online payment | R15 for all providers |
 | — | Scope | All features in this document approved; POPIA toolkit and kids check-in are highlights |
 | — | Early-bird ribbon | Added before everything else; shipped as 1.32.0, all later versions moved up by one |
+| — | Hub domain | `events-hub.crosscode.co.za` (2026-10-23) |
+| — | Licence keys | Generated by the Hub when Joshua clicks "Generate" on a customer (2026-10-23) |
+| — | Grace period / suspension | 14-day grace; suspended = read-only (tickets still scan, data export still works) (2026-10-23) |
+| — | Income in the heartbeat | Included, as **ranges** only (R0–R1 000, R1 001–R5 000, …), never exact amounts (2026-10-23) |
+| — | Licence plans | One plan for now (2026-10-23) |
+| — | AI in 2.0 | The **headline feature of 2.0**: one-button helpers only (draft an event, summarise reports and feedback, draft messages, improve text) — no chat yet (2026-10-24) |
+| — | AI provider and key | One provider, **Claude** (Haiku 5.5 to start, for cost). Joshua provides the key; installs call AI **through the Hub**, which holds the key and meters usage (2026-10-24) |
+| — | AI cost limits | A **monthly rand cap per install**, set in the Hub per licence to match what the church pays; admins see their usage in Site settings → AI (2026-10-24) |
+| — | AI later | Ask AI (read-only, tools only), help/navigation assistant, actions with confirmation, more helpers, and long-term **self-hosted** AI behind the same Hub endpoint — not tied to versions (2026-10-24) |
+| — | POPIA: message kinds | Bulk messages are either **Event updates** (to registrants — still sent after unsubscribing) or **News & announcements** (marketing — opt-in, one-click unsubscribe). Every bulk email links to the preferences (2026-10-23) |
+| — | POPIA: existing users | Kept opted in to news (logged as "existing account"), asked once at their next login to confirm or opt out. New sign-ups choose with an unticked box (2026-10-23) |
+| — | POPIA: deleting an account | A request: the account is deactivated at once, personal info is anonymised when an admin approves. Waits while the person has an open registration for an upcoming event (2026-10-23) |
+| — | POPIA part 2 split | 1.39.0: privacy notice editor + versions + re-acceptance, operator register, Information Officer on the contact page, consent log, access log. 1.40.0: retention policies + nightly job, breach register, children's-data flags, readiness page. Hub moves to 1.41.0 (2026-10-23) |
+| — | POPIA: privacy notice | Today's notice becomes the starting template, one editable box per section; org name, Information Officer, retention periods and the operator list fill in automatically. Publishing saves a numbered version (2026-10-23) |
+| — | POPIA: re-accepting the notice | The admin decides per version ("significant change — ask everyone to accept again"); people are asked once after login (2026-10-23) |
+| — | POPIA: inactive accounts | Anonymised after 5 years without a login or registration, **on by default**, with a warning email 30 days before; staff/supervisor/admin accounts never (2026-10-23) |
+| — | POPIA: WhatsApp STOP | In 1.38.0, via WAWP's incoming `message` webhook with a secret in the URL (WAWP doesn't sign webhooks) (2026-10-23) |
 
 ## Still open
 
-Hub (needed before phase 6, not before 1.33.0):
-
-1. Hub domain and server, and where licence keys come from (created by hand
-   in the Hub per customer?).
-2. Grace period length (proposed 14 days) and suspended = read-only (tickets
-   still scan, data export still works) — agreed?
-3. Should payment totals be in the heartbeat at all (opt-in per customer), or
-   counts only?
-4. Licence plans/tiers (e.g. limits on campuses or WhatsApp), or one plan for
-   now?
+Nothing for now.

e2e/fixtures.ts

@@ -5,8 +5,11 @@ import path from "path";
 export type Role = "admin" | "supervisor" | "staff" | "user";
 export type Seed = {
   users: Record<Role, { id: string; name: string; email: string; token: string }>;
-  events: { free: string; paid: string; course: string; dropIn: string };
+  events: { free: string; paid: string; course: string; dropIn: string; conference: string };
   course: { sessions: { id: string; label: string }[]; ticketId: string; qrCode: string };
+  unsubscribeToken: string;
+  newsPromptUser: { id: string; token: string };
+  retention: { toWarn: string; toAnonymise: string };
 };
 
 export const API = "http://localhost:5100";

e2e/payfast.spec.ts

@@ -0,0 +1,60 @@
+import { test, expect, seed, loginAs, api } from "./fixtures";
+
+// Pays into a real PayFast sandbox account, so it needs one:
+//   E2E_PAYFAST_MERCHANT_ID, E2E_PAYFAST_MERCHANT_KEY, E2E_PAYFAST_PASSPHRASE
+// (from the Sandbox dashboard). Skipped when they aren't set, e.g. in CI.
+const PF = {
+  merchantId: process.env.E2E_PAYFAST_MERCHANT_ID || "",
+  merchantKey: process.env.E2E_PAYFAST_MERCHANT_KEY || "",
+  passphrase: process.env.E2E_PAYFAST_PASSPHRASE || "",
+};
+
+type EventWithOptions = { eventOptions: { id: string; isMainTicket: boolean }[] };
+type Registration = { id: string };
+type Checkout = { checkoutId: string; redirectUrl: string; provider: string | null };
+
+test.describe("PayFast", () => {
+  test.skip(!PF.merchantId, "Set E2E_PAYFAST_* to test against a PayFast sandbox account");
+
+  test("choose PayFast on the pay page and land on PayFast's payment page", async ({ page }) => {
+    await api(page, "admin", "PUT", "/api/payfast/config", { ...PF, mode: "sandbox" });
+    try {
+      await api(page, "admin", "PUT", "/api/payments/providers/settings", { providers: [{ id: "yoco", enabled: true }, { id: "payfast", enabled: true }] });
+
+      // A booking for the paid conference, then an online checkout for it
+      const event = await api<EventWithOptions>(page, "staff", "GET", `/api/events/${seed().events.paid}`);
+      const option = event.eventOptions.find((o) => o.isMainTicket)!;
+      const reg = await api<Registration>(page, "staff", "POST", "/api/registrations", { eventId: seed().events.paid, options: [{ eventOptionId: option.id, quantity: 1 }] });
+      const origin = new URL(page.url() === "about:blank" ? "http://localhost:3100" : page.url()).origin;
+      const checkout = await api<Checkout>(page, "staff", "POST", "/api/payments/checkout", {
+        registrationId: reg.id, successUrl: `${origin}/payment/success`, cancelUrl: `${origin}/payment/cancel`, failureUrl: `${origin}/payment/failure`,
+      });
+      // Yoco and PayFast are both on, so the payer chooses
+      expect(checkout.provider).toBeNull();
+      expect(checkout.redirectUrl).toContain(`/pay/${checkout.checkoutId}`);
+
+      await loginAs(page, "staff");
+      await page.goto(new URL(checkout.redirectUrl).pathname);
+      await expect(page.getByText("R150.00")).toBeVisible();
+      await expect(page.getByRole("button", { name: "Pay with Yoco" })).toBeVisible();
+      await page.getByRole("button", { name: "Pay with PayFast" }).click();
+
+      // The browser posts the signed form to the sandbox, which shows its payment page
+      await page.waitForURL(/sandbox\.payfast\.co\.za/, { timeout: 30_000 });
+      await expect(page.locator("body")).not.toContainText(/signature/i);
+      await expect(page.locator("body")).toContainText(/150[.,]00/);
+
+      // Not paid at PayFast: the status check asks PayFast's API (signed) and says so
+      await loginAs(page, "supervisor");
+      await page.goto("/dashboard/supervisor/payments");
+      await page.getByText("Reconcile", { exact: true }).click();
+      const row = page.getByRole("row").filter({ hasText: "PayFast" }).filter({ hasText: "R 150.00" }).first();
+      await row.getByRole("button", { name: "Check status" }).click();
+      await expect(row.getByText("Not paid (yet)")).toBeVisible({ timeout: 30_000 });
+      await expect(page.getByText("No new payments found.")).toBeVisible();
+    } finally {
+      await api(page, "admin", "PUT", "/api/payments/providers/settings", { providers: [{ id: "yoco", enabled: true }, { id: "payfast", enabled: false }] });
+      await api(page, "admin", "PUT", "/api/payfast/config", { merchantId: "", merchantKey: "", passphrase: "" });
+    }
+  });
+});

e2e/payments.spec.ts

@@ -0,0 +1,66 @@
+import { test, expect, seed, loginAs, api } from "./fixtures";
+
+type ProviderSetting = { id: string; label: string; enabled: boolean; configured: boolean };
+
+test.describe("payment providers", () => {
+  test("admin: Payments tab turns a provider on and off", async ({ page }) => {
+    await loginAs(page, "admin");
+    // The tab's older name still opens it.
+    await page.goto("/dashboard/admin/settings?tab=yoco");
+    await expect(page.getByRole("heading", { name: "Payments", exact: true })).toBeVisible();
+    await expect(page.getByRole("heading", { name: "Yoco payments" })).toBeVisible();
+
+    const providers = page.getByRole("list", { name: "Payment providers" });
+    const yoco = providers.getByRole("checkbox", { name: "Enable Yoco" });
+    await expect(yoco).toBeChecked();
+
+    try {
+      await yoco.uncheck();
+      await expect(page.getByText("Payment providers saved")).toBeVisible();
+      await expect(page.getByText(/Online payments are off/)).toBeVisible();
+      // A switched-off provider's settings are hidden
+      await expect(page.getByRole("heading", { name: "Yoco payments" })).toBeHidden();
+      const off = await api<{ providers: { id: string }[]; minimumAmount: number }>(page, "user", "GET", "/api/payments/providers");
+      expect(off.providers).toEqual([]);
+      expect(off.minimumAmount).toBe(15);
+
+      await yoco.check();
+      await expect(yoco).toBeChecked();
+      await expect(page.getByRole("heading", { name: "Yoco payments" })).toBeVisible();
+      const settings = await api<{ providers: ProviderSetting[] }>(page, "admin", "GET", "/api/payments/providers/settings");
+      expect(settings.providers.find((p) => p.id === "yoco")?.enabled).toBe(true);
+    } finally {
+      // Leave Yoco on for the other tests.
+      await api(page, "admin", "PUT", "/api/payments/providers/settings", { providers: [{ id: "yoco", enabled: true }] });
+    }
+  });
+
+  test("with no provider on, nothing offers to pay online", async ({ page }) => {
+    type EventWithOptions = { eventOptions: { id: string; isMainTicket: boolean }[] };
+    const event = await api<EventWithOptions>(page, "admin", "GET", `/api/events/${seed().events.paid}`);
+    const option = event.eventOptions.find((o) => o.isMainTicket)!;
+    const reg = await api<{ id: string }>(page, "admin", "POST", "/api/registrations", { eventId: seed().events.paid, options: [{ eventOptionId: option.id, quantity: 1 }] });
+
+    await api(page, "admin", "PUT", "/api/payments/providers/settings", { providers: [{ id: "yoco", enabled: false }, { id: "payfast", enabled: false }] });
+    try {
+      await loginAs(page, "admin");
+      await page.goto(`/registration/success?registrationId=${reg.id}`);
+      await expect(page.getByText(/Online payment isn.t available/)).toBeVisible();
+      await expect(page.getByRole("button", { name: "Pay online" })).toHaveCount(0);
+
+      await page.goto("/dashboard/user");
+      await expect(page.getByRole("button", { name: "Make donation" })).toHaveCount(0);
+      await page.goto("/dashboard/user/donate");
+      await expect(page.getByText(/Online donations aren.t available/)).toBeVisible();
+    } finally {
+      await api(page, "admin", "PUT", "/api/payments/providers/settings", { providers: [{ id: "yoco", enabled: true }, { id: "payfast", enabled: false }] });
+    }
+
+    // Back on (when Yoco is set up in this environment), the button returns
+    const on = await api<{ providers: unknown[] }>(page, "admin", "GET", "/api/payments/providers");
+    if (on.providers.length > 0) {
+      await page.goto(`/registration/success?registrationId=${reg.id}`);
+      await expect(page.getByRole("button", { name: "Pay online" })).toBeVisible();
+    }
+  });
+});

e2e/pick-sessions.spec.ts

@@ -1,6 +1,7 @@
 import { test, expect, seed, loginAs, api } from "./fixtures";
 
-type Registration = { id: string; eventId: string; registrationOptions: { sessionId?: string | null; priceSnapshot: number }[] };
+type Registration = { id: string; eventId: string; user?: { name: string }; registrationOptions: { sessionId?: string | null; sessionIds?: string[]; priceSnapshot: number; quantity: number }[] };
+type WaitlistEntry = { eventId: string; sessionId: string | null; quantity: number };
 
 test.describe("pick sessions", () => {
   test("book two classes of a drop-in event; a full class can't be ticked", async ({ page }) => {
@@ -23,4 +24,71 @@ test.describe("pick sessions", () => {
     const reg = regs.find((r) => r.eventId === seed().events.dropIn);
     expect(reg?.registrationOptions.filter((o) => o.sessionId)).toHaveLength(2);
   });
+
+  test("an all-sessions pass: tick the days, pay one price", async ({ page }) => {
+    await loginAs(page, "user");
+    await page.goto(`/register/${seed().events.conference}`);
+    await expect(page.getByText("R200.00", { exact: true })).toBeVisible();
+    await expect(page.getByText("per session")).toHaveCount(0);
+
+    const picker = page.getByRole("group", { name: "Choose sessions" });
+    await picker.getByRole("checkbox").nth(0).check();
+    await picker.getByRole("checkbox").nth(2).check();
+    await expect(page.getByText("Total: R200.00")).toBeVisible();
+
+    await page.getByRole("button", { name: "Register", exact: true }).click();
+    await page.waitForURL(/\/registration\/success/);
+
+    const regs = await api<Registration[]>(page, "user", "GET", "/api/registrations/myregistrations");
+    const line = regs.find((r) => r.eventId === seed().events.conference)?.registrationOptions[0];
+    expect(line?.sessionId ?? null).toBeNull();
+    expect(line?.sessionIds).toHaveLength(2);
+    expect(line?.priceSnapshot).toBe(200);
+    expect(line?.quantity).toBe(1);
+  });
+
+  test("join the waitlist for a full class", async ({ page }) => {
+    await loginAs(page, "admin");
+    await page.goto(`/register/${seed().events.dropIn}`);
+    await page.getByRole("button", { name: "+" }).first().click();
+
+    const picker = page.getByRole("group", { name: "Choose sessions" });
+    await picker.getByRole("button", { name: "Join waitlist" }).click();
+    await expect(page.getByText(/Drop-in — Class 1/)).toBeVisible();
+    await page.locator("form").filter({ hasText: "Join the waitlist" }).getByRole("button", { name: "Join waitlist" }).click();
+    await expect(page.getByText(/You're on the waitlist/)).toBeVisible();
+
+    const mine = await api<WaitlistEntry[]>(page, "admin", "GET", "/api/waitlist/mine");
+    const entry = mine.find((e) => e.eventId === seed().events.dropIn);
+    expect(entry?.sessionId).toBeTruthy();
+    expect(entry?.quantity).toBe(1);
+  });
+
+  test("at the door: book a class for a walk-in", async ({ page }) => {
+    await loginAs(page, "supervisor");
+    await page.goto("/dashboard/supervisor/at-the-door");
+    const value = await page.locator("option", { hasText: "E2E Drop-in Class" }).getAttribute("value");
+    // The page picks a default event once its list loads; choose ours after that.
+    await page.waitForLoadState("networkidle");
+    await page.locator("select").first().selectOption(value!);
+    await page.waitForLoadState("networkidle");
+    await expect(page.locator("select").first()).toHaveValue(value!);
+
+    await page.getByPlaceholder("Name, email or phone…").fill("Door Walk In");
+    await page.getByText('New attendee "Door Walk In"…').click();
+    await page.getByPlaceholder("Email address").fill("door-walkin@e2e.test");
+    await page.getByRole("button", { name: "Next — Choose Items" }).click();
+
+    await expect(page.getByText("R 50.00 per session")).toBeVisible();
+    await page.getByRole("button", { name: "+" }).first().click();
+    const picker = page.getByRole("group", { name: "Choose sessions" });
+    await picker.getByRole("checkbox").nth(1).check();
+    await expect(page.getByText("Total: R 50.00")).toBeVisible();
+    await page.getByRole("button", { name: "Confirm Registration" }).click();
+    await expect(page.getByText("Select Items")).toBeHidden();
+
+    const regs = await api<Registration[]>(page, "supervisor", "GET", `/api/registrations/event/${seed().events.dropIn}`);
+    const reg = regs.find((r) => r.user?.name === "Door Walk In");
+    expect(reg?.registrationOptions.filter((o) => o.sessionId)).toHaveLength(1);
+  });
 });

e2e/privacy-notice.spec.ts

@@ -0,0 +1,91 @@
+import { test, expect, seed, loginAs, api, API, type Role } from "./fixtures";
+
+type Section = { id: string; title: string; body: string };
+type Draft = { sections: Section[]; versions: { version: number; acceptances: number }[] };
+type Notice = { version: number; builtIn: boolean; sections: Section[] };
+type Operator = { id: string; name: string; active: boolean };
+type AccessLog = { rows: { action: string; what: string; records: number | null; actor: string }[] };
+type ConsentLog = { rows: { version?: number; source: string; email: string | null }[] };
+
+test.describe("privacy notice, operators and access log (POPIA)", () => {
+  // A version that needs accepting is published below; accept it for every seeded account
+  // afterwards so later test files don't meet the prompt.
+  test.afterAll(async ({ request }) => {
+    const tokens = [...(["admin", "supervisor", "staff", "user"] as Role[]).map(r => seed().users[r].token), seed().newsPromptUser.token];
+    for (const token of tokens) {
+      await request.post(`${API}/api/privacy/me/notice/accept`, { headers: { Authorization: `Bearer ${token}` } });
+    }
+  });
+
+  test("the built-in notice is shown until a version is published, with the operator register filled in", async ({ page }) => {
+    const notice = await (await page.request.get(`${API}/api/privacy/notice`)).json() as Notice;
+    expect(notice.version).toBe(0);
+    expect(notice.sections.find(s => s.id === "sharing")?.body).toContain("• PayFast (South Africa)");
+
+    await page.goto("/legal/privacy");
+    await expect(page.getByRole("heading", { name: "Privacy Policy" })).toBeVisible();
+    await expect(page.getByText("• PayFast (South Africa)", { exact: false })).toBeVisible();
+  });
+
+  test("an admin edits and publishes; operators feed the notice", async ({ page }) => {
+    // A new operator appears in the notice's {operators} list.
+    const op = await api<Operator>(page, "admin", "POST", "/api/privacy/operators", { name: "E2E Mailer", purpose: "Sending emails", dataShared: "Email address", location: "Ireland" });
+
+    await loginAs(page, "admin");
+    await page.goto("/dashboard/admin/privacy?tab=notice");
+    const intro = page.getByLabel("1. Introduction text");
+    await expect(intro).toBeVisible();
+    await intro.fill("{org} looks after your information carefully. (E2E edit)");
+    await page.getByRole("button", { name: "Save draft" }).click();
+    await expect(page.getByText("Draft saved.")).toBeVisible();
+
+    // Nothing public changes until it's published.
+    expect(((await (await page.request.get(`${API}/api/privacy/notice`)).json()) as Notice).version).toBe(0);
+
+    await page.getByRole("button", { name: "Publish…" }).click();
+    await page.getByPlaceholder("e.g. We now use PayFast for online payments.").fill("Clearer introduction.");
+    await page.getByRole("button", { name: "Publish", exact: true }).click();
+    await expect(page.getByText("Version 1 is published.")).toBeVisible();
+
+    await page.goto("/legal/privacy");
+    await expect(page.getByText("E2E Church looks after your information carefully. (E2E edit)")).toBeVisible();
+    await expect(page.getByText("• E2E Mailer (Ireland) — Sending emails.", { exact: false })).toBeVisible();
+    await expect(page.getByText(/Version 1/).first()).toBeVisible();
+
+    await api(page, "admin", "DELETE", `/api/privacy/operators/${op.id}`);
+  });
+
+  test("a significant change is accepted once, after login", async ({ page }) => {
+    const draft = await api<Draft>(page, "admin", "GET", "/api/privacy/notice/draft");
+    // Re-acceptance needs a summary of what changed.
+    await expect(api(page, "admin", "POST", "/api/privacy/notice/publish", { sections: draft.sections, requiresAcceptance: true })).rejects.toThrow(/400/);
+    const published = await api<{ version: number }>(page, "admin", "POST", "/api/privacy/notice/publish", { sections: draft.sections, requiresAcceptance: true, changeSummary: "We added WhatsApp news." });
+
+    await loginAs(page, "user");
+    await page.goto("/dashboard/user");
+    const dialog = page.getByRole("dialog", { name: "We've updated our privacy notice" });
+    await expect(dialog).toBeVisible();
+    await expect(dialog.getByText("We added WhatsApp news.")).toBeVisible();
+    await dialog.getByRole("button", { name: "I accept" }).click();
+    await expect(dialog).toBeHidden();
+    await page.reload();
+    await expect(page.getByText("My Events").first()).toBeVisible();
+    await expect(page.getByRole("dialog", { name: "We've updated our privacy notice" })).toHaveCount(0);
+
+    const log = await api<ConsentLog>(page, "admin", "GET", `/api/privacy/consent-log?type=notice&q=${encodeURIComponent(seed().users.user.email)}`);
+    expect(log.rows[0]).toMatchObject({ version: published.version, source: "prompt" });
+  });
+
+  test("bulk exports are in the access log", async ({ page }) => {
+    const res = await page.request.post(`${API}/api/reports/pdf`, {
+      headers: { Authorization: `Bearer ${seed().users.supervisor.token}`, "Content-Type": "application/json" },
+      data: JSON.stringify({ title: "E2E attendee list", kind: "table", table: { columns: ["Name"], rows: [["A"], ["B"], ["C"]] } }),
+    });
+    expect(res.ok()).toBe(true);
+    await api(page, "supervisor", "GET", `/api/consent/events/${seed().events.free}`);
+
+    const log = await api<AccessLog>(page, "admin", "GET", "/api/privacy/access-log");
+    expect(log.rows.find(r => r.action === "report_pdf")).toMatchObject({ what: "E2E attendee list", records: 3, actor: "Sam Supervisor" });
+    expect(log.rows.some(r => r.action === "consent_list")).toBe(true);
+  });
+});

e2e/privacy-retention.spec.ts

@@ -0,0 +1,64 @@
+import { test, expect, seed, loginAs, api } from "./fixtures";
+
+type RunResult = { result: Record<string, Record<string, number>> };
+type UserRow = { name: string; email: string; isActive: boolean };
+type Readiness = { score: number; checks: { key: string; ok: boolean; applies: boolean }[] };
+type Breach = { id: string; status: string; regulatorNotifiedAt: string | null };
+
+test.describe("retention, breaches and readiness (POPIA)", () => {
+  test("the retention job warns inactive accounts first, and anonymises them 30 days after the warning", async ({ page }) => {
+    const { result } = await api<RunResult>(page, "admin", "POST", "/api/privacy/retention/run");
+    expect(result.inactive_accounts.warned).toBeGreaterThanOrEqual(1);
+    expect(result.inactive_accounts.anonymised).toBeGreaterThanOrEqual(1);
+    expect(result.login_history.deleted).toBeGreaterThanOrEqual(1);
+
+    const warned = await api<UserRow>(page, "admin", "GET", `/api/users/${seed().retention.toWarn}`);
+    expect(warned.email).toBe("dormant@e2e.test");
+    const gone = await api<UserRow>(page, "admin", "GET", `/api/users/${seed().retention.toAnonymise}`);
+    expect(gone.name).toBe("Deleted User");
+    expect(gone.email).toMatch(/@deleted\.invalid$/);
+
+    // Seeded accounts (staff roles, and the recently active user) are untouched.
+    expect((await api<UserRow>(page, "admin", "GET", `/api/users/${seed().users.user.id}`)).email).toBe("user@e2e.test");
+  });
+
+  test("retention periods are validated and saved; the notice follows them", async ({ page }) => {
+    const state = await api<{ policies: Record<string, { enabled: boolean; months: number }> }>(page, "admin", "GET", "/api/privacy/retention");
+    await expect(api(page, "admin", "PUT", "/api/privacy/retention", { policies: { ...state.policies, inactive_accounts: { enabled: true, months: 3 } } })).rejects.toThrow(/400/);
+    await api(page, "admin", "PUT", "/api/privacy/retention", { policies: { ...state.policies, form_answers: { enabled: true, months: 18 } } });
+
+    await page.goto("/legal/privacy");
+    await expect(page.getByText("Answers to event forms are deleted 18 months after the event.", { exact: false })).toBeVisible();
+  });
+
+  test("a breach is recorded, reported, and drafts are ready to copy", async ({ page }) => {
+    const breach = await api<Breach>(page, "admin", "POST", "/api/privacy/breaches", {
+      title: "Phone with the attendee list lost", discoveredAt: new Date().toISOString(),
+      description: "A leader's phone was stolen at the camp site.", dataAffected: "Names and phone numbers of 40 campers",
+    });
+    expect(breach.status).toBe("open");
+
+    await loginAs(page, "admin");
+    await page.goto("/dashboard/admin/privacy?tab=breaches");
+    await page.getByRole("button", { name: /Phone with the attendee list lost/ }).click();
+    await expect(page.getByText("Draft message to the people affected")).toBeVisible();
+    await expect(page.getByText("Personal information affected: Names and phone numbers of 40 campers")).toBeVisible();
+    await page.getByRole("button", { name: "Regulator told today" }).click();
+    await expect(page.getByRole("button", { name: "Regulator told today" })).toHaveCount(0);
+
+    const list = await api<Breach[]>(page, "admin", "GET", "/api/privacy/breaches");
+    expect(list.find(b => b.id === breach.id)?.regulatorNotifiedAt).toBeTruthy();
+  });
+
+  test("the readiness page scores the install", async ({ page }) => {
+    const r = await api<Readiness>(page, "admin", "GET", "/api/privacy/readiness");
+    expect(r.score).toBeGreaterThan(0);
+    expect(r.checks.find(c => c.key === "retention_reviewed")?.ok).toBe(true);
+    expect(r.checks.find(c => c.key === "retention_running")?.ok).toBe(false); // jobs are off in e2e
+
+    await loginAs(page, "admin");
+    await page.goto("/dashboard/admin/privacy");
+    await expect(page.getByText("POPIA readiness")).toBeVisible();
+    await expect(page.getByText(`${r.score}%`)).toBeVisible();
+  });
+});

e2e/privacy.spec.ts

@@ -0,0 +1,111 @@
+import type { Page } from "@playwright/test";
+import { test, expect, seed, loginAs, api, API } from "./fixtures";
+
+type Account = { id: string; token: string; email: string };
+type PrivacyInfo = { news: { email: boolean; whatsapp: boolean }; history: { source: string }[]; requests: { type: string; status: string }[] };
+type Preview = { kind: string; matched: number; skipped: number };
+type Requests = { requests: { id: string; type: string; userId: string; blockers: unknown[] }[] };
+
+/** A brand-new account made through sign-up, so tests can change it freely. */
+async function signUp(page: Page, newsOptIn: boolean): Promise<Account> {
+  const email = `privacy-${Date.now()}-${Math.floor(Math.random() * 1e6)}@e2e.test`;
+  const res = await page.request.post(`${API}/api/users`, {
+    data: { name: "Pat Privacy", email, password: "E2e-password-123", newsOptIn },
+  });
+  expect(res.ok()).toBe(true);
+  const body = await res.json();
+  return { id: body.id, token: body.token, email };
+}
+
+async function asAccount<T>(page: Page, account: Account, method: string, url: string, body?: unknown) {
+  const res = await page.request.fetch(`${API}${url}`, {
+    method,
+    headers: { Authorization: `Bearer ${account.token}`, "Content-Type": "application/json" },
+    data: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: res.status(), body: (await res.json().catch(() => null)) as T };
+}
+
+test.describe("privacy (POPIA)", () => {
+  test("sign-up records the news choice; the privacy page changes it and downloads my data", async ({ page }) => {
+    const me = await signUp(page, false);
+    const before = await asAccount<PrivacyInfo>(page, me, "GET", "/api/privacy/me");
+    expect(before.body.news.email).toBe(false);
+    expect(before.body.history.map((h) => h.source)).toContain("signup");
+
+    await page.addInitScript((token) => localStorage.setItem("hope_events_token", token), me.token);
+    await page.goto("/dashboard/user/privacy");
+    const byEmail = page.getByRole("checkbox", { name: "By email" });
+    await expect(byEmail).not.toBeChecked();
+    await byEmail.check();
+    await expect(page.getByText("You're subscribed.")).toBeVisible();
+    await expect(byEmail).toBeChecked();
+
+    const exported = await asAccount<{ account: { email: string }; communication: { news: { email: boolean } } }>(page, me, "GET", "/api/privacy/me/export");
+    expect(exported.status).toBe(200);
+    expect(exported.body.account.email).toBe(me.email);
+    expect(exported.body.communication.news.email).toBe(true);
+  });
+
+  test("news broadcasts skip people who aren't opted in; event updates don't", async ({ page }) => {
+    const out = await signUp(page, false);
+    const news = await api<Preview>(page, "supervisor", "POST", "/api/broadcasts/preview", { userIds: [out.id, seed().users.admin.id], emails: "", kind: "news" });
+    expect(news.matched).toBe(1);
+    expect(news.skipped).toBe(1);
+    const update = await api<Preview>(page, "supervisor", "POST", "/api/broadcasts/preview", { userIds: [out.id, seed().users.admin.id], emails: "", kind: "update" });
+    expect(update.matched).toBe(2);
+    expect(update.skipped).toBe(0);
+  });
+
+  test("the unsubscribe link turns news off", async ({ page }) => {
+    await page.goto(`/unsubscribe?t=${encodeURIComponent(seed().unsubscribeToken)}`);
+    await page.getByRole("button", { name: "Unsubscribe from all news" }).click();
+    await expect(page.getByText(/You're unsubscribed from news and announcements/)).toBeVisible();
+    const after = await api<PrivacyInfo>(page, "user", "GET", "/api/privacy/me");
+    expect(after.news).toEqual({ email: false, whatsapp: false });
+    expect(after.history.some((h) => h.source === "unsubscribe_link")).toBe(true);
+
+    const bad = await page.request.get(`${API}/api/privacy/unsubscribe/not-a-real-token`);
+    expect(bad.status()).toBe(404);
+  });
+
+  test("accounts that never answered are asked once after logging in", async ({ page }) => {
+    await page.addInitScript((token) => localStorage.setItem("hope_events_token", token), seed().newsPromptUser.token);
+    await page.goto("/dashboard/user");
+    const dialog = page.getByRole("dialog", { name: "Hear about upcoming events?" });
+    await expect(dialog).toBeVisible();
+    await dialog.getByRole("button", { name: "No thanks" }).click();
+    await expect(dialog).toBeHidden();
+
+    await page.reload();
+    await expect(page.getByText("My Events").first()).toBeVisible();
+    await expect(page.getByRole("dialog", { name: "Hear about upcoming events?" })).toHaveCount(0);
+  });
+
+  test("delete my account: closed at once, anonymised when an admin completes the request", async ({ page }) => {
+    const me = await signUp(page, true);
+    const wrong = await asAccount(page, me, "POST", "/api/privacy/me/requests", { type: "deletion", password: "nope" });
+    expect(wrong.status).toBe(400);
+    const made = await asAccount(page, me, "POST", "/api/privacy/me/requests", { type: "deletion", password: "E2e-password-123" });
+    expect(made.status).toBe(201);
+
+    // The account is closed: the old session no longer works, and logging in is refused.
+    expect((await asAccount(page, me, "GET", "/api/privacy/me")).status).toBe(401);
+    const login = await page.request.post(`${API}/api/users/login`, { data: { email: me.email, password: "E2e-password-123" } });
+    expect(login.ok()).toBe(false);
+
+    const inbox = await api<Requests>(page, "admin", "GET", "/api/privacy/requests?status=open");
+    const request = inbox.requests.find((r) => r.userId === me.id);
+    expect(request?.type).toBe("deletion");
+    expect(request?.blockers).toEqual([]);
+
+    // The admin page shows it; completing it removes the personal information.
+    await loginAs(page, "admin");
+    await page.goto("/dashboard/admin/data-requests");
+    await expect(page.getByText(me.email)).toBeVisible();
+    await api(page, "admin", "POST", `/api/privacy/requests/${request!.id}/complete`, {});
+    const user = await api<{ name: string; email: string }>(page, "admin", "GET", `/api/users/${me.id}`);
+    expect(user.name).toBe("Deleted User");
+    expect(user.email).toMatch(/@deleted\.invalid$/);
+  });
+});

e2e/support/prepare-db.js

@@ -48,8 +48,10 @@ async function seed(url) {
   });
 
   const password = await hashPassword('E2e-password-123');
+  // Opted in to news and already asked (newsAskedAt), so the one-time news question
+  // doesn't cover the dashboards in every test.
   const mk = (role, name, email, phoneNumber) => prisma.user.create({
-    data: { name, email, phoneNumber, role, password, isActive: true, updatedAt: new Date() },
+    data: { name, email, phoneNumber, role, password, isActive: true, updatedAt: new Date(), newsEmail: true, newsWhatsApp: true, newsAskedAt: new Date() },
   });
   const users = {
     admin: await mk('admin', 'Ada Admin', 'admin@e2e.test', '0820000001'),
@@ -110,12 +112,27 @@ async function seed(url) {
     data: {
       title: 'E2E Drop-in Class', description: 'Come to the classes you like.', startDate: classes[0].startsAt, endDate: classes[2].endsAt,
       price: 50, location: '1 Test Street, Pretoria', createdById: users.supervisor.id,
-      scheduleType: 'sessions', attendanceMode: 'pick',
+      scheduleType: 'sessions', attendanceMode: 'pick', waitlistEnabled: true,
       sessions: { create: classes },
       eventOptions: { create: [{ name: 'Drop-in', price: 50, isMainTicket: true, sessionMode: 'pick' }] },
     },
     include: { sessions: { orderBy: { startsAt: 'asc' } }, eventOptions: true },
   });
+  // A conference sold per pass: people tick the days they'll come, one price for the pass.
+  const days = [2, 3, 4].map((d, i) => {
+    const startsAt = at(d, 7, 0);
+    return { label: `Day ${i + 1}`, startsAt, endsAt: new Date(startsAt.getTime() + 8 * 60 * 60 * 1000), order: i };
+  });
+  const conference = await prisma.event.create({
+    data: {
+      title: 'E2E Conference', description: 'Three days; come to the days you can.', startDate: days[0].startsAt, endDate: days[2].endsAt,
+      price: 200, location: '1 Test Street, Pretoria', createdById: users.supervisor.id,
+      scheduleType: 'sessions', attendanceMode: 'pick',
+      sessions: { create: days },
+      eventOptions: { create: [{ name: 'Conference pass', price: 200, isMainTicket: true, sessionMode: 'all' }] },
+    },
+  });
+
   // Someone else already has the only place in class 1.
   await prisma.registration.create({
     data: {
@@ -138,8 +155,25 @@ async function seed(url) {
 
   const out = {
     users: Object.fromEntries(Object.entries(users).map(([k, u]) => [k, { id: u.id, name: u.name, email: u.email, token: generateToken(u.id, u.role, u.tokenVersion || 0) }])),
-    events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id },
+    events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id, conference: conference.id },
     course: { sessions: course.sessions.map(s => ({ id: s.id, label: s.label })), ticketId: ticket.id, qrCode: ticket.qrCode },
+    // An account that has never answered the news question (asked once after login).
+    newsPromptUser: await (async () => {
+      const u = await prisma.user.create({ data: { name: 'Nomsa New', email: 'prompt@e2e.test', role: 'user', password, isActive: true, updatedAt: new Date(), newsEmail: true } });
+      return { id: u.id, token: generateToken(u.id, u.role, 0) };
+    })(),
+    // Retention: two accounts untouched for six years — one not yet warned, one warned 40 days
+    // ago (so the next run anonymises it) — and three-year-old login history.
+    retention: await (async () => {
+      const longAgo = new Date(Date.now() - 6 * 365 * 24 * 60 * 60 * 1000);
+      const oldUser = (email, warnedAt) => prisma.user.create({ data: { name: `Old ${email}`, email, role: 'user', password, isActive: true, createdAt: longAgo, updatedAt: longAgo, inactivityWarnedAt: warnedAt } });
+      const toWarn = await oldUser('dormant@e2e.test', null);
+      const toAnonymise = await oldUser('gone-quiet@e2e.test', new Date(Date.now() - 40 * 24 * 60 * 60 * 1000));
+      await prisma.securityEvent.create({ data: { userId: toWarn.id, type: 'login', createdAt: new Date(Date.now() - 3 * 365 * 24 * 60 * 60 * 1000) } });
+      return { toWarn: toWarn.id, toAnonymise: toAnonymise.id };
+    })(),
+    // The link a news email to the seeded user would carry (signed with JWT_SECRET).
+    unsubscribeToken: require(path.join(backend, 'src/utils/privacy')).unsubscribeToken({ userId: users.user.id }),
   };
   fs.mkdirSync(path.join(root, 'e2e', '.data'), { recursive: true });
   fs.writeFileSync(path.join(root, 'e2e', '.data', 'seed.json'), JSON.stringify(out, null, 2));

ecosystem.config.example.js

@@ -1,3 +1,6 @@
+// PM2 config template. Each install keeps its own copy as ecosystem.config.js (not in git,
+// so deploys never change it); scripts/deploy.sh creates it from this file the first time.
+// Change the app names (unique per install on a server) and the frontend port to suit.
 module.exports = {
   apps: [
     {

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.35.0",
+  "version": "1.40.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hope-events-frontend",
-      "version": "1.35.0",
+      "version": "1.40.0",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",
         "@hookform/resolvers": "^5.2.1",

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hope-events-frontend",
-  "version": "1.35.0",
+  "version": "1.40.0",
   "private": true,
   "scripts": {
     "dev": "next dev --turbopack",

frontend/public/sw.js

@@ -1,14 +1,18 @@
 /*
  * Service worker for offline ticket scanning.
  *
- * Only the scanner page and the static files it needs are cached:
- * - /_next/static/* (hashed, never change): cache-first.
- * - The scanner page itself: network-first, falling back to the cached copy offline.
+ * Only the scanner page and the static files it needs are cached, both network-first
+ * with the cached copy as the offline fallback:
+ * - /_next/static/*. Not cache-first: under `next dev` these files keep their names when
+ *   their content changes, so cache-first served stale code on every page, for good.
+ *   (Production files are hashed and come from the browser's HTTP cache anyway.)
+ * - The scanner page itself.
  * - The page can ask (postMessage { type: 'cache-urls', urls }) for the files it has
  *   loaded to be cached up front, so it works offline straight after "Enable offline mode".
  * API calls are never cached — offline scans go through IndexedDB instead.
  */
-const CACHE = 'hope-scanner-v1';
+// v2: drops v1 caches, which could hold stale development scripts (see above).
+const CACHE = 'hope-scanner-v2';
 const SCANNER_PATH = '/dashboard/staff/ticket-scanning';
 
 self.addEventListener('install', () => self.skipWaiting());
@@ -41,11 +45,15 @@ self.addEventListener('fetch', (event) => {
   if (url.pathname.startsWith('/_next/static/')) {
     event.respondWith((async () => {
       const cache = await caches.open(CACHE);
-      const hit = await cache.match(req);
-      if (hit) return hit;
-      const res = await fetch(req);
-      if (res.ok) cache.put(req, res.clone());
-      return res;
+      try {
+        const res = await fetch(req);
+        if (res.ok) cache.put(req, res.clone());
+        return res;
+      } catch {
+        const hit = await cache.match(req);
+        if (hit) return hit;
+        throw new Error('offline and not cached');
+      }
     })());
     return;
   }

frontend/src/app/contact/page.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import { Mail, Phone, MapPin } from "lucide-react";
+import Link from "next/link";
+import { Mail, Phone, MapPin, ShieldCheck } from "lucide-react";
 import { Navbar } from "@/components/layout/Navbar";
 import { Footer } from "@/components/layout/Footer";
 import { useSiteSettings } from "@/contexts/SiteSettingsContext";
@@ -13,6 +14,8 @@ export default function ContactPage() {
   const email = settings.org_email || "";
   const phone = settings.org_phone || "";
   const address = settings.org_address || "";
+  const ioName = settings.legal_io_name || "";
+  const ioEmail = settings.legal_io_email || "";
   const hasAny = !!(email || phone || address);
 
   return (
@@ -75,6 +78,24 @@ export default function ContactPage() {
             <LocationMap address={address} />
           </div>
         )}
+
+        {/* POPIA: the Information Officer, once one is set in Site Settings → Legal. */}
+        {ioName && (
+          <div className="mt-8 flex items-start gap-3 border rounded-xl p-5 bg-white shadow-sm">
+            <div className="w-10 h-10 rounded-full bg-brand-50 flex items-center justify-center shrink-0">
+              <ShieldCheck className="w-5 h-5 text-brand-600" />
+            </div>
+            <div className="text-sm text-gray-600">
+              <div className="font-semibold text-gray-900">Privacy and your personal information</div>
+              <p className="mt-1">
+                Our Information Officer is <strong>{ioName}</strong>
+                {ioEmail && <> — <a href={`mailto:${ioEmail}`} className="text-brand-600 hover:underline break-all">{ioEmail}</a></>}.
+                Contact them about the information we hold about you, or see our{" "}
+                <Link href="/legal/privacy" className="text-brand-600 hover:underline">privacy notice</Link>.
+              </p>
+            </div>
+          </div>
+        )}
       </main>
       <Footer />
     </div>

frontend/src/app/dashboard/admin/audit-log/page.tsx

@@ -40,6 +40,17 @@ const ACTIONS = [
   "yoco_config_updated",
   "yoco_webhook_registered",
   "yoco_webhook_deleted",
+  "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",
 ] as const;
 
 const ACTION_LABELS: Record<string, string> = {
@@ -72,6 +83,17 @@ const ACTION_LABELS: Record<string, string> = {
   yoco_config_updated: "Yoco settings changed",
   yoco_webhook_registered: "Yoco webhook registered",
   yoco_webhook_deleted: "Yoco webhook deleted",
+  data_request_completed: "Privacy request completed",
+  data_request_rejected: "Privacy request rejected/cancelled",
+  user_anonymised: "User's personal data deleted",
+  privacy_notice_published: "Privacy notice published",
+  operator_created: "Operator added",
+  operator_updated: "Operator changed",
+  operator_deleted: "Operator removed",
+  retention_policies_updated: "Retention periods changed",
+  retention_run: "Retention job deleted/anonymised data",
+  breach_recorded: "Security compromise recorded",
+  breach_updated: "Security compromise updated",
 };
 
 interface AuditLogEntry {

frontend/src/app/dashboard/admin/data-requests/page.tsx

@@ -0,0 +1,201 @@
+"use client";
+
+import React, { useCallback, useEffect, useState } from "react";
+import Link from "next/link";
+import { useAuth } from "@/hooks/useAuth";
+import { apiFetch } from "@/lib/api";
+import { useDismissingState } from "@/hooks/useDismissingState";
+import { Inbox, AlertTriangle } from "lucide-react";
+import { errorMessage } from "@/lib/utils";
+import { BackLink } from "@/components/shared/BackLink";
+
+type RequestType = "access" | "correction" | "deletion";
+type RequestStatus = "open" | "completed" | "rejected" | "cancelled";
+type Blocker = { registrationId: string; status: string; eventId: string; eventTitle: string; endDate: string };
+type DataRequest = {
+  id: string; type: RequestType; status: RequestStatus; name: string; email: string; details: string | null; response: string | null;
+  dueAt: string; closedAt: string | null; createdAt: string; userId: string | null; handledBy: string | null; overdue: boolean; blockers: Blocker[];
+};
+type Msg = { type: "ok" | "err"; text: string } | null;
+
+const TYPE_LABEL: Record<RequestType, string> = { access: "Access", correction: "Correction", deletion: "Delete account" };
+const STATUS_TONE: Record<RequestStatus, string> = {
+  open: "bg-amber-50 text-amber-700",
+  completed: "bg-green-50 text-green-700",
+  rejected: "bg-red-50 text-red-700",
+  cancelled: "bg-gray-100 text-gray-600",
+};
+
+const fmtDate = (d: string) => new Date(d).toLocaleDateString(undefined, { day: "numeric", month: "short", year: "numeric" });
+
+/** One open request with its actions: complete (deletion: anonymise), reject or cancel. */
+function OpenRequest({ request, token, onDone }: { request: DataRequest; token: string; onDone: (msg: Msg) => void }) {
+  const [mode, setMode] = useState<"idle" | "complete" | "reject">("idle");
+  const [response, setResponse] = useState("");
+  const [cancelled, setCancelled] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const isDeletion = request.type === "deletion";
+
+  const submit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (mode === "complete" && isDeletion && !confirm(`Delete ${request.name}'s personal information? This can't be undone.`)) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await apiFetch(`/api/privacy/requests/${request.id}/${mode}`, {
+        method: "POST",
+        authToken: token,
+        body: { response: response || undefined, cancelled: mode === "reject" ? cancelled : undefined },
+      });
+      onDone({ type: "ok", text: mode === "complete" ? (isDeletion ? `${request.name}'s personal information was deleted.` : "Request completed.") : "Request closed." });
+    } catch (e) {
+      setError(errorMessage(e) || "Something went wrong.");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <li className={`border rounded-xl p-4 bg-white shadow-sm ${request.overdue ? "border-red-300" : ""}`}>
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="font-semibold text-gray-900">{TYPE_LABEL[request.type]}</span>
+        <span className="text-sm text-gray-700">— {request.name}</span>
+        <a href={`mailto:${request.email}`} className="text-sm text-brand-600 hover:underline">{request.email}</a>
+        <span className={`ml-auto text-xs px-2 py-0.5 rounded-full ${request.overdue ? "bg-red-50 text-red-700" : "bg-gray-100 text-gray-600"}`}>
+          {request.overdue ? "Overdue — was due " : "Due "}{fmtDate(request.dueAt)}
+        </span>
+      </div>
+      <p className="text-xs text-gray-400 mt-1">Received {fmtDate(request.createdAt)}</p>
+      {request.details && <p className="text-sm text-gray-700 mt-2 whitespace-pre-line">{request.details}</p>}
+
+      {isDeletion && (
+        request.blockers.length > 0 ? (
+          <div className="mt-3 p-3 rounded-lg bg-amber-50 border border-amber-200 text-sm text-amber-900">
+            <div className="flex items-center gap-2 font-medium"><AlertTriangle className="w-4 h-4" /> Waiting on registrations for upcoming events</div>
+            <ul className="mt-1 list-disc pl-5">
+              {request.blockers.map(b => (
+                <li key={b.registrationId}>{b.eventTitle} ({b.status}, ends {fmtDate(b.endDate)})</li>
+              ))}
+            </ul>
+            <p className="mt-1 text-xs">
+              Cancel (and refund where needed) on <Link href="/dashboard/admin/registrations" className="text-brand-600 hover:underline">Registrations</Link> —
+              search for {request.email} — or wait until the event is over. The account is already closed.
+            </p>
+          </div>
+        ) : (
+          <p className="mt-2 text-xs text-gray-500">The account is closed. Completing deletes their name, contact details, attendees, form answers and payer details; payments and registrations stay as &quot;Deleted User&quot;.</p>
+        )
+      )}
+
+      {mode === "idle" ? (
+        <div className="flex flex-wrap gap-2 mt-3">
+          <button onClick={() => setMode("complete")} disabled={isDeletion && request.blockers.length > 0} className="px-3 py-1.5 rounded-lg bg-brand-600 text-white text-sm font-medium hover:bg-brand-700 disabled:opacity-50">
+            {isDeletion ? "Delete personal data…" : "Mark as done…"}
+          </button>
+          <button onClick={() => setMode("reject")} className="px-3 py-1.5 rounded-lg border border-gray-300 text-gray-700 text-sm font-medium hover:bg-gray-50">
+            Reject or cancel…
+          </button>
+        </div>
+      ) : (
+        <form onSubmit={submit} className="mt-3 space-y-3">
+          <label className="block text-sm font-medium text-gray-700">
+            {mode === "reject" ? "Reason (emailed to them)" : request.type === "correction" ? "What was corrected (emailed to them)" : "Message to them (optional)"}
+          </label>
+          <textarea
+            className="w-full border rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500"
+            rows={3}
+            maxLength={5000}
+            value={response}
+            onChange={e => setResponse(e.target.value)}
+            required={mode === "reject" || request.type === "correction"}
+          />
+          {mode === "reject" && (
+            <label className="flex items-center gap-2 text-sm text-gray-700">
+              <input type="checkbox" className="h-4 w-4 accent-brand-600" checked={cancelled} onChange={e => setCancelled(e.target.checked)} />
+              They withdrew it (cancelled, not rejected)
+            </label>
+          )}
+          {mode === "reject" && isDeletion && <p className="text-xs text-gray-500">Their account is opened again so they can log in.</p>}
+          <div className="flex gap-2">
+            <button type="button" onClick={() => { setMode("idle"); setResponse(""); setError(null); }} className="px-3 py-1.5 rounded-lg bg-gray-100 text-sm font-medium hover:bg-gray-200">Back</button>
+            <button type="submit" disabled={busy} className={`px-3 py-1.5 rounded-lg text-white text-sm font-medium disabled:opacity-50 ${mode === "complete" && isDeletion ? "bg-red-600 hover:bg-red-700" : "bg-brand-600 hover:bg-brand-700"}`}>
+              {busy ? "Saving…" : mode === "complete" ? (isDeletion ? "Delete personal data" : "Complete") : cancelled ? "Cancel request" : "Reject request"}
+            </button>
+          </div>
+          {error && <p className="text-sm text-red-600">{error}</p>}
+        </form>
+      )}
+    </li>
+  );
+}
+
+export default function DataRequestsPage() {
+  const { token } = useAuth();
+  const [view, setView] = useState<"open" | "closed">("open");
+  const [requests, setRequests] = useState<DataRequest[] | null>(null);
+  const [openCount, setOpenCount] = useState(0);
+  const [msg, setMsg] = useDismissingState<Msg>(null);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    try {
+      const res = await apiFetch<{ requests: DataRequest[]; openCount: number }>(`/api/privacy/requests?status=${view}`, { authToken: token });
+      setRequests(res.requests);
+      setOpenCount(res.openCount);
+    } catch (e) {
+      setMsg({ type: "err", text: errorMessage(e) || "Could not load requests." });
+    }
+  }, [token, view, setMsg]);
+  useEffect(() => { setRequests(null); load(); }, [load]);
+
+  return (
+    <div className="max-w-4xl mx-auto w-full">
+      <div className="mb-6">
+        <BackLink href="/dashboard/admin" />
+        <div className="flex items-center gap-2 mt-0.5">
+          <Inbox className="w-6 h-6 text-brand-600" />
+          <h1 className="text-2xl font-semibold text-gray-900">Data requests</h1>
+        </div>
+        <p className="text-sm text-gray-500 mt-1">
+          POPIA requests from people about their personal information. Answer within 30 days. Downloads people make
+          themselves from their Privacy page aren&apos;t listed here.
+        </p>
+      </div>
+
+      <div className="flex gap-2 mb-4">
+        {(["open", "closed"] as const).map(v => (
+          <button key={v} onClick={() => setView(v)} className={`px-3 py-1.5 rounded-lg text-sm font-medium ${view === v ? "bg-brand-600 text-white" : "bg-white border text-gray-700 hover:bg-gray-50"}`}>
+            {v === "open" ? `Open${openCount ? ` (${openCount})` : ""}` : "Closed"}
+          </button>
+        ))}
+      </div>
+
+      {msg && <div className={`mb-4 p-3 rounded-lg text-sm ${msg.type === "ok" ? "bg-green-50 text-green-800 border border-green-200" : "bg-red-50 text-red-800 border border-red-200"}`}>{msg.text}</div>}
+
+      {requests === null ? (
+        <p className="text-sm text-gray-400">Loading…</p>
+      ) : requests.length === 0 ? (
+        <p className="text-sm text-gray-500">{view === "open" ? "No open requests." : "No closed requests yet."}</p>
+      ) : view === "open" ? (
+        <ul className="space-y-3">
+          {requests.map(r => <OpenRequest key={r.id} request={r} token={token!} onDone={m => { setMsg(m); load(); }} />)}
+        </ul>
+      ) : (
+        <ul className="space-y-2">
+          {requests.map(r => (
+            <li key={r.id} className="border rounded-xl p-3 bg-white text-sm">
+              <div className="flex flex-wrap items-center gap-2">
+                <span className="font-medium text-gray-900">{TYPE_LABEL[r.type]}</span>
+                <span className="text-gray-700">— {r.name}</span>
+                <span className={`text-xs px-2 py-0.5 rounded-full ${STATUS_TONE[r.status]}`}>{r.status}</span>
+                <span className="ml-auto text-xs text-gray-400">{r.closedAt ? `Closed ${fmtDate(r.closedAt)}` : ""}{r.handledBy ? ` by ${r.handledBy}` : ""}</span>
+              </div>
+              {r.response && <p className="text-gray-600 mt-1 whitespace-pre-line">{r.response}</p>}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

frontend/src/app/dashboard/admin/page.tsx

@@ -8,7 +8,7 @@ import { useStableState } from "@/hooks/useStableState";
 import { useVisiblePolling } from "@/hooks/useVisiblePolling";
 import {
   Calendar, Banknote, Gift, Users, Ticket, QrCode, ClipboardList,
-  UserPlus, FileText, MessageCircle, BarChart2, Mail, Wallet, DoorOpen, History, TicketPercent, ShieldCheck, ListChecks, WifiOff, BedDouble, Filter, ClipboardCheck,
+  UserPlus, FileText, MessageCircle, BarChart2, Mail, Wallet, DoorOpen, History, TicketPercent, ShieldCheck, ListChecks, WifiOff, BedDouble, Filter, ClipboardCheck, Inbox,
 } from "lucide-react";
 import { StatCard, StatCardRow } from "@/components/shared/StatCard";
 import { QuickActionTile, QuickActionGrid } from "@/components/shared/QuickActionTile";
@@ -42,6 +42,8 @@ const QUICK_ACTIONS = [
   { href: "/dashboard/supervisor/whatsapp-attendees", label: "WhatsApp attendees", description: "Send a WhatsApp message to event attendees", icon: MessageCircle },
   { href: "/dashboard/admin/cashup", label: "Post-event Cashup", description: "Set costs, reconcile takings, and close out events", icon: Wallet },
   { href: "/dashboard/admin/audit-log", label: "Audit log", description: "Review refunds, manual registrations, event and settings changes", icon: History },
+  { href: "/dashboard/admin/data-requests", label: "Data requests", description: "POPIA: people asking to correct or delete their information", icon: Inbox },
+  { href: "/dashboard/admin/privacy", label: "Privacy (POPIA)", description: "Privacy notice, operators, consent and access logs", icon: ShieldCheck },
 ] as const;
 
 type OverviewMetric = { thisMonth: number; lastMonth: number; pctChange: number | null };