From 82ff525527070e7139ce241493eddc6bf829818a Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 27 May 2026 15:24:00 +1000
Subject: [PATCH] feat(stripe): allow selecting Stripe.js SDK version

Adds a `version` option to `useScriptStripe()` and the registry config
to pin the Stripe.js SDK release (e.g. `acacia`, `basil`, `clover`,
`dahlia`), mirroring the Google Maps `v` option. Defaults to `basil`
for backward compatibility.

Closes #796
---
 docs/content/scripts/stripe.md                  | 2 +-
 packages/script/src/registry-types.json         | 9 ++++++++-
 packages/script/src/runtime/registry/schemas.ts | 7 +++++++
 packages/script/src/runtime/registry/stripe.ts  | 2 +-
 4 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/docs/content/scripts/stripe.md b/docs/content/scripts/stripe.md
index 1fc4bdbb0..bdf41905f 100644
--- a/docs/content/scripts/stripe.md
+++ b/docs/content/scripts/stripe.md
@@ -15,7 +15,7 @@ links:
 [Stripe](https://stripe.com) is a popular payment gateway that allows you to accept payments online.
 
 Nuxt Scripts provides two Stripe features:
-- [`useScriptStripe()`{lang="ts"}](/scripts/stripe){lang="ts"} composable which loads the script `https://js.stripe.com/basil/stripe.js`.
+- [`useScriptStripe()`{lang="ts"}](/scripts/stripe){lang="ts"} composable which loads the script `https://js.stripe.com/basil/stripe.js` by default. Use the `version` option to [pin a Stripe.js SDK release](https://docs.stripe.com/sdks/stripejs-versioning) (e.g. `acacia`, `clover`, `dahlia`).
 - `ScriptStripePricingTable` component that allows you to embed a [Stripe Pricing Table](https://docs.stripe.com/payments/checkout/pricing-table) on your site using `https://js.stripe.com/v3/pricing-table.js`.
 
 ::script-stats
diff --git a/packages/script/src/registry-types.json b/packages/script/src/registry-types.json
index 99d35cc93..b1a9e9d2c 100644
--- a/packages/script/src/registry-types.json
+++ b/packages/script/src/registry-types.json
@@ -970,7 +970,7 @@
       {
         "name": "StripeOptions",
         "kind": "const",
-        "code": "export const StripeOptions = object({\n  /**\n   * Whether to load Stripe's advanced fraud detection signals.\n   * Set to `false` to opt out.\n   * @default true\n   * @see https://docs.stripe.com/disputes/prevention/advanced-fraud-detection\n   */\n  advancedFraudSignals: optional(boolean()),\n})"
+        "code": "export const StripeOptions = object({\n  /**\n   * Whether to load Stripe's advanced fraud detection signals.\n   * Set to `false` to opt out.\n   * @default true\n   * @see https://docs.stripe.com/disputes/prevention/advanced-fraud-detection\n   */\n  advancedFraudSignals: optional(boolean()),\n  /**\n   * The Stripe.js SDK version to load.\n   * Named releases get autocomplete; any future codename is also accepted.\n   * @default 'basil'\n   * @see https://docs.stripe.com/sdks/stripejs-versioning\n   */\n  version: optional(union([literal('v3'), literal('acacia'), literal('basil'), literal('clover'), literal('dahlia'), string()])),\n})"
       },
       {
         "name": "StripeApi",
@@ -2396,6 +2396,13 @@
         "required": false,
         "description": "Whether to load Stripe's advanced fraud detection signals. Set to `false` to opt out.",
         "defaultValue": "true"
+      },
+      {
+        "name": "version",
+        "type": "'v3' | 'acacia' | 'basil' | 'clover' | 'dahlia' | string",
+        "required": false,
+        "description": "The Stripe.js SDK version to load. Named releases get autocomplete; any future codename is also accepted.",
+        "defaultValue": "'basil'"
       }
     ],
     "TikTokPixelOptions": [
diff --git a/packages/script/src/runtime/registry/schemas.ts b/packages/script/src/runtime/registry/schemas.ts
index d6be8661d..257fe4eeb 100644
--- a/packages/script/src/runtime/registry/schemas.ts
+++ b/packages/script/src/runtime/registry/schemas.ts
@@ -1028,6 +1028,13 @@ export const StripeOptions = object({
    * @see https://docs.stripe.com/disputes/prevention/advanced-fraud-detection
    */
   advancedFraudSignals: optional(boolean()),
+  /**
+   * The Stripe.js SDK version to load.
+   * Named releases get autocomplete; any future codename is also accepted.
+   * @default 'basil'
+   * @see https://docs.stripe.com/sdks/stripejs-versioning
+   */
+  version: optional(union([literal('v3'), literal('acacia'), literal('basil'), literal('clover'), literal('dahlia'), string()])),
 })
 
 export const TikTokPixelOptions = object({
diff --git a/packages/script/src/runtime/registry/stripe.ts b/packages/script/src/runtime/registry/stripe.ts
index 2b9a3a251..15a602648 100644
--- a/packages/script/src/runtime/registry/stripe.ts
+++ b/packages/script/src/runtime/registry/stripe.ts
@@ -16,7 +16,7 @@ export function useScriptStripe<T extends StripeApi>(_options?: StripeInput) {
   return useRegistryScript<T, typeof StripeOptions>('stripe', options => ({
     scriptInput: {
       src: withQuery(
-        `https://js.stripe.com/basil/stripe.js`,
+        `https://js.stripe.com/${options?.version || 'basil'}/stripe.js`,
         (typeof options?.advancedFraudSignals === 'boolean' && !options?.advancedFraudSignals) ? { advancedFraudSignals: false } : {},
       ),
       // opt-out of privacy defaults