Fix the production build: escape quotes in the Payments help text

The deploy's next build fails on react/no-unescaped-entities. Bump to 1.37.3; the handover now says to lint the whole frontend before tagging. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge branch 'feat/payment-status'
2026-10-23 15:57:46 +02:00 · 2026-10-23 15:28:31 +02:00 · 2026-10-23 15:28:31 +02:00 · 2026-10-23 15:28:28 +02:00 · 2026-10-23 15:05:01 +02:00 · 2026-10-23 15:05:01 +02:00
56 changed files with 2026 additions and 166 deletions
@@ -7,6 +7,35 @@ and this project follows [Semantic Versioning](https://semver.org/).

 ## [Unreleased]

+## [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
@@ -203,6 +203,14 @@ Feedback → Attendance**.
  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.
@@ -503,7 +511,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 |
-| Payments | Online payment providers: Enabled toggle and order; Yoco's 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.
@@ -558,6 +566,7 @@ 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`) |
@@ -598,7 +607,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 |
@@ -63,6 +63,9 @@ Managed in the Payments tab (through `/api/payments/providers/settings` and `/ap

 | 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. |
@@ -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,8 @@ 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
 # 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
@@ -579,6 +579,10 @@ Options and variants also accept an optional `staffPrice`, charged automatically
 | 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 |
@@ -784,6 +788,7 @@ Manages the WAWP WhatsApp API instance. Credentials are stored in `AppSetting` (

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
+| 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/webhooks/whatsapp` | — | WAWP inbound event webhook |

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

 ## Yoco

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

 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
@@ -1,12 +1,12 @@
 {
  "name": "event-management-backend",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "event-management-backend",
-      "version": "1.36.0",
+      "version": "1.37.3",
      "hasInstallScript": true,
      "dependencies": {
        "@prisma/adapter-pg": "^7.10.1",
@@ -1,6 +1,6 @@
 {
  "name": "event-management-backend",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "description": "Event Management System Backend",
  "main": "src/index.js",
  "scripts": {
@@ -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");
@@ -564,6 +564,7 @@ enum AdminAuditAction {
  yoco_webhook_registered
  yoco_webhook_deleted
  payment_providers_updated
+  payfast_config_updated
  event_sessions_changed
  attendance_marked
  attendance_unmarked
@@ -700,6 +701,9 @@ model ProviderTransaction {
  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

@@ -707,6 +711,27 @@ model ProviderTransaction {
  @@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
@@ -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 };
@@ -1010,6 +1010,8 @@ const createCheckout = async (req, res) => {
      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()}`,
    });
@@ -1,5 +1,6 @@
 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');
@@ -58,4 +59,119 @@ const updatePaymentProviderSettings = async (req, res) => {
  }
 };

-module.exports = { listPaymentProviders, getPaymentProviderSettings, updatePaymentProviderSettings };
+/** 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,
+};
@@ -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);
@@ -84,6 +84,8 @@ const createSponsorCheckout = async (req, res) => {
      cancelUrl: back,
      failureUrl: `${back}?sponsored=failed`,
      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: checkout.redirectUrl, checkoutId: checkout.checkoutId, provider: checkout.provider, amount: charge.amount });
@@ -147,6 +147,7 @@ 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');

 // Mount webhook routes BEFORE JSON body parser to avoid double-reading the stream
 app.use('/api/webhooks', webhookRoutes);
@@ -190,6 +191,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');
@@ -801,6 +803,10 @@ app.get('/docs', async (req, res) => {
      { 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 }] }}},
@@ -1071,6 +1077,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' }}},
@@ -1079,6 +1086,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 }}]},
@@ -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(),
@@ -1,8 +1,9 @@
 /**
 * 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 or the first available one
- * (./index.js); the registration remembers the checkout so the webhook can find it.
+ * 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');
@@ -76,6 +77,8 @@ async function createRegistrationCheckout(registrationId, userId, { successUrl,
    },
    lineItems,
    successUrl, cancelUrl, failureUrl,
+    payer: { name: registration.user?.name || '', email: registration.user?.email || '' },
+    description: registration.event.title,
    idempotencyKey: `reg_${registrationId}_${amountCents}_${Date.now()}`,
  });

@@ -1,29 +1,37 @@
 /**
 * Online payment providers.
 *
- * Every provider implements the same interface (see providers/yoco.js):
+ * 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<{ checkoutId, redirectUrl }>
- *                           input: { amountCents, currency, metadata, lineItems, successUrl,
- *                           cancelUrl, failureUrl, idempotencyKey }; lineItems:
- *                           [{ name, quantity, unitCents }] (negative unitCents = a deduction)
+ *   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
 *
- * Admins switch providers on and off and set their order in Site settings → Payments
- * (AppSetting `payment_providers`). People pay with the first enabled provider that's
- * configured, unless they pick one. Provider fees are never deducted or added: payments are
- * recorded at the full amount and fees are handled at cashup.
+ * 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')];
+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.
@@ -77,35 +85,94 @@ function serializeProviderSettings(list) {
  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 checkout with `providerId` (or the first available provider).
- * @returns {Promise<{ provider: string, checkoutId: string, redirectUrl: string }>}
+ * 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();
-  let provider;
  if (providerId) {
    provider = getProvider(providerId);
    if (!provider) throw paymentError('Unknown payment provider.');
-    const state = (await providerSettings()).find(p => p.id === provider.id);
-    if (!state?.enabled) throw paymentError(`Paying with ${provider.label} is turned off.`);
-  } else {
-    provider = available.length ? getProvider(available[0].id) : null;
-    if (!provider) {
-      // Nothing enabled: say so. Enabled but not configured: 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);
-    }
+    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 { checkoutId, redirectUrl } = await provider.createCheckout({ currency: 'ZAR', ...input });
-  return { provider: provider.id, checkoutId, redirectUrl };
+
+  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, createCheckout,
+  getProvider, parseProviderSettings, serializeProviderSettings, providerSettings, availableProviders,
+  payPageUrl, assertUsable, createCheckout, startCheckout, findCheckout,
 };
@@ -0,0 +1,303 @@
+/**
+ * PayFast as a payment provider (see ../index.js for the interface), using PayFast's
+ * "custom integration" (developers.payfast.co.za/docs → Custom Integration).
+ *
+ * Checkout: the payer's browser posts a signed form to https://<host>/eng/process (from our
+ * /pay/<checkoutId> page). Fields go in the order PayFast lists them; the signature is the MD5
+ * of the non-blank fields as name=value pairs (URL-encoded, upper-case escapes, spaces as '+')
+ * joined with '&', plus &passphrase=… when one is set.
+ *
+ * ITN (Instant Transaction Notification): PayFast posts the result, form-encoded, to
+ * /api/webhooks/payfast. Before trusting it we check, as PayFast requires: the signature, that
+ * it came from a PayFast host, and — by posting it back to /eng/query/validate — that PayFast
+ * says it's VALID. The amount is checked against the checkout in ../webhook.js.
+ *
+ * Status checks: when an ITN never arrives, findPayments looks the checkout up in PayFast's
+ * transaction history (its API, signed differently — see apiSignature). Refunds aren't done
+ * through the API: they're made in the PayFast dashboard and recorded with the manual flow.
+ */
+
+const crypto = require('crypto');
+const dns = require('dns').promises;
+const axios = require('axios');
+const { getPayfastConfig, payfastHost, payfastNotifyUrl } = require('../../utils/payfast');
+
+// getTransaction: payments can be looked up in PayFast's transaction history (findPayments).
+const capabilities = { refund: false, getTransaction: true, listTransactions: false };
+
+// Hosts PayFast sends ITNs from.
+const VALID_HOSTS = ['www.payfast.co.za', 'w1w.payfast.co.za', 'w2w.payfast.co.za', 'sandbox.payfast.co.za'];
+
+async function isConfigured() {
+  const c = await getPayfastConfig();
+  return !!(c.merchantId && c.merchantKey);
+}
+
+/**
+ * URL-encodes a value the way PayFast's signature expects (PHP urlencode): every character
+ * but letters, digits and -_. is %-escaped in upper case, and spaces become '+'. Checked
+ * against the sandbox: PayFast's own Node sample, which leaves ' ( ) ! * ~ as they are, is
+ * rejected for names like "Men's Camp (Youth)"; this is accepted.
+ */
+function pfEncode(value) {
+  return encodeURIComponent(String(value).trim())
+    .replace(/[!'()*~]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+    .replace(/%20/g, '+');
+}
+
+/**
+ * name=value&… of the pairs, in order. Pure. A checkout signs only the non-blank fields; an
+ * ITN is checked over every field PayFast posted, blanks included (`allFields`).
+ */
+function paramString(pairs, { allFields = false } = {}) {
+  const keep = allFields ? pairs : pairs.filter(([, v]) => v !== undefined && v !== null && String(v).trim() !== '');
+  return keep.map(([k, v]) => `${k}=${pfEncode(v ?? '')}`).join('&');
+}
+
+/** PayFast's MD5 signature over ordered pairs (and the passphrase, if any). Pure. */
+function signature(pairs, passphrase = '', opts = {}) {
+  let s = paramString(pairs, opts);
+  if (passphrase) s += `&passphrase=${pfEncode(passphrase)}`;
+  return crypto.createHash('md5').update(s).digest('hex');
+}
+
+/** Text we send PayFast (item and payer names): one line, within PayFast's length limit. Pure. */
+function cleanText(value, max) {
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/** "Camp ticket x2, T-shirt" → the item description (charged lines only). Pure. */
+function describeLines(lineItems) {
+  return (lineItems || []).filter(l => l.unitCents > 0).map(l => `${l.name}${l.quantity > 1 ? ` x${l.quantity}` : ''}`).join(', ');
+}
+
+async function createCheckout({ checkoutId, amountCents, successUrl, cancelUrl, payer, description, lineItems }) {
+  const c = await getPayfastConfig();
+  if (!c.merchantId || !c.merchantKey) {
+    const err = new Error('PayFast isn\'t set up. An admin needs to add the merchant ID and key in Site Settings → Payments → PayFast.');
+    err.statusCode = 503;
+    throw err;
+  }
+  const notifyUrl = payfastNotifyUrl();
+  const [first, ...rest] = String(payer?.name || '').trim().split(/\s+/);
+  const email = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(String(payer?.email || '')) && !String(payer.email).endsWith('.local') && !String(payer.email).endsWith('.invalid') ? payer.email : '';
+  const items = describeLines(lineItems);
+  // In the order PayFast documents them — the signature depends on it.
+  const pairs = [
+    ['merchant_id', c.merchantId],
+    ['merchant_key', c.merchantKey],
+    ['return_url', successUrl],
+    ['cancel_url', cancelUrl],
+    ['notify_url', notifyUrl],
+    ['name_first', cleanText(first, 100)],
+    ['name_last', cleanText(rest.join(' '), 100)],
+    ['email_address', email],
+    ['m_payment_id', checkoutId],
+    ['amount', (amountCents / 100).toFixed(2)],
+    ['item_name', cleanText(description || items || 'Payment', 100)],
+    ['item_description', cleanText(items, 255)],
+  ].filter(([, v]) => v !== undefined && v !== null && String(v).trim() !== '');
+  const fields = Object.fromEntries(pairs.map(([k, v]) => [k, String(v).trim()]));
+  fields.signature = signature(pairs, c.passphrase);
+  return { form: { action: `https://${payfastHost(c.mode)}/eng/process`, fields } };
+}
+
+/** The ITN's name/value pairs, decoded, in the order PayFast sent them. Pure. */
+function parsePairs(rawBody) {
+  return String(rawBody || '').split('&').filter(Boolean).map(kv => {
+    const i = kv.indexOf('=');
+    const dec = (s) => decodeURIComponent(s.replace(/\+/g, ' '));
+    return i < 0 ? [dec(kv), ''] : [dec(kv.slice(0, i)), dec(kv.slice(i + 1))];
+  });
+}
+
+function readWebhookBody(rawBody) {
+  return Object.fromEntries(parsePairs(rawBody));
+}
+
+/** The caller's IP, without IPv4-mapped-IPv6 noise (needs TRUST_PROXY behind a proxy). */
+function requestIp(req) {
+  return String(req.ip || req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
+}
+
+async function payfastIps() {
+  const all = await Promise.all(VALID_HOSTS.map(h => dns.lookup(h, { all: true }).catch(() => [])));
+  return new Set(all.flat().map(a => a.address));
+}
+
+/** PayFast's four ITN checks, less the amount (checked against the checkout in ../webhook.js). */
+async function verifyWebhook(req, { lookupIps = payfastIps, post = axios.post } = {}) {
+  const pairs = parsePairs(req.rawBody);
+  const data = Object.fromEntries(pairs);
+  if (!data.signature || !data.pf_payment_id) return { ok: false, status: 400, message: 'Not a PayFast notification' };
+
+  const c = await getPayfastConfig();
+  if (!c.merchantId) return { ok: false, status: 500, message: 'PayFast isn\'t set up' };
+  if (data.merchant_id && data.merchant_id !== c.merchantId) return { ok: false, status: 403, message: 'Notification for a different PayFast merchant' };
+
+  // 1. Signature: every posted field before the signature, in order, plus our passphrase.
+  const signed = [];
+  for (const pair of pairs) { if (pair[0] === 'signature') break; signed.push(pair); }
+  if (signature(signed, c.passphrase, { allFields: true }) !== data.signature) {
+    console.error('PayFast ITN: invalid signature');
+    return { ok: false, status: 403, message: 'Invalid signature' };
+  }
+
+  // 2. It came from PayFast.
+  if (process.env.PAYFAST_SKIP_IP_CHECK !== 'true') {
+    const ip = requestIp(req);
+    if (!(await lookupIps()).has(ip)) {
+      console.error(`PayFast ITN from ${ip}, which isn't a PayFast address (behind a proxy? set TRUST_PROXY)`);
+      return { ok: false, status: 403, message: 'Notification did not come from PayFast' };
+    }
+  }
+
+  // 3. PayFast confirms the details.
+  let reply = '';
+  try {
+    const res = await post(`https://${payfastHost(c.mode)}/eng/query/validate`, paramString(signed, { allFields: true }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, timeout: 15000 });
+    reply = String(res.data || '').trim();
+  } catch (e) {
+    console.error('PayFast ITN: could not confirm with PayFast:', e.message);
+    return { ok: false, status: 502, message: 'Could not confirm the notification with PayFast' };
+  }
+  if (reply !== 'VALID') {
+    console.error('PayFast ITN: PayFast did not confirm it:', reply.slice(0, 100));
+    return { ok: false, status: 403, message: 'PayFast did not confirm the notification' };
+  }
+
+  return { ok: true, webhookId: data.pf_payment_id, timestamp: null };
+}
+
+/** An ITN body → { type, transaction }. Pure. */
+function parseWebhook(body) {
+  const status = String(body?.payment_status || '').toUpperCase();
+  const gross = parseFloat(body?.amount_gross);
+  return {
+    type: status === 'COMPLETE' ? 'payment.succeeded' : `payment.${status.toLowerCase() || 'unknown'}`,
+    transaction: {
+      externalId: body?.pf_payment_id || null,
+      amountCents: Number.isFinite(gross) ? Math.round(gross * 100) : null,
+      currency: 'ZAR',
+      createdDate: null,
+      checkoutId: body?.m_payment_id || null,
+      // PayFast doesn't say how the payer paid; it settles like a card payment.
+      methodType: null,
+      metadata: {},
+      status: status === 'COMPLETE' ? 'succeeded' : status.toLowerCase(),
+    },
+  };
+}
+
+// ─── PayFast API (developers.payfast.co.za/api) ──────────────────────────────
+
+const API_BASE = 'https://api.payfast.co.za';
+
+/**
+ * The API signature: every header and query variable plus the passphrase, sorted
+ * alphabetically, URL-encoded, joined with '&' (not the payment form's field order). Pure.
+ */
+function apiSignature(vars) {
+  const s = Object.keys(vars).sort()
+    .filter(k => vars[k] !== undefined && vars[k] !== null && String(vars[k]) !== '')
+    .map(k => `${k}=${pfEncode(vars[k])}`).join('&');
+  return crypto.createHash('md5').update(s).digest('hex');
+}
+
+/** A signed GET to the PayFast API; the sandbox adds ?testing=true (left out of the signature). */
+async function apiGet(path, query = {}, { get = axios.get } = {}) {
+  const c = await getPayfastConfig();
+  const headers = { 'merchant-id': c.merchantId, version: 'v1', timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, '+00:00') };
+  const signature = apiSignature({ ...headers, ...query, ...(c.passphrase ? { passphrase: c.passphrase } : {}) });
+  const params = { ...query, ...(c.mode === 'live' ? {} : { testing: 'true' }) };
+  try {
+    const res = await get(`${API_BASE}${path}`, { params, headers: { ...headers, signature }, timeout: 20000, responseType: 'text', transformResponse: r => r });
+    return res.data;
+  } catch (e) {
+    const status = e.response?.status;
+    let detail = '';
+    try { detail = JSON.parse(e.response?.data || '{}')?.data?.response || ''; } catch { /* not JSON */ }
+    const err = new Error(status === 401
+      ? 'PayFast refused the merchant ID or passphrase (check they match your PayFast dashboard, and the mode).'
+      : `Could not reach PayFast${detail ? `: ${detail}` : status ? ` (${status})` : `: ${e.message}`}`);
+    err.statusCode = status === 401 ? 400 : 502;
+    throw err;
+  }
+}
+
+/** Checks the credentials with PayFast (GET /ping, signed). */
+async function testConnection(deps) {
+  await apiGet('/ping', {}, deps);
+  return true;
+}
+
+/** Rows of a CSV with a header line, as objects keyed by the header. Pure. */
+function parseCsv(text) {
+  const rows = [];
+  let row = [], field = '', quoted = false;
+  const s = String(text || '');
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (quoted) {
+      if (ch === '"' && s[i + 1] === '"') { field += '"'; i++; }
+      else if (ch === '"') quoted = false;
+      else field += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === ',') { row.push(field); field = ''; }
+    else if (ch === '\n' || ch === '\r') {
+      if (ch === '\r' && s[i + 1] === '\n') i++;
+      row.push(field); field = '';
+      if (row.some(v => v !== '')) rows.push(row);
+      row = [];
+    } else field += ch;
+  }
+  row.push(field);
+  if (row.some(v => v !== '')) rows.push(row);
+  const [header, ...data] = rows;
+  return header ? data.map(r => Object.fromEntries(header.map((h, i) => [h, r[i] ?? '']))) : [];
+}
+
+const day = (d) => new Date(d).toISOString().slice(0, 10);
+
+/**
+ * Payments PayFast received for our checkouts (from its transaction history, matched on
+ * "M Payment ID" = our checkout id). For notifications (ITNs) that never arrived.
+ * @param {object[]} checkouts - ProviderCheckout rows
+ * @returns {Promise<Map<string, object>>} checkout id → transaction (as parseWebhook gives)
+ */
+async function findPayments(checkouts, deps) {
+  const found = new Map();
+  if (!checkouts.length) return found;
+  const ids = new Set(checkouts.map(c => c.id));
+  const from = day(Math.min(...checkouts.map(c => new Date(c.createdAt).getTime())) - 24 * 60 * 60 * 1000);
+  const to = day(Date.now() + 24 * 60 * 60 * 1000);
+  const PAGE = 1000;
+  for (let offset = 0; offset < 20 * PAGE; offset += PAGE) {
+    const rows = parseCsv(await apiGet('/transactions/history', { from, to, limit: PAGE, offset }, deps));
+    for (const r of rows) {
+      const id = r['M Payment ID'];
+      if (!ids.has(id) || r.Type !== 'FUNDS_RECEIVED' || found.has(id)) continue;
+      const gross = parseFloat(String(r.Gross).replace(/,/g, ''));
+      found.set(id, {
+        externalId: r['PF Payment ID'] || null,
+        amountCents: Number.isFinite(gross) ? Math.round(gross * 100) : null,
+        currency: r.Currency || 'ZAR',
+        // PayFast's history times are South African time
+        createdDate: r.Date ? new Date(`${r.Date.replace(' ', 'T')}+02:00`) : null,
+        checkoutId: id,
+        methodType: null,
+        metadata: {},
+        status: 'succeeded',
+      });
+    }
+    if (rows.length < PAGE || found.size === ids.size) break;
+  }
+  return found;
+}
+
+module.exports = {
+  id: 'payfast', label: 'PayFast', capabilities,
+  isConfigured, createCheckout, verifyWebhook, parseWebhook, readWebhookBody, findPayments, testConnection,
+  // for tests
+  pfEncode, paramString, signature, cleanText, parsePairs, VALID_HOSTS, apiSignature, parseCsv,
+};
@@ -30,7 +30,7 @@ async function createCheckout({ amountCents, currency, metadata, lineItems, succ
  const data = await yocoRequest('post', '/checkouts', {
    amount: amountCents, currency, metadata, successUrl, cancelUrl, failureUrl, lineItems: toYocoLineItems(lineItems),
  }, undefined, idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {});
-  return { checkoutId: data.id, redirectUrl: data.redirectUrl };
+  return { externalId: data.id, redirectUrl: data.redirectUrl };
 }

 /**
@@ -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 };
@@ -5,6 +5,9 @@
 * - 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.
@@ -14,7 +17,7 @@

 const prisma = require('../config/db');
 const { v4: uuidv4 } = require('uuid');
-const { getProvider } = require('./index');
+const { getProvider, findCheckout } = require('./index');
 const { generateTicketsForRegistration } = require('../utils/ticketUtils');
 const { computeRegistrationTotalDue, refreshPricingForRegistration } = require('../utils/pricing');

@@ -29,11 +32,17 @@ const handleProviderWebhook = (providerId) => async (req, res) => {
      return res.status(verified.status).json({ success: false, message: verified.message, ...(verified.details ? { details: verified.details } : {}) });
    }

-    const body = JSON.parse(req.rawBody);
+    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 || '';
@@ -58,7 +67,7 @@ const handleProviderWebhook = (providerId) => async (req, res) => {
    // 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: receivedCheckoutId }, select: { id: true } });
+        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;
@@ -86,7 +95,11 @@ const handleProviderWebhook = (providerId) => async (req, res) => {
      });
    }

-    const processedData = await recordSucceededPayment(provider.id, event, body);
+    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`,
@@ -98,7 +111,23 @@ const handleProviderWebhook = (providerId) => async (req, res) => {
  }
 };

-const REG_INCLUDE = { event: { select: { id: true, title: true } }, user: { select: { id: true, name: true, email: true } } };
+/**
+ * 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) {
@@ -113,7 +142,8 @@ async function recordSucceededPayment(providerId, event, body) {
  }

  let registration = null;
-  if (checkoutId) registration = await prisma.registration.findFirst({ where: { checkoutId }, include: REG_INCLUDE });
+  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)
@@ -268,4 +298,4 @@ async function saveProviderTransaction(providerId, event, body, updates = {}) {
  }
 }

-module.exports = { handleProviderWebhook, recordSucceededPayment, updateRegistrationStatus, saveProviderTransaction };
+module.exports = { handleProviderWebhook, settlePayment, recordSucceededPayment, updateRegistrationStatus, saveProviderTransaction };
@@ -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;
@@ -15,12 +15,16 @@ const {
  getPaymentStats,
  sendReceipt,
 } = require('../controllers/paymentController');
-const { listPaymentProviders, getPaymentProviderSettings, updatePaymentProviderSettings } = require('../controllers/paymentProvidersController');
+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.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);
@@ -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;
@@ -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,
+};
@@ -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;
@@ -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' })]);
+  });
+});
@@ -2,33 +2,46 @@ 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(), create: jest.fn(), update: 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', () => {
@@ -58,6 +71,7 @@ describe('provider settings', () => {
 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 () => {
@@ -70,19 +84,36 @@ describe('createCheckout', () => {
    await expect(payments.createCheckout('yoco', { amountCents: 5000 })).rejects.toThrow(/Yoco is turned off/);
  });

-  test('enabled but no key: the provider explains what is missing', async () => {
+  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('uses the first available provider and passes ZAR', async () => {
+  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({ checkoutId: 'ch_1', redirectUrl: 'https://pay/1' });
-    const out = await payments.createCheckout(null, { amountCents: 5000, metadata: { a: 1 } });
-    expect(out).toEqual({ provider: 'yoco', checkoutId: 'ch_1', redirectUrl: 'https://pay/1' });
-    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ amountCents: 5000, currency: 'ZAR', metadata: { a: 1 } }));
+    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', () => {
@@ -101,8 +132,8 @@ describe('Yoco provider', () => {
  });

  test('a correctly signed webhook verifies', async () => {
-    settings({ yoco_webhook_secret: '' });
    process.env.YOCO_WEBHOOK_SECRET = SECRET;
+    settings({});
    await expect(yoco.verifyWebhook(signed(), now)).resolves.toMatchObject({ ok: true, webhookId: 'msg_1' });
  });

@@ -136,12 +167,109 @@ describe('Yoco provider', () => {
  });
 });

+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 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 };
-  };
  const response = () => {
    const res = { statusCode: 200, body: null };
    res.status = (c) => { res.statusCode = c; return res; };
@@ -150,8 +278,6 @@ describe('webhook flow', () => {
  };

  beforeEach(() => {
-    process.env.YOCO_WEBHOOK_SECRET = SECRET;
-    settings({});
    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 }));
@@ -159,41 +285,91 @@ describe('webhook flow', () => {
    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([]);
  });

-  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);
+  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({}); });

-    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('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();
+    });
  });

-  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);
+  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' } });
+    });

-    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 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('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();
+    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/) }) });
+    });
  });
 });
@@ -1,6 +1,6 @@
 # Handover — where things stand and how to carry on

-Last updated: 2026-10-23, after **1.36.0**. The plan itself is in
+Last updated: 2026-10-23, after **1.37.3**. 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).

@@ -12,21 +12,17 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 | 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.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.37.0 PayFast → 1.38.0 SnapScan → 1.39.0 Zapper** (one release each), each as a
-   provider in `backend/src/payments` (see "Where the payment code lives" below). 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. With a second
-   provider the checkout needs a provider picker (the public `GET /api/payments/providers`
-   lists the enabled ones), and "pay online" buttons should hide below R15 / when none is on.
-   Decisions: fees are **never** deducted or passed on (people handle fees at cashup);
-   minimum online payment **R15** for all providers.
-2. **1.40.0–1.41.0 — POPIA toolkit** (spec §3 in the roadmap).
-3. **1.42.0 + Hub v1** — install/update tooling and the Hope Events Hub (separate repo
+1. **1.38.0–1.39.0 — POPIA toolkit** (spec §3 in the roadmap).
+2. **1.40.0 + Hub v1** — install/update tooling and the Hope Events Hub (separate repo
   `joshua/hope-events-hub`).

 ## Working on this repo
@@ -36,6 +32,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
@@ -53,6 +50,12 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 ## 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
@@ -92,6 +95,10 @@ features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md).
 - `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
@@ -17,7 +17,10 @@ reminders, certificates); 1.34.0 job queue (pg-boss), Playwright E2E tests, Gite
 workflow (waiting for a runner) and deploy script; 1.35.0 multi-day events phase B
 (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). **Next: 1.37.0 PayFast, then SnapScan, Zapper.**
+(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).
+**Next: 1.38.0 POPIA toolkit.**

 **Repositories:**

@@ -31,7 +34,7 @@ picker at the door and session choice on "All sessions" tickets; 1.36.0 payment
 ## 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)
@@ -266,11 +269,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.
@@ -279,10 +283,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
@@ -299,10 +303,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.
@@ -725,14 +726,14 @@ 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 |
+| 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 | **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.40.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.41.0 | **Multi-campus** | Kids rooms and volunteer roles are per campus, so campuses come first |
+| 8 | 1.42.0 – 1.43.0 | Kids check-in, Volunteer rosters | Depend on sessions and campuses |
+| 9 | 1.44.0 – 1.46.0 | Event series & cloning, Wallet passes, Outbound webhooks | Smaller, independent wins |
+| 10 | 1.47.0 – 1.49.0 | Admin dashboard/Ctrl+K/bulk actions, Afrikaans, Accessibility pass | Polish before the big release |
+| 11 | 1.50.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 |

 Each phase should add matching help content (`frontend/src/content/help/`),
@@ -755,7 +756,8 @@ 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 |
@@ -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: "" });
+    }
+  });
+});
@@ -1,4 +1,4 @@
-import { test, expect, loginAs, api } from "./fixtures";
+import { test, expect, seed, loginAs, api } from "./fixtures";

 type ProviderSetting = { id: string; label: string; enabled: boolean; configured: boolean };

@@ -34,4 +34,33 @@ test.describe("payment providers", () => {
      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();
+    }
+  });
 });
@@ -1,12 +1,12 @@
 {
  "name": "hope-events-frontend",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "hope-events-frontend",
-      "version": "1.36.0",
+      "version": "1.37.3",
      "dependencies": {
        "@dnd-kit/core": "^6.3.1",
        "@hookform/resolvers": "^5.2.1",
@@ -1,6 +1,6 @@
 {
  "name": "hope-events-frontend",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack",
@@ -587,7 +587,7 @@ function EmailAttendeesPageInner() {
                        <li><code>{'{{event.title}}'}</code> — the event title.</li>
                        <li><code>{'{{event.start}}'}</code> — the event start date/time (local).</li>
                        <li><code>{'{{balance}}'}</code> — outstanding amount across the attendee’s registrations for the selected event.</li>
-                        <li><code>{'{{payment.link}}'}</code> — a direct Yoco payment link for the attendee&apos;s outstanding balance (generated per recipient when sending).</li>
+                        <li><code>{'{{payment.link}}'}</code> — a direct online payment link for the attendee&apos;s outstanding balance (generated per recipient when sending).</li>
                      </ul>
                      <p className="mb-2">Example: Hi <code>{'{{name}}'}</code>, your balance is <code>{'{{balance}}'}</code>. Pay here: <code>{'{{payment.link}}'}</code></p>
                      <p className="text-[11px] text-gray-500">To add new placeholders, extend <span className="font-mono">backend/src/utils/placeholders.js</span> and update this help.</p>
@@ -11,6 +11,8 @@ import { errorMessage } from "@/lib/utils";
 import { registrationOptionUnitPrice } from "@/lib/pricing";
 import type { Event, Payment, Registration, User } from "@/types";
 import { BackLink } from "@/components/shared/BackLink";
+import { useOnlinePayments } from "@/lib/onlinePayments";
+import { WaitingForPayment } from "@/components/payments/WaitingForPayment";

 // A donation is never mutated once created — assigning it to a registration creates a separate
 // "leg" Payment row (isDonation:false, originalPaymentId -> the donation, amount > 0) instead.
@@ -47,6 +49,8 @@ type ProviderTx = {
  methodType?: string | null;
  createdDate?: string | null;
  metadata?: { userId?: string; eventId?: string } | null;
+  // Why it wasn't recorded automatically (e.g. paid a different amount from the checkout)
+  note?: string | null;
 };

 function RegistrationOptions({ regs, regOutstanding }: {
@@ -143,6 +147,7 @@ function UserSearchField({ allUsers, value, onChange, placeholder = "Search by n

 function PaymentsContent() {
  const { user, loading, token } = useAuth();
+  const online = useOnlinePayments();
  const router = useRouter();
  const search = useSearchParams();

@@ -539,16 +544,23 @@ function PaymentsContent() {
          <ScanLine className="w-4 h-4" />
          Reconcile
        </label>
+        {/* Payment links are paid online, so only while a payment provider is on */}
+        {online.available && (
        <label className={`inline-flex items-center gap-1.5 px-3 py-1.5 text-sm rounded border ${mode === 'link' ? 'bg-brand-600 text-white border-brand-600' : 'bg-white text-gray-800 border-gray-200'} cursor-pointer`}>
          <input type="radio" name="mode" value="link" className="hidden" checked={mode==='link'} onChange={() => setMode('link')} />
          <Link2 className="w-4 h-4" />
          Payment Link
        </label>
+        )}
      </div>


      <div className="grid lg:grid-cols-3 gap-6">
        <div className="lg:col-span-2 space-y-6">
+          {mode === 'reconcile' && (
+            <WaitingForPayment token={token} onRecorded={() => { loadUnreconciled(); loadPayments(); loadRegistrations(); }} />
+          )}
+
          {/* Online payment reconciliation panel */}
          {mode === 'reconcile' && (
          <div className="border rounded-xl p-4 bg-white shadow-sm">
@@ -577,7 +589,10 @@ function PaymentsContent() {
                    <React.Fragment key={tx.id}>
                      <tr className="border-b hover:bg-gray-50">
                        <td className="py-2 pr-3 whitespace-nowrap">{tx.createdDate ? new Date(tx.createdDate).toLocaleString() : '-'}</td>
-                        <td className="py-2 pr-3">{tx.providerLabel}</td>
+                        <td className="py-2 pr-3">
+                          {tx.providerLabel}
+                          {tx.note && <div className="text-xs text-amber-800 bg-amber-50 border border-amber-200 rounded px-1.5 py-0.5 mt-1 max-w-[16rem]">{tx.note}</div>}
+                        </td>
                        <td className="py-2 pr-3 font-mono text-xs break-all max-w-[10rem]">{tx.externalId}</td>
                        <td className="py-2 pr-3">R {(Number(tx.amount || 0)/100).toFixed(2)}</td>
                        <td className="py-2 pr-3 break-all max-w-[8rem]">{tx.checkoutId || '-'}</td>
@@ -753,7 +768,7 @@ function PaymentsContent() {
            </>
          )}

-          {mode === 'link' && (
+          {mode === 'link' && online.available && (
          <div className="border rounded-xl p-4 bg-white shadow-sm">
            <div className="text-lg font-semibold mb-3">Create payment link</div>
            <div className="grid sm:grid-cols-2 gap-3">
@@ -699,7 +699,7 @@ function WhatsAppAttendeesPageInner() {
                        <li><code>{"{{event.title}}"}</code> — the event title.</li>
                        <li><code>{"{{event.start}}"}</code> — the event start date/time.</li>
                        <li><code>{"{{balance}}"}</code> — outstanding balance for the event.</li>
-                        <li><code>{"{{payment.link}}"}</code> — a direct Yoco payment link for the attendee&apos;s outstanding balance (generated per recipient when sending).</li>
+                        <li><code>{"{{payment.link}}"}</code> — a direct online payment link for the attendee&apos;s outstanding balance (generated per recipient when sending).</li>
                      </ul>
                      <p className="text-[11px] text-gray-500 mt-2">
                        Preference indicators: <span className="text-green-700 bg-green-50 px-1 rounded">WA</span> = WhatsApp only,{" "}
@@ -7,9 +7,11 @@ import { HandHeart } from "lucide-react";
 import { errorMessage } from "@/lib/utils";
 import type { Event } from "@/types";
 import { BackLink } from "@/components/shared/BackLink";
+import { useOnlinePayments } from "@/lib/onlinePayments";

 export default function DonatePage() {
  const { token } = useAuth();
+  const online = useOnlinePayments();
  const [events, setEvents] = useState<Event[]>([]);
  const [eventId, setEventId] = useState<string>("");
  const [amount, setAmount] = useState<string>("");
@@ -72,6 +74,11 @@ export default function DonatePage() {
        </div>
      </div>

+      {online.ready && !online.available ? (
+        <div className="border rounded-xl p-5 bg-white shadow-sm text-sm text-gray-700">
+          Online donations aren&apos;t available at the moment. You can give at an event, or contact the organiser.
+        </div>
+      ) : (
      <div className="border rounded-xl p-5 bg-white shadow-sm">
        {error && <p className="text-red-600 text-sm mb-3 bg-red-50 border border-red-100 rounded-lg p-2.5">{error}</p>}
        {info && <p className="text-green-700 text-sm mb-3 bg-green-50 border border-green-100 rounded-lg p-2.5">{info}</p>}
@@ -99,6 +106,7 @@ export default function DonatePage() {
          className="w-full bg-brand-600 hover:bg-brand-700 text-white px-4 py-2.5 rounded-lg disabled:opacity-60 font-medium transition-colors"
        >{loading?"Starting checkout...":"Donate"}</button>
      </div>
+      )}
    </div>
  );
 }
@@ -2,6 +2,7 @@
 import React, { useEffect, useMemo, useState } from "react";
 import { useAuth } from "@/hooks/useAuth";
 import { apiFetch, createFullPaymentCheckout } from "@/lib/api";
+import { useOnlinePayments } from "@/lib/onlinePayments";
 import { useRouter } from "next/navigation";
 import { formatDate } from "@/lib/date";
 import { printTicketCards } from "@/lib/ticketPrint";
@@ -81,6 +82,7 @@ function effectiveEventOptionUnitPrice(eo: EventOption, variantId: string | null

 export default function UserDashboardPage() {
  const { token, user } = useAuth();
+  const online = useOnlinePayments();
  const [registrations, setRegistrations] = useState<Registration[]>([]);
  const [tickets, setTickets] = useState<TicketRecord[]>([]);
  const [error, setError] = useDismissingState<string | null>(null);
@@ -313,13 +315,13 @@ export default function UserDashboardPage() {
    else sendReceipt(id, channel);
  };

-  // Creates a Yoco checkout for the full outstanding balance and redirects there directly —
+  // Creates an online checkout for the full outstanding balance and redirects there directly —
  // choosing a partial amount is only available from the supervisor payments dashboard.
  const payNow = async (registrationId: string) => {
    if (!token) return;
    setError(null);
    setInfo(null);
-    setDialog({ open: true, message: "Creating payment link…", loading: true, loadingTitle: "Creating payment link…", loadingSubtitle: "Please wait while we redirect you to Yoco." });
+    setDialog({ open: true, message: "Creating payment link…", loading: true, loadingTitle: "Creating payment link…", loadingSubtitle: "Please wait while we take you to the secure payment page." });
    try {
      const res = await createFullPaymentCheckout(token, registrationId);
      if (res.priceUpdated) {
@@ -654,10 +656,12 @@ export default function UserDashboardPage() {
            className="px-2.5 py-1 text-xs rounded bg-gray-100 hover:bg-gray-200 text-gray-800 shadow-sm focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-1"
            onClick={() => router.push("/dashboard/user/payments")}
          >Payment history</button>
-          <button
-            className="px-3 py-1.5 text-sm rounded bg-brand-600 text-white hover:bg-brand-700 shadow-sm focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-1"
-            onClick={() => router.push("/dashboard/user/donate")}
-          >Make donation</button>
+          {online.available && (
+            <button
+              className="px-3 py-1.5 text-sm rounded bg-brand-600 text-white hover:bg-brand-700 shadow-sm focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-1"
+              onClick={() => router.push("/dashboard/user/donate")}
+            >Make donation</button>
+          )}
        </div>
      </div>
      {error && <p className="text-red-600 text-sm mb-3">{error}</p>}
@@ -1194,7 +1198,7 @@ export default function UserDashboardPage() {
                  className="px-3 py-1.5 text-sm rounded bg-gray-100 hover:bg-gray-200 text-gray-800 shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-1"
                  onClick={() => setChannelPicker({ kind: 'invoice', id: activeReg.id })}
                >Invoice</button>
-                {canModifyActive && activeBill && activeBill.outstanding > 0 && (
+                {canModifyActive && activeBill && online.canPay(activeBill.outstanding) && (
                  <button
                    className="px-3 py-1.5 text-sm bg-green-600 text-white rounded hover:bg-green-700 shadow-sm focus:outline-none focus:ring-2 focus:ring-green-500 focus:ring-offset-1"
                    onClick={() => payNow(activeReg.id)}
@@ -1207,6 +1211,10 @@ export default function UserDashboardPage() {
                }}>Print all tickets</button>
              </div>

+              {canModifyActive && activeBill && activeBill.outstanding > 0 && online.reason(activeBill.outstanding) && (
+                <p className="text-xs text-gray-500">{online.reason(activeBill.outstanding)}</p>
+              )}
+
              {/* Cancel registration — only shown when no payments have been made and the event still permits changes */}
              {canModifyActive && activeReg.status !== 'cancelled' && (activeBill?.totalPaid ?? 0) === 0 && (
                <div className="pt-3 border-t mt-1">
@@ -96,7 +96,7 @@ export default function PrivacyPolicyPage() {
                            <li>We don&apos;t sell your data, and only share it with the services that process payments and deliver messages.</li>
                            <li>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.</li>
                            <li>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.</li>
-                            <li>Payments go through Yoco; we never see your card details.</li>
+                            <li>Online payments go through Yoco or PayFast; we never see your card details.</li>
                            <li>We send tickets, updates and security alerts by email and/or WhatsApp (powered by WAWP).</li>
                            <li>Visit statistics are only collected if you click &quot;Allow&quot; on the cookie notice — no third-party analytics.</li>
                            <li>You can ask what we hold about you, or delete your account, at any time. We keep data for up to 5 years after your last event registration.</li>
@@ -135,7 +135,7 @@ function Section({
            "• 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 Yoco; 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.",
+            "• 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.",
            "• Communication data: emails or messages exchanged with our team.",
            "• Visit statistics: only if you allow them on the cookie notice (see section 11).",
@@ -198,7 +198,7 @@ function Section({
        ],
        sharing: [
            "We do not sell or rent your personal information. Outside our organisation, it is shared only with:",
-            "• Yoco (a South African payment processor), to process payments securely.",
+            "• Yoco and PayFast (South African payment processors), to process payments securely — your name and email may be passed to PayFast to fill in its payment page.",
            "• WAWP (wawp.net), a WhatsApp Business API provider, to deliver WhatsApp messages — only your mobile number and the message content, solely for delivery.",
            "• Our email delivery provider, to deliver emails.",
            "• Anyone we are required to share it with under South African law.",
@@ -236,7 +236,7 @@ function Section({
            "• 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 Yoco's secure checkout page, which uses its own cookies on Yoco's site.",
+            "• 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.",
        ],
        security: [
@@ -91,7 +91,7 @@ export default function TermsOfUsePage() {
                            <li>Provide accurate information during registration and payments.</li>
                            <li>Keep your login details safe.</li>
                            <li>Respect that under 18s need parental permission to register.</li>
-                            <li>Understand that all payments go through Yoco, and we don&apos;t store your card details.</li>
+                            <li>Understand that online payments go through our payment providers (Yoco or PayFast), and we don&apos;t store your card details.</li>
                            <li>Accept that we may contact you via email and/or WhatsApp (based on your preference) about events you register for, your tickets, and account security alerts.</li>
                            <li>Only enter other people&apos;s details (when booking for them or passing on a ticket) if you&apos;re allowed to.</li>
                            <li>Where an event allows it, you can pass your ticket to someone else before the event — it moves to them once they accept, with a new QR code.</li>
@@ -140,7 +140,7 @@ function Section({
            `Accounts may also be created on your behalf — by an administrator (e.g. for walk-in event registration), or when someone registers you for an event or transfers a ticket to you. You will receive an activation link by email or WhatsApp, and can choose whether to activate the account.`,
        ],
        payments: [
-            "Payments are processed securely through Yoco, a third-party payment processor.",
+            "Online payments are processed securely by third-party payment processors (Yoco or PayFast).",
            `${orgName} does not store or process credit card information.`,
            "Payment confirmations and receipts are issued electronically.",
            "All prices are listed in South African Rand (ZAR) unless stated otherwise.",
@@ -0,0 +1,121 @@
+"use client";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { useParams } from "next/navigation";
+import { Navbar } from "@/components/layout/Navbar";
+import { Footer } from "@/components/layout/Footer";
+import { apiFetch, ApiError } from "@/lib/api";
+import { CreditCard } from "lucide-react";
+
+type ProviderForm = { action: string; fields: Record<string, string> };
+type PayPage = {
+  id: string;
+  status: "open" | "paid";
+  amount: number;
+  description: string;
+  provider: string | null;
+  providers: { id: string; label: string }[];
+  cancelUrl: string | null;
+  redirectUrl: string | null;
+  form: ProviderForm | null;
+};
+
+/**
+ * The payer's page for an online checkout (/pay/<id>): choose how to pay when several payment
+ * providers are enabled, or — for a provider that takes a signed form (PayFast) — post that
+ * form. Payment links in emails, WhatsApp and invoice QR codes can point here.
+ */
+export default function PayPage() {
+  const params = useParams<{ id: string }>();
+  const id = params?.id;
+  const [page, setPage] = useState<PayPage | null>(null);
+  const [form, setForm] = useState<ProviderForm | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const formRef = useRef<HTMLFormElement>(null);
+
+  const go = useCallback((res: { redirectUrl: string | null; form: ProviderForm | null }) => {
+    if (res.form) setForm(res.form);
+    else if (res.redirectUrl) window.location.href = res.redirectUrl;
+  }, []);
+
+  useEffect(() => {
+    if (!id) return;
+    apiFetch<PayPage>(`/api/payments/pay/${encodeURIComponent(id)}`)
+      .then(p => {
+        setPage(p);
+        if (p.status === "open") go(p);
+      })
+      .catch(e => setError(e instanceof ApiError ? e.message : "Couldn't load this payment."));
+  }, [id, go]);
+
+  // Once a provider's form is known, the browser posts it to the provider.
+  useEffect(() => { if (form) formRef.current?.submit(); }, [form]);
+
+  const choose = async (provider: string) => {
+    if (!id) return;
+    setBusy(provider);
+    setError(null);
+    try {
+      go(await apiFetch<{ redirectUrl: string | null; form: ProviderForm | null }>(`/api/payments/pay/${encodeURIComponent(id)}`, { method: "POST", body: { provider } }));
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "Couldn't start the payment. Please try again.");
+      setBusy(null);
+    }
+  };
+
+  const choosing = page?.status === "open" && !page.provider && !form;
+
+  return (
+    <div className="min-h-screen flex flex-col">
+      <Navbar />
+      <main className="flex-1 px-4 py-10 max-w-xl mx-auto w-full">
+        <div className="flex items-center gap-3 mb-4">
+          <div className="w-10 h-10 rounded-xl bg-brand-50 flex items-center justify-center shrink-0">
+            <CreditCard className="w-5 h-5 text-brand-600" />
+          </div>
+          <h1 className="text-2xl font-semibold text-gray-900">Pay online</h1>
+        </div>
+        {error && <div className="border rounded-xl p-4 mb-4 bg-red-50 text-red-800 text-sm">{error}</div>}
+        {!page && !error && <div className="text-sm text-gray-600">Loading…</div>}
+        {page && (
+          <div className="border rounded-xl p-5 bg-white shadow-sm space-y-4">
+            <div>
+              {page.description && <div className="font-semibold text-gray-900">{page.description}</div>}
+              <div className="text-2xl font-semibold mt-1">R{page.amount.toFixed(2)}</div>
+            </div>
+            {page.status === "paid" ? (
+              <p className="text-sm text-green-800 bg-green-50 border border-green-200 rounded-lg p-3">This has been paid. Thank you!</p>
+            ) : choosing ? (
+              page.providers.length === 0 ? (
+                <p className="text-sm text-amber-900 bg-amber-50 border border-amber-200 rounded-lg p-3">Online payments aren&apos;t available right now. Please pay at the door or contact the organiser.</p>
+              ) : (
+                <div className="space-y-2" role="group" aria-label="How would you like to pay?">
+                  <p className="text-sm text-gray-600">How would you like to pay?</p>
+                  {page.providers.map(p => (
+                    <button key={p.id} type="button" disabled={!!busy} onClick={() => choose(p.id)}
+                      className="w-full px-4 py-3 rounded-lg border border-brand-300 bg-white hover:bg-brand-50 text-left font-medium disabled:opacity-50">
+                      {busy === p.id ? `Taking you to ${p.label}…` : `Pay with ${p.label}`}
+                    </button>
+                  ))}
+                </div>
+              )
+            ) : (
+              <p className="text-sm text-gray-600">Taking you to the payment page…</p>
+            )}
+            {form && (
+              <form ref={formRef} method="POST" action={form.action}>
+                {Object.entries(form.fields).map(([name, value]) => <input key={name} type="hidden" name={name} value={value} />)}
+                <noscript><button type="submit" className="px-4 py-2 rounded-lg bg-brand-600 text-white text-sm font-medium">Continue to payment</button></noscript>
+                <button type="submit" className="text-sm text-brand-700 underline">Not moving? Continue to payment</button>
+              </form>
+            )}
+            {page.status === "open" && page.cancelUrl && (
+              <a href={page.cancelUrl} className="block text-sm text-gray-500 hover:underline">Cancel</a>
+            )}
+          </div>
+        )}
+      </main>
+      <Footer />
+    </div>
+  );
+}
@@ -3,6 +3,7 @@
 import React, { useEffect, useMemo, useState } from "react";
 import { useAuth } from "@/hooks/useAuth";
 import { apiFetch } from "@/lib/api";
+import { useOnlinePayments } from "@/lib/onlinePayments";
 import { CouponCodeField, AppliedCoupon } from "@/components/shared/CouponCodeField";
 import { BundleBuilder, BundleOffers, BundleSavings, useBundleQuote } from "@/components/shared/BundleDeals";
 import type { EventSession, LateJoinInfo, PublicBundle } from "@/types";
@@ -375,6 +376,7 @@ function DonationPicker({

 export default function RegisterForm({ event: baseEvent }: { event: RegisterEvent }) {
  const { token, user } = useAuth();
+  const online = useOnlinePayments();
  const eventId = baseEvent.id;

  // A waitlist claim link (?waitlist=<token>): the places held for this person are
@@ -502,12 +504,12 @@ export default function RegisterForm({ event: baseEvent }: { event: RegisterEven
  // a code, so its total wins.
  const payable = coupon ? coupon.total : bundleQuote ? bundleQuote.total : total;

-  // Optional donation on top of the tickets — paid in the same Yoco checkout and recorded
+  // Optional donation on top of the tickets — paid in the same online checkout and recorded
  // as a separate donation payment. Only offered when there's something to pay online.
  const [donationChoice, setDonationChoice] = useState<DonationChoice>({ kind: "none" });
  const [customDonation, setCustomDonation] = useState("");
  const presets = useMemo(() => donationPresets(total), [total]);
-  const showDonation = isLoggedIn && payable > 0 && !eventSoldOut;
+  const showDonation = isLoggedIn && payable > 0 && !eventSoldOut && online.available;
  const donation = !showDonation ? 0
    : donationChoice.kind === "preset" ? (presets[donationChoice.index] ?? 0)
    : donationChoice.kind === "custom" ? Math.max(0, Math.round((parseFloat(customDonation) || 0) * 100) / 100)
@@ -5,6 +5,7 @@ import { Footer } from "@/components/layout/Footer";
 import { useSearchParams, useRouter } from "next/navigation";
 import { useAuth } from "@/hooks/useAuth";
 import { CheckCircle2 } from "lucide-react";
+import { useOnlinePayments } from "@/lib/onlinePayments";
 import { errorMessage } from "@/lib/utils";
 import type { Registration } from "@/types";

@@ -21,7 +22,7 @@ function RegistrationSuccessContent() {
    return isNaN(n) ? 0 : n;
  }, [fallbackTotalParam]);

-  // Optional donation picked on the register form; added to the Yoco checkout as its own line.
+  // Optional donation picked on the register form; added to the online checkout as its own line.
  const donationParam = search.get("donation");
  const donation = React.useMemo(() => {
    const n = donationParam ? Number(donationParam) : 0;
@@ -67,7 +68,7 @@ function RegistrationSuccessContent() {
  }, [reg]);

  React.useEffect(() => {
-    // If free registration, do not show Yoco and redirect to dashboard after a short delay
+    // If free registration, don't offer online payment and redirect to dashboard after a short delay
    if (reg && totalDue === 0) {
      // attempt ticket generation if status is paid (may fail if required forms aren't completed)
      (async () => {
@@ -108,6 +109,11 @@ function RegistrationSuccessContent() {
    }
  };

+  const online = useOnlinePayments();
+  const owed = totalDue > 0 || (!reg && fallbackTotalDue > 0);
+  const payAmount = (reg ? totalDue : fallbackTotalDue) + donation;
+  const payOnline = owed && online.canPay(payAmount);
+
  const goDashboard = () => {
    router.push("/dashboard/user");
  };
@@ -129,29 +135,31 @@ function RegistrationSuccessContent() {
              <div className="font-medium">This event requires attendee details.</div>
              <div className="text-sm">Please complete one form per main ticket to receive tickets. You can also do this later from your dashboard, but tickets cannot be generated until completed.</div>
            </div>
-          ) : (totalDue > 0 || (!reg && fallbackTotalDue > 0)) ? (
+          ) : payOnline ? (
            <>
              {donation > 0 && (
                <p className="text-gray-700 mb-2">
                  Thank you for adding a donation of <strong>R{donation.toFixed(2)}</strong>. It&apos;s included when you pay now.
                </p>
              )}
-              <p className="text-gray-700 mb-6">Would you like to pay with Yoco now?</p>
+              <p className="text-gray-700 mb-6">Would you like to pay online now?</p>
            </>
+          ) : owed && online.reason(payAmount) ? (
+            <p className="text-gray-700 mb-6">{online.reason(payAmount)}</p>
          ) : null}

          <div className="flex flex-col sm:flex-row gap-3 mt-4">
-            {(totalDue > 0 || (!reg && fallbackTotalDue > 0)) && (
+            {payOnline && (
              <button
                onClick={goPay}
                disabled={!registrationId || payLoading}
                className="px-4 py-2 rounded bg-green-600 text-white disabled:opacity-60"
-              >{payLoading ? "Creating checkout..." : "Pay with Yoco"}</button>
+              >{payLoading ? "Creating checkout..." : "Pay online"}</button>
            )}
            <button
              onClick={goDashboard}
              className="px-4 py-2 rounded bg-gray-100 text-gray-800 hover:bg-gray-200"
-            >{(totalDue > 0 || (!reg && fallbackTotalDue > 0)) ? "Go to Dashboard (Pay Later)" : "Go to Dashboard"}</button>
+            >{payOnline ? "Go to Dashboard (Pay Later)" : "Go to Dashboard"}</button>
          </div>
          {error && <p className="text-sm text-red-600 mt-3">{error}</p>}
          {!registrationId && (
@@ -0,0 +1,165 @@
+"use client";
+
+import React, { useCallback, useEffect, useState } from "react";
+import { useAuth } from "@/hooks/useAuth";
+import { apiFetch } from "@/lib/api";
+import { useDismissingState } from "@/hooks/useDismissingState";
+import { Wallet } from "lucide-react";
+import { errorMessage } from "@/lib/utils";
+
+interface PayFastConfig {
+  merchantId: string;
+  merchantKey: string;
+  passphraseMasked: string;
+  hasPassphrase: boolean;
+  mode: "sandbox" | "live";
+  notifyUrl: string;
+  notifyUrlProblem: string | null;
+  configured: boolean;
+}
+
+const inputCls = "w-full border rounded-lg px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-brand-400";
+const primaryBtn = "px-3 py-1.5 text-sm rounded-lg bg-brand-600 hover:bg-brand-700 disabled:opacity-50 text-white font-medium";
+
+/**
+ * PayFast settings (Site settings → Payments, while PayFast is enabled): merchant ID and key,
+ * the passphrase that signs payments (stored encrypted), and sandbox or live.
+ * onChanged: called after a save, so the Payments tab can refresh whether PayFast is set up.
+ */
+export function PayFastSettings({ active, onChanged }: { active: boolean; onChanged?: () => void }) {
+  const { token } = useAuth();
+  const [cfg, setCfg] = useState<PayFastConfig | null>(null);
+  const [merchantId, setMerchantId] = useState("");
+  const [merchantKey, setMerchantKey] = useState("");
+  const [passphrase, setPassphrase] = useState("");
+  const [mode, setMode] = useState<"sandbox" | "live">("sandbox");
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useDismissingState<{ type: "ok" | "err"; text: string } | null>(null);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    try {
+      const c = await apiFetch<PayFastConfig>("/api/payfast/config", { authToken: token });
+      setCfg(c);
+      setMerchantId(c.merchantId);
+      setMerchantKey(c.merchantKey);
+      setMode(c.mode);
+      setPassphrase("");
+    } catch (e) {
+      setMessage({ type: "err", text: errorMessage(e) || "Failed to load PayFast settings" });
+    }
+  }, [token, setMessage]);
+
+  useEffect(() => { if (active) load(); }, [active, load]);
+
+  const save = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!token) return;
+    setSaving(true);
+    try {
+      await apiFetch("/api/payfast/config", {
+        method: "PUT", authToken: token,
+        // An empty passphrase box keeps the saved one.
+        body: { merchantId, merchantKey, mode, ...(passphrase ? { passphrase } : {}) },
+      });
+      setMessage({ type: "ok", text: "PayFast settings saved." });
+      await load();
+      onChanged?.();
+    } catch (err) {
+      setMessage({ type: "err", text: errorMessage(err) || "Could not save" });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const [testing, setTesting] = useState(false);
+  // Checks the saved merchant ID and passphrase with PayFast (a signed API ping).
+  const test = async () => {
+    if (!token) return;
+    setTesting(true);
+    try {
+      const res = await apiFetch<{ message: string }>("/api/payfast/test", { method: "POST", authToken: token });
+      setMessage({ type: "ok", text: res.message });
+    } catch (err) {
+      setMessage({ type: "err", text: errorMessage(err) || "PayFast didn't accept the settings" });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  const removePassphrase = async () => {
+    if (!token || !window.confirm("Remove the passphrase? Only do this if it's also removed on your PayFast dashboard.")) return;
+    try {
+      await apiFetch("/api/payfast/config", { method: "PUT", authToken: token, body: { passphrase: "" } });
+      setMessage({ type: "ok", text: "Passphrase removed." });
+      await load();
+    } catch (err) {
+      setMessage({ type: "err", text: errorMessage(err) || "Could not remove it" });
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-3">
+        <div className="w-9 h-9 rounded-lg bg-brand-50 flex items-center justify-center shrink-0">
+          <Wallet className="w-4 h-4 text-brand-600" />
+        </div>
+        <div>
+          <h2 className="text-lg font-semibold text-gray-900">PayFast payments</h2>
+          <p className="text-xs text-gray-500">Card, instant EFT and more through PayFast. Find these on your PayFast (or Sandbox) dashboard under Settings.</p>
+        </div>
+      </div>
+
+      {message && (
+        <div className={`text-sm p-2.5 rounded-lg ${message.type === "ok" ? "bg-green-50 text-green-700" : "bg-red-50 text-red-700"}`}>{message.text}</div>
+      )}
+
+      {!cfg ? (
+        <p className="text-sm text-gray-400">Loading…</p>
+      ) : (
+        <form onSubmit={save} className="border rounded-lg p-4 space-y-3">
+          <div className="grid sm:grid-cols-2 gap-3">
+            <div>
+              <label className="block text-xs font-medium text-gray-700 mb-1" htmlFor="pf-merchant-id">Merchant ID</label>
+              <input id="pf-merchant-id" className={inputCls} value={merchantId} onChange={e => setMerchantId(e.target.value)} inputMode="numeric" placeholder="From your PayFast dashboard" />
+            </div>
+            <div>
+              <label className="block text-xs font-medium text-gray-700 mb-1" htmlFor="pf-merchant-key">Merchant key</label>
+              <input id="pf-merchant-key" className={inputCls} value={merchantKey} onChange={e => setMerchantKey(e.target.value)} placeholder="From your PayFast dashboard" />
+            </div>
+          </div>
+          <div>
+            <label className="block text-xs font-medium text-gray-700 mb-1" htmlFor="pf-passphrase">Salt passphrase</label>
+            <input id="pf-passphrase" type="password" autoComplete="off" className={inputCls} value={passphrase} onChange={e => setPassphrase(e.target.value)}
+              placeholder={cfg.hasPassphrase ? `Saved (${cfg.passphraseMasked}) — type to replace` : "The passphrase set on your PayFast dashboard"} />
+            <p className="text-xs text-gray-500 mt-1">
+              Must match the one on your PayFast dashboard exactly, or payments are refused. Stored encrypted.
+              {cfg.hasPassphrase && <> <button type="button" className="underline" onClick={removePassphrase}>Remove</button></>}
+            </p>
+          </div>
+          <div>
+            <span className="block text-xs font-medium text-gray-700 mb-1">Mode</span>
+            <div className="flex gap-4 text-sm" role="radiogroup" aria-label="PayFast mode">
+              <label className="flex items-center gap-1.5"><input type="radio" name="pf-mode" checked={mode === "sandbox"} onChange={() => setMode("sandbox")} /> Sandbox (testing)</label>
+              <label className="flex items-center gap-1.5"><input type="radio" name="pf-mode" checked={mode === "live"} onChange={() => setMode("live")} /> Live</label>
+            </div>
+            {mode === "live" && <p className="text-xs text-amber-700 mt-1">Live takes real money. Use your live merchant ID, key and passphrase — the sandbox ones won&apos;t work.</p>}
+          </div>
+          <div className="text-xs text-gray-600">
+            Payment notifications go to <span className="font-mono break-all">{cfg.notifyUrl || "(not set)"}</span>.
+            {cfg.notifyUrlProblem && <p className="text-amber-700 mt-1">{cfg.notifyUrlProblem}</p>}
+          </div>
+          <div className="flex flex-wrap gap-2">
+            <button type="submit" className={primaryBtn} disabled={saving}>{saving ? "Saving…" : "Save PayFast settings"}</button>
+            {cfg.configured && (
+              <button type="button" className="px-3 py-1.5 text-sm rounded-lg bg-gray-100 hover:bg-gray-200 disabled:opacity-50" disabled={testing} onClick={test}>
+                {testing ? "Testing…" : "Test connection"}
+              </button>
+            )}
+          </div>
+          <p className="text-xs text-gray-500">Test connection checks the saved settings — save any changes first.</p>
+        </form>
+      )}
+    </div>
+  );
+}
@@ -7,6 +7,7 @@ import { apiFetch } from "@/lib/api";
 import { useDismissingState } from "@/hooks/useDismissingState";
 import { errorMessage } from "@/lib/utils";
 import { YocoTab } from "@/components/admin/YocoTab";
+import { PayFastSettings } from "@/components/admin/PayFastSettings";

 type ProviderSetting = { id: string; label: string; enabled: boolean; configured: boolean };

@@ -119,6 +120,11 @@ export function PaymentsTab({ active }: { active: boolean }) {
          <YocoTab active={active} onChanged={load} />
        </div>
      )}
+      {providers?.some(p => p.id === "payfast" && p.enabled) && (
+        <div className="border-t pt-5">
+          <PayFastSettings active={active} onChanged={load} />
+        </div>
+      )}
    </div>
  );
 }
@@ -5,6 +5,7 @@ import { HeartHandshake, X } from "lucide-react";
 import { apiFetch } from "@/lib/api";
 import { useAuth } from "@/hooks/useAuth";
 import { errorMessage } from "@/lib/utils";
+import { useOnlinePayments } from "@/lib/onlinePayments";

 type Sponsorship = { enabled: boolean; open?: boolean; spotPrice?: number | null; showProgress?: boolean; goalSpots?: number | null; spotsFunded?: number | null; sponsors?: number | null };

@@ -14,7 +15,7 @@ const rand = (n: number) => `R${n.toLocaleString("en-ZA", { minimumFractionDigit
 /**
 * "Sponsor a spot": progress towards the event's sponsorship goal, and a form to fund
 * one or more spots (or any amount) for people who can't afford to come. Payment is
- * through Yoco; the money lands in the event's sponsorship pool.
+ * online; the money lands in the event's sponsorship pool.
 */
 export function SponsorSpot({ eventId, eventTitle }: { eventId: string; eventTitle: string }) {
  const { token, user } = useAuth();
@@ -30,6 +31,7 @@ export function SponsorSpot({ eventId, eventTitle }: { eventId: string; eventTit
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [returned, setReturned] = useState<string | null>(null);
+  const online = useOnlinePayments();

  useEffect(() => {
    apiFetch<Sponsorship>(`/api/sponsorships/event/${encodeURIComponent(eventId)}`).then(setData).catch(() => setData(null));
@@ -39,7 +41,8 @@ export function SponsorSpot({ eventId, eventTitle }: { eventId: string; eventTit
    } catch { /* no window */ }
  }, [eventId]);

-  if (!data?.enabled) return null;
+  // Sponsoring is paid online, so it's offered only when online payment is possible.
+  if (!data?.enabled || (!online.available && !returned)) return null;
  const price = data.spotPrice || null;
  const loggedIn = !!(token && user);
  const total = mode === "spots" && price ? spots * price : Number(amount) || 0;
@@ -0,0 +1,137 @@
+"use client";
+
+import React, { useCallback, useEffect, useState } from "react";
+import { apiFetch } from "@/lib/api";
+import { errorMessage } from "@/lib/utils";
+
+type OpenCheckout = {
+  id: string;
+  provider: string;
+  providerLabel: string;
+  canCheck: boolean;
+  amount: number;
+  description: string;
+  type: string | null;
+  registrationId: string | null;
+  payer: string | null;
+  createdAt: string;
+};
+type CheckResult = { status: "paid" | "recorded" | "needs_review" | "not_paid" | "cant_check"; note?: string };
+
+const RESULT_TEXT: Record<CheckResult["status"], string> = {
+  paid: "Already paid",
+  recorded: "Payment found and recorded",
+  needs_review: "Paid a different amount — see Unreconciled below",
+  not_paid: "Not paid (yet)",
+  cant_check: "Can't check — look in the provider's portal",
+};
+
+/**
+ * Online checkouts from the last 14 days with no payment yet (Payments → Reconcile). For when a
+ * provider's notification never arrived: "Check status" asks the provider and records any
+ * payment it received. A background job does the same every 15 minutes.
+ */
+export function WaitingForPayment({ token, onRecorded }: { token: string | null; onRecorded: () => void }) {
+  const [list, setList] = useState<OpenCheckout[] | null>(null);
+  const [results, setResults] = useState<Record<string, CheckResult>>({});
+  const [busy, setBusy] = useState<string | null>(null);
+  const [message, setMessage] = useState<{ ok: boolean; text: string } | null>(null);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    try {
+      const res = await apiFetch<{ checkouts: OpenCheckout[] }>("/api/payments/checkouts/open", { authToken: token });
+      setList(res.checkouts);
+    } catch (e) {
+      setMessage({ ok: false, text: errorMessage(e) || "Couldn't load waiting payments" });
+    }
+  }, [token]);
+  useEffect(() => { load(); }, [load]);
+
+  const check = async (ids?: string[]) => {
+    if (!token) return;
+    setBusy(ids?.[0] || "all");
+    setMessage(null);
+    try {
+      const res = await apiFetch<{ results: Record<string, CheckResult>; recorded: number; message: string }>("/api/payments/checkouts/check", {
+        method: "POST", authToken: token, body: ids ? { ids } : {},
+      });
+      setResults(r => ({ ...r, ...res.results }));
+      setMessage({ ok: true, text: res.message });
+      if (res.recorded > 0) onRecorded();
+    } catch (e) {
+      setMessage({ ok: false, text: errorMessage(e) || "Couldn't check" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const checkable = (list || []).some(c => c.canCheck);
+
+  return (
+    <div className="border rounded-xl p-4 bg-white shadow-sm">
+      <div className="flex items-center justify-between gap-2 mb-1">
+        <div className="text-lg font-semibold">Waiting for payment</div>
+        <div className="flex gap-2">
+          {checkable && (
+            <button className="px-3 py-1.5 text-sm rounded bg-brand-600 hover:bg-brand-700 text-white disabled:opacity-50" disabled={!!busy} onClick={() => check()}>
+              {busy === "all" ? "Checking…" : "Check all"}
+            </button>
+          )}
+          <button className="px-3 py-1.5 text-sm rounded bg-gray-100 hover:bg-gray-200 text-gray-800" onClick={() => { setResults({}); load(); }}>Refresh</button>
+        </div>
+      </div>
+      <p className="text-xs text-gray-500 mb-3">
+        Online payments started in the last 14 days that haven&apos;t been confirmed. If the provider&apos;s notification didn&apos;t arrive, check the status here — PayFast payments are also checked automatically every 15 minutes.
+      </p>
+      {message && <div className={`text-sm mb-3 p-2 rounded ${message.ok ? "bg-green-50 text-green-800" : "bg-red-50 text-red-700"}`}>{message.text}</div>}
+      {!list ? (
+        <div className="text-sm text-gray-500">Loading…</div>
+      ) : list.length === 0 ? (
+        <div className="text-sm text-gray-500">Nothing waiting.</div>
+      ) : (
+        <div className="overflow-x-auto w-full">
+          <table className="min-w-full text-sm">
+            <thead>
+              <tr className="text-left border-b">
+                <th className="py-2 pr-3">Started</th>
+                <th className="py-2 pr-3">Payer</th>
+                <th className="py-2 pr-3">For</th>
+                <th className="py-2 pr-3">Amount</th>
+                <th className="py-2 pr-3">Provider</th>
+                <th className="py-2">Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {list.map(c => {
+                const result = results[c.id];
+                return (
+                  <tr key={c.id} className="border-b align-top">
+                    <td className="py-2 pr-3 whitespace-nowrap">{new Date(c.createdAt).toLocaleString()}</td>
+                    <td className="py-2 pr-3">{c.payer || "—"}</td>
+                    <td className="py-2 pr-3">{c.description || (c.type === "donation" ? "Donation" : "—")}</td>
+                    <td className="py-2 pr-3 whitespace-nowrap">R {c.amount.toFixed(2)}</td>
+                    <td className="py-2 pr-3">{c.providerLabel}</td>
+                    <td className="py-2">
+                      {result ? (
+                        <span className={result.status === "recorded" || result.status === "paid" ? "text-green-700" : result.status === "needs_review" ? "text-amber-800" : "text-gray-600"}>
+                          {RESULT_TEXT[result.status]}
+                        </span>
+                      ) : c.canCheck ? (
+                        <button className="px-2 py-1 rounded border border-brand-300 text-brand-700 hover:bg-brand-50 disabled:opacity-50" disabled={!!busy} onClick={() => check([c.id])}>
+                          {busy === c.id ? "Checking…" : "Check status"}
+                        </button>
+                      ) : (
+                        <span className="text-xs text-gray-500">Can&apos;t check automatically — look in the {c.providerLabel} portal, then use Reconcile</span>
+                      )}
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}
@@ -17,7 +17,7 @@ export const dashboardUserDonateHelpContent: HelpContent = {
      icon: HandHeart,
      content: (
        <div className="space-y-4">
-          <p>Pick an event to support and an amount (minimum R15), then you&apos;ll be redirected to a secure Yoco checkout to complete payment.</p>
+          <p>Pick an event to support and an amount (minimum R15), then you&apos;ll be taken to a secure online checkout to complete payment.</p>
          <GuideItem icon={HandHeart} title="Not tied to a registration" tone="rose">
            A donation is separate from paying for your own ticket — it&apos;s a direct contribution, and it isn&apos;t required to register for or attend an event.
          </GuideItem>
@@ -26,7 +26,7 @@ export const eventDetailHelpContent: HelpContent = {
              &quot;N remaining&quot; appears once stock runs low, and &quot;Sold out&quot; once an option is fully booked. Some events have a waitlist: tap &quot;Join waitlist&quot; and you&apos;ll be emailed or WhatsApped a link to claim a place if one opens up (it&apos;s held for you for a limited time).
            </GuideItem>
            <GuideItem icon={HeartHandshake} title="Sponsor a spot" tone="rose">
-              Some events let you pay for a place for someone who can&apos;t afford it. Tap &quot;Sponsor a spot&quot;, choose one or more spots (or any amount), and pay securely with Yoco. You can give anonymously or add a name and a message for the organisers. You&apos;ll get a receipt, and who is helped is never shared.
+              Some events let you pay for a place for someone who can&apos;t afford it. Tap &quot;Sponsor a spot&quot;, choose one or more spots (or any amount), and pay securely online. You can give anonymously or add a name and a message for the organisers. You&apos;ll get a receipt, and who is helped is never shared.
            </GuideItem>
            <GuideItem icon={Users} title="Registering for other people?" tone="violet">
              Some events let you name each person you&apos;re booking for. Each named person gets their own ticket and their own attendee form, and you can choose to have every ticket sent to you or each person their own. On youth events, you&apos;ll give each person&apos;s date of birth; for anyone under 18, their parent or guardian is asked to give consent by email and WhatsApp before they can be checked in.
@@ -110,6 +110,9 @@ export const siteSettingsHelpContent: HelpContent = {
            <GuideItem icon={KeyRound} title="Yoco" tone="green">
              Shown while Yoco is ticked. Paste the secret key, then generate the webhook (or enter its secret) so payments are confirmed automatically. Secrets are stored encrypted and never shown in full.
            </GuideItem>
+            <GuideItem icon={KeyRound} title="PayFast" tone="green">
+              Shown while PayFast is ticked. Enter the merchant ID, merchant key and salt passphrase from your PayFast dashboard (Settings), and choose Sandbox to test or Live for real payments. The passphrase must match the dashboard exactly — save, then use Test connection to check. When more than one provider is ticked, payers choose how to pay.
+            </GuideItem>
            <GuideItem icon={CreditCard} title="Minimum and fees" tone="gray">
              Online payments must be at least R15. Payments are recorded at the full amount paid; provider fees aren&apos;t deducted or added to the payer&apos;s total — deal with them at cashup.
            </GuideItem>
@@ -25,7 +25,7 @@ export const supervisorPaymentsHelpContent: HelpContent = {
              Assign an unassigned donation to a registration with an outstanding balance. Donations can be partially allocated, leaving the remainder available for another registration. Money from &quot;Sponsor a spot&quot; is marked as a sponsorship. Tick &quot;Only the sponsorship pool&quot; to assign just those, and you&apos;ll see the sponsor&apos;s message. The Donations breakdown report shows each event&apos;s pool: received, assigned and remaining.
            </GuideItem>
            <GuideItem icon={ScanLine} title="Reconcile" tone="green">
-              Match unreconciled online payments (from Yoco, or another payment provider) to a registration, log them as a donation, or ignore them.
+              Match unreconciled online payments (from Yoco, PayFast…) to a registration, log them as a donation, or ignore them. A payment of a different amount from its checkout lands here with a note — check it in the provider&apos;s dashboard first. &quot;Waiting for payment&quot; lists online checkouts with no payment yet: if someone paid but it hasn&apos;t shown up, press Check status (PayFast) — it&apos;s also checked automatically every 15 minutes. Yoco can&apos;t be checked automatically: find the payment in the Yoco portal.
            </GuideItem>
            <GuideItem icon={Link2} title="Payment Link" tone="violet">
              Generate an online payment link for a user — copy it or send by email/WhatsApp. It uses the default payment provider (Site settings → Payments). Online payments must be at least R15. Generating a new link invalidates the previous one.
@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { apiFetch } from "@/lib/api";
+
+type ProvidersResponse = { providers: { id: string; label: string }[]; minimumAmount: number };
+
+export type OnlinePayments = {
+  /** The answer has arrived (until then, nothing offers online payment). */
+  ready: boolean;
+  /** At least one payment provider is switched on and set up. */
+  available: boolean;
+  /** Online payments must be at least this much (R15). */
+  minimum: number;
+  /** Whether `amount` can be paid online now. */
+  canPay: (amount: number) => boolean;
+  /** Why `amount` can't be paid online, for showing instead of the button; null when it can. */
+  reason: (amount: number) => string | null;
+};
+
+// One request per page load, shared by every component that asks.
+let pending: Promise<ProvidersResponse | null> | null = null;
+function load() {
+  if (!pending) pending = apiFetch<ProvidersResponse>("/api/payments/providers").catch(() => null);
+  return pending;
+}
+
+/**
+ * Whether people can pay online: only when a payment provider is enabled (Site settings →
+ * Payments) and the amount is at least the online minimum. "Pay online" buttons use this to
+ * stay hidden otherwise.
+ */
+export function useOnlinePayments(): OnlinePayments {
+  const [state, setState] = useState<{ ready: boolean; available: boolean; minimum: number }>({ ready: false, available: false, minimum: 15 });
+
+  useEffect(() => {
+    let cancelled = false;
+    load().then(res => {
+      if (!cancelled) setState({ ready: true, available: !!res && res.providers.length > 0, minimum: res?.minimumAmount ?? 15 });
+    });
+    return () => { cancelled = true; };
+  }, []);
+
+  const canPay = (amount: number) => state.ready && state.available && amount >= state.minimum;
+  const reason = (amount: number) => {
+    if (!state.ready || canPay(amount)) return null;
+    if (!state.available) return "Online payment isn't available at the moment. You can pay at the event, or contact the organiser.";
+    return `Online payments must be at least R${state.minimum}. You can pay this at the event.`;
+  };
+  return { ...state, canPay, reason };
+}
@@ -1,12 +1,12 @@
 {
  "name": "hope-events",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "hope-events",
-      "version": "1.36.0",
+      "version": "1.37.3",
      "license": "ISC",
      "devDependencies": {
        "@playwright/test": "^1.64.0",
@@ -1,6 +1,6 @@
 {
  "name": "hope-events",
-  "version": "1.36.0",
+  "version": "1.37.3",
  "main": "index.js",
  "scripts": {
    "dev:backend": "cd backend && npm run dev",
Author	SHA1	Message	Date
joshuaandClaude Opus 5.5	4cae0fc672	Fix the production build: escape quotes in the Payments help text CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details The deploy's next build fails on react/no-unescaped-entities. Bump to 1.37.3; the handover now says to lint the whole frontend before tagging. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 15:57:46 +02:00
joshua	cd33ba281e	Merge branch 'feat/payment-status' CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details	2026-10-23 15:28:31 +02:00
joshuaandClaude Opus 5.5	220dafb400	Bump to 1.37.2 CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 15:28:31 +02:00
joshuaandClaude Opus 5.5	eb0f390215	Payment status checks for notifications that never arrive - src/payments/status.js: open checkouts, checkCheckouts and the payment-status job (every 15 min, checkouts 10 min - 3 days old). Found payments are settled exactly as their webhook would be (settlePayment, extracted from the webhook handler: amount check, record, emails). - PayFast: signed API client (alphabetical signature, testing=true in sandbox), findPayments from the transaction history CSV matched on M Payment ID, and testConnection (signed /ping). Verified against a real sandbox account. - Yoco documents no checkout lookup, so its checkouts are "can't check". - Payments -> Reconcile: "Waiting for payment" with Check status / Check all; PayFast card: Test connection. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 15:28:28 +02:00
joshua	55a7ee2970	Merge branch 'feat/hide-pay-online' CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details	2026-10-23 15:05:01 +02:00
joshuaandClaude Opus 5.5	4bc7dbc989	Bump to 1.37.1 CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 15:05:01 +02:00
joshuaandClaude Opus 5.5	71b9da2458	Hide "Pay online" when no provider is on or the amount is under R15 A shared useOnlinePayments hook (GET /api/payments/providers) gates the registration success page, My Events (Make payment, Make donation), the donate page, Sponsor a spot, the register form's donation box and the supervisor Payment Link tab; they explain why where it helps. Roadmap: SnapScan and Zapper dropped; later versions move up by two. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 15:04:58 +02:00
joshua	654f51b86d	Merge branch 'feat/payfast' CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details	2026-10-23 14:26:09 +02:00
joshuaandClaude Opus 5.5	aeb5d6d678	Bump to 1.37.0 CI / Backend tests (push) Canceled after 0s Details CI / Frontend lint, typecheck, build (push) Canceled after 0s Details CI / End-to-end tests (push) Canceled after 0s Details CI / Deploy tagged release (push) Canceled after 0s Details Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 14:26:09 +02:00
joshuaandClaude Opus 5.5	f2b51dbd88	PayFast provider, Pay online page, amount checks on payments - PayFast (custom integration): signed form (PHP-style encoding, checked against a real sandbox), ITN checks (signature over all posted fields, PayFast host, VALID from /eng/query/validate, amount vs checkout). - ProviderCheckout records every checkout (amount, metadata, request); webhooks match payments to it and hold a different amount for review (ProviderTransaction.note). - /pay/<id>: payers choose a provider when several are on, and the browser posts PayFast's form from there, so payment links work for every provider. - Site settings → Payments: PayFast card (merchant ID/key, encrypted passphrase, sandbox/live) while PayFast is enabled. - Payer-facing wording no longer names Yoco; legal pages name both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-23 14:25:49 +02:00