feat(payment): expand Stripe methods and checkout handoff

src/app/_components/payment/__tests__/external-browser-checkout-button.test.tsx

@@ -0,0 +1,76 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createCheckoutHandoff, openUrlWithExternalBrowser } = vi.hoisted(
+  () => ({
+    createCheckoutHandoff: vi.fn(),
+    openUrlWithExternalBrowser: vi.fn(),
+  }),
+);
+
+vi.mock("@/lib/auth/checkout_handoff", () => ({ createCheckoutHandoff }));
+vi.mock("@/utils/url-launcher-util", () => ({
+  UrlLauncherUtil: { openUrlWithExternalBrowser },
+}));
+vi.mock("@/utils/browser-detect", () => ({
+  BrowserDetector: { isFacebookInAppBrowser: () => true },
+}));
+
+import { ExternalBrowserCheckoutButton } from "../external-browser-checkout-button";
+
+describe("ExternalBrowserCheckoutButton", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createCheckoutHandoff.mockResolvedValue({
+      success: true,
+      data: {
+        externalUrl:
+          "https://cozsweet.com/external-entry?target=checkout&handoffToken=opaque",
+        expiresAt: "2026-07-28T16:00:00+00:00",
+      },
+    });
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it("creates only a handoff before opening the external browser", async () => {
+    await act(async () => {
+      root.render(
+        <ExternalBrowserCheckoutButton
+          checkoutIntent={{
+            planId: "vip_monthly",
+            autoRenew: true,
+            commercialOfferId: "offer-1",
+          }}
+        />,
+      );
+    });
+
+    const button = container.querySelector("button");
+    expect(button?.textContent).toContain(
+      "Open in browser for more payment methods",
+    );
+    await act(async () => button?.click());
+
+    expect(createCheckoutHandoff).toHaveBeenCalledWith({
+      planId: "vip_monthly",
+      autoRenew: true,
+      commercialOfferId: "offer-1",
+    });
+    expect(openUrlWithExternalBrowser).toHaveBeenCalledWith(
+      "https://cozsweet.com/external-entry?target=checkout&handoffToken=opaque",
+    );
+  });
+});

src/app/_components/payment/__tests__/payment-launch-dialogs.test.tsx

@@ -18,6 +18,8 @@ const hiddenLaunch = {
   shouldShowQrisDialog: false,
   shouldShowStripeDialog: false,
   stripeClientSecret: null,
+  stripeCustomerSessionClientSecret: null,
+  savedPaymentMethodsEnabled: false,
 };
 
 describe("PaymentLaunchDialogs", () => {

src/app/_components/payment/__tests__/stripe-payment-dialog.test.tsx

@@ -2,18 +2,57 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { StripePaymentDialogLoading } from "../lazy-stripe-payment-dialog";
+const stripeConfirmPayment = vi.fn(async () => ({}));
+const elementsSubmit = vi.fn(async () => ({}));
+let capturedElementsOptions: Record<string, unknown> | null = null;
+let capturedExpressProps: Record<string, unknown> | null = null;
+let capturedPaymentProps: Record<string, unknown> | null = null;
+
+vi.hoisted(() => {
+  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY = "pk_test_checkout";
+});
+
+vi.mock("@stripe/stripe-js", () => ({
+  loadStripe: vi.fn(() => Promise.resolve({})),
+}));
+
+vi.mock("@stripe/react-stripe-js", () => ({
+  Elements: ({
+    children,
+    options,
+  }: {
+    children: React.ReactNode;
+    options: Record<string, unknown>;
+  }) => {
+    capturedElementsOptions = options;
+    return <>{children}</>;
+  },
+  ExpressCheckoutElement: (props: Record<string, unknown>) => {
+    capturedExpressProps = props;
+    return <div data-testid="express-checkout" />;
+  },
+  PaymentElement: (props: Record<string, unknown>) => {
+    capturedPaymentProps = props;
+    return <div data-testid="payment-element" />;
+  },
+  useElements: () => ({ submit: elementsSubmit }),
+  useStripe: () => ({ confirmPayment: stripeConfirmPayment }),
+}));
+
 import { StripePaymentDialog } from "../stripe-payment-dialog";
 
-describe("Stripe payment portal states", () => {
+describe("StripePaymentDialog", () => {
   let container: HTMLDivElement;
   let root: Root;
 
   beforeEach(() => {
+    vi.clearAllMocks();
+    capturedElementsOptions = null;
+    capturedExpressProps = null;
+    capturedPaymentProps = null;
     (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
       .IS_REACT_ACT_ENVIRONMENT = true;
     container = document.createElement("div");
-    container.style.transform = "translateX(50%)";
     document.body.appendChild(container);
     root = createRoot(container);
   });
@@ -24,40 +63,101 @@ describe("Stripe payment portal states", () => {
     document.body.style.overflow = "";
   });
 
-  it("portals the unavailable state and keeps its explicit close action", () => {
-    const onClose = vi.fn();
-
+  it("renders Express Checkout first and a collapsed Pay by card section last", () => {
     act(() =>
       root.render(
         <StripePaymentDialog
-          clientSecret="client-secret"
-          onClose={onClose}
+          clientSecret="pi_123_secret_payment"
+          customerSessionClientSecret="cuss_123_secret_saved"
+          savedPaymentMethodsEnabled
+          onClose={vi.fn()}
         />,
       ),
     );
 
-    const dialog = document.body.querySelector('[role="alertdialog"]');
-    expect(dialog).not.toBeNull();
-    expect(container.contains(dialog)).toBe(false);
-    expect(dialog?.textContent).toContain("Payment unavailable");
-    expect(dialog?.getAttribute("aria-labelledby")).toBeTruthy();
-    expect(dialog?.getAttribute("aria-describedby")).toBeTruthy();
-
-    const okButton = Array.from(dialog?.querySelectorAll("button") ?? []).find(
-      (button) => button.textContent === "OK",
-    );
-    act(() => okButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
-    expect(onClose).toHaveBeenCalledOnce();
+    expect(capturedElementsOptions).toMatchObject({
+      clientSecret: "pi_123_secret_payment",
+      customerSessionClientSecret: "cuss_123_secret_saved",
+    });
+    expect(capturedExpressProps?.options).toMatchObject({
+      paymentMethodOrder: [
+        "apple_pay",
+        "google_pay",
+        "link",
+        "paypal",
+        "amazon_pay",
+        "klarna",
+      ],
+      paymentMethods: {
+        applePay: "always",
+        googlePay: "always",
+        link: "auto",
+        paypal: "auto",
+        amazonPay: "auto",
+        klarna: "auto",
+      },
+    });
+    expect(capturedPaymentProps?.options).toMatchObject({
+      layout: { type: "accordion", defaultCollapsed: true },
+      paymentMethodOrder: ["card"],
+      wallets: { applePay: "never", googlePay: "never", link: "never" },
+    });
+    const text = document.body.textContent ?? "";
+    expect(text).toContain("Pay by card");
+    const express = document.body.querySelector('[data-testid="express-checkout"]');
+    const card = document.body.querySelector('[data-testid="payment-element"]');
+    expect(express).not.toBeNull();
+    expect(card).not.toBeNull();
+    expect(
+      express!.compareDocumentPosition(card!) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
   });
 
-  it("portals the lazy loading state", () => {
-    act(() => root.render(<StripePaymentDialogLoading />));
+  it("does not pass an invalid or disabled Customer Session secret", () => {
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="pi_123_secret_payment"
+          customerSessionClientSecret="invalid"
+          savedPaymentMethodsEnabled={false}
+          onClose={vi.fn()}
+        />,
+      ),
+    );
 
-    const dialog = document.body.querySelector('[role="dialog"]');
-    expect(dialog).not.toBeNull();
-    expect(container.contains(dialog)).toBe(false);
-    expect(dialog?.textContent).toContain("Preparing secure payment");
-    expect(dialog?.textContent).toContain("Loading payment methods...");
-    expect(dialog?.querySelector('[aria-busy="true"]')).not.toBeNull();
+    expect(capturedElementsOptions).not.toHaveProperty(
+      "customerSessionClientSecret",
+    );
+  });
+
+  it("uses the same confirmation path for an Express Checkout approval", async () => {
+    const onConfirmed = vi.fn();
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="pi_123_secret_payment"
+          onClose={vi.fn()}
+          onConfirmed={onConfirmed}
+        />,
+      ),
+    );
+
+    const onConfirm = capturedExpressProps?.onConfirm as
+      | ((event: { paymentFailed: ReturnType<typeof vi.fn> }) => Promise<void>)
+      | undefined;
+    expect(onConfirm).toBeTypeOf("function");
+    await act(async () => {
+      await onConfirm?.({ paymentFailed: vi.fn() });
+    });
+
+    expect(stripeConfirmPayment).toHaveBeenCalledTimes(1);
+    expect(stripeConfirmPayment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        elements: expect.any(Object),
+        redirect: "if_required",
+      }),
+    );
+    expect(onConfirmed).toHaveBeenCalledTimes(1);
   });
 });

src/app/_components/payment/external-browser-checkout-button.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { useState, useSyncExternalStore } from "react";
+
+import type { CheckoutIntent } from "@/data/schemas/auth";
+import { createCheckoutHandoff } from "@/lib/auth/checkout_handoff";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { ExceptionHandler } from "@/core/errors";
+import { Result } from "@/utils/result";
+import { UrlLauncherUtil } from "@/utils/url-launcher-util";
+
+export interface ExternalBrowserCheckoutButtonProps {
+  checkoutIntent: CheckoutIntent;
+  disabled?: boolean;
+}
+
+export function ExternalBrowserCheckoutButton({
+  checkoutIntent,
+  disabled = false,
+}: ExternalBrowserCheckoutButtonProps) {
+  const isFacebookBrowser = useSyncExternalStore(
+    () => () => undefined,
+    () => BrowserDetector.isFacebookInAppBrowser(),
+    () => false,
+  );
+  const [isOpening, setIsOpening] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  if (!isFacebookBrowser) return null;
+
+  const handleOpen = async () => {
+    if (disabled || isOpening) return;
+    setIsOpening(true);
+    setErrorMessage(null);
+    const result = await createCheckoutHandoff(checkoutIntent);
+    if (Result.isErr(result)) {
+      setErrorMessage(
+        ExceptionHandler.message(
+          result.error,
+          "Could not open this checkout in your browser. Please sign in and try again.",
+        ),
+      );
+      setIsOpening(false);
+      return;
+    }
+    UrlLauncherUtil.openUrlWithExternalBrowser(result.data.externalUrl);
+  };
+
+  return (
+    <div className="mt-2 w-full text-center">
+      <button
+        type="button"
+        className="min-h-11 w-full cursor-pointer rounded-full border border-black/15 bg-white px-4 py-2.5 text-sm font-semibold text-text-foreground disabled:cursor-not-allowed disabled:opacity-55"
+        disabled={disabled || isOpening}
+        onClick={() => void handleOpen()}
+      >
+        {isOpening
+          ? "Opening browser..."
+          : "Open in browser for more payment methods"}
+      </button>
+      {errorMessage ? (
+        <p className="mt-2 text-sm text-[#c0392b]" role="alert">
+          {errorMessage}
+        </p>
+      ) : null}
+    </div>
+  );
+}

src/app/_components/payment/payment-launch-dialogs.tsx

@@ -24,6 +24,8 @@ type PaymentLaunchDialogFlow = Pick<
   | "shouldShowQrisDialog"
   | "shouldShowStripeDialog"
   | "stripeClientSecret"
+  | "stripeCustomerSessionClientSecret"
+  | "savedPaymentMethodsEnabled"
 >;
 
 export interface PaymentLaunchDialogsProps {
@@ -64,6 +66,10 @@ export function PaymentLaunchDialogs({
       {launch.shouldShowStripeDialog && launch.stripeClientSecret ? (
         <LazyStripePaymentDialog
           clientSecret={launch.stripeClientSecret}
+          customerSessionClientSecret={
+            launch.stripeCustomerSessionClientSecret
+          }
+          savedPaymentMethodsEnabled={launch.savedPaymentMethodsEnabled}
           returnPath={stripeReturnPath}
           onClose={launch.handleStripeClose}
           onConfirmed={launch.handleStripeConfirmed}

src/app/_components/payment/stripe-payment-dialog.styles.ts

@@ -9,6 +9,11 @@ export const stripePaymentDialogStyles = {
   content:
     "m-0 text-(length:--responsive-body,14px) leading-normal text-[#393939]",
   form: "flex flex-col gap-(--page-section-gap,18px)",
+  expressSection: "w-full empty:hidden",
+  cardSection:
+    "flex w-full flex-col gap-(--spacing-sm,8px) border-t border-black/10 pt-(--page-section-gap,18px)",
+  cardTitle:
+    "m-0 text-(length:--responsive-body,16px) font-semibold text-text-foreground",
   error:
     "m-0 text-(length:--responsive-caption,13px) leading-[1.45] text-[#c0392b]",
   actions: "flex w-full gap-(--spacing-md,12px)",

src/app/_components/payment/stripe-payment-dialog.tsx

@@ -4,19 +4,28 @@
  *
  * 后端当前返回 PaymentIntent clientSecret，因此这里直接用它完成前端确认。
  */
-import { useId, useState, type FormEvent } from "react";
+import { useEffect, useId, useRef, useState, type FormEvent } from "react";
 import {
   Elements,
+  ExpressCheckoutElement,
   PaymentElement,
   useElements,
   useStripe,
 } from "@stripe/react-stripe-js";
-import { loadStripe } from "@stripe/stripe-js";
+import {
+  loadStripe,
+  type AvailablePaymentMethods,
+  type StripeExpressCheckoutElementConfirmEvent,
+} from "@stripe/stripe-js";
 
 import { ModalPortal } from "@/app/_components/core/modal-portal";
 import { ExceptionHandler } from "@/core/errors";
 import { ROUTES } from "@/router/routes";
 import { Logger } from "@/utils/logger";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { getStripeCustomerSessionClientSecret } from "@/lib/payment/payment_launch";
+import { behaviorAnalytics } from "@/lib/analytics";
 
 import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles";
 
@@ -26,8 +35,16 @@ const stripePromise = stripePublishableKey
   ? loadStripe(stripePublishableKey)
   : null;
 
+type ExpressAvailabilityValue = boolean | { available: boolean } | undefined;
+
+function isExpressMethodAvailable(value: ExpressAvailabilityValue): boolean {
+  return value === true || (typeof value === "object" && value.available);
+}
+
 export interface StripePaymentDialogProps {
   clientSecret: string;
+  customerSessionClientSecret?: string | null;
+  savedPaymentMethodsEnabled?: boolean;
   returnPath?: string;
   onClose: () => void;
   onConfirmed?: () => void;
@@ -35,12 +52,19 @@ export interface StripePaymentDialogProps {
 
 export function StripePaymentDialog({
   clientSecret,
+  customerSessionClientSecret = null,
+  savedPaymentMethodsEnabled = false,
   returnPath = ROUTES.subscription + "/success",
   onClose,
   onConfirmed,
 }: StripePaymentDialogProps) {
   const titleId = useId();
   const descriptionId = useId();
+  const savedCardClientSecret = getStripeCustomerSessionClientSecret({
+    provider: "stripe",
+    customerSessionClientSecret,
+    savedPaymentMethodsEnabled,
+  });
 
   if (!stripePromise) {
     return (
@@ -100,6 +124,9 @@ export function StripePaymentDialog({
         stripe={stripePromise}
         options={{
           clientSecret,
+          ...(savedCardClientSecret
+            ? { customerSessionClientSecret: savedCardClientSecret }
+            : {}),
           appearance: {
             theme: "stripe",
             variables: {
@@ -132,6 +159,20 @@ function StripePaymentForm({
   const elements = useElements();
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const submittingRef = useRef(false);
+  const [hasExpressPaymentMethods, setHasExpressPaymentMethods] = useState<
+    boolean | null
+  >(null);
+  const [expressMaxColumns, setExpressMaxColumns] = useState(1);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return;
+    const query = window.matchMedia("(min-width: 640px)");
+    const updateColumns = () => setExpressMaxColumns(query.matches ? 2 : 1);
+    updateColumns();
+    query.addEventListener("change", updateColumns);
+    return () => query.removeEventListener("change", updateColumns);
+  }, []);
 
   const handleLoadError = (event: Parameters<
     NonNullable<React.ComponentProps<typeof PaymentElement>["onLoadError"]>
@@ -150,38 +191,118 @@ function StripePaymentForm({
     );
   };
 
-  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    if (!stripe || !elements || isSubmitting) return;
+  const updateExpressAvailability = (
+    availablePaymentMethods:
+      | AvailablePaymentMethods
+      | {
+          applePay?: { available: boolean };
+          googlePay?: { available: boolean };
+          link?: { available: boolean };
+          paypal?: { available: boolean };
+          amazonPay?: { available: boolean };
+          klarna?: { available: boolean };
+        }
+      | undefined,
+  ) => {
+    const availability = {
+      applePay: isExpressMethodAvailable(availablePaymentMethods?.applePay),
+      googlePay: isExpressMethodAvailable(availablePaymentMethods?.googlePay),
+      link: isExpressMethodAvailable(availablePaymentMethods?.link),
+      paypal: isExpressMethodAvailable(availablePaymentMethods?.paypal),
+      amazonPay: isExpressMethodAvailable(availablePaymentMethods?.amazonPay),
+      klarna: isExpressMethodAvailable(availablePaymentMethods?.klarna),
+    };
+    setHasExpressPaymentMethods(Object.values(availability).some(Boolean));
+    const browser = BrowserDetector.isFacebookInAppBrowser()
+        ? "facebook"
+        : BrowserDetector.getBrowserName() || "unknown";
+    const platform = PlatformDetector.getPlatform();
+    const metadata = {
+      browser,
+      platform,
+      availablePaymentMethods: availability,
+    };
+    log.info(
+      "[stripe-payment-dialog] Express Checkout availability",
+      metadata,
+    );
+    behaviorAnalytics.elementClick(
+      "stripe.express_checkout_availability",
+      "Stripe Express Checkout availability",
+      metadata,
+    );
+  };
 
+  const handleExpressLoadError = (event: Parameters<
+    NonNullable<
+      React.ComponentProps<typeof ExpressCheckoutElement>["onLoadError"]
+    >
+  >[0]) => {
+    setHasExpressPaymentMethods(false);
+    log.warn("[stripe-payment-dialog] Express Checkout load failed", {
+      type: event.error.type,
+      code: event.error.code,
+      message: event.error.message,
+    });
+  };
+
+  const confirmPayment = async (
+    options: {
+      submitPaymentElement: boolean;
+      expressEvent?: StripeExpressCheckoutElementConfirmEvent;
+    },
+  ) => {
+    if (!stripe || !elements || submittingRef.current) return;
+
+    submittingRef.current = true;
     setIsSubmitting(true);
     setErrorMessage(null);
 
-    const { error: submitError } = await elements.submit();
-    if (submitError) {
-      setErrorMessage(
-        ExceptionHandler.message(submitError, "Please check your payment info."),
-      );
-      setIsSubmitting(false);
-      return;
+    if (options.submitPaymentElement) {
+      let submitError: unknown;
+      try {
+        ({ error: submitError } = await elements.submit());
+      } catch (error) {
+        submitError = error;
+      }
+      if (submitError) {
+        setErrorMessage(
+          ExceptionHandler.message(
+            submitError,
+            "Please check your payment info.",
+          ),
+        );
+        submittingRef.current = false;
+        setIsSubmitting(false);
+        return;
+      }
     }
 
     const returnUrl = new URL(
       returnPath ?? ROUTES.subscription + "/success",
       window.location.origin,
     );
-    const { error } = await stripe.confirmPayment({
-      elements,
-      confirmParams: {
-        return_url: returnUrl.toString(),
-      },
-      redirect: "if_required",
-    });
+    let confirmationError: unknown;
+    try {
+      ({ error: confirmationError } = await stripe.confirmPayment({
+        elements,
+        confirmParams: {
+          return_url: returnUrl.toString(),
+        },
+        redirect: "if_required",
+      }));
+    } catch (error) {
+      confirmationError = error;
+    }
 
-    if (error) {
-      setErrorMessage(
-        ExceptionHandler.message(error, "Payment confirmation failed."),
+    if (confirmationError) {
+      const message = ExceptionHandler.message(
+        confirmationError,
+        "Payment confirmation failed.",
       );
+      setErrorMessage(message);
+      options.expressEvent?.paymentFailed({ reason: "fail", message });
+      submittingRef.current = false;
       setIsSubmitting(false);
       return;
     }
@@ -189,9 +310,74 @@ function StripePaymentForm({
     onConfirmed?.();
   };
 
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    await confirmPayment({ submitPaymentElement: true });
+  };
+
   return (
     <form className={styles.form} onSubmit={handleSubmit}>
-      <PaymentElement onLoadError={handleLoadError} />
+      <section
+        className={styles.expressSection}
+        hidden={hasExpressPaymentMethods === false}
+        aria-label="Express payment methods"
+      >
+        <ExpressCheckoutElement
+          options={{
+            paymentMethodOrder: [
+              "apple_pay",
+              "google_pay",
+              "link",
+              "paypal",
+              "amazon_pay",
+              "klarna",
+            ],
+            paymentMethods: {
+              applePay: "always",
+              googlePay: "always",
+              link: "auto",
+              paypal: "auto",
+              amazonPay: "auto",
+              klarna: "auto",
+            },
+            layout: {
+              maxColumns: expressMaxColumns,
+              maxRows: 6,
+              overflow: "never",
+            },
+          }}
+          onReady={(event) =>
+            updateExpressAvailability(event.availablePaymentMethods)
+          }
+          onAvailablePaymentMethodsChange={(event) =>
+            updateExpressAvailability(event.paymentMethods)
+          }
+          onLoadError={handleExpressLoadError}
+          onConfirm={(event) =>
+            void confirmPayment({
+              submitPaymentElement: false,
+              expressEvent: event,
+            })
+          }
+        />
+      </section>
+      <section className={styles.cardSection} aria-labelledby="pay-by-card-title">
+        <h3 id="pay-by-card-title" className={styles.cardTitle}>
+          Pay by card
+        </h3>
+        <PaymentElement
+          options={{
+            layout: { type: "accordion", defaultCollapsed: true },
+            paymentMethodOrder: ["card"],
+            wallets: {
+              applePay: "never",
+              googlePay: "never",
+              link: "never",
+            },
+          }}
+          onLoadError={handleLoadError}
+        />
+      </section>
       {errorMessage ? (
         <p
           role="alert"