@tribe-nest/forge 3.67.0 → 3.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.67.0",
+  "version": "3.69.0",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/useCheckoutLink.ts

@@ -0,0 +1,70 @@
+import { useQuery } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+
+/** What the pay page may show about a checkout link. Nothing about the buyer. */
+export type CheckoutLinkView = {
+  status: "open" | "paid" | "expired" | "cancelled";
+  /** The buyer paid after the link closed: nothing was confirmed and the money goes back. */
+  needsRefund: boolean;
+  item: { type: "event_ticket" | "product" | "booking"; title: string } | null;
+  /**
+   * A booking link only: every session it holds (ISO), the business's own time
+   * zone, and the service's booking page for picking another time.
+   */
+  booking?: {
+    sessions: { startsAt: string; endsAt: string }[];
+    timezone: string | null;
+    servicePath: string | null;
+  };
+  quantity: number;
+  /** Minor units, in `currency`. */
+  unitPriceCents: number | null;
+  totalCents: number;
+  currency: string;
+  /** ISO. When the hold ends if nobody pays. */
+  expiresAt: string;
+};
+
+export type CheckoutLinkFinalizeResult = {
+  /** `fulfilled`, `paid` (settling), `unpaid`, or `needs_refund`. */
+  outcome: string;
+  link: CheckoutLinkView;
+};
+
+/**
+ * Open a checkout link by its token (`POST /public/checkout-links/open`).
+ *
+ * A POST, and not refetched on focus: opening extends the link's hold to the
+ * payment window, which is a write the page should make once per visit.
+ */
+export function useCheckoutLink(token?: string | null) {
+  const { client, profileId } = useForge();
+  return useQuery<CheckoutLinkView>({
+    queryKey: ["checkout-link", token, profileId],
+    queryFn: async () => {
+      const res = await client.post("/public/checkout-links/open", { profileId, token });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!token,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+/**
+ * Settle a checkout link on the return page (`POST /public/checkout-links/finalize`).
+ * Idempotent on the server: a reload settles nothing twice.
+ */
+export function useCheckoutLinkFinalize(token?: string | null, enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<CheckoutLinkFinalizeResult>({
+    queryKey: ["checkout-link-finalize", token, profileId],
+    queryFn: async () => {
+      const res = await client.post("/public/checkout-links/finalize", { profileId, token });
+      return res.data;
+    },
+    enabled: enabled && !!profileId && !!client && !!token,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}

package/src/i18n/de.json

@@ -713,6 +713,31 @@
   "forge.checkout_confirmation.total": "Gesamt",
   "forge.checkout_confirmation.total_paid": "Bezahlt gesamt",
   "forge.checkout_confirmation.view_orders": "Bestellungen ansehen",
+  "forge.checkout_link_payment.browse_store": "Zum Shop",
+  "forge.checkout_link_payment.cancelled_body": "Das Unternehmen hat diesen Link zurückgezogen. Es wurde nichts berechnet.",
+  "forge.checkout_link_payment.cancelled_title": "Dieser Link ist nicht mehr verfügbar",
+  "forge.checkout_link_payment.each": "je {price}",
+  "forge.checkout_link_payment.ended_body": "Wir konnten dies nicht länger für Sie reservieren, deshalb ist es wieder im Verkauf. Es wurde nichts berechnet.",
+  "forge.checkout_link_payment.ended_title": "Diese Reservierung ist abgelaufen",
+  "forge.checkout_link_payment.held_until": "Für Sie reserviert bis {time}",
+  "forge.checkout_link_payment.hold_noun": "Artikel",
+  "forge.checkout_link_payment.hold_noun_booking": "diesen Termin",
+  "forge.checkout_link_payment.not_found_body": "Dieser Link ist ungültig. Prüfen Sie die Adresse in Ihrer E-Mail.",
+  "forge.checkout_link_payment.not_found_title": "Link nicht gefunden",
+  "forge.checkout_link_payment.other_times": "Anderen Termin wählen",
+  "forge.checkout_link_payment.paid_body": "Vielen Dank. Die Details sind unterwegs an Ihre E-Mail-Adresse.",
+  "forge.checkout_link_payment.paid_title": "Zahlung erhalten",
+  "forge.checkout_link_payment.pay_amount": "{amount} bezahlen",
+  "forge.checkout_link_payment.payment_unavailable": "Die Zahlung ist gerade nicht möglich. Bitte versuchen Sie es gleich noch einmal.",
+  "forge.checkout_link_payment.preparing_payment": "Zahlung wird vorbereitet…",
+  "forge.checkout_link_payment.quantity": "Anzahl: {quantity}",
+  "forge.checkout_link_payment.title": "Für Sie reserviert",
+  "forge.checkout_link_payment.too_late_body": "Ihre Zahlung ist nach dem Ende dieser Reservierung eingegangen, deshalb wurde nichts gebucht. Ihre Zahlung wird erstattet.",
+  "forge.checkout_link_payment.too_late_title": "Ihre Zahlung wird erstattet",
+  "forge.checkout_link_payment.total": "Gesamt",
+  "forge.checkout_link_payment.try_again": "Erneut versuchen",
+  "forge.checkout_link_payment.unpaid_body": "Ihre Zahlung ist nicht durchgegangen, und es wurde nichts berechnet. Ihre Reservierung besteht weiter, Sie können es erneut versuchen.",
+  "forge.checkout_link_payment.unpaid_title": "Zahlung nicht abgeschlossen",
   "forge.coaching_booking.aria_close": "Schließen",
   "forge.coaching_booking.aria_next_month": "Nächster Monat",
   "forge.coaching_booking.aria_next_week": "Nächste Woche",

package/src/i18n/en.json

@@ -713,6 +713,31 @@
   "forge.checkout_confirmation.total": "Total",
   "forge.checkout_confirmation.total_paid": "Total paid",
   "forge.checkout_confirmation.view_orders": "View your orders",
+  "forge.checkout_link_payment.browse_store": "Browse the store",
+  "forge.checkout_link_payment.cancelled_body": "The business withdrew this link. Nothing was charged.",
+  "forge.checkout_link_payment.cancelled_title": "This link is no longer available",
+  "forge.checkout_link_payment.each": "{price} each",
+  "forge.checkout_link_payment.ended_body": "We could not hold this for you any longer, so it went back on sale. Nothing was charged.",
+  "forge.checkout_link_payment.ended_title": "This reservation has ended",
+  "forge.checkout_link_payment.held_until": "Held for you until {time}",
+  "forge.checkout_link_payment.hold_noun": "items",
+  "forge.checkout_link_payment.hold_noun_booking": "this time",
+  "forge.checkout_link_payment.not_found_body": "This link is not valid. Check the address in your email.",
+  "forge.checkout_link_payment.not_found_title": "Link not found",
+  "forge.checkout_link_payment.other_times": "Pick another time",
+  "forge.checkout_link_payment.paid_body": "Thank you. The details are on their way to your email.",
+  "forge.checkout_link_payment.paid_title": "Payment received",
+  "forge.checkout_link_payment.pay_amount": "Pay {amount}",
+  "forge.checkout_link_payment.payment_unavailable": "Payment is not available right now. Please try again in a moment.",
+  "forge.checkout_link_payment.preparing_payment": "Preparing payment…",
+  "forge.checkout_link_payment.quantity": "Quantity: {quantity}",
+  "forge.checkout_link_payment.title": "Held for you",
+  "forge.checkout_link_payment.too_late_body": "Your payment arrived after this reservation had ended, so nothing was booked. Your payment will be refunded.",
+  "forge.checkout_link_payment.too_late_title": "Your payment will be refunded",
+  "forge.checkout_link_payment.total": "Total",
+  "forge.checkout_link_payment.try_again": "Try again",
+  "forge.checkout_link_payment.unpaid_body": "Your payment did not go through, and nothing was charged. Your reservation is still held, so you can try again.",
+  "forge.checkout_link_payment.unpaid_title": "Payment not completed",
   "forge.coaching_booking.aria_close": "Close",
   "forge.coaching_booking.aria_next_month": "Next month",
   "forge.coaching_booking.aria_next_week": "Next week",

package/src/index.ts

@@ -104,6 +104,7 @@ export * from "./data/queries/useMusicLink";
 export * from "./data/queries/useEventSeries";
 export * from "./data/queries/useInvoice";
 export * from "./data/queries/usePaymentLink";
+export * from "./data/queries/useCheckoutLink";
 export * from "./data/queries/useLeadMagnet";
 export * from "./data/queries/useBlogComments";
 export * from "./data/queries/usePageActions";

package/src/runtime/pages.ts

@@ -59,6 +59,7 @@ export const INTERNAL_PAGES = [
   "blog/$slug",
   "checkout",
   "checkout/finalise",
+  "checkout/pay/$token",
   "checkout/resume",
   "coaching",
   "coaching/$slug",

package/src/ui/headless/checkoutLink/useCheckoutLinkPayment.ts

@@ -0,0 +1,78 @@
+import { useCallback, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCheckoutLink, useCheckoutLinkFinalize } from "../../../data/queries/useCheckoutLink";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+
+export interface UseCheckoutLinkPaymentOptions {
+  /** Where the provider returns the buyer. Default: this page with `?finalise=1`. */
+  returnPath?: string;
+  /**
+   * True on the return leg (the provider sent the buyer back): the hook then
+   * settles the link instead of offering to pay.
+   */
+  returning?: boolean;
+}
+
+type ApiError = { response?: { status?: number; data?: { message?: string; code?: string; details?: { status?: string } } } };
+
+/**
+ * Headless checkout link payment: the hosted pay page `/i/checkout/pay/<token>`.
+ *
+ * Loads the link (`open`, which extends its hold to the payment window), starts
+ * its ONE payment only when the buyer presses Pay (`start-payment` runs the
+ * server's checks first: a closed link or a hold whose items were taken is
+ * refused before any payment exists), and on the return leg settles it
+ * (`finalize`). Stripe renders from `clientSecret`; Paystack opens its modal.
+ */
+export function useCheckoutLinkPayment(token?: string | null, opts: UseCheckoutLinkPaymentOptions = {}) {
+  const queryClient = useQueryClient();
+  const link = useCheckoutLink(opts.returning ? null : token);
+  const finalize = useCheckoutLinkFinalize(token, !!opts.returning);
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const pathname = typeof window !== "undefined" ? window.location.pathname : "";
+  const returnUrl = token ? `${origin}${opts.returnPath ?? pathname}?finalise=1` : "";
+
+  const flow = usePaymentFlow({
+    path: "/public/checkout-links/start-payment",
+    body: { token },
+    returnUrl,
+    autoStart: false,
+    enabled: !!token,
+  });
+
+  const [refusal, setRefusal] = useState<{ message: string; code: string | null; status: string | null } | null>(null);
+
+  const pay = useCallback(async () => {
+    setRefusal(null);
+    try {
+      await flow.start();
+    } catch (error) {
+      const data = (error as ApiError)?.response?.data;
+      setRefusal({
+        message: data?.message ?? "",
+        code: data?.code ?? null,
+        status: data?.details?.status ?? null,
+      });
+      // The link's own state may have moved (paid in another tab, expired).
+      await queryClient.invalidateQueries({ queryKey: ["checkout-link", token] });
+    }
+  }, [flow, queryClient, token]);
+
+  return {
+    link,
+    finalize,
+    returnUrl,
+    pay,
+    isStarting: flow.isStarting,
+    clientSecret: flow.clientSecret,
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
+    /** The server's refusal of the last Pay, in its own words, with its code. */
+    refusal,
+    /** When the hold ends: the link's own deadline, as Pay last extended it. */
+    holdExpiresAt:
+      (flow.result as { link?: { expiresAt?: string } } | null)?.link?.expiresAt ?? link.data?.expiresAt ?? null,
+  };
+}

package/src/ui/headless/index.ts

@@ -159,6 +159,7 @@ export {
 } from "./membership/membershipQuestionnaire";
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
+export { useCheckoutLinkPayment, type UseCheckoutLinkPaymentOptions } from "./checkoutLink/useCheckoutLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";
 export {
   broadcastListStatus,

package/src/ui/index.ts

@@ -94,6 +94,8 @@ export {
 export { Cart, type CartProps } from "./styled/Cart";
 /** The page a cart-recovery email lands on. Drop in at `/i/checkout/resume`. */
 export { ResumeCart, type ResumeCartProps } from "./styled/ResumeCart";
+/** The page a checkout link lands on: an item held for this person. Drop in at `/i/checkout/pay/$token`. */
+export { CheckoutLinkPayment, type CheckoutLinkPaymentProps } from "./styled/CheckoutLinkPayment";
 // The resolver is exported alongside the component because the Craft themes
 // are a separate rendering stack (Tailwind, not inline styles) and cannot use
 // the component: but the legacy `color`/`size` fallback must not diverge.

package/src/ui/styled/CheckoutLinkPayment.tsx

@@ -0,0 +1,303 @@
+import type { CSSProperties } from "react";
+import { useForgeT } from "../../i18n";
+import { useCheckoutLinkPayment } from "../headless/checkoutLink/useCheckoutLinkPayment";
+import { useInventoryHold } from "../headless/checkout/useInventoryHold";
+import { usePaymentRenderer } from "../payment/ForgePaymentProvider";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { useAmountFormatter } from "../format/useFormatCurrency";
+import type { CheckoutLinkView } from "../../data/queries/useCheckoutLink";
+import { Button } from "./Button";
+import { HoldNotice } from "./HoldNotice";
+import { Loading } from "./Loading";
+import { PaystackPayButton } from "./PaystackPayButton";
+
+export interface CheckoutLinkPaymentProps {
+  /** The token from the link (`/i/checkout/pay/<token>`). */
+  token?: string | null;
+  /**
+   * True when the payment provider has just sent the buyer back (`?finalise=1`
+   * or Stripe's `redirect_status`): the page settles the link instead of
+   * offering to pay.
+   */
+  returning?: boolean;
+  /** Where "browse the store" goes when the link can no longer be paid. Default `/i/store`. */
+  storePath?: string;
+  /** Format a numeric amount for display. */
+  formatAmount?: (amount: number, currencyCode?: string) => string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * The hosted pay page for a checkout link (`/i/checkout/pay/<token>`).
+ *
+ * A business (or its agent) held an item for this person and sent them here.
+ * The page shows exactly what is held, at what price and until when, and
+ * continues to the normal payment step. It does not build a checkout: the
+ * checkout already exists on the server, and the `<Checkout>` drop-in always
+ * makes a new one, which is why this is its own component.
+ *
+ * Pressing Pay asks the server first (the link still open, the hold still
+ * there or taken again); a refusal is shown in the server's own words, before
+ * any card form exists. A paid, expired or cancelled link says which, with a
+ * way to the store.
+ */
+export function CheckoutLinkPayment({
+  token,
+  returning = false,
+  storePath = "/i/store",
+  formatAmount,
+  className,
+  style,
+}: CheckoutLinkPaymentProps) {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  const fmt = useAmountFormatter(formatAmount);
+  const renderPayment = usePaymentRenderer();
+  const page = useCheckoutLinkPayment(token, { returning });
+  const hold = useInventoryHold(page.holdExpiresAt);
+
+  const shell: CSSProperties = {
+    maxWidth: 560,
+    margin: "0 auto",
+    color: t.text,
+    fontFamily: t.fontFamily,
+    ...style,
+  };
+  const heading: CSSProperties = { fontSize: 26, fontWeight: 800, fontFamily: t.headingFontFamily, marginBottom: 8 };
+  const muted: CSSProperties = { color: t.muted, fontSize: 15, lineHeight: 1.6 };
+
+  const toStore = (
+    <div style={{ marginTop: 24 }}>
+      <Button onClick={() => go(storePath)} data-testid="checkout-link-store">
+        {tr("forge.checkout_link_payment.browse_store")}
+      </Button>
+    </div>
+  );
+  // A booking whose time is gone: the way on is another time of the same service.
+  const otherTimes = (path: string | null | undefined) =>
+    path ? (
+      <div style={{ marginTop: 24 }}>
+        <Button onClick={() => go(path)} data-testid="checkout-link-other-times">
+          {tr("forge.checkout_link_payment.other_times")}
+        </Button>
+      </div>
+    ) : (
+      toStore
+    );
+
+  // ── The return leg: settle, then say what is true ────────────────────────
+  if (returning) {
+    if (page.finalize.isLoading) return <Loading fullPage />;
+    const outcome = page.finalize.data?.outcome;
+    if (page.finalize.error || !page.finalize.data) {
+      return (
+        <div className={className} style={shell} data-testid="checkout-link-page" data-state="not-found">
+          <h1 style={heading}>{tr("forge.checkout_link_payment.not_found_title")}</h1>
+          <p style={muted}>{tr("forge.checkout_link_payment.not_found_body")}</p>
+          {toStore}
+        </div>
+      );
+    }
+    if (outcome === "needs_refund" || page.finalize.data.link.needsRefund) {
+      return (
+        <div className={className} style={shell} data-testid="checkout-link-page" data-state="needs-refund">
+          <h1 style={heading}>{tr("forge.checkout_link_payment.too_late_title")}</h1>
+          <p style={muted}>{tr("forge.checkout_link_payment.too_late_body")}</p>
+          {toStore}
+        </div>
+      );
+    }
+    if (outcome === "fulfilled" || outcome === "paid") {
+      return (
+        <div className={className} style={shell} data-testid="checkout-link-page" data-state="paid">
+          <h1 style={heading}>{tr("forge.checkout_link_payment.paid_title")}</h1>
+          <Summary view={page.finalize.data.link} fmt={fmt} />
+          <p style={{ ...muted, marginTop: 16 }}>{tr("forge.checkout_link_payment.paid_body")}</p>
+        </div>
+      );
+    }
+    // Not paid (a declined card, a closed window): the link is still open, so
+    // they can try again from the same address.
+    return (
+      <div className={className} style={shell} data-testid="checkout-link-page" data-state="unpaid">
+        <h1 style={heading}>{tr("forge.checkout_link_payment.unpaid_title")}</h1>
+        <p style={muted}>{tr("forge.checkout_link_payment.unpaid_body")}</p>
+        <div style={{ marginTop: 24 }}>
+          <Button onClick={() => go(typeof window !== "undefined" ? window.location.pathname : "")}>
+            {tr("forge.checkout_link_payment.try_again")}
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  // ── The page as the email opens it ───────────────────────────────────────
+  if (page.link.isLoading) return <Loading fullPage />;
+  const view = page.link.data;
+  if (page.link.error || !view) {
+    return (
+      <div className={className} style={shell} data-testid="checkout-link-page" data-state="not-found">
+        <h1 style={heading}>{tr("forge.checkout_link_payment.not_found_title")}</h1>
+        <p style={muted}>{tr("forge.checkout_link_payment.not_found_body")}</p>
+        {toStore}
+      </div>
+    );
+  }
+
+  if (view.status !== "open") {
+    const closed = view.needsRefund
+      ? { title: tr("forge.checkout_link_payment.too_late_title"), body: tr("forge.checkout_link_payment.too_late_body") }
+      : view.status === "paid"
+        ? { title: tr("forge.checkout_link_payment.paid_title"), body: tr("forge.checkout_link_payment.paid_body") }
+        : view.status === "cancelled"
+          ? {
+              title: tr("forge.checkout_link_payment.cancelled_title"),
+              body: tr("forge.checkout_link_payment.cancelled_body"),
+            }
+          : { title: tr("forge.checkout_link_payment.ended_title"), body: tr("forge.checkout_link_payment.ended_body") };
+    return (
+      <div className={className} style={shell} data-testid="checkout-link-page" data-state={view.status}>
+        <h1 style={heading}>{closed.title}</h1>
+        <p style={muted}>{closed.body}</p>
+        {view.status !== "paid" && (view.booking ? otherTimes(view.booking.servicePath) : toStore)}
+      </div>
+    );
+  }
+
+  const total = fmt(view.totalCents / 100, view.currency);
+  const refused = page.refusal;
+  const timeTaken = !!refused && refused.code === "INVENTORY_HOLD_EXPIRED" && !!view.booking;
+
+  return (
+    <div className={className} style={shell} data-testid="checkout-link-page" data-state="open">
+      <h1 style={heading}>{tr("forge.checkout_link_payment.title")}</h1>
+      <Summary view={view} fmt={fmt} />
+
+      <div style={{ marginTop: 16 }}>
+        <HoldNotice
+          hold={hold}
+          noun={tr(view.booking ? "forge.checkout_link_payment.hold_noun_booking" : "forge.checkout_link_payment.hold_noun")}
+        />
+      </div>
+
+      {refused && (
+        <p role="alert" data-testid="checkout-link-refusal" style={{ color: t.secondary, fontSize: 14, marginTop: 8 }}>
+          {refused.message || tr("forge.checkout_link_payment.payment_unavailable")}
+        </p>
+      )}
+      {timeTaken && otherTimes(view.booking?.servicePath)}
+
+      <div style={{ marginTop: 16 }}>
+        {page.isPaystack ? (
+          page.canOpenPaystack ? (
+            <PaystackPayButton
+              onPay={page.openPaystackCheckout}
+              label={tr("forge.checkout_link_payment.pay_amount", { amount: total })}
+            />
+          ) : (
+            <Loading label={tr("forge.checkout_link_payment.preparing_payment")} size={22} />
+          )
+        ) : page.clientSecret ? (
+          renderPayment?.({
+            clientSecret: page.clientSecret,
+            returnUrl: page.returnUrl,
+            amount: view.totalCents / 100,
+            currency: view.currency,
+            mode: "redirect",
+          })
+        ) : timeTaken ? null : (
+          <Button
+            fullWidth
+            loading={page.isStarting}
+            disabled={hold.hasLapsed && !refused}
+            onClick={() => void page.pay()}
+            data-testid="checkout-link-pay"
+          >
+            {tr("forge.checkout_link_payment.pay_amount", { amount: total })}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function Summary({
+  view,
+  fmt,
+}: {
+  view: CheckoutLinkView;
+  fmt: (amount: number, currencyCode?: string) => string;
+}) {
+  const tr = useForgeT();
+  const t = useThemeTokens();
+  return (
+    <div
+      data-testid="checkout-link-summary"
+      style={{
+        border: `1px solid ${t.border}`,
+        borderRadius: t.cornerRadius,
+        padding: 20,
+        background: t.surface,
+      }}
+    >
+      <div style={{ fontSize: 18, fontWeight: 700 }} data-testid="checkout-link-item">
+        {view.item?.title}
+      </div>
+      {view.booking ? (
+        <div style={{ marginTop: 12, color: t.muted }}>
+          {view.booking.sessions.map((session) => (
+            // The buyer's own clock: the time is shown in the zone of the
+            // device reading it, with the zone named.
+            <div key={session.startsAt} data-testid="checkout-link-session" suppressHydrationWarning>
+              {formatLocalTime(session.startsAt)}
+            </div>
+          ))}
+          {view.status === "open" && (
+            <div style={{ marginTop: 8, fontSize: 14 }} data-testid="checkout-link-held-until" suppressHydrationWarning>
+              {tr("forge.checkout_link_payment.held_until", { time: formatLocalTime(view.expiresAt) })}
+            </div>
+          )}
+        </div>
+      ) : (
+        <div style={{ display: "flex", justifyContent: "space-between", marginTop: 12, color: t.muted }}>
+          <span data-testid="checkout-link-quantity">
+            {tr("forge.checkout_link_payment.quantity", { quantity: view.quantity })}
+          </span>
+          {view.unitPriceCents !== null && (
+            <span>{tr("forge.checkout_link_payment.each", { price: fmt(view.unitPriceCents / 100, view.currency) })}</span>
+          )}
+        </div>
+      )}
+      <div
+        style={{ display: "flex", justifyContent: "space-between", marginTop: 12, fontSize: 20, fontWeight: 800 }}
+      >
+        <span>{tr("forge.checkout_link_payment.total")}</span>
+        <span data-testid="checkout-link-total" style={{ color: t.primary }}>
+          {fmt(view.totalCents / 100, view.currency)}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+function go(path: string) {
+  if (typeof window !== "undefined") window.location.href = path;
+}
+
+/** A moment in the reader's own time zone, with the zone named ("Tuesday 14 October, 10:00 CEST"). */
+function formatLocalTime(iso: string, timeZone?: string): string {
+  try {
+    return new Intl.DateTimeFormat(undefined, {
+      weekday: "long",
+      day: "numeric",
+      month: "long",
+      hour: "2-digit",
+      minute: "2-digit",
+      timeZoneName: "short",
+      ...(timeZone ? { timeZone } : {}),
+    }).format(new Date(iso));
+  } catch {
+    return new Date(iso).toISOString();
+  }
+}

package/src/ui/styled/_tests/CheckoutLinkPayment.spec.tsx

@@ -0,0 +1,231 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import type { CheckoutLinkView } from "../../../data/queries/useCheckoutLink";
+
+/**
+ * The hosted pay page for a checkout link (`/i/checkout/pay/<token>`).
+ *
+ * `useCheckoutLinkPayment` is stubbed at the module boundary: the server
+ * decides everything (open, closed, paid too late); what can only go wrong
+ * here is the page drawing the wrong state. Each state is a different fact
+ * the buyer acts on: pay now, it is already paid, the hold ended, it was
+ * withdrawn, or a refund is coming.
+ *
+ * Rendered through `react-dom/server`, so no DOM and no effects.
+ */
+
+type Page = ReturnType<typeof import("../../headless/checkoutLink/useCheckoutLinkPayment").useCheckoutLinkPayment>;
+const state = vi.hoisted(() => ({ current: null as unknown }));
+
+vi.mock("../../headless/checkoutLink/useCheckoutLinkPayment", () => ({
+  useCheckoutLinkPayment: () => state.current,
+}));
+
+const { CheckoutLinkPayment } = await import("../CheckoutLinkPayment");
+
+const view = (overrides: Partial<CheckoutLinkView> = {}): CheckoutLinkView => ({
+  status: "open",
+  needsRefund: false,
+  item: { type: "event_ticket", title: "Spring Show: General" },
+  quantity: 2,
+  unitPriceCents: 2500,
+  totalCents: 5000,
+  currency: "USD",
+  expiresAt: new Date(Date.now() + 20 * 60_000).toISOString(),
+  ...overrides,
+});
+
+const page = (overrides: Record<string, unknown> = {}) =>
+  ({
+    link: { isLoading: false, error: null, data: view() },
+    finalize: { isLoading: false, error: null, data: undefined },
+    returnUrl: "https://shop.test/i/checkout/pay/tok?finalise=1",
+    pay: async () => {},
+    isStarting: false,
+    clientSecret: undefined,
+    isPaystack: false,
+    canOpenPaystack: false,
+    openPaystackCheckout: async () => "unavailable",
+    refusal: null,
+    holdExpiresAt: view().expiresAt,
+    ...overrides,
+  }) as unknown as Page;
+
+function render(current: Page, props: { returning?: boolean } = {}): string {
+  state.current = current;
+  return renderToStaticMarkup(
+    <QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId="profile-1">
+        <PublicAuthContext.Provider value={{ currencies: null, userSelectedCurrency: "USD" } as never}>
+          <ForgeThemeProvider
+            theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}
+          >
+            <CheckoutLinkPayment token="tok" formatAmount={(n) => `$${n.toFixed(2)}`} {...props} />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("CheckoutLinkPayment", () => {
+  it("an open link shows the item, the quantity, the price and a Pay button for the total", () => {
+    const html = render(page());
+    expect(html).toContain('data-state="open"');
+    expect(html).toContain("Held for you");
+    expect(html).toContain("Spring Show: General");
+    expect(html).toContain("Quantity: 2");
+    expect(html).toContain("$25.00 each");
+    expect(html).toContain("$50.00");
+    expect(html).toContain('data-testid="checkout-link-pay"');
+    expect(html).toContain("Pay $50.00");
+  });
+
+  it("a refused Pay shows the server's own words", () => {
+    const html = render(
+      page({ refusal: { message: "These tickets are no longer held for you.", code: "INVENTORY_HOLD_EXPIRED", status: null } }),
+    );
+    expect(html).toContain('data-testid="checkout-link-refusal"');
+    expect(html).toContain("These tickets are no longer held for you.");
+  });
+
+  it.each([
+    [{ status: "paid" as const }, "Payment received", false],
+    [{ status: "expired" as const }, "This reservation has ended", true],
+    [{ status: "cancelled" as const }, "This link is no longer available", true],
+    [{ status: "expired" as const, needsRefund: true }, "Your payment will be refunded", true],
+  ])("a closed link (%o) says so, and offers the store unless it was paid", (overrides, title, offersStore) => {
+    const html = render(page({ link: { isLoading: false, error: null, data: view(overrides) } }));
+    expect(html).toContain(title);
+    expect(html).not.toContain('data-testid="checkout-link-pay"');
+    expect(html.includes('data-testid="checkout-link-store"')).toBe(offersStore);
+  });
+
+  describe("a booking", () => {
+    const START = "2026-11-03T15:00:00.000Z";
+    const booking = (overrides: Partial<CheckoutLinkView> = {}) =>
+      view({
+        item: { type: "booking", title: "Initial consultation" },
+        quantity: 1,
+        unitPriceCents: 15000,
+        totalCents: 15000,
+        expiresAt: "2026-11-01T12:30:00.000Z",
+        booking: {
+          sessions: [{ startsAt: START, endsAt: "2026-11-03T16:00:00.000Z" }],
+          timezone: "America/New_York",
+          servicePath: "/i/coaching/initial-consultation",
+        },
+        ...overrides,
+      });
+    // What the page must print: the buyer's own clock, the zone named.
+    const local = (iso: string) =>
+      new Intl.DateTimeFormat(undefined, {
+        weekday: "long",
+        day: "numeric",
+        month: "long",
+        hour: "2-digit",
+        minute: "2-digit",
+        timeZoneName: "short",
+      }).format(new Date(iso));
+
+    it("shows the service, the session in the reader's own zone, until when it is held, and the price, with no quantity", () => {
+      const html = render(page({ link: { isLoading: false, error: null, data: booking() } }));
+      expect(html).toContain('data-state="open"');
+      expect(html).toContain("Initial consultation");
+      expect(html).toContain('data-testid="checkout-link-session"');
+      expect(html).toContain(local(START));
+      expect(html).toContain(`Held for you until ${local("2026-11-01T12:30:00.000Z")}`);
+      expect(html).toContain("Pay $150.00");
+      expect(html).not.toContain('data-testid="checkout-link-quantity"');
+    });
+
+    it("lists every session of a package", () => {
+      const second = "2026-11-10T15:00:00.000Z";
+      const html = render(
+        page({
+          link: {
+            isLoading: false,
+            error: null,
+            data: booking({
+              booking: {
+                sessions: [
+                  { startsAt: START, endsAt: "2026-11-03T16:00:00.000Z" },
+                  { startsAt: second, endsAt: "2026-11-10T16:00:00.000Z" },
+                ],
+                timezone: "UTC",
+                servicePath: null,
+              },
+            }),
+          },
+        }),
+      );
+      expect(html.split('data-testid="checkout-link-session"')).toHaveLength(3);
+      expect(html).toContain(local(second));
+    });
+
+    it("a time that was taken while unpaid: the refusal, no Pay button, and a way to pick another time", () => {
+      const html = render(
+        page({
+          link: { isLoading: false, error: null, data: booking() },
+          refusal: {
+            message: "Your hold on this time expired and it is no longer available. Please pick another time",
+            code: "INVENTORY_HOLD_EXPIRED",
+            status: null,
+          },
+        }),
+      );
+      expect(html).toContain('data-testid="checkout-link-refusal"');
+      expect(html).toContain('data-testid="checkout-link-other-times"');
+      expect(html).toContain("Pick another time");
+      expect(html).not.toContain('data-testid="checkout-link-pay"');
+    });
+
+    it("an ended booking link offers another time instead of the store", () => {
+      const html = render(page({ link: { isLoading: false, error: null, data: booking({ status: "expired" }) } }));
+      expect(html).toContain("This reservation has ended");
+      expect(html).toContain('data-testid="checkout-link-other-times"');
+      expect(html).not.toContain('data-testid="checkout-link-store"');
+      expect(html).not.toContain('data-testid="checkout-link-held-until"');
+    });
+  });
+
+  it("an unknown link says it is not valid", () => {
+    const html = render(page({ link: { isLoading: false, error: new Error("404"), data: undefined } }));
+    expect(html).toContain('data-state="not-found"');
+    expect(html).toContain("Link not found");
+  });
+
+  it("the return leg: paid shows the confirmation, unpaid offers another try, too late says a refund is coming", () => {
+    const paid = render(
+      page({ finalize: { isLoading: false, error: null, data: { outcome: "fulfilled", link: view({ status: "paid" }) } } }),
+      { returning: true },
+    );
+    expect(paid).toContain('data-state="paid"');
+    expect(paid).toContain("Payment received");
+    expect(paid).toContain("Spring Show: General");
+
+    const unpaid = render(
+      page({ finalize: { isLoading: false, error: null, data: { outcome: "unpaid", link: view() } } }),
+      { returning: true },
+    );
+    expect(unpaid).toContain('data-state="unpaid"');
+    expect(unpaid).toContain("Try again");
+
+    const late = render(
+      page({
+        finalize: {
+          isLoading: false,
+          error: null,
+          data: { outcome: "needs_refund", link: view({ status: "expired", needsRefund: true }) },
+        },
+      }),
+      { returning: true },
+    );
+    expect(late).toContain('data-state="needs-refund"');
+    expect(late).toContain("Your payment will be refunded");
+  });
+});