@fantastic.dev/better-stripe 0.10.0 → 0.10.2

package/docs/accounts-v2-preview.md

@@ -0,0 +1,142 @@
+# Customer-only Accounts v2 preview
+
+Connect platforms keep the default `2026-09-30.endive` API version. Non-Connect
+merchants can explicitly opt into `2026-09-30.preview` for customer-configured
+Accounts. The package does not enable Connect or onboard a merchant/recipient
+when creating a buyer with `ensureCustomerAccount`.
+
+Connect users do not need the **Reusable payment methods for Global Payouts**
+toggle merely to use GA Accounts v2, ordinary Connect payouts, or marketplace
+splits. Non-Connect merchants using customer-configured Accounts do need that
+preview enabled, plus the supported preview request version. Actual Global
+Payouts credential reuse has separate preview eligibility for all users; see
+[Stripe's credential-reuse guide](https://docs.stripe.com/global-payouts/credential-reuse).
+Selecting a different API-reference version in Stripe's documentation does not
+enable the account feature or extend BetterStripe's supported-version list.
+
+## Enable the sandbox feature first
+
+In the intended sandbox, the account owner must enable **Reusable payment
+methods for Global Payouts** under **Account previews and features**. If the toggle
+is unavailable or disabled, check account-owner permissions and request access
+using Stripe's form. A disabled toggle alone does not identify the cause. This also enables Stripe's
+reusable payout credentials preview; it is not a Connect onboarding flow.
+Changing an API version cannot enable the feature on the Stripe account.
+
+Enabling the preview synchronizes existing Customers with customer-configured
+Accounts and changes how Stripe-hosted integrations create customers. Review
+Stripe's limitations and migration behavior before changing any live account.
+See [Stripe's customer Account guide](https://docs.stripe.com/accounts-v2/use-accounts-as-customers).
+
+## Configure one client and its webhook route
+
+```ts
+// convex/stripe.ts
+import {
+  BetterStripe,
+  STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+} from "@fantastic.dev/better-stripe";
+import { components } from "./_generated/api";
+
+export const stripe = new BetterStripe(components.betterStripe, {
+  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+  stripeApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+});
+```
+
+```ts
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { stripe } from "./stripe";
+
+const http = httpRouter();
+stripe.registerRoutes(http, {
+  webhookPath: "/stripe/webhook",
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  webhookSecretV2: process.env.STRIPE_WEBHOOK_SECRET_V2,
+  // Preserve your existing `webhooks` handler references and retry policy here.
+});
+export default http;
+```
+
+The instance route inherits its client's key and version. Conflicting explicit
+values fail at registration. The standalone `registerRoutes` function remains
+available; when using it, pass `stripeApiVersion: stripe.stripeApiVersion` and the
+same secret key explicitly. The client accepts only the supported GA and customer
+preview versions; unsupported values fail with `INVALID_CONFIGURATION`.
+
+All client operations use the selected version: account creation/configuration,
+Checkout, subscriptions, portal sessions, refunds, authoritative reads, and the
+provider calls made while handling webhooks. Component database writes remain
+provider-version independent. SDK caches separate clients by key and version.
+
+## Create a buyer and Checkout Session
+
+Authenticate the caller and validate ownership/prices on the server. The client
+is not an authorization boundary. Persist logical request identities in your host
+app so retries keep the same provider keys and new purchases use distinct keys.
+
+```ts
+const buyer = await stripe.ensureCustomerAccount(ctx, {
+  userId: identity.subject,
+  email: verifiedEmail,
+  idempotencyKey: accountProvisioningKey,
+});
+const checkout = await stripe.createCheckoutSession(ctx, {
+  userId: identity.subject,
+  accountId: buyer.stripeAccountId,
+  stripePriceId: authorizedPriceId,
+  mode: "subscription",
+  uiMode: "redirect",
+  returnUrl: "https://example.com/receipt?session_id={CHECKOUT_SESSION_ID}",
+  idempotencyKey: orderKey,
+});
+```
+
+The buyer is an `acct_` object with the customer configuration. Checkout uses
+`customer_account`, not a connected-account destination. No seller, recipient,
+transfer, or application fee is added by this configuration.
+
+After verifying buyer/order ownership, use `getCheckoutSessionFromStripe` to
+check current payment status. Completion alone does not prove payment: fulfill
+only when your payment policy accepts the authoritative status, and deduplicate
+fulfillment by a durable order key. Subscription and coupon reads use the same
+configured version. Cancellation/reactivation and refunds keep their existing
+public API signatures and caller idempotency behavior.
+
+## Match webhook payload versions and scope
+
+Snapshot destinations created through this client pin `snapshot_api_version` to
+the selected version. V1 webhook endpoints pin their `api_version`. Thin events
+are unversioned; their related customer Account is fetched with the selected
+request version and only customer/identity includes in customer-preview mode.
+
+The preview's default thin subscription covers Account creation, customer
+configuration changes, and identity changes, using Stripe's `@self` and
+`@accounts` scopes. Subscription and invoice changes continue to use V1 snapshot
+events. No merchant or recipient capability events are subscribed by default in
+customer-preview mode. The GA defaults retain their existing event selection.
+
+Stripe cannot update a destination's snapshot version or event scopes in place.
+`setupEventDestination` refuses an incompatible existing destination rather than
+silently reusing it. Create a replacement at a new webhook path, register the
+matching route and signing secret, verify deliveries, then retire the old
+endpoint. A low-level `createWebhookEndpoint` call retains its existing same-URL
+secret-rotation behavior; do not use it as an implicit migration plan.
+
+See [event destination creation](https://docs.stripe.com/api/v2/core/event-destinations/create)
+and [update restrictions](https://docs.stripe.com/api/v2/core/event-destinations/update).
+
+## Verification boundary
+
+Package tests exercise serialized SDK request headers, customer-only account
+configuration, idempotency keys, Checkout buyer binding, authoritative reads,
+subscription cancellation/reactivation, portal and refund calls, webhook route
+configuration, thin-event synchronization, and snapshot version/scope checks.
+The GA version has regression coverage alongside the preview version.
+
+A real non-Connect sandbox test additionally requires the owner-enabled preview
+and sandbox credentials. A Connect sandbox, mocked transport, or successful
+TypeScript compilation does not prove that separate eligibility requirement.
+Do not report checkout, receipt, renewal, portal or refund acceptance as verified
+for a non-Connect merchant until those flows run in its enabled sandbox.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -59,6 +59,7 @@
     "src",
     "docs/react-workflows.md",
     "docs/settlement.md",
+    "docs/accounts-v2-preview.md",
     "docs/react-workflows-audit.md",
     "CHANGELOG.md",
     "MIGRATION.md"

package/src/client/apiVersion.ts

@@ -0,0 +1,20 @@
+import { STRIPE_API_VERSION } from "./constants.js";
+import { throwStripeError } from "./errors.js";
+/** Explicit opt-in for Stripe's customer-only Accounts v2 public preview. */
+export const STRIPE_CUSTOMER_PREVIEW_API_VERSION = "2026-09-30.preview";
+export type SupportedStripeApiVersion =
+  typeof STRIPE_API_VERSION | typeof STRIPE_CUSTOMER_PREVIEW_API_VERSION;
+export function resolveStripeApiVersion(
+  version?: string,
+): SupportedStripeApiVersion {
+  if (version === undefined) return STRIPE_API_VERSION;
+  if (
+    version === STRIPE_API_VERSION ||
+    version === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+  )
+    return version;
+  throwStripeError(
+    "INVALID_CONFIGURATION",
+    `Unsupported Stripe API version. Use ${STRIPE_API_VERSION} or ${STRIPE_CUSTOMER_PREVIEW_API_VERSION}.`,
+  );
+}

package/src/client/billing/subscriptionCancellation.test.ts

@@ -0,0 +1,68 @@
+import type Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import type { WebhookContext } from "../webhooks/helpers.js";
+import { processEvent } from "../webhooks/processors.js";
+import { syncAllSubscriptions } from "./subscriptions.js";
+
+const component = componentsGeneric().betterStripe as unknown as Component;
+function subscription(cancelAt: number | null) {
+  return {
+    id: "sub_portal",
+    customer_account: "acct_buyer",
+    status: "active",
+    cancel_at_period_end: false,
+    cancel_at: cancelAt,
+    metadata: { userId: "buyer" },
+    items: { data: [{ current_period_end: 2000 }] },
+  } as unknown as Stripe.Subscription;
+}
+it.each([
+  [2000, true],
+  [1900, false],
+  [null, false],
+] as const)(
+  "normalizes portal cancel_at=%s without misclassifying other dates",
+  async (cancelAt, expected) => {
+    const runMutation = vi.fn();
+    const whCtx = {
+      ctx: { runMutation },
+      component,
+      stripe: {} as Stripe,
+    } as unknown as WebhookContext;
+    await processEvent(whCtx, {
+      type: "customer.subscription.updated",
+      data: { object: subscription(cancelAt) },
+    } as Stripe.Event);
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        stripeSubscriptionId: "sub_portal",
+        cancelAtPeriodEnd: expected,
+      }),
+    );
+  },
+);
+it("keeps portal-scheduled cancellation when rebuilding the component store", async () => {
+  const stripe = {
+    subscriptions: {
+      list: () => ({
+        async *[Symbol.asyncIterator]() {
+          yield subscription(2000);
+        },
+      }),
+    },
+  } as unknown as Stripe;
+  const runMutation = vi.fn();
+  await syncAllSubscriptions(stripe, component, {
+    runMutation,
+  } as unknown as RunCtx);
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      stripeSubscriptionId: "sub_portal",
+      cancelAtPeriodEnd: true,
+    }),
+  );
+});

package/src/client/billing/subscriptionCancellation.ts

@@ -0,0 +1,10 @@
+import type Stripe from "stripe";
+
+/** Portal cancellation can use cancel_at instead of cancel_at_period_end. */
+export function cancelsAtPeriodEnd(subscription: Stripe.Subscription): boolean {
+  const periodEnd = subscription.items?.data?.[0]?.current_period_end;
+  return (
+    subscription.cancel_at_period_end ||
+    (periodEnd != null && subscription.cancel_at === periodEnd)
+  );
+}

package/src/client/billing/subscriptions.ts

@@ -1,4 +1,5 @@
 import { subscriptionRouting } from "./subscriptionRouting.js";
+import { cancelsAtPeriodEnd } from "./subscriptionCancellation.js";
 import { resolveOwnerAccount } from "../utils/owner.js";
 import type Stripe from "stripe";
 
@@ -212,7 +213,7 @@ export async function createSubscription(
         firstItem?.current_period_start ?? undefined,
       ),
       currentPeriodEnd: epochToIso(firstItem?.current_period_end ?? undefined),
-      cancelAtPeriodEnd: sub.cancel_at_period_end,
+      cancelAtPeriodEnd: cancelsAtPeriodEnd(sub),
       canceledAt: epochToIso(sub.canceled_at),
       isTrialing: sub.status === "trialing",
       trialStart: epochToIso(sub.trial_start),
@@ -584,7 +585,7 @@ export async function syncAllSubscriptions(
           quantity: firstItem?.quantity ?? undefined,
           currentPeriodStart: epochToIso(periodStart),
           currentPeriodEnd: epochToIso(periodEnd),
-          cancelAtPeriodEnd: sub.cancel_at_period_end,
+          cancelAtPeriodEnd: cancelsAtPeriodEnd(sub),
           isCollectionPaused: !!sub.pause_collection,
           canceledAt: epochToIso(sub.canceled_at),
           isTrialing: sub.status === "trialing",

package/src/client/customer-preview-thin.test.ts

@@ -0,0 +1,41 @@
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { handleV2Event } from "./webhooks/v2.js";
+import type { WebhookContext } from "./webhooks/helpers.js";
+import type { V2ThinEvent } from "./types.js";
+it("syncs a preview customer without requesting merchant, recipient or Connect requirements", async () => {
+  const retrieve = vi.fn().mockResolvedValue({
+    id: "acct_buyer",
+    metadata: { userId: "buyer" },
+    configuration: { customer: { applied: true } },
+    applied_configurations: ["customer"],
+    identity: { country: "us" },
+  });
+  const runMutation = vi.fn();
+  const ctx = {
+    component: componentsGeneric().betterStripe,
+    ctx: { runMutation },
+    stripe: { v2: { core: { accounts: { retrieve } } } },
+    config: { stripeApiVersion: "2026-09-30.preview" },
+  } as unknown as WebhookContext;
+  await handleV2Event(ctx, {
+    id: "evt_preview",
+    type: "v2.core.account[configuration.customer].updated",
+    context: "acct_merchant",
+    related_object: { id: "acct_buyer", type: "v2.core.account" },
+  } as V2ThinEvent);
+  expect(retrieve).toHaveBeenCalledWith(
+    "acct_buyer",
+    { include: ["configuration.customer", "identity"] },
+    { stripeContext: "acct_merchant" },
+  );
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      userId: "buyer",
+      stripeAccountId: "acct_buyer",
+      appliedConfigurations: ["customer"],
+      onboardingStatus: "complete",
+    }),
+  );
+});

package/src/client/customer-preview-webhooks.test.ts

@@ -0,0 +1,150 @@
+import type Stripe from "stripe";
+import { componentsGeneric, type HttpRouter } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "./index.js";
+import type { Component, RunCtx } from "./helpers.js";
+import {
+  createWebhookEndpoint,
+  setupEventDestination,
+} from "./utils/webhookEndpoints.js";
+const handle = vi.hoisted(() => vi.fn(async () => new Response("ok")));
+vi.mock("./webhooks/handler.js", () => ({ handleWebhookRequest: handle }));
+const version = "2026-09-30.preview";
+const component = componentsGeneric().betterStripe as unknown as Component;
+it("instance routes inherit the selected client version and reject conflicting configuration", async () => {
+  const bs = new BetterStripe(component, {
+    STRIPE_SECRET_KEY: "sk_test_preview_routes",
+    stripeApiVersion: version,
+  });
+  const route = vi.fn();
+  bs.registerRoutes({ route } as unknown as HttpRouter, {
+    webhookSecret: "whsec_fixture",
+  });
+  const handler = route.mock.calls[0][0].handler as {
+    _handler: (ctx: unknown, request: Request) => Promise<Response>;
+  };
+  await handler._handler(
+    {},
+    new Request("https://example.com/stripe/webhook", { method: "POST" }),
+  );
+  expect(handle).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.anything(),
+    component,
+    expect.objectContaining({
+      stripeApiVersion: version,
+      stripeSecretKey: "sk_test_preview_routes",
+      webhookSecret: "whsec_fixture",
+    }),
+  );
+  expect(() =>
+    bs.registerRoutes({ route } as unknown as HttpRouter, {
+      stripeApiVersion: "2026-09-30.endive",
+    }),
+  ).toThrow("match");
+  expect(route).toHaveBeenCalledTimes(1);
+});
+function sdk() {
+  const raw = {
+    webhookEndpoints: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+      create: vi.fn().mockResolvedValue({
+        id: "we_preview",
+        url: "https://example.com/events",
+        secret: "whsec_fixture",
+      }),
+    },
+    v2: {
+      core: {
+        eventDestinations: {
+          list: vi.fn().mockResolvedValue({ data: [] }),
+          create: vi.fn().mockResolvedValue({
+            id: "ed_preview",
+            enabled_events: [],
+            webhook_endpoint: { signing_secret: "whsec_fixture" },
+          }),
+          update: vi.fn(),
+        },
+      },
+    },
+  };
+  return { raw, stripe: raw as unknown as Stripe };
+}
+it("pins snapshot payloads, leaves thin payloads unversioned, and uses canonical preview scopes", async () => {
+  const { raw, stripe } = sdk(),
+    ctx = {} as RunCtx;
+  await createWebhookEndpoint(stripe, ctx, {
+    url: "https://example.com/events",
+    apiVersion: version,
+  });
+  expect(raw.webhookEndpoints.create).toHaveBeenCalledWith(
+    expect.objectContaining({ api_version: version }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "snapshot",
+    apiVersion: version,
+  });
+  expect(raw.v2.core.eventDestinations.create).toHaveBeenLastCalledWith(
+    expect.objectContaining({
+      snapshot_api_version: version,
+      events_from: ["@self"],
+    }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "thin",
+    apiVersion: version,
+  });
+  const thin = raw.v2.core.eventDestinations.create.mock.calls[1][0];
+  expect(thin).not.toHaveProperty("snapshot_api_version");
+  expect(thin.events_from).toEqual(["@self", "@accounts"]);
+  expect(thin.enabled_events).toEqual([
+    "v2.core.account.created",
+    "v2.core.account[configuration.customer].updated",
+    "v2.core.account[identity].updated",
+  ]);
+});
+it("refuses to reuse a snapshot destination whose immutable version differs", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "snapshot",
+        snapshot_api_version: "2026-09-30.endive",
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "snapshot",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("version");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+  expect(raw.v2.core.eventDestinations.create).not.toHaveBeenCalled();
+});
+it("refuses a preview thin destination that cannot deliver managed customer account events", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "thin",
+        events_from: ["@self"],
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "thin",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("scope");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+});

package/src/client/customer-preview.test.ts

@@ -0,0 +1,185 @@
+import Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe, type BetterStripeOptions } from "./index.js";
+import { getStripeClient, type Component, type RunCtx } from "./helpers.js";
+
+const preview = "2026-09-30.preview";
+const component = componentsGeneric().betterStripe as unknown as Component;
+const ctx = {
+  runQuery: vi.fn().mockImplementation(async (_ref, args) =>
+    args?.stripeAccountId
+      ? {
+          _id: "row",
+          userId: "buyer",
+          stripeAccountId: "acct_buyer",
+          appliedConfigurations: [],
+        }
+      : null,
+  ),
+  runMutation: vi.fn().mockResolvedValue("row"),
+} as unknown as RunCtx;
+function fixture(version: string | undefined) {
+  const key = `sk_test_preview_transport_${crypto.randomUUID()}`;
+  const bs = new BetterStripe(component, {
+    STRIPE_SECRET_KEY: key,
+    ...(version === undefined ? {} : { stripeApiVersion: version }),
+  } as BetterStripeOptions);
+  const calls: {
+    path: string;
+    version: string;
+    idempotency: string | undefined;
+    body: string;
+  }[] = [];
+  for (const selected of new Set([version, "2026-09-30.endive"])) {
+    const sdk = getStripeClient(key, selected);
+    (
+      sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
+    )._setApiField("httpClient", {
+      getClientName: () => "preview-contract-test",
+      makeRequest: async (
+        ...[, , path, , headers, body]: Parameters<
+          ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+        >
+      ) => {
+        calls.push({
+          path,
+          version: String(headers["Stripe-Version"]),
+          idempotency: headers["Idempotency-Key"] as string | undefined,
+          body: String(body),
+        });
+        const data = path.includes("/checkout/sessions")
+          ? {
+              id: "cs_preview",
+              object: "checkout.session",
+              client_secret: "test_secret",
+              status: "open",
+            }
+          : path.includes("/v2/core/accounts")
+            ? {
+                id: "acct_buyer",
+                object: "v2.core.account",
+                applied_configurations: ["customer"],
+                configuration: { customer: {} },
+                metadata: { userId: "buyer" },
+              }
+            : path.includes("/prices/")
+              ? {
+                  id: "price_preview",
+                  active: true,
+                  unit_amount: 1000,
+                  currency: "usd",
+                  type: "one_time",
+                  product: "prod_preview",
+                }
+              : path.includes("/products/")
+                ? { id: "prod_preview", active: true }
+                : path.includes("/billing_portal/sessions")
+                  ? {
+                      id: "bps_preview",
+                      url: "https://billing.stripe.com/test",
+                    }
+                  : path.includes("/refunds")
+                    ? { id: "re_preview", status: "succeeded" }
+                    : path.includes("/payment_intents/")
+                      ? {
+                          id: "pi_preview",
+                          latest_charge: {
+                            id: "ch_preview",
+                            amount: 1000,
+                            currency: "usd",
+                          },
+                        }
+                      : path.includes("/charges/")
+                        ? { id: "ch_preview", amount: 1000, currency: "usd" }
+                        : path.includes("/coupons/")
+                          ? { id: "coupon_preview", valid: true }
+                          : {
+                              id: "sub_preview",
+                              status: "active",
+                              customer_account: "acct_buyer",
+                              items: { data: [] },
+                              metadata: {},
+                            };
+        return {
+          getStatusCode: () => 200,
+          getHeaders: () => ({}),
+          getRawResponse: () => ({}),
+          toJSON: async () => data,
+          toStream: () => {
+            throw new Error("Unexpected stream");
+          },
+        };
+      },
+    });
+  }
+  return { bs, calls };
+}
+it.each([undefined, preview])(
+  "uses one selected version for account, Checkout, billing, refunds and authoritative reads (%s)",
+  async (version) => {
+    const { bs, calls } = fixture(version);
+    await bs.ensureCustomerAccount(ctx, {
+      userId: "buyer",
+      email: "buyer@example.com",
+      idempotencyKey: "account:buyer",
+    });
+    await bs.createCheckoutSession(ctx, {
+      userId: "buyer",
+      accountId: "acct_buyer",
+      stripePriceId: "price_preview",
+      mode: "payment",
+      returnUrl: "https://example.com/receipt",
+      idempotencyKey: "order:one",
+    });
+    await bs.getCheckoutSessionFromStripe(ctx, {
+      stripeSessionId: "cs_preview",
+    });
+    await bs.getSubscriptionFromStripe(ctx, {
+      stripeSubscriptionId: "sub_preview",
+    });
+    await bs.getCouponFromStripe(ctx, { stripeCouponId: "coupon_preview" });
+    await bs.cancelSubscription(ctx, { stripeSubscriptionId: "sub_preview" });
+    await bs.reactivateSubscription(ctx, {
+      stripeSubscriptionId: "sub_preview",
+    });
+    await bs.createBillingPortalSession(ctx, {
+      stripeAccountId: "acct_buyer",
+      returnUrl: "https://example.com/billing",
+    });
+    await bs.createRefund(ctx, {
+      stripeChargeId: "ch_preview",
+      idempotencyKey: "refund:one",
+    });
+    expect(calls.length).toBeGreaterThanOrEqual(8);
+    expect(new Set(calls.map((c) => c.version))).toEqual(
+      new Set([version ?? "2026-09-30.endive"]),
+    );
+    expect(calls.find((c) => c.path === "/v2/core/accounts")?.idempotency).toBe(
+      "account:buyer",
+    );
+    expect(
+      calls.find((c) => c.path === "/v1/checkout/sessions" && c.idempotency)
+        ?.idempotency,
+    ).toBe("order:one");
+    expect(
+      calls.find((c) => c.path === "/v1/checkout/sessions" && c.idempotency)
+        ?.body,
+    ).toContain("customer_account=acct_buyer");
+    expect(
+      calls.find((c) => c.path === "/v2/core/accounts")?.body,
+    ).not.toContain("merchant");
+    expect(bs.stripeApiVersion).toBe(version ?? "2026-09-30.endive");
+  },
+);
+it.each(["", "2020-08-27", "2026-09-30.preview; unsafe", "not-a-version"])(
+  "rejects unsupported client versions clearly (%s)",
+  (version) => {
+    expect(
+      () =>
+        new BetterStripe(component, {
+          stripeApiVersion: version,
+        } as unknown as BetterStripeOptions),
+    ).toThrow("Unsupported Stripe API version");
+  },
+);