[breaking] Update types for Checkout SDK (#803)

pololi-stripe · web-flow · commit 1a679ae2f28d · 2025-09-09T12:51:20.000-07:00
* Update types for Checkout SDK

* pl - fix comment
diff --git a/tests/types/src/invalid.ts b/tests/types/src/invalid.ts
@@ -498,23 +498,30 @@ elements.create('paymentMethodMessaging', {
 
 stripe
   .initCheckout({
-    // @ts-expect-error Object literal may only specify known properties, and 'clientSecret' does not exist in type 'StripeCheckoutOptions'.
-    clientSecret: 'cs_test_foo',
+    // @ts-expect-error Object literal may only specify known properties, and 'fetchClientSecret' does not exist in type 'StripeCheckoutOptions'.
+    fetchClientSecret: () => Promise.resolve('cs_test_foo'),
   })
-  .then((checkout) => {
-    // @ts-expect-error Property 'createElement' does not exist on type 'StripeCheckout'.
-    checkout.createElement('payment');
+  // @ts-expect-error Property 'then' does not exist on type 'StripeCheckout'.
+  .then((checkout) => {});
+
+const checkout = stripe.initCheckout({clientSecret: 'cs_test_foo'});
+// @ts-expect-error Property 'createElement' does not exist on type 'StripeCheckout'.
+checkout.createElement('payment');
+// @ts-expect-error - doesn't take a number
+checkout.loadFonts(42);
+checkout.loadFonts([
+  {
+    cssSrc: 'https://example.com/font.css',
+    // @ts-expect-error - this is not a valid field
+    extraWrongField: false,
+  },
+]);
+checkout.loadActions().then((loadActionsResult) => {
+  if (loadActionsResult.type === 'success') {
+    const {actions} = loadActionsResult;
     // @ts-expect-error Type 'StripeCheckoutAmount' is not assignable to type 'number'.
-    const subtotal: number = checkout.session().total.subtotal;
-
-    // @ts-expect-error - doesn't take a number
-    checkout.loadFonts(42);
-
-    checkout.loadFonts([
-      {
-        cssSrc: 'https://example.com/font.css',
-        // @ts-expect-error - this is not a valid field
-        extraWrongField: false,
-      },
-    ]);
-  });
+    const subtotal: number = actions.getSession().total.subtotal;
+  } else {
+    const {error} = loadActionsResult;
+  }
+});
diff --git a/tests/types/src/valid.ts b/tests/types/src/valid.ts
@@ -3829,52 +3829,71 @@ stripe.createEphemeralKeyNonce({
   issuingCard: '',
 });
 
-stripe
-  .initCheckout({
-    fetchClientSecret: async () => 'cs_test_foo',
-  })
-  .then(async (checkout) => {
-    const checkoutPaymentElement: StripePaymentElement = checkout.createPaymentElement();
-    checkout.getPaymentElement();
-    const checkoutAddressElement: StripeAddressElement = checkout.createBillingAddressElement();
-    checkout.getBillingAddressElement();
-    checkout.applyPromotionCode('code');
-
-    checkout.loadFonts([
-      {
-        cssSrc: 'https://example.com/font.css',
-      },
-      {
-        src: 'url(https://example.com/Blah.woff)',
-        family: 'Blah',
-        weight: '500',
-        style: 'italic',
-        unicodeRange: 'some range',
-        display: 'display value',
-      },
-    ]);
+stripe.initCheckout({clientSecret: Promise.resolve('cs_test_foo')});
+const checkout = stripe.initCheckout({clientSecret: 'cs_test_foo'});
+const checkoutPaymentElement: StripePaymentElement = checkout.createPaymentElement();
+checkout.getPaymentElement();
+const checkoutAddressElement: StripeAddressElement = checkout.createBillingAddressElement();
+checkout.getBillingAddressElement();
+checkout.loadFonts([
+  {
+    cssSrc: 'https://example.com/font.css',
+  },
+  {
+    src: 'url(https://example.com/Blah.woff)',
+    family: 'Blah',
+    weight: '500',
+    style: 'italic',
+    unicodeRange: 'some range',
+    display: 'display value',
+  },
+]);
+
+checkout.loadActions().then((loadActionsResult) => {
+  if (loadActionsResult.type === 'success') {
+    const {actions} = loadActionsResult;
+    actions.applyPromotionCode('code').then((result) => {
+      if (result.type === 'success') {
+        const {session} = result;
+      } else {
+        const {error} = result;
+      }
+    });
+    actions.removePromotionCode().then((result) => {
+      if (result.type === 'success') {
+        const {session} = result;
+      } else {
+        const {error} = result;
+      }
+    });
 
+    const session = actions.getSession();
     const {
       minorUnitsAmountDivisor,
       lineItems,
       total: {
         taxExclusive: {amount, minorUnitsAmount},
       },
-    } = checkout.session();
+    } = session;
     const {
       subtotal: {amount: _, minorUnitsAmount: __},
     } = lineItems[0];
-    const result = await checkout.confirm();
-    if (result.type === 'success') {
-      const {session} = result;
-    } else {
-      const {error} = result;
-    }
-  });
+
+    actions.confirm().then((result) => {
+      if (result.type === 'success') {
+        const {session} = result;
+      } else {
+        const {error} = result;
+      }
+    });
+  } else {
+    const {error} = loadActionsResult;
+  }
+});
 
 // savedPaymentMethod variations for initCheckout:
 stripe.initCheckout({
-  fetchClientSecret: async () => 'cs_test_foo',
+  clientSecret: 'cs_test_foo',
   elementsOptions: {
     savedPaymentMethod: {
       enableSave: 'never',
@@ -3885,7 +3904,7 @@ stripe.initCheckout({
 
 // only enableSave
 stripe.initCheckout({
-  fetchClientSecret: async () => 'cs_test_foo',
+  clientSecret: 'cs_test_foo',
   elementsOptions: {
     savedPaymentMethod: {
       enableSave: 'auto',
@@ -3895,7 +3914,7 @@ stripe.initCheckout({
 
 // only enableRedisplay
 stripe.initCheckout({
-  fetchClientSecret: async () => 'cs_test_foo',
+  clientSecret: 'cs_test_foo',
   elementsOptions: {
     savedPaymentMethod: {
       enableRedisplay: 'never',
@@ -3905,7 +3924,7 @@ stripe.initCheckout({
 
 // empty savedPaymentMethod object
 stripe.initCheckout({
-  fetchClientSecret: async () => 'cs_test_foo',
+  clientSecret: 'cs_test_foo',
   elementsOptions: {
     savedPaymentMethod: {},
   },
diff --git a/types/stripe-js/checkout.d.ts b/types/stripe-js/checkout.d.ts
@@ -32,7 +32,7 @@ export interface StripeCheckoutElementsOptions {
 }
 
 export interface StripeCheckoutOptions {
-  fetchClientSecret: () => Promise<string>;
+  clientSecret: Promise<string> | string;
   elementsOptions?: StripeCheckoutElementsOptions;
 }
 
@@ -556,8 +556,8 @@ export type StripeCheckoutRunServerUpdateResult =
   | {type: 'success'; session: StripeCheckoutSession}
   | {type: 'error'; error: AnyBuyerError};
 
-export interface StripeCheckout {
-  /* Custom Checkout methods */
+type LoadActionsError = {message: string; code: null};
+type LoadActionsSuccess = {
   applyPromotionCode: (
     promotionCode: string
   ) => Promise<StripeCheckoutApplyPromotionCodeResult>;
@@ -569,9 +569,11 @@ export interface StripeCheckout {
     billingAddress: StripeCheckoutContact | null
   ) => Promise<StripeCheckoutUpdateAddressResult>;
   updatePhoneNumber: (
-    phoneNumber: string
+    phoneNumber: string | null
   ) => Promise<StripeCheckoutUpdatePhoneNumberResult>;
-  updateEmail: (email: string) => Promise<StripeCheckoutUpdateEmailResult>;
+  updateEmail: (
+    email: string | null
+  ) => Promise<StripeCheckoutUpdateEmailResult>;
   updateLineItemQuantity: (args: {
     lineItem: string;
     quantity: number;
@@ -593,11 +595,18 @@ export interface StripeCheckout {
     shippingAddress?: StripeCheckoutContact;
     expressCheckoutConfirmEvent?: StripeExpressCheckoutElementConfirmEvent;
   }) => Promise<StripeCheckoutConfirmResult>;
-  session: () => StripeCheckoutSession;
-  on: (event: 'change', handler: StripeCheckoutUpdateHandler) => void;
+  getSession: () => StripeCheckoutSession;
   runServerUpdate: (
     userFunction: RunServerUpdateFunction
   ) => Promise<StripeCheckoutRunServerUpdateResult>;
+};
+export type StripeCheckoutLoadActionsResult =
+  | {type: 'success'; actions: LoadActionsSuccess}
+  | {type: 'error'; error: LoadActionsError};
+
+export interface StripeCheckout {
+  on: (event: 'change', handler: StripeCheckoutUpdateHandler) => void;
+  loadActions: () => Promise<StripeCheckoutLoadActionsResult>;
 
   /* Elements methods */
   changeAppearance: (appearance: Appearance) => void;
diff --git a/types/stripe-js/stripe.d.ts b/types/stripe-js/stripe.d.ts
@@ -1280,10 +1280,11 @@ export interface Stripe {
   ): Promise<EphemeralKeyNonceResult>;
 
   /**
-   * Requires beta access:
-   * Contact [Stripe support](https://support.stripe.com/) for more information.
+   * Use `stripe.initCheckout` to initialize a Checkout instance
+   *
+   * * @docs https://docs.stripe.com/payments/accept-a-payment?platform=web&ui=embedded-components
    */
-  initCheckout(options: StripeCheckoutOptions): Promise<StripeCheckout>;
+  initCheckout(options: StripeCheckoutOptions): StripeCheckout;
 
   /**
    * Use `stripe.initEmbeddedCheckout` to initialize an embedded Checkout instance
