Updated dependencies, Added Hosted mode for Stripe checkout

* chore: bump version to 3.1.0 and update dependencies in package.json, pnpm-lock.yaml, and pnpm-workspace.yaml; enhance billing services with support for hosted checkout page in Stripe integration

* Enhance error handling in billing services to log error messages instead of objects; update documentation for Stripe integration to clarify publishable key requirements based on UI mode.

packages/billing/core/src/services/billing-strategy-provider.service.ts

@@ -33,7 +33,8 @@ export abstract class BillingStrategyProviderService {
   abstract createCheckoutSession(
     params: z.output<typeof CreateBillingCheckoutSchema>,
   ): Promise<{
-    checkoutToken: string;
+    checkoutToken: string | null;
+    url?: string | null;
   }>;
 
   abstract cancelSubscription(

packages/billing/stripe/src/components/stripe-embedded-checkout.tsx

@@ -16,7 +16,7 @@ const { publishableKey } = StripeClientEnvSchema.parse({
   publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
 });
 
-const stripePromise = loadStripe(publishableKey);
+const stripePromise = loadStripe(publishableKey as string);
 
 export function StripeCheckout({
   checkoutToken,

packages/billing/stripe/src/schema/stripe-client-env.schema.ts

@@ -1,11 +1,19 @@
 import * as z from 'zod';
 
+const isHostedMode = process.env.STRIPE_UI_MODE === 'hosted_page';
+
 export const StripeClientEnvSchema = z
   .object({
-    publishableKey: z.string().min(1),
+    publishableKey: isHostedMode
+      ? z.string().optional()
+      : z.string().min(1),
   })
   .refine(
     (schema) => {
+      if (isHostedMode || !schema.publishableKey) {
+        return true;
+      }
+
       return schema.publishableKey.startsWith('pk_');
     },
     {

packages/billing/stripe/src/services/create-stripe-checkout.ts

@@ -1,13 +1,20 @@
-import type { Stripe } from 'stripe';
-import * as z from 'zod';
+import type { Stripe } from "stripe";
+import * as z from "zod";
 
-import type { CreateBillingCheckoutSchema } from '@kit/billing/schema';
+import type { CreateBillingCheckoutSchema } from "@kit/billing/schema";
 
 /**
  * @description If set to true, users can start a trial without entering their credit card details
  */
 const enableTrialWithoutCreditCard =
-  process.env.STRIPE_ENABLE_TRIAL_WITHOUT_CC === 'true';
+  process.env.STRIPE_ENABLE_TRIAL_WITHOUT_CC === "true";
+
+const UI_MODE_VALUES = ["embedded_page", "hosted_page"] as const;
+
+const uiMode = z
+  .enum(UI_MODE_VALUES)
+  .default("embedded_page")
+  .parse(process.env.STRIPE_UI_MODE);
 
 /**
  * @name createStripeCheckout
@@ -30,9 +37,9 @@ export async function createStripeCheckout(
 
   // docs: https://stripe.com/docs/billing/subscriptions/build-subscription
   const mode: Stripe.Checkout.SessionCreateParams.Mode =
-    params.plan.paymentType === 'recurring' ? 'subscription' : 'payment';
+    params.plan.paymentType === "recurring" ? "subscription" : "payment";
 
-  const isSubscription = mode === 'subscription';
+  const isSubscription = mode === "subscription";
 
   let trialDays: number | null | undefined = params.plan.trialDays;
 
@@ -46,7 +53,7 @@ export async function createStripeCheckout(
       ? {
           trial_settings: {
             end_behavior: {
-              missing_payment_method: 'cancel' as const,
+              missing_payment_method: "cancel" as const,
             },
           },
         }
@@ -68,11 +75,9 @@ export async function createStripeCheckout(
 
   const urls = getUrls({
     returnUrl: params.returnUrl,
+    uiMode,
   });
 
-  // we use the embedded mode, so the user does not leave the page
-  const uiMode = 'embedded';
-
   const customerData = customer
     ? {
         customer,
@@ -84,10 +89,10 @@ export async function createStripeCheckout(
   const customerCreation =
     isSubscription || customer
       ? ({} as Record<string, string>)
-      : { customer_creation: 'always' };
+      : { customer_creation: "always" };
 
   const lineItems = params.plan.lineItems.map((item) => {
-    if (item.type === 'metered') {
+    if (item.type === "metered") {
       return {
         price: item.id,
       };
@@ -109,7 +114,7 @@ export async function createStripeCheckout(
   const paymentCollectionMethod =
     enableTrialWithoutCreditCard && params.plan.trialDays
       ? {
-          payment_method_collection: 'if_required' as const,
+          payment_method_collection: "if_required" as const,
         }
       : {};
 
@@ -127,10 +132,20 @@ export async function createStripeCheckout(
   });
 }
 
-function getUrls(params: { returnUrl: string }) {
-  const returnUrl = `${params.returnUrl}?session_id={CHECKOUT_SESSION_ID}`;
+function getUrls(params: {
+  returnUrl: string;
+  uiMode: (typeof UI_MODE_VALUES)[number];
+}) {
+  const url = `${params.returnUrl}?session_id={CHECKOUT_SESSION_ID}`;
+
+  if (params.uiMode === "hosted_page") {
+    return {
+      success_url: url,
+      cancel_url: params.returnUrl,
+    };
+  }
 
   return {
-    return_url: returnUrl,
+    return_url: url,
   };
 }

packages/billing/stripe/src/services/stripe-billing-strategy.service.ts

@@ -47,9 +47,9 @@ export class StripeBillingStrategyService implements BillingStrategyProviderServ
 
     logger.info(ctx, 'Creating checkout session...');
 
-    const { client_secret } = await createStripeCheckout(stripe, params);
+    const { client_secret, url } = await createStripeCheckout(stripe, params);
 
-    if (!client_secret) {
+    if (!client_secret && !url) {
       logger.error(ctx, 'Failed to create checkout session');
 
       throw new Error('Failed to create checkout session');
@@ -57,7 +57,10 @@ export class StripeBillingStrategyService implements BillingStrategyProviderServ
 
     logger.info(ctx, 'Checkout session created successfully');
 
-    return { checkoutToken: client_secret };
+    return {
+      checkoutToken: client_secret ?? null,
+      url,
+    };
   }
 
   /**

packages/billing/stripe/src/services/stripe-sdk.ts

@@ -1,7 +1,7 @@
 import 'server-only';
 import { StripeServerEnvSchema } from '../schema/stripe-server-env.schema';
 
-const STRIPE_API_VERSION = '2026-02-25.clover';
+const STRIPE_API_VERSION = '2026-03-25.dahlia';
 
 /**
  * @description returns a Stripe instance

packages/mcp-server/src/tools/env/model.ts

@@ -625,7 +625,8 @@ export const envVariables: EnvVariableModel[] = [
   {
     name: 'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY',
     displayName: 'Stripe Publishable Key',
-    description: 'Your Stripe publishable key.',
+    description:
+      'Your Stripe publishable key. Required when using embedded checkout (default), optional when STRIPE_UI_MODE is set to hosted_page.',
     hint: `Ex. pk_test_123456789012345678901234`,
     category: 'Billing',
     type: 'string',
@@ -635,7 +636,13 @@ export const envVariables: EnvVariableModel[] = [
           variable: 'NEXT_PUBLIC_BILLING_PROVIDER',
           condition: (value) => value === 'stripe',
           message:
-            'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is required when NEXT_PUBLIC_BILLING_PROVIDER is set to "stripe"',
+            'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is required when NEXT_PUBLIC_BILLING_PROVIDER is set to "stripe" and STRIPE_UI_MODE is not "hosted_page"',
+        },
+        {
+          variable: 'STRIPE_UI_MODE',
+          condition: (value) => value !== 'hosted_page',
+          message:
+            'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is required when STRIPE_UI_MODE is not set to "hosted_page"',
         },
       ],
       validate: ({ value }) => {
@@ -1391,6 +1398,21 @@ export const envVariables: EnvVariableModel[] = [
       return z.coerce.boolean().optional().safeParse(value);
     },
   },
+  {
+    name: 'STRIPE_UI_MODE',
+    displayName: 'Stripe Checkout UI Mode',
+    description:
+      'Controls whether Stripe Checkout uses an embedded page or a hosted page. Defaults to embedded_page.',
+    category: 'Billing',
+    type: 'enum',
+    values: ['embedded_page', 'hosted_page'],
+    validate: ({ value }) => {
+      return z
+        .enum(['embedded_page', 'hosted_page'])
+        .optional()
+        .safeParse(value);
+    },
+  },
   {
     name: 'NEXT_PUBLIC_THEME_COLOR',
     displayName: 'Theme Color',

packages/ui/package.json

@@ -106,40 +106,40 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
-    "@hookform/resolvers": "^5.2.2",
+    "@base-ui/react": "catalog:",
+    "@hookform/resolvers": "catalog:",
     "@kit/shared": "workspace:*",
-    "clsx": "^2.1.1",
-    "cmdk": "^1.1.1",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.4.2",
+    "clsx": "catalog:",
+    "cmdk": "catalog:",
+    "embla-carousel-react": "catalog:",
+    "input-otp": "catalog:",
     "lucide-react": "catalog:",
-    "react-dropzone": "^15.0.0",
+    "react-dropzone": "catalog:",
     "react-resizable-panels": "catalog:",
-    "react-top-loading-bar": "^3.0.2",
-    "recharts": "3.7.0",
-    "tailwind-merge": "^3.5.0"
+    "react-top-loading-bar": "catalog:",
+    "recharts": "catalog:",
+    "tailwind-merge": "catalog:"
   },
   "devDependencies": {
     "@kit/i18n": "workspace:*",
     "@kit/tsconfig": "workspace:*",
     "@supabase/supabase-js": "catalog:",
     "@tanstack/react-query": "catalog:",
-    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-table": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "class-variance-authority": "^0.7.1",
-    "date-fns": "^4.1.0",
+    "class-variance-authority": "catalog:",
+    "date-fns": "catalog:",
     "next": "catalog:",
-    "next-intl": "^4.8.3",
-    "next-safe-action": "^8.1.8",
-    "next-themes": "0.4.6",
-    "react-day-picker": "^9.14.0",
+    "next-intl": "catalog:",
+    "next-safe-action": "catalog:",
+    "next-themes": "catalog:",
+    "react-day-picker": "catalog:",
     "react-hook-form": "catalog:",
     "shadcn": "catalog:",
-    "sonner": "^2.0.7",
+    "sonner": "catalog:",
     "tailwindcss": "catalog:",
-    "vaul": "^1.1.2",
+    "vaul": "catalog:",
     "vitest": "catalog:",
     "zod": "catalog:"
   }