From 1d2a87e83716108b47d68e85af2f941b6b548552 Mon Sep 17 00:00:00 2001
From: mahmutkaya <mahmutkaya.nl@gmail.com>
Date: Sat, 5 Sep 2026 21:46:24 +0200
Subject: [PATCH 1/2] feat(payments): the restaurant's own onboarding page,
 minting a fresh Stripe link per request (E4)

---
 .../onboarding/payments/[token]/page.tsx      | 76 +++++++++++++++++
 lib/connect-account-links.ts                  | 64 ++++++++++++++
 lib/connect-account-store.ts                  | 54 +++++++++++-
 lib/onboarding-payments.ts                    | 76 +++++++++++++++++
 lib/stripe-connect-accounts.ts                | 33 +++++++-
 messages/ar.json                              |  9 ++
 messages/de.json                              |  9 ++
 messages/en.json                              |  9 ++
 messages/fr.json                              |  9 ++
 messages/nl.json                              |  9 ++
 messages/tr.json                              |  9 ++
 .../migration.sql                             | 35 ++++++++
 prisma/schema.prisma                          | 12 +++
 tests/unit/connect-account-links.test.ts      | 83 +++++++++++++++++++
 tests/unit/connect-account-store.test.ts      |  7 ++
 vitest.config.ts                              |  5 ++
 16 files changed, 496 insertions(+), 3 deletions(-)
 create mode 100644 app/[locale]/onboarding/payments/[token]/page.tsx
 create mode 100644 lib/connect-account-links.ts
 create mode 100644 lib/onboarding-payments.ts
 create mode 100644 prisma/migrations/20260905210000_connect_account_onboarding_token/migration.sql
 create mode 100644 tests/unit/connect-account-links.test.ts

diff --git a/app/[locale]/onboarding/payments/[token]/page.tsx b/app/[locale]/onboarding/payments/[token]/page.tsx
new file mode 100644
index 0000000..b501730
--- /dev/null
+++ b/app/[locale]/onboarding/payments/[token]/page.tsx
@@ -0,0 +1,76 @@
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import Header from "@/components/Header";
+import Footer from "@/components/Footer";
+import { SITE_URL } from "@/lib/seo";
+import { resolvePaymentsLink } from "@/lib/onboarding-payments";
+
+// RUNTIME, never prerendered, and never indexed.
+//
+// Every request must mint a NEW Stripe Account Link: one lives 300 seconds
+// (measured), and two calls return two different URLs. A cached page would hand
+// a restaurant a dead link and a static one could not exist at all. `noindex` for
+// the obvious reason — the URL is the credential.
+export const dynamic = "force-dynamic";
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "onboardingPayments" });
+  return { title: t("meta.title"), robots: { index: false, follow: false } };
+}
+
+/**
+ * The one door between a restaurant and Stripe's hosted onboarding (ADR-011
+ * amendment, E4).
+ *
+ * UNAUTHENTICATED by necessity, and that is why the path carries a 32-byte token
+ * rather than a slug: the restaurant has no login here — they log into their own
+ * tenant app, never into the control plane — and the link this page produces is a
+ * bearer capability over their KYC and their payout bank account. CLAUDE.md §5.1
+ * governs the `(control)` plane; this page is deliberately NOT in it. It is on the
+ * public site, beside `/signup`, because its visitor is a member of the public,
+ * and it holds the same obligation the five unauthenticated control surfaces
+ * hold: it answers the same way to every wrong input, so it cannot be asked
+ * whether a token is nearly right.
+ *
+ * It never renders a Stripe URL and never stores one. On success it redirects; the
+ * body below only exists for the two states where it cannot.
+ */
+export default async function OnboardingPaymentsPage({
+  params,
+}: {
+  params: Promise<{ locale: string; token: string }>;
+}) {
+  const { locale, token } = await params;
+  const t = await getTranslations({ locale, namespace: "onboardingPayments" });
+
+  // The page's OWN url becomes Stripe's refresh_url and return_url, so it is built
+  // from the request that actually arrived rather than from a constant: a tenant on
+  // a partner's own zone, or staging, must come back to where it left.
+  const host = (await headers()).get("host");
+  const origin = host ? `https://${host}` : SITE_URL;
+  const outcome = await resolvePaymentsLink(token, `${origin}/${locale}/onboarding/payments/${token}`);
+
+  // Outside the try/catch-free zone on purpose: `redirect` throws by design in
+  // Next, so it must be called where nothing will swallow it.
+  if (outcome.kind === "redirect") redirect(outcome.url);
+
+  const body = outcome.kind === "unknownToken" ? "unknownToken" : "unavailable";
+  return (
+    <>
+      <Header />
+      <main className="mx-auto grid max-w-2xl gap-4 px-6 py-24">
+        <h1 className="font-display text-3xl text-foreground">{t("title")}</h1>
+        <p className="font-body text-base text-muted-foreground">{t(body)}</p>
+        <p className="font-body text-sm text-muted-foreground">{t("contact")}</p>
+      </main>
+      <Footer />
+    </>
+  );
+}
diff --git a/lib/connect-account-links.ts b/lib/connect-account-links.ts
new file mode 100644
index 0000000..0d909a8
--- /dev/null
+++ b/lib/connect-account-links.ts
@@ -0,0 +1,64 @@
+// WHICH Stripe link a restaurant should be sent to, and what to ask Stripe for
+// (ADR-011 amendment, slice E4). Pure: no network, no env, no clock.
+//
+// There are two links, not one, and the choice is not cosmetic — MEASURED
+// 2026-09-05 on a fresh CH Express account (deleted afterwards; GET -> 403):
+//
+//   POST /v1/account_links type=account_onboarding -> 200, and
+//        `expires_at - created` = 300 SECONDS. Two calls return two DIFFERENT
+//        urls, so a link is a one-shot handle, never a stored address.
+//   POST /v1/accounts/{id}/login_links            -> 400 "Cannot create a login
+//        link for an account that has not completed onboarding."
+//   POST /v1/account_links type=account_update    -> 400 "You cannot create
+//        `account_update` type Account Links for this account. Valid types for
+//        this account are ["account_onboarding"]."
+//
+// So: before onboarding, only an onboarding link exists; after it, only a login
+// link does; and `account_update` — the obvious "let them edit their details"
+// choice — does not exist on Express at all. Sending the wrong one is a 400 in
+// the restaurant's face at the exact moment they are trying to get paid.
+
+/** What Stripe reports about an account, reduced to the fields that decide. */
+export type ConnectAccountState = {
+  /** True once the restaurant has finished Stripe's hosted form. */
+  details_submitted?: boolean;
+};
+
+export type ConnectLinkKind = "onboarding" | "login";
+
+/**
+ * `details_submitted` and nothing else.
+ *
+ * NOT `charges_enabled`: an account can have submitted everything and still be
+ * under review, and in that window `charges_enabled` is false while the
+ * onboarding link is refused — asking for the onboarding link there would show a
+ * restaurant a form it has already filled in. `details_submitted` is precisely
+ * the fact the login-link refusal is worded against ("has not completed
+ * onboarding").
+ */
+export function chooseConnectLink(account: ConnectAccountState): ConnectLinkKind {
+  return account.details_submitted === true ? "login" : "onboarding";
+}
+
+/**
+ * The `POST /v1/account_links` form.
+ *
+ * Both URLs point back at OUR page, and both are the same URL on purpose:
+ *
+ *  - `refresh_url` is where Stripe sends the restaurant when the link has died —
+ *    it lasts 300 seconds, so this is an ordinary event, not an error. Our page
+ *    mints a fresh link on every request, so landing back on it simply continues
+ *    the journey. Anything else here (an error page, the marketing site) would
+ *    strand someone mid-KYC for having taken a phone call.
+ *  - `return_url` is where they land when they are done. The same page then
+ *    chooses the LOGIN link instead (see `chooseConnectLink`), which is what a
+ *    finished restaurant should get.
+ */
+export function onboardingLinkForm(accountId: string, pageUrl: string): Record<string, string> {
+  return {
+    account: accountId,
+    type: "account_onboarding",
+    refresh_url: pageUrl,
+    return_url: pageUrl,
+  };
+}
diff --git a/lib/connect-account-store.ts b/lib/connect-account-store.ts
index ac2ee7f..e720438 100644
--- a/lib/connect-account-store.ts
+++ b/lib/connect-account-store.ts
@@ -24,6 +24,8 @@
 // decisions that are easy to get wrong — what the key is, and what the write is
 // keyed on — are then decidable by a unit test with no DB and no network.
 
+import { randomBytes } from "node:crypto";
+
 import { db } from "@/lib/db";
 
 /**
@@ -63,12 +65,33 @@ export function connectExpressIdempotencyKey(slug: string): string {
   return `${slug}-${CONNECT_KEY_SUFFIX}`;
 }
 
+/**
+ * The unguessable half of `/onboarding/payments/<token>` (E4).
+ *
+ * That page mints a Stripe Account Link and redirects to it, and an Account Link
+ * is a BEARER capability: whoever opens it can submit this restaurant's KYC and
+ * set the bank account its money is paid into. So the page cannot be addressed by
+ * slug — `?slug=rumi` would be an open door onto a real restaurant's payout
+ * details. 32 random bytes from `node:crypto`, base64url so it survives a URL and
+ * an email client, and never derived from anything about the tenant.
+ *
+ * It is long-lived on purpose, unlike the 300-second link it produces: it travels
+ * in the tenant's own env (`Stripe__PaymentsLinkUrl`) and in a welcome mail, both
+ * of which outlive five minutes. Its blast radius is one restaurant's onboarding,
+ * and it sits beside a box `.env` that already holds the platform Stripe key —
+ * strictly less powerful than what is next to it.
+ */
+export function newOnboardingToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
 /** One row of `StripeConnectAccount`, exactly as the database takes it. */
 export type ConnectAccountRow = {
   tenantSlug: string;
   stripeAccountId: string;
   idempotencyKey: string;
   country: string;
+  onboardingToken: string;
 };
 
 /**
@@ -106,11 +129,38 @@ export function connectAccountUpsert(row: ConnectAccountRow): ConnectAccountUpse
 export async function findConnectAccountForSlug(slug: string): Promise<ConnectAccountRow | null> {
   const row = await db.stripeConnectAccount.findUnique({
     where: { tenantSlug: slug },
-    select: { tenantSlug: true, stripeAccountId: true, idempotencyKey: true, country: true },
+    select: SELECT,
   });
-  return row;
+  return row?.onboardingToken ? { ...row, onboardingToken: row.onboardingToken } : null;
 }
 
+/**
+ * The account a `/onboarding/payments/<token>` request is about, or null.
+ *
+ * Null covers both "no such token" and "a row minted before tokens existed", and
+ * the caller must answer both with the SAME 404: a page that distinguished them
+ * would confirm to a stranger that a given token is nearly right.
+ */
+export async function findConnectAccountByToken(token: string): Promise<ConnectAccountRow | null> {
+  // A blank token would otherwise match a NULL-free `findUnique` on nothing —
+  // cheap to refuse, and the one input an empty URL segment produces.
+  if (!token) return null;
+  const row = await db.stripeConnectAccount.findUnique({
+    where: { onboardingToken: token },
+    select: SELECT,
+  });
+  return row?.onboardingToken ? { ...row, onboardingToken: row.onboardingToken } : null;
+}
+
+/** The columns every read here returns — one list, so two readers cannot drift. */
+const SELECT = {
+  tenantSlug: true,
+  stripeAccountId: true,
+  idempotencyKey: true,
+  country: true,
+  onboardingToken: true,
+} as const;
+
 /**
  * Record a minted account. Called immediately after `POST /v1/accounts` returns
  * and before the registry PR is composed.
diff --git a/lib/onboarding-payments.ts b/lib/onboarding-payments.ts
new file mode 100644
index 0000000..79bd502
--- /dev/null
+++ b/lib/onboarding-payments.ts
@@ -0,0 +1,76 @@
+// What `/onboarding/payments/<token>` should do with one request (E4).
+//
+// The restaurant's whole journey into Stripe runs through this: a welcome mail
+// and the tenant's own Payments tab both point at that page, never at a Stripe
+// URL, because an Account Link lives 300 SECONDS (measured) and is dead before
+// most people finish reading an email.
+//
+// Every branch is a decision about a person mid-onboarding, so none of them may
+// throw and none may be vague:
+//
+//  - unknown token          -> 404, and the SAME 404 for a row that predates
+//                              tokens. Telling them apart would confirm to a
+//                              stranger that a token is nearly right.
+//  - onboarding unfinished  -> a FRESH onboarding link, every single request.
+//                              This is also the `refresh_url` landing, i.e. the
+//                              restaurant took a phone call and their link
+//                              expired — the ordinary case, not an error.
+//  - onboarding finished    -> the Express dashboard LOGIN link instead. Asking
+//                              for an onboarding link there shows someone a form
+//                              they already filled in; `account_update` links do
+//                              not exist on Express at all (400, measured).
+//  - Stripe unreachable     -> say so plainly and let them retry. Never a blank
+//                              page, and never a Stripe error string.
+
+import { findConnectAccountByToken } from "@/lib/connect-account-store";
+import { chooseConnectLink } from "@/lib/connect-account-links";
+import {
+  createLoginLink,
+  createOnboardingLink,
+  readConnectAccount,
+} from "@/lib/stripe-connect-accounts";
+import { stripeConfigured } from "@/lib/stripe";
+
+export type PaymentsLinkOutcome =
+  | { kind: "redirect"; url: string }
+  | { kind: "unknownToken" }
+  | { kind: "unavailable" };
+
+/**
+ * @param token the URL segment, exactly as received.
+ * @param pageUrl this page's own absolute URL — handed in rather than derived
+ *   here, because it becomes Stripe's `refresh_url`/`return_url` and a wrong
+ *   origin would send a restaurant somewhere that does not exist. The route
+ *   builds it from the request it actually received.
+ */
+export async function resolvePaymentsLink(token: string, pageUrl: string): Promise<PaymentsLinkOutcome> {
+  // The two failures are NOT the same answer, and collapsing them is the exact
+  // fail-quiet this repo keeps catching: a database outage would otherwise tell a
+  // restaurant "this link is not one we recognise" — a confident falsehood about
+  // their own link, sending them to hunt for a better one that does not exist —
+  // when the truthful sentence is "we could not reach it, try again in a minute".
+  let account;
+  try {
+    account = await findConnectAccountByToken(token);
+  } catch (e) {
+    console.error("resolvePaymentsLink could not read the token", e);
+    return { kind: "unavailable" };
+  }
+  if (!account) return { kind: "unknownToken" };
+  if (!stripeConfigured()) return { kind: "unavailable" };
+
+  try {
+    const state = await readConnectAccount(account.stripeAccountId);
+    if (chooseConnectLink(state) === "login") {
+      const login = await createLoginLink(account.stripeAccountId);
+      return { kind: "redirect", url: login.url };
+    }
+    const link = await createOnboardingLink(account.stripeAccountId, pageUrl);
+    return { kind: "redirect", url: link.url };
+  } catch (e) {
+    // No PII, and no Stripe wording passed to the visitor: they are a restaurant
+    // owner, not an operator, and "No such account" would be alarming and useless.
+    console.error("resolvePaymentsLink failed", account.tenantSlug, e);
+    return { kind: "unavailable" };
+  }
+}
diff --git a/lib/stripe-connect-accounts.ts b/lib/stripe-connect-accounts.ts
index ddc09f7..6576e04 100644
--- a/lib/stripe-connect-accounts.ts
+++ b/lib/stripe-connect-accounts.ts
@@ -30,10 +30,12 @@
 import {
   connectExpressIdempotencyKey,
   findConnectAccountForSlug,
+  newOnboardingToken,
   recordConnectAccount,
 } from "@/lib/connect-account-store";
 import { expressAccountForm, type ExpressAccountInput } from "@/lib/connect-account-request";
-import { stripePost } from "@/lib/stripe";
+import { onboardingLinkForm, type ConnectAccountState } from "@/lib/connect-account-links";
+import { stripeGet, stripePost } from "@/lib/stripe";
 
 /** The slice of Stripe's Account object this module reads. */
 type StripeAccountCreated = { id: string };
@@ -68,7 +70,36 @@ export async function createExpressAccount(input: ExpressAccountInput): Promise<
     stripeAccountId: account.id,
     idempotencyKey,
     country: form.country,
+    // Minted here, with the account, and never re-issued: it is how the restaurant
+    // reaches its own onboarding page for as long as that page exists.
+    onboardingToken: newOnboardingToken(),
   });
 
   return { stripeAccountId: account.id, reused: false };
 }
+
+/** Stripe's `AccountLink` / `LoginLink` — both are `{ url }` and nothing else is read. */
+type StripeLink = { url: string };
+
+/**
+ * A FRESH onboarding link. Never cached, never stored, never emailed: it lives
+ * 300 seconds (measured), so any copy of it is a dead link by the time a person
+ * reads it. That is why the restaurant is given a page of OURS instead.
+ */
+export function createOnboardingLink(accountId: string, pageUrl: string): Promise<StripeLink> {
+  return stripePost<StripeLink>("/v1/account_links", onboardingLinkForm(accountId, pageUrl));
+}
+
+/**
+ * The Express dashboard login link, for an account that has finished onboarding.
+ * Refused (400) before that, which is why `chooseConnectLink` decides first.
+ */
+export function createLoginLink(accountId: string): Promise<StripeLink> {
+  return stripePost<StripeLink>(`/v1/accounts/${accountId}/login_links`, {});
+}
+
+/** Read an account's onboarding state. The 5-minute-cached tenant-side reader in
+ *  the backend is unchanged; this is the control plane's own, per request. */
+export function readConnectAccount(accountId: string): Promise<ConnectAccountState> {
+  return stripeGet<ConnectAccountState>(`/v1/accounts/${accountId}`);
+}
diff --git a/messages/ar.json b/messages/ar.json
index b972c8f..0095d4f 100644
--- a/messages/ar.json
+++ b/messages/ar.json
@@ -1673,5 +1673,14 @@
       "vat": "إذا كان لشركتك رقم ضريبة قيمة مضافة في الاتحاد الأوروبي، فأضفه أيضًا وسنطبّق الاحتساب العكسي للضريبة بدلًا من تحصيلها منك.",
       "cta": "أضف بيانات الفوترة"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "إعداد المدفوعات بالبطاقة"
+    },
+    "title": "المدفوعات بالبطاقة",
+    "unknownToken": "لا نعرف هذا الرابط. كل رابط يخص مطعمًا واحدًا — من فضلك استخدم الرابط الوارد في رسالة الترحيب، أو الزر الموجود في لوحة إدارتك ضمن الإعدادات ← المدفوعات.",
+    "unavailable": "تعذّر الوصول إلى Stripe الآن، لذلك لا يمكن فتح النموذج. لم يضع شيء — أعد المحاولة بالرابط نفسه بعد بضع دقائق.",
+    "contact": "إذا تكرر الأمر، ردّ على أي من رسائلنا وسنحلّه معك."
   }
 }
diff --git a/messages/de.json b/messages/de.json
index 8280b7b..71eba5e 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1673,5 +1673,14 @@
       "vat": "Wenn Ihr Unternehmen eine EU-USt-IdNr. hat, tragen Sie sie ebenfalls ein — dann wenden wir das Reverse-Charge-Verfahren an, statt Ihnen die Umsatzsteuer zu berechnen.",
       "cta": "Rechnungsdaten hinzufügen"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "Kartenzahlungen einrichten"
+    },
+    "title": "Kartenzahlungen",
+    "unknownToken": "Diesen Link kennen wir nicht. Jeder Link gehört zu genau einem Restaurant — bitte nehmen Sie den aus Ihrer Willkommens-E-Mail oder die Schaltfläche in Ihrer eigenen Verwaltung unter Einstellungen → Zahlungen.",
+    "unavailable": "Wir konnten Stripe gerade nicht erreichen, deshalb lässt sich Ihr Formular nicht öffnen. Es geht nichts verloren — versuchen Sie denselben Link in ein paar Minuten erneut.",
+    "contact": "Wenn es weiter auftritt, antworten Sie einfach auf eine unserer E-Mails, und wir klären es gemeinsam."
   }
 }
diff --git a/messages/en.json b/messages/en.json
index 78ac0fb..6eee570 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1673,5 +1673,14 @@
       "vat": "If your company has an EU VAT number, add it too and we will reverse-charge the VAT instead of charging it.",
       "cta": "Add your billing details"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "Set up card payments"
+    },
+    "title": "Card payments",
+    "unknownToken": "This link is not one we recognise. Links are personal to one restaurant, so please use the one in your welcome email or the button in your own admin under Settings → Payments.",
+    "unavailable": "We could not reach Stripe just now, so we cannot open your form. Nothing is lost — please try the same link again in a few minutes.",
+    "contact": "If it keeps happening, reply to any of our emails and we will sort it out with you."
   }
 }
diff --git a/messages/fr.json b/messages/fr.json
index a1607d8..b749abe 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1673,5 +1673,14 @@
       "vat": "Si votre société a un numéro de TVA intracommunautaire, ajoutez-le : nous appliquerons l'autoliquidation de la TVA au lieu de la facturer.",
       "cta": "Ajouter vos informations de facturation"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "Configurer les paiements par carte"
+    },
+    "title": "Paiements par carte",
+    "unknownToken": "Nous ne reconnaissons pas ce lien. Chaque lien appartient à un seul restaurant : utilisez celui de votre e-mail de bienvenue, ou le bouton dans votre propre administration, sous Réglages → Paiements.",
+    "unavailable": "Nous n'avons pas pu joindre Stripe à l'instant, votre formulaire ne peut donc pas s'ouvrir. Rien n'est perdu : réessayez le même lien dans quelques minutes.",
+    "contact": "Si cela persiste, répondez à l'un de nos e-mails et nous réglerons cela avec vous."
   }
 }
diff --git a/messages/nl.json b/messages/nl.json
index 1a436aa..5ab76e9 100644
--- a/messages/nl.json
+++ b/messages/nl.json
@@ -1673,5 +1673,14 @@
       "vat": "Heeft uw bedrijf een EU-btw-nummer? Vul dat er ook bij in, dan verleggen we de btw in plaats van die in rekening te brengen.",
       "cta": "Vul uw factuurgegevens in"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "Kaartbetalingen instellen"
+    },
+    "title": "Kaartbetalingen",
+    "unknownToken": "Deze link kennen we niet. Elke link hoort bij één restaurant — gebruik de link uit je welkomstmail, of de knop in je eigen beheer onder Instellingen → Betalingen.",
+    "unavailable": "We konden Stripe zojuist niet bereiken, dus je formulier kan niet openen. Er gaat niets verloren — probeer dezelfde link over een paar minuten opnieuw.",
+    "contact": "Blijft het gebeuren, beantwoord dan een van onze e-mails; dan lossen we het samen op."
   }
 }
diff --git a/messages/tr.json b/messages/tr.json
index b831187..f457521 100644
--- a/messages/tr.json
+++ b/messages/tr.json
@@ -1673,5 +1673,14 @@
       "vat": "Şirketinizin AB KDV numarası varsa onu da ekleyin; KDV'yi sizden tahsil etmek yerine tersine tahsilat (reverse charge) uygularız.",
       "cta": "Fatura bilgilerinizi ekleyin"
     }
+  },
+  "onboardingPayments": {
+    "meta": {
+      "title": "Kartlı ödemeleri kurun"
+    },
+    "title": "Kartlı ödemeler",
+    "unknownToken": "Bu bağlantıyı tanımıyoruz. Her bağlantı tek bir restorana aittir — lütfen hoş geldiniz e-postanızdaki bağlantıyı ya da kendi yönetim panelinizde Ayarlar → Ödemeler altındaki düğmeyi kullanın.",
+    "unavailable": "Şu anda Stripe'a ulaşamadık, bu yüzden formunuz açılamıyor. Hiçbir şey kaybolmadı — birkaç dakika sonra aynı bağlantıyı yeniden deneyin.",
+    "contact": "Sorun sürerse e-postalarımızdan herhangi birini yanıtlayın, birlikte çözelim."
   }
 }
diff --git a/prisma/migrations/20260905210000_connect_account_onboarding_token/migration.sql b/prisma/migrations/20260905210000_connect_account_onboarding_token/migration.sql
new file mode 100644
index 0000000..297f530
--- /dev/null
+++ b/prisma/migrations/20260905210000_connect_account_onboarding_token/migration.sql
@@ -0,0 +1,35 @@
+-- The unguessable half of `/onboarding/payments/<token>` (ADR-011 amendment, E4).
+--
+-- That page mints a Stripe Account Link and 302s to it. An Account Link is a
+-- BEARER capability: whoever opens it can submit this restaurant's KYC and set
+-- the bank account its money is paid into. So the page must not be addressable
+-- by slug — `/onboarding/payments?slug=rumi` would be an open door onto a real
+-- restaurant's payout details, and the restaurant has no login here to put in
+-- front of it (they log into their own tenant app, never into the control plane).
+--
+-- 32 random bytes, base64url, generated by lib/connect-account-store.ts at the
+-- moment the account is minted. Long-lived on purpose, unlike the 300-second
+-- link it produces (MEASURED: `expires_at - created = 300`, and two calls return
+-- two different URLs), because it travels in the tenant's own env
+-- (`Stripe__PaymentsLinkUrl`) and in a welcome mail, both of which outlive five
+-- minutes. Its blast radius is one restaurant's onboarding, and it sits in a box
+-- `.env` beside the platform Stripe key — strictly less powerful than its
+-- neighbour.
+--
+-- ADDITIVE ONLY, and safe on a DB with live rows: one NULLABLE column and one
+-- unique index on "StripeConnectAccount" (20260905190000). No column is retyped,
+-- no constraint is dropped, no row changes meaning, and nothing is backfilled.
+--
+-- NULLABLE, deliberately, even though every row this app writes will carry a
+-- token: the column arrived after the table, so a row written in between has
+-- none, and NULL is the honest record of that. A unique index in Postgres allows
+-- many NULLs, so this neither collides nor blocks. The read path
+-- (`findConnectAccountByToken`) treats a NULL token as NO MATCH, so such a row is
+-- unreachable by the page rather than reachable without a token — and the same
+-- 404 answers "no such token" and "a row from before tokens", because a page that
+-- told them apart would confirm to a stranger that a token is nearly right.
+
+ALTER TABLE "StripeConnectAccount" ADD COLUMN "onboardingToken" TEXT;
+
+CREATE UNIQUE INDEX "StripeConnectAccount_onboardingToken_key"
+  ON "StripeConnectAccount"("onboardingToken");
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index ecfb2a7..edb8d8d 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -975,6 +975,18 @@ model StripeConnectAccount {
   /// it is the field a wrong tenant address would have silently baked in.
   country String
 
+  /// The unguessable path segment of `/onboarding/payments/<token>` (E4) — 32
+  /// random bytes, base64url. The page it addresses mints a Stripe Account Link
+  /// and redirects to it, and that link is a BEARER capability: whoever opens it
+  /// can submit this restaurant's KYC and set the bank account its money is paid
+  /// into. Addressing the page by slug would therefore be an open door onto a
+  /// real restaurant's payout details.
+  ///
+  /// NULLABLE only because the column arrived after the table did; every row this
+  /// app writes has one, and a row without one is unreachable by that page rather
+  /// than reachable without a token.
+  onboardingToken String? @unique
+
   /// When WE recorded it. Deliberately not "when Stripe created it": the two are
   /// seconds apart and nothing here periodises on this, so a second clock would
   /// be a field that can only ever disagree.
diff --git a/tests/unit/connect-account-links.test.ts b/tests/unit/connect-account-links.test.ts
new file mode 100644
index 0000000..a6417b4
--- /dev/null
+++ b/tests/unit/connect-account-links.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { chooseConnectLink, onboardingLinkForm } from "@/lib/connect-account-links";
+import { newOnboardingToken } from "@/lib/connect-account-store";
+import { resolvePaymentsLink } from "@/lib/onboarding-payments";
+
+// MEASURED 2026-09-05 on a fresh CH Express account (test mode, deleted after,
+// GET -> 403). These are the numbers the module is written against:
+//   account_links (account_onboarding) -> 200, expires_at - created = 300s,
+//     and two calls return two DIFFERENT urls
+//   login_links   -> 400 "Cannot create a login link for an account that has not
+//     completed onboarding."
+//   account_links type=account_update -> 400 'Valid types for this account are
+//     ["account_onboarding"]'
+
+describe("chooseConnectLink", () => {
+  it("sends an unfinished account to onboarding", () => {
+    // A fresh Express account reports details_submitted: false (measured), and a
+    // login link for it is a 400 in the restaurant's face.
+    expect(chooseConnectLink({ details_submitted: false })).toBe("onboarding");
+  });
+
+  it("sends a finished account to its Express dashboard instead", () => {
+    // Asking for an onboarding link here shows someone a form they already filled
+    // in — and `account_update`, the obvious third option, does not exist on
+    // Express at all.
+    expect(chooseConnectLink({ details_submitted: true })).toBe("login");
+  });
+
+  it("treats an unknown state as unfinished", () => {
+    // Guidance is the safe default, the same direction the tenant-facing tab takes:
+    // an onboarding link for a finished account is a wasted click, while a login
+    // link for an unfinished one is a refusal.
+    expect(chooseConnectLink({})).toBe("onboarding");
+    expect(chooseConnectLink({ details_submitted: undefined })).toBe("onboarding");
+  });
+});
+
+describe("onboardingLinkForm", () => {
+  const page = "https://sofrapiwas.com/fr/onboarding/payments/tok";
+
+  it("asks for an account_onboarding link", () => {
+    expect(onboardingLinkForm("acct_1UCPNgFqVH9gPNlT", page).type).toBe("account_onboarding");
+    expect(onboardingLinkForm("acct_1UCPNgFqVH9gPNlT", page).account).toBe("acct_1UCPNgFqVH9gPNlT");
+  });
+
+  it("points BOTH urls back at our own page", () => {
+    // `refresh_url` is where Stripe sends someone whose link has expired — 300
+    // seconds, so an ordinary event, not an error. Our page mints a new link on
+    // every request, so landing back on it continues the journey. Anything else
+    // strands a restaurant mid-KYC for having taken a phone call.
+    const form = onboardingLinkForm("acct_1UCPNgFqVH9gPNlT", page);
+    expect(form.refresh_url).toBe(page);
+    expect(form.return_url).toBe(page);
+  });
+});
+
+describe("newOnboardingToken", () => {
+  it("is unguessable and URL-safe", () => {
+    // 32 random bytes, base64url: it is the whole access control on a page that
+    // can set a restaurant's payout bank account.
+    const token = newOnboardingToken();
+    expect(token).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(token).not.toContain("+");
+    expect(token).not.toContain("/");
+    expect(token).not.toContain("=");
+  });
+
+  it("never repeats", () => {
+    const many = new Set(Array.from({ length: 500 }, newOnboardingToken));
+    expect(many.size).toBe(500);
+  });
+});
+
+describe("resolvePaymentsLink", () => {
+  it("answers an empty token with the same 404 as a wrong one, and touches nothing", async () => {
+    // An empty URL segment is the one input a bad link reliably produces. It is
+    // refused before the database and before Stripe — so this test also proves the
+    // ordering, since a suite with no DB would otherwise fail loudly here.
+    await expect(resolvePaymentsLink("", "https://sofrapiwas.com/en/onboarding/payments/")).resolves.toEqual({
+      kind: "unknownToken",
+    });
+  });
+});
diff --git a/tests/unit/connect-account-store.test.ts b/tests/unit/connect-account-store.test.ts
index 03481f7..1f013c9 100644
--- a/tests/unit/connect-account-store.test.ts
+++ b/tests/unit/connect-account-store.test.ts
@@ -52,6 +52,13 @@ describe("connectAccountUpsert — the anchor", () => {
     stripeAccountId: "acct_1UCOkhCSPiP2JWOQ",
     idempotencyKey: "rumi-connect-express-v1",
     country: "CH",
+    // Deliberately low-entropy and self-describing. A realistic 43-character
+    // base64url token here is indistinguishable from a real credential to
+    // gitleaks, which failed this PR's first run on exactly that (generic-api-key)
+    // — and a scanner that cries wolf on fixtures is one people learn to skip.
+    // The REAL shape is asserted in connect-account-links.test.ts, on a token
+    // `newOnboardingToken()` actually produced.
+    onboardingToken: "not-a-secret-fixture-token",
     ...over,
   });
 
diff --git a/vitest.config.ts b/vitest.config.ts
index 637a6d6..f2f6b0b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -212,6 +212,11 @@ export default defineConfig({
         // creation and refuses it on update, so a wrong derivation is a live account
         // in the wrong country for a real restaurant.
         "lib/connect-account-country.ts",
+        // E4 — which of Stripe's two links a restaurant should be sent to, and what to
+        // ask for. Pure, and in scope because sending the wrong one is a 400 in the
+        // restaurant's face at the moment they are trying to get paid: a login link
+        // before onboarding is refused, and `account_update` does not exist on Express.
+        "lib/connect-account-links.ts",
       ],
       reporter: ["text-summary", "text"],
       // Floors sit a few points under the current 100/95/100/100 so a trivial

From 1e0587a47f79d1bdfbd9d92ada69b2a73f9eb3f2 Mon Sep 17 00:00:00 2001
From: mahmutkaya <mahmutkaya.nl@gmail.com>
Date: Sat, 5 Sep 2026 21:52:02 +0200
Subject: [PATCH 2/2] chore(payments): read-only props on the onboarding page
 (SonarCloud S6759)

---
 app/[locale]/onboarding/payments/[token]/page.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/app/[locale]/onboarding/payments/[token]/page.tsx b/app/[locale]/onboarding/payments/[token]/page.tsx
index b501730..723885f 100644
--- a/app/[locale]/onboarding/payments/[token]/page.tsx
+++ b/app/[locale]/onboarding/payments/[token]/page.tsx
@@ -44,9 +44,9 @@ export async function generateMetadata({
  */
 export default async function OnboardingPaymentsPage({
   params,
-}: {
+}: Readonly<{
   params: Promise<{ locale: string; token: string }>;
-}) {
+}>) {
   const { locale, token } = await params;
   const t = await getTranslations({ locale, namespace: "onboardingPayments" });