@tribe-nest/forge 3.53.0 → 3.57.0

package/src/ui/headless/membership/useMembershipCheckout.ts

@@ -1,6 +1,11 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import {
+  readMembershipInviteFromUrl,
+  useApplyForMembership,
+  useConfirmMembershipApplication,
+  useGetMembershipTiers,
+} from "../../../data/queries/useMembership";
 import {
   useCreateSubscription,
   useCreateFreeSubscription,
@@ -14,7 +19,15 @@ import {
   type PaystackCheckoutOutcome,
   type PaystackCheckoutSession,
 } from "../../../utils/paystackCheckout";
-import type { MembershipTier } from "../../../types/models";
+import type { MembershipApplication, MembershipTier, QuestionnaireQuestion } from "../../../types/models";
+import { stripeIntentKind } from "../../payment/stripeIntentKind";
+import { tierTrialDays, trialEndDate } from "./membershipTrial";
+import { buildQuestionnaireAnswers, firstMissingAnswer, tierQuestionnaire } from "./membershipQuestionnaire";
+import {
+  membershipApplicationOutcome,
+  tierUsesApplication,
+  type MembershipApplicationOutcome,
+} from "./membershipApplication";
 import {
   cycleCeiling,
   cycleFloor,
@@ -54,6 +67,19 @@ export interface UseMembershipCheckoutOptions {
    * is no provider payment for the account page to reconcile.
    */
   onComplete?: (result: { requiresConfirmation: boolean }) => void;
+  /**
+   * A membership invite token, sent with the subscribe call and the tier list so
+   * an invite-only tier can be joined. Omitted, the `invite` search param of
+   * the current url is used; `null` sends none.
+   */
+  inviteToken?: string | null;
+  /**
+   * Where Stripe returns after a redirect-based card confirmation on an
+   * APPLICATION (a card that needed a bank redirect). Default
+   * `/i/account?tab=membership`, where the fan's applications are listed. The
+   * application id is appended as `confirmApplication`.
+   */
+  applicationReturnPath?: string;
 }
 
 const errMessage = (e: unknown) =>
@@ -80,10 +106,13 @@ const errMessage = (e: unknown) =>
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user, refetchUser } = usePublicAuth();
-  const { data: tiers, isLoading } = useGetMembershipTiers();
+  const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
+  const { data: tiers, isLoading } = useGetMembershipTiers({ inviteToken: inviteToken ?? null });
   const createPaid = useCreateSubscription();
   const createFree = useCreateFreeSubscription();
   const confirmLatest = useConfirmLatestSubscription();
+  const applyMutation = useApplyForMembership();
+  const confirmApplicationMutation = useConfirmMembershipApplication();
 
   const [step, setStep] = useState<MembershipCheckoutStep>(opts.initialTierId ? "select" : "tier");
   const [selectedTierId, setSelectedTierId] = useState<string | undefined>(opts.initialTierId);
@@ -94,8 +123,20 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   /** The started Paystack checkout, kept so the modal can be re-opened. */
   const [paystackSession, setPaystackSession] = useState<PaystackCheckoutSession | null>(null);
   const [error, setError] = useState<string | null>(null);
+  /** Answers to the selected tier's questions, keyed by question id. */
+  const [questionnaireAnswers, setQuestionnaireAnswers] = useState<Record<string, string>>({});
+  /** Set once subscribe() was pressed on this tier, so blank required answers read as refused from then on. */
+  const [questionnaireAttempted, setQuestionnaireAttempted] = useState(false);
+  /** The application this checkout submitted, once it has. */
+  const [application, setApplication] = useState<MembershipApplication | null>(null);
+  /** Set once the card renderer reported the SetupIntent confirmed. */
+  const [cardConfirmed, setCardConfirmed] = useState(false);
+  /** The free trial the paid subscribe call started, if any. */
+  const [trial, setTrial] = useState<{ days: number; endsAt: string } | null>(null);
 
   const selectedTier = useMemo(() => tiers?.find((t) => t.id === selectedTierId), [tiers, selectedTierId]);
+  /** The questions this checkout asks: none when completing a `payment_failed` application. */
+  const questionnaire = useMemo(() => tierQuestionnaire(selectedTier), [selectedTier]);
 
   /**
    * Seed the cycle and the amount box from the tier itself.
@@ -109,6 +150,9 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
    * keying on that would wipe the amount a fan had just typed.
    */
   useEffect(() => {
+    // Answers belong to one tier's questions: a different tier starts blank.
+    setQuestionnaireAnswers({});
+    setQuestionnaireAttempted(false);
     if (!selectedTier) return;
     const cycle = defaultCycle(selectedTier);
     setBillingCycleState(cycle);
@@ -129,6 +173,9 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
 
   const selectTier = useCallback((tier: MembershipTier) => {
     setSelectedTierId(tier.id);
+    setApplication(null);
+    setTrial(null);
+    setCardConfirmed(false);
     setError(null);
     setAmountRefusal(null);
     setStep("select");
@@ -136,15 +183,36 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
 
   const backToTierList = useCallback(() => {
     setSelectedTierId(undefined);
+    setApplication(null);
+    setTrial(null);
+    setCardConfirmed(false);
     setError(null);
     setAmountRefusal(null);
     setStep("tier");
   }, []);
 
+  const setQuestionnaireAnswer = useCallback((questionId: string, value: string) => {
+    setQuestionnaireAnswers((prev) => ({ ...prev, [questionId]: value }));
+  }, []);
+  /**
+   * Derived, not stored: once a subscribe attempt was made it follows the
+   * answers, so the message beside the questions never names one the fan has
+   * just answered.
+   */
+  const questionnaireRefusal: QuestionnaireQuestion | null = questionnaireAttempted
+    ? firstMissingAnswer(questionnaire, questionnaireAnswers)
+    : null;
+
   const minimumAmount = selectedTier ? cycleFloor(selectedTier, billingCycle) : 0;
   const maximumAmount = selectedTier ? cycleCeiling(selectedTier, billingCycle) : null;
   const cycles = selectedTier ? offeredCycles(selectedTier) : { month: false, year: false };
   const isFreeCycle = selectedTier ? cycleIsFree(selectedTier, billingCycle) : false;
+  /**
+   * True when subscribe() APPLIES rather than joins: an `application` tier,
+   * except when the fan's own application is `payment_failed`, where the
+   * ordinary paid checkout completes the membership they were approved for.
+   */
+  const isApplication = tierUsesApplication(selectedTier);
 
   /**
    * What will be charged, and what will be SENT. A fixed tier ignores the
@@ -167,6 +235,14 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const isChange =
     !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
 
+  /**
+   * The free trial this fan would start on the selected tier, in days, or 0.
+   * Zero on a free cycle (nothing to trial) and on a tier change (the server
+   * moves an existing subscription, it does not start a new one). An
+   * application tier still reports it: approval starts the trial.
+   */
+  const trialDays = isFreeCycle || isChange ? 0 : tierTrialDays(selectedTier);
+
   /**
    * `await`ed by every caller, because of the refetch below.
    *
@@ -195,9 +271,14 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
   };
 
+  /** `{ questionnaire }` for the request body, or nothing when this checkout asks no questions. */
+  const questionnaireBody = () =>
+    questionnaire.length ? { questionnaire: buildQuestionnaireAnswers(questionnaire, questionnaireAnswers) } : {};
+
   const subscribe = async () => {
     setError(null);
     setAmountRefusal(null);
+    setTrial(null);
     if (!selectedTier) {
       setError("Select a membership tier.");
       return;
@@ -210,17 +291,31 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     // (or still on its initial zero) is a message beside the field rather than
     // an `amount_must_be_positive` 400 with nowhere to land.
     const refusal = refuseMembershipAmount(selectedTier, billingCycle, customAmount);
-    if (refusal) {
-      setAmountRefusal(refusal);
+    // Same for the tier's questions: a blank required answer is refused beside
+    // the questions, before any request, rather than as a 400 from the server.
+    const missing = firstMissingAnswer(questionnaire, questionnaireAnswers);
+    setQuestionnaireAttempted(true);
+    if (refusal) setAmountRefusal(refusal);
+    if (refusal || missing) return;
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    if (isApplication) {
+      await submitApplication(origin);
       return;
     }
-    const origin = typeof window !== "undefined" ? window.location.origin : "";
     const returnUrl = `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`;
     const attributionRefId = readAttributionRef() ?? undefined;
     const landing = readLanding() ?? {};
+    const invite = inviteToken ? { inviteToken } : {};
+    const answers = questionnaireBody();
     try {
       if (isFreeCycle) {
-        await createFree.mutateAsync({ membershipTierId: selectedTier.id, attributionRefId, ...landing });
+        await createFree.mutateAsync({
+          membershipTierId: selectedTier.id,
+          attributionRefId,
+          ...landing,
+          ...invite,
+          ...answers,
+        });
         await finish(false);
         return;
       }
@@ -231,6 +326,8 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
         returnUrl,
         attributionRefId,
         ...landing,
+        ...invite,
+        ...answers,
       });
 
       // A member who already subscribes is CHANGING TIER: the server moved their
@@ -265,6 +362,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
         return;
       }
 
+      // A trial saves the card instead of charging it: the secret is a
+      // SetupIntent, the renderer confirms it with `confirmSetup`, and the return
+      // page's `confirmLatest` activates the membership like any paid one.
+      setTrial(data.trial ?? null);
       setClientSecret(data.clientSecret);
       setStep("payment");
     } catch (e) {
@@ -272,6 +373,69 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
   };
 
+  /**
+   * Apply to an `application` tier. Free: the application is lodged and the
+   * outcome is set. Paid: the server hands back a SetupIntent secret, the step
+   * moves to "payment" and the renderer saves the card; `confirmApplication()`
+   * runs after it succeeds. Nothing is charged until the business approves.
+   */
+  const applicationReturnBase = opts.applicationReturnPath ?? "/i/account?tab=membership";
+  const submitApplication = async (origin: string) => {
+    if (!selectedTier) return;
+    try {
+      const data = await applyMutation.mutateAsync({
+        membershipTierId: selectedTier.id,
+        ...(isFreeCycle ? {} : { billingCycle, amount }),
+        ...questionnaireBody(),
+        returnUrl: `${origin}${applicationReturnBase}`,
+      });
+      setApplication(data.application);
+      setCardConfirmed(false);
+      if (data.requiresCard && data.clientSecret) {
+        setClientSecret(data.clientSecret);
+        setStep("payment");
+      }
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  /** Call after the card renderer confirmed the SetupIntent. Idempotent on the server. */
+  const confirmApplication = async () => {
+    if (!application) return;
+    setError(null);
+    setCardConfirmed(true);
+    try {
+      const data = await confirmApplicationMutation.mutateAsync({ applicationId: application.id });
+      setApplication(data.application);
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  const applicationOutcome: MembershipApplicationOutcome | null = membershipApplicationOutcome(
+    application,
+    cardConfirmed,
+  );
+  /**
+   * What the payment step is confirming, read off the SECRET, not off the tier:
+   * a `seti_` secret is a card save whatever started it (an application, or a
+   * paid subscription that opens with a free trial), and confirming it as a
+   * payment fails with an error the fan cannot act on.
+   */
+  const paymentKind: "setup" | "payment" = paystackSession ? "payment" : stripeIntentKind(clientSecret);
+  /** Why a card is being saved: `application`, `trial`, or null when it is a payment. */
+  const setupPurpose: "application" | "trial" | null =
+    paymentKind !== "setup" ? null : isApplication && application ? "application" : "trial";
+  /** When the first charge falls: the server's date once subscribed, else today + trialDays. */
+  const trialEndsAt: string | null = trial?.endsAt ?? (trialDays > 0 ? trialEndDate(trialDays).toISOString() : null);
+
+  const applicationReturnUrl = application
+    ? `${typeof window !== "undefined" ? window.location.origin : ""}${applicationReturnBase}${
+        applicationReturnBase.includes("?") ? "&" : "?"
+      }confirmApplication=${encodeURIComponent(application.id)}`
+    : undefined;
+
   return {
     tiers,
     isLoading,
@@ -314,11 +478,66 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
             onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
           })
         : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
-    isProcessing: createPaid.isPending || createFree.isPending,
+    isProcessing:
+      createPaid.isPending || createFree.isPending || applyMutation.isPending || confirmApplicationMutation.isPending,
     error,
     /** Call on the return page to reconcile the latest subscription. */
     confirmLatest,
     /** Signals a completed paid payment (the Stripe `onSucceeded` leg). */
     finish,
+    /** The invite token this checkout forwards, if any. */
+    inviteToken,
+    /** True when subscribe() applies to the tier instead of joining it. */
+    isApplication,
+    /**
+     * The selected tier's questions, asked before paying, joining or applying.
+     * Empty when the tier asks none, and when completing an approved
+     * application whose card was declined (its answers were already given).
+     */
+    questionnaire,
+    /** The answers so far, keyed by question id. Reset when the tier changes. */
+    questionnaireAnswers,
+    /** Record the answer to one question. */
+    setQuestionnaireAnswer,
+    /**
+     * The first required question left blank, once subscribe() refused for it;
+     * null otherwise. Nothing was sent. Show it beside the questions.
+     */
+    questionnaireRefusal,
+    /** The application this checkout submitted, as the server last returned it. */
+    application,
+    /**
+     * Where the application stands once submitted: `received`, `approved`,
+     * `tier_full`, `declined` or `closed`; null before submitting and while the
+     * card step is still ahead.
+     */
+    applicationOutcome,
+    /**
+     * `"setup"` while the payment step is saving a card for an application
+     * (the secret is a SetupIntent), else `"payment"`.
+     */
+    paymentKind,
+    /** Why the payment step saves a card: `application`, `trial`, or null when it charges. */
+    setupPurpose,
+    /**
+     * The free trial the selected tier gives THIS fan, in days (0 for none: no
+     * trial on the tier, already had one with this business, a free cycle, or a
+     * tier change).
+     */
+    trialDays,
+    /** The trial the subscribe call started (`{ days, endsAt }`), or null. */
+    trial,
+    /** When the first charge falls for a trial (ISO), or null without one. */
+    trialEndsAt,
+    /**
+     * Call once the card renderer reports success. An application's saved card
+     * goes to `confirmApplication`; a paid subscription (charged, or a trial's
+     * saved card) finishes to the return page, which runs `confirmLatest`.
+     */
+    onPaymentSucceeded: () => (setupPurpose === "application" ? confirmApplication() : finish(true)),
+    /** The renderer's `returnUrl` for an application's card step. */
+    applicationReturnUrl,
+    /** Call after the card renderer confirmed an application's SetupIntent. */
+    confirmApplication,
   };
 }

package/src/ui/index.ts

@@ -41,6 +41,7 @@ export {
   usePaymentRenderer,
   type PaymentRenderer,
   type PaymentRenderProps,
+  type PaymentTrial,
 } from "./payment/ForgePaymentProvider";
 
 // Re-export the headless layer so consumers can reach both tiers from `forge/ui`.
@@ -73,6 +74,23 @@ export {
 export { PresaleCodeField, type PresaleCodeFieldProps } from "./styled/PresaleCode";
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
+// For a custom payment renderer: which post-confirm statuses count as done
+// (a deferred charge stops at `requires_capture`), and the deferred-charge
+// wording decision the built-in renderer makes.
+export {
+  deferredChargeNotice,
+  isDeferredSettlement,
+  isManualConfirmSuccess,
+  MANUAL_CONFIRM_SUCCESS_STATUSES,
+} from "./payment/stripeConfirmOutcome";
+// For a custom payment renderer: a SetupIntent secret (an application to a
+// membership tier, or a paid membership starting with a free trial) saves the card through `confirmSetup` instead of charging it.
+export {
+  isSetupConfirmSuccess,
+  SETUP_CONFIRM_SUCCESS_STATUSES,
+  stripeIntentKind,
+  type StripeIntentKind,
+} from "./payment/stripeIntentKind";
 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";
@@ -346,3 +364,12 @@ export * from "./styled/work";
 
 // Unified member home (`/i/members`) styled blocks.
 export * from "./styled/members";
+
+// The review page a "how did we do?" email lands on. Here rather than in a
+// storefront because both the hosted `/i/reviews/$token` page and every site's
+// root-level `/reviews/$token` alias render it.
+export * from "./styled/ReviewRequestPage";
+// The contract signing page. Here for the same reason: both storefronts render
+// it, at BOTH the canonical `/i/documents/$token` and the older
+// `/documents/$token` that already-sent links point at.
+export * from "./styled/DocumentSigningPage";

package/src/ui/payment/ForgePaymentProvider.tsx

@@ -1,3 +1,4 @@
+import type { DeferredChargeStrategy, PaymentSettlement } from "../../types/models";
 import { createContext, useContext, type ReactNode } from "react";
 import { ForgeStripePayment } from "./ForgeStripePayment";
 
@@ -16,6 +17,34 @@ export interface PaymentRenderProps {
   mode?: "redirect" | "manual";
   onSucceeded?: () => void;
   onFailed?: (message?: string) => void;
+  /**
+   * `"deferred"` when the charge is committed now and taken only if the
+   * organiser approves (a ticket request). The built-in renderer then labels
+   * the button "Authorize {amount}" and says under it that the card is charged
+   * only on approval. Absent on every ordinary sale, so a custom renderer that
+   * ignores it keeps working exactly as before.
+   */
+  settlement?: PaymentSettlement;
+  /**
+   * How the provider defers: `"authorization"` shows a temporary hold on the
+   * fan's statement and the renderer says so; `"saved_instrument"` takes
+   * nothing until approval. Only sent with `settlement: "deferred"`.
+   */
+  deferredStrategy?: DeferredChargeStrategy | null;
+  /**
+   * Set when a SetupIntent secret starts a FREE TRIAL on a paid membership
+   * rather than an application. The built-in renderer then reads "Start free
+   * trial" and says under the button that nothing is charged today, what is
+   * charged per cycle, and from which date. Ignored on a payment secret.
+   */
+  trial?: PaymentTrial | null;
+}
+
+/** The free trial a card save starts: when the first charge falls, and its cycle. */
+export interface PaymentTrial {
+  /** ISO date of the first charge. */
+  endsAt: string;
+  billingCycle: "month" | "year";
 }
 
 export type PaymentRenderer = (props: PaymentRenderProps) => ReactNode;

package/src/ui/payment/ForgeStripePayment.tsx

@@ -5,7 +5,11 @@ import { useForgeTheme } from "../theme/ForgeThemeProvider";
 import { readableTextOn } from "../theme/contrast";
 import { useFormatCurrency } from "../format/useFormatCurrency";
 import { useSiteConfig } from "../../data/queries/useWebsite";
+import { useForgeLocale, useForgeT } from "../../i18n";
+import { formatTrialDate } from "../headless/membership/membershipTrial";
 import type { PaymentRenderProps } from "./ForgePaymentProvider";
+import { deferredChargeNotice, isDeferredSettlement, isManualConfirmSuccess } from "./stripeConfirmOutcome";
+import { isSetupConfirmSuccess, stripeIntentKind, type StripeIntentKind } from "./stripeIntentKind";
 
 function alpha(hex: number) {
   return Math.round(hex * 255)
@@ -21,6 +25,13 @@ function alpha(hex: number) {
  * `useSiteConfig()` (Stripe Connect: `loadStripe(platformKey, { stripeAccount })`),
  * the appearance from `ForgeThemeProvider`, and the pay-button amount from
  * `useFormatCurrency()`. The consuming site wires nothing.
+ *
+ * A SetupIntent secret (`seti_...`) saves the card instead of charging it (an
+ * application to a membership tier): the same Element renders, the confirm goes
+ * through `stripe.confirmSetup`, and the button and the line under it say that
+ * the card is charged only on approval. A setup that starts a free trial on a
+ * paid membership (`trial` set) reads "Start free trial" and says nothing is
+ * charged today, then what is charged from which date.
  */
 export function ForgeStripePayment({
   clientSecret,
@@ -30,6 +41,9 @@ export function ForgeStripePayment({
   mode = "redirect",
   onSucceeded,
   onFailed,
+  settlement,
+  deferredStrategy,
+  trial,
 }: PaymentRenderProps) {
   const theme = useForgeTheme();
   const { data: siteConfig } = useSiteConfig();
@@ -91,33 +105,97 @@ export function ForgeStripePayment({
 
   return (
     <Elements options={{ clientSecret, appearance, loader: "auto" }} stripe={stripePromise}>
-      <Inner returnUrl={returnUrl} amount={amount} currency={currency} mode={mode} onSucceeded={onSucceeded} onFailed={onFailed} />
+      <Inner
+        intentKind={stripeIntentKind(clientSecret)}
+        returnUrl={returnUrl}
+        amount={amount}
+        currency={currency}
+        mode={mode}
+        onSucceeded={onSucceeded}
+        onFailed={onFailed}
+        settlement={settlement}
+        deferredStrategy={deferredStrategy}
+        trial={trial}
+      />
     </Elements>
   );
 }
 
 function Inner({
+  intentKind,
   returnUrl,
   amount,
   currency,
   mode = "redirect",
   onSucceeded,
   onFailed,
-}: Omit<PaymentRenderProps, "clientSecret">) {
+  settlement,
+  deferredStrategy,
+  trial,
+}: Omit<PaymentRenderProps, "clientSecret"> & { intentKind: StripeIntentKind }) {
   const theme = useForgeTheme();
+  const t = useForgeT();
+  const locale = useForgeLocale();
   const { formatCurrency } = useFormatCurrency();
   const stripe = useStripe();
   const elements = useElements();
   const [message, setMessage] = useState("");
   const [isLoading, setIsLoading] = useState(false);
 
-  const buttonText = `Pay ${formatCurrency(amount, currency || undefined)} Now`;
+  // A deferred charge is not a payment yet: the button says what actually
+  // happens when it is pressed, and the line under it says when the money
+  // moves. That line is content, not help: a fan reading "Authorize" without
+  // it has been told their card was committed and nothing about why.
+  const deferred = isDeferredSettlement(settlement);
+  const formattedAmount = formatCurrency(amount, currency || undefined);
+  // A setup takes nothing now: the button submits the application, and the
+  // consent line under it is the thing the fan is agreeing to, so it is content.
+  const isSetup = intentKind === "setup";
+  // A trial also saves the card, but for a subscription the fan is starting now.
+  const isTrial = isSetup && !!trial;
+  const buttonText = isTrial
+    ? t("forge.forge_stripe_payment.start_free_trial")
+    : isSetup
+    ? t("forge.forge_stripe_payment.submit_application")
+    : deferred
+      ? t("forge.forge_stripe_payment.authorize", { amount: formattedAmount })
+      : `Pay ${formattedAmount} Now`;
 
   const handleSubmit = useCallback(async () => {
     if (!stripe || !elements) return;
     setIsLoading(true);
     setMessage("");
 
+    if (isSetup) {
+      if (mode === "manual") {
+        const { error, setupIntent } = await stripe.confirmSetup({
+          elements,
+          confirmParams: { return_url: returnUrl },
+          redirect: "if_required",
+        });
+        if (error) {
+          const msg = error.message ?? t("forge.forge_stripe_payment.setup_failed");
+          setMessage(msg);
+          setIsLoading(false);
+          onFailed?.(msg);
+          return;
+        }
+        setIsLoading(false);
+        if (isSetupConfirmSuccess(setupIntent?.status)) {
+          onSucceeded?.();
+          return;
+        }
+        const msg = t("forge.forge_stripe_payment.setup_incomplete");
+        setMessage(msg);
+        onFailed?.(msg);
+        return;
+      }
+      const { error } = await stripe.confirmSetup({ elements, confirmParams: { return_url: returnUrl } });
+      setMessage(error.message ?? t("forge.forge_stripe_payment.setup_failed"));
+      setIsLoading(false);
+      return;
+    }
+
     if (mode === "manual") {
       const { error, paymentIntent } = await stripe.confirmPayment({
         elements,
@@ -131,7 +209,9 @@ function Inner({
         onFailed?.(msg);
         return;
       }
-      if (paymentIntent?.status === "succeeded" || paymentIntent?.status === "processing") {
+      // `requires_capture` is a deferred charge that went through: the card is
+      // authorised and the platform captures it on approval. See the helper.
+      if (isManualConfirmSuccess(paymentIntent?.status)) {
         setIsLoading(false);
         onSucceeded?.();
         return;
@@ -144,7 +224,7 @@ function Inner({
     const { error } = await stripe.confirmPayment({ elements, confirmParams: { return_url: returnUrl } });
     setMessage(error.message ?? "An unexpected error occurred.");
     setIsLoading(false);
-  }, [stripe, elements, mode, returnUrl, onSucceeded, onFailed]);
+  }, [stripe, elements, mode, returnUrl, onSucceeded, onFailed, isSetup, t]);
 
   return (
     <form onSubmit={(e) => e.preventDefault()} style={{ display: "flex", flexDirection: "column", gap: 12 }}>
@@ -166,6 +246,31 @@ function Inner({
       >
         {isLoading ? "Processing…" : buttonText}
       </button>
+      {isTrial && trial && (
+        <p data-testid="trial-consent-notice" style={{ margin: 0, fontSize: 13, opacity: 0.8, lineHeight: 1.5 }}>
+          {t("forge.forge_stripe_payment.trial_consent", {
+            amount: formattedAmount,
+            cycle:
+              trial.billingCycle === "year"
+                ? t("forge.forge_stripe_payment.cycle_year")
+                : t("forge.forge_stripe_payment.cycle_month"),
+            date: formatTrialDate(trial.endsAt, locale),
+          })}
+        </p>
+      )}
+      {isSetup && !isTrial && (
+        <p data-testid="setup-consent-notice" style={{ margin: 0, fontSize: 13, opacity: 0.8, lineHeight: 1.5 }}>
+          {t("forge.forge_stripe_payment.setup_charged_on_approval", { amount: formattedAmount })}
+        </p>
+      )}
+      {!isSetup && deferred && (
+        <p data-testid="deferred-charge-notice" style={{ margin: 0, fontSize: 13, opacity: 0.8, lineHeight: 1.5 }}>
+          {t("forge.forge_stripe_payment.deferred_charged_on_approval")}
+          {deferredChargeNotice(deferredStrategy) === "authorization" && (
+            <> {t("forge.forge_stripe_payment.deferred_hold_on_statement")}</>
+          )}
+        </p>
+      )}
     </form>
   );
 }