feat(payment): add checkout locale to Stripe elements (#3088)

PavlenkoM · web-flow · commit 01b4fbb1e56b · 2025-12-04T14:25:44.000+02:00
* feat(payment): add checkout locale to Stripe elements
diff --git a/packages/core/src/cart/cart-selector.ts b/packages/core/src/cart/cart-selector.ts
@@ -12,6 +12,7 @@ export default interface CartSelector {
     getCartOrThrow(): Cart;
     getLoadError(): Error | undefined;
     isLoading(): boolean;
+    getLocale(): string | undefined;
 }
 
 export type CartSelectorFactory = (state: CartState) => CartSelector;
@@ -36,12 +37,18 @@ export function createCartSelectorFactory() {
         (status) => () => status,
     );
 
+    const getLocale = createSelector(
+        (state: CartState) => state.data?.locale,
+        (data) => () => data,
+    );
+
     return memoizeOne((state: CartState = DEFAULT_STATE): CartSelector => {
         return {
             getCart: getCart(state),
             getCartOrThrow: getCartOrThrow(state),
             getLoadError: getLoadError(state),
             isLoading: isLoading(state),
+            getLocale: getLocale(state),
         };
     });
 }
diff --git a/packages/core/src/cart/cart.ts b/packages/core/src/cart/cart.ts
@@ -35,4 +35,5 @@ export default interface Cart {
     createdTime: string;
     updatedTime: string;
     source?: CartSource;
+    locale: string;
 }
diff --git a/packages/core/src/cart/carts.mock.ts b/packages/core/src/cart/carts.mock.ts
@@ -26,6 +26,7 @@ export function getCart(): Cart {
         },
         createdTime: '2018-03-06T04:41:49+00:00',
         updatedTime: '2018-03-07T03:44:51+00:00',
+        locale: 'en',
     };
 }
 
diff --git a/packages/core/src/payment-integration/create-payment-integration-selectors.ts b/packages/core/src/payment-integration/create-payment-integration-selectors.ts
@@ -5,7 +5,7 @@ import { cloneResult as clone } from '../common/utility';
 
 export default function createPaymentIntegrationSelectors({
     billingAddress: { getBillingAddress, getBillingAddressOrThrow },
-    cart: { getCart, getCartOrThrow },
+    cart: { getCart, getCartOrThrow, getLocale: getCartLocale },
     checkout: { getCheckout, getCheckoutOrThrow, getOutstandingBalance },
     config: {
         getContextConfig,
@@ -50,6 +50,7 @@ export default function createPaymentIntegrationSelectors({
     return {
         getHost: clone(getHost),
         getLocale: clone(getLocale),
+        getCartLocale: clone(getCartLocale),
         getBillingAddress: clone(getBillingAddress),
         getBillingAddressOrThrow: clone(getBillingAddressOrThrow),
         getCart: clone(getCart),
diff --git a/packages/core/src/shipping/strategies/stripe-upe/stripe-upe-shipping-strategy.spec.ts b/packages/core/src/shipping/strategies/stripe-upe/stripe-upe-shipping-strategy.spec.ts
@@ -4,6 +4,8 @@ import { createScriptLoader } from '@bigcommerce/script-loader';
 import { Observable, of } from 'rxjs';
 
 import {
+    STRIPE_UPE_CLIENT_API_VERSION,
+    STRIPE_UPE_CLIENT_BETAS,
     StripeClient,
     StripeDisplayName,
     StripeElement,
@@ -139,6 +141,8 @@ describe('StripeUPEShippingStrategy', () => {
             jest.spyOn(store.getState().paymentMethods, 'getPaymentMethodOrThrow').mockReturnValue(
                 getStripeUPE(),
             );
+
+            jest.spyOn(store.getState().cart, 'getLocale').mockReturnValue('en');
         });
 
         afterEach(() => {
@@ -152,6 +156,12 @@ describe('StripeUPEShippingStrategy', () => {
             );
 
             expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledTimes(1);
+            expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledWith(
+                paymentMethodMock.initializationData,
+                'en',
+                STRIPE_UPE_CLIENT_BETAS,
+                STRIPE_UPE_CLIENT_API_VERSION,
+            );
             expect(stripeUPEJsMock.elements).toHaveBeenCalledTimes(1);
         });
 
diff --git a/packages/core/src/shipping/strategies/stripe-upe/stripe-upe-shipping-strategy.ts b/packages/core/src/shipping/strategies/stripe-upe/stripe-upe-shipping-strategy.ts
@@ -96,6 +96,7 @@ export default class StripeUPEShippingStrategy implements ShippingStrategy {
 
         this._stripeUPEClient = await this._stripeUPEScriptLoader.getStripeClient(
             initializationData,
+            state.cart.getLocale(),
             STRIPE_UPE_CLIENT_BETAS,
             STRIPE_UPE_CLIENT_API_VERSION,
         );
diff --git a/packages/payment-integration-api/src/cart/cart.ts b/packages/payment-integration-api/src/cart/cart.ts
@@ -20,4 +20,5 @@ export default interface Cart {
     createdTime: string;
     updatedTime: string;
     source?: CartSource;
+    locale: string;
 }
diff --git a/packages/payment-integration-api/src/mocks/carts.mock.ts b/packages/payment-integration-api/src/mocks/carts.mock.ts
@@ -30,6 +30,7 @@ export default function getCart(): Cart {
         },
         createdTime: '2018-03-06T04:41:49+00:00',
         updatedTime: '2018-03-07T03:44:51+00:00',
+        locale: 'en',
     };
 }
 
diff --git a/packages/payment-integration-api/src/payment-integration-selectors.ts b/packages/payment-integration-api/src/payment-integration-selectors.ts
@@ -17,6 +17,7 @@ import { Consignment, ShippingAddress } from './shipping';
 export default interface PaymentIntegrationSelectors {
     getHost(): string | undefined;
     getLocale(): string | undefined;
+    getCartLocale(): string | undefined;
 
     getBillingAddress(): BillingAddress | undefined;
     getBillingAddressOrThrow(): BillingAddress;
diff --git a/packages/payment-integrations-test-utils/src/test-utils/carts.mock.ts b/packages/payment-integrations-test-utils/src/test-utils/carts.mock.ts
@@ -30,6 +30,7 @@ export default function getCart(): Cart {
         },
         createdTime: '2018-03-06T04:41:49+00:00',
         updatedTime: '2018-03-07T03:44:51+00:00',
+        locale: 'en',
     };
 }
 
diff --git a/packages/payment-integrations-test-utils/src/test-utils/payment-integration-service.mock.ts b/packages/payment-integrations-test-utils/src/test-utils/payment-integration-service.mock.ts
@@ -32,6 +32,7 @@ const state = {
     getCustomerOrThrow: jest.fn(() => getCustomer()),
     getHost: jest.fn(),
     getLocale: jest.fn(),
+    getCartLocale: jest.fn(),
     getOrder: jest.fn(() => getOrder()),
     getOrderOrThrow: jest.fn(() => getOrder()),
     getOrderMeta: jest.fn(() => getOrderMeta()),
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-button-strategy.spec.ts b/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-button-strategy.spec.ts
@@ -135,6 +135,7 @@ describe('StripeLinkV2ButtonStrategy', () => {
         jest.spyOn(paymentIntegrationService.getState(), 'getPaymentMethodOrThrow').mockReturnValue(
             stripePaymentMethod,
         );
+        jest.spyOn(paymentIntegrationService.getState(), 'getCartLocale').mockReturnValue('en');
         jest.spyOn(stripeIntegrationService, 'isPaymentCompleted').mockReturnValue(
             Promise.resolve(false),
         );
@@ -194,10 +195,13 @@ describe('StripeLinkV2ButtonStrategy', () => {
             stripePaymentMethod.initializationData.captureMethod = 'automatic';
             await strategy.initialize(initialiseOptions);
 
-            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith({
-                ...stripePaymentMethod.initializationData,
-                captureMethod: 'automatic',
-            });
+            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith(
+                {
+                    ...stripePaymentMethod.initializationData,
+                    captureMethod: 'automatic',
+                },
+                'en',
+            );
             expect(elements.create).toHaveBeenCalledWith(
                 'expressCheckout',
                 expressCheckoutOptionsMock,
@@ -215,10 +219,13 @@ describe('StripeLinkV2ButtonStrategy', () => {
             stripePaymentMethod.initializationData.captureMethod = 'manual';
             await strategy.initialize(initialiseOptions);
 
-            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith({
-                ...stripePaymentMethod.initializationData,
-                captureMethod: 'manual',
-            });
+            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith(
+                {
+                    ...stripePaymentMethod.initializationData,
+                    captureMethod: 'manual',
+                },
+                'en',
+            );
             expect(elements.create).toHaveBeenCalledWith(
                 'expressCheckout',
                 expressCheckoutOptionsMock,
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-button-strategy.ts b/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-button-strategy.ts
@@ -90,7 +90,10 @@ export default class StripeLinkV2ButtonStrategy implements CheckoutButtonStrateg
         const { captureMethod } = initializationData;
 
         this._captureMethod = captureMethod;
-        this._stripeClient = await this.scriptLoader.getStripeClient(initializationData);
+        this._stripeClient = await this.scriptLoader.getStripeClient(
+            initializationData,
+            state.getCartLocale(),
+        );
 
         await this.paymentIntegrationService.loadDefaultCheckout();
 
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-customer-strategy.spec.ts b/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-customer-strategy.spec.ts
@@ -135,6 +135,7 @@ describe('StripeLinkV2CustomerStrategy', () => {
         jest.spyOn(paymentIntegrationService.getState(), 'getPaymentMethodOrThrow').mockReturnValue(
             stripePaymentMethod,
         );
+        jest.spyOn(paymentIntegrationService.getState(), 'getCartLocale').mockReturnValue('en');
         jest.spyOn(stripeIntegrationService, 'isPaymentCompleted').mockReturnValue(
             Promise.resolve(false),
         );
@@ -200,10 +201,13 @@ describe('StripeLinkV2CustomerStrategy', () => {
             stripePaymentMethod.initializationData.captureMethod = 'automatic';
             await strategy.initialize(initialiseOptions);
 
-            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith({
-                ...stripePaymentMethod.initializationData,
-                captureMethod: 'automatic',
-            });
+            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith(
+                {
+                    ...stripePaymentMethod.initializationData,
+                    captureMethod: 'automatic',
+                },
+                'en',
+            );
             expect(elements.create).toHaveBeenCalledWith(
                 'expressCheckout',
                 expressCheckoutOptionsMock,
@@ -221,10 +225,13 @@ describe('StripeLinkV2CustomerStrategy', () => {
             stripePaymentMethod.initializationData.captureMethod = 'manual';
             await strategy.initialize(initialiseOptions);
 
-            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith({
-                ...stripePaymentMethod.initializationData,
-                captureMethod: 'manual',
-            });
+            expect(scriptLoader.getStripeClient).toHaveBeenCalledWith(
+                {
+                    ...stripePaymentMethod.initializationData,
+                    captureMethod: 'manual',
+                },
+                'en',
+            );
             expect(elements.create).toHaveBeenCalledWith(
                 'expressCheckout',
                 expressCheckoutOptionsMock,
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-customer-strategy.ts b/packages/stripe-integration/src/stripe-ocs/stripe-link-v2-customer-strategy.ts
@@ -93,7 +93,10 @@ export default class StripeLinkV2CustomerStrategy implements CustomerStrategy {
         const { captureMethod } = initializationData;
 
         this._captureMethod = captureMethod;
-        this._stripeClient = await this.scriptLoader.getStripeClient(initializationData);
+        this._stripeClient = await this.scriptLoader.getStripeClient(
+            initializationData,
+            state.getCartLocale(),
+        );
 
         await this._mountExpressCheckoutElement(
             methodId,
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-ocs-payment-strategy.spec.ts b/packages/stripe-integration/src/stripe-ocs/stripe-ocs-payment-strategy.spec.ts
@@ -72,6 +72,7 @@ describe('StripeOCSPaymentStrategy', () => {
         jest.spyOn(paymentIntegrationService.getState(), 'getPaymentMethodOrThrow').mockReturnValue(
             getStripeOCSMock(),
         );
+        jest.spyOn(paymentIntegrationService.getState(), 'getCartLocale').mockReturnValue('en');
         jest.spyOn(stripeScriptLoader, 'getElements').mockReturnValue(
             Promise.resolve(stripeUPEJsMock.elements({})),
         );
@@ -386,6 +387,10 @@ describe('StripeOCSPaymentStrategy', () => {
             await stripeOCSPaymentStrategy.initialize(stripeOptions);
 
             expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledTimes(1);
+            expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledWith(
+                getStripeOCSMock().initializationData,
+                'en',
+            );
         });
 
         it('should enable Link by initialization data option', async () => {
diff --git a/packages/stripe-integration/src/stripe-ocs/stripe-ocs-payment-strategy.ts b/packages/stripe-integration/src/stripe-ocs/stripe-ocs-payment-strategy.ts
@@ -242,7 +242,9 @@ export default class StripeOCSPaymentStrategy implements PaymentStrategy {
             return this.stripeClient;
         }
 
-        return this.scriptLoader.getStripeClient(initializationData);
+        const state = this.paymentIntegrationService.getState();
+
+        return this.scriptLoader.getStripeClient(initializationData, state.getCartLocale());
     }
 
     private _collapseStripeElement() {
diff --git a/packages/stripe-integration/src/stripe-upe/stripe-upe-customer-strategy.spec.ts b/packages/stripe-integration/src/stripe-upe/stripe-upe-customer-strategy.spec.ts
@@ -14,6 +14,8 @@ import {
     PaymentIntegrationServiceMock,
 } from '@bigcommerce/checkout-sdk/payment-integrations-test-utils';
 import {
+    STRIPE_UPE_CLIENT_API_VERSION,
+    STRIPE_UPE_CLIENT_BETAS,
     StripeClient,
     StripeCustomerEvent,
     StripeElement,
@@ -58,6 +60,7 @@ describe('StripeUpeCustomerStrategy', () => {
         jest.spyOn(paymentIntegrationService.getState(), 'getPaymentMethod').mockReturnValue(
             paymentMethodMock,
         );
+        jest.spyOn(paymentIntegrationService.getState(), 'getCartLocale').mockReturnValue('en');
         jest.spyOn(paymentIntegrationService, 'loadPaymentMethod').mockResolvedValue(
             paymentIntegrationService.getState(),
         );
@@ -112,6 +115,12 @@ describe('StripeUpeCustomerStrategy', () => {
             await strategy.initialize(customerInitialization);
 
             expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledTimes(1);
+            expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledWith(
+                paymentMethodMock.initializationData,
+                'en',
+                STRIPE_UPE_CLIENT_BETAS,
+                STRIPE_UPE_CLIENT_API_VERSION,
+            );
             expect(stripeUPEJsMock.elements).toHaveBeenCalledTimes(1);
         });
 
diff --git a/packages/stripe-integration/src/stripe-upe/stripe-upe-customer-strategy.ts b/packages/stripe-integration/src/stripe-upe/stripe-upe-customer-strategy.ts
@@ -106,6 +106,7 @@ export default class StripeUPECustomerStrategy implements CustomerStrategy {
 
             stripeUPEClient = await this.scriptLoader.getStripeClient(
                 paymentMethod.initializationData,
+                state.getCartLocale(),
                 STRIPE_UPE_CLIENT_BETAS,
                 STRIPE_UPE_CLIENT_API_VERSION,
             );
diff --git a/packages/stripe-integration/src/stripe-upe/stripe-upe-payment-strategy.spec.ts b/packages/stripe-integration/src/stripe-upe/stripe-upe-payment-strategy.spec.ts
@@ -30,6 +30,8 @@ import {
     getRetrievePaymentIntentResponseWithError,
     getStripeIntegrationServiceMock,
     getStripeJsMock,
+    STRIPE_UPE_CLIENT_API_VERSION,
+    STRIPE_UPE_CLIENT_BETAS,
     StripeClient,
     StripeElementsOptions,
     StripeElementType,
@@ -80,6 +82,7 @@ describe('StripeUPEPaymentStrategy', () => {
         jest.spyOn(paymentIntegrationService.getState(), 'getCheckoutOrThrow').mockReturnValue(
             checkoutMock,
         );
+        jest.spyOn(paymentIntegrationService.getState(), 'getCartLocale').mockReturnValue('en');
 
         jest.spyOn(paymentIntegrationService, 'updateBillingAddress').mockImplementation(jest.fn());
 
@@ -192,6 +195,12 @@ describe('StripeUPEPaymentStrategy', () => {
             await strategy.initialize(options);
 
             expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledTimes(1);
+            expect(stripeScriptLoader.getStripeClient).toHaveBeenCalledWith(
+                getStripeUPEMock().initializationData,
+                'en',
+                STRIPE_UPE_CLIENT_BETAS,
+                STRIPE_UPE_CLIENT_API_VERSION,
+            );
 
             expect(stripeUPEJsMock.elements).toHaveBeenNthCalledWith(1, {
                 locale: 'en',
diff --git a/packages/stripe-integration/src/stripe-upe/stripe-upe-payment-strategy.ts b/packages/stripe-integration/src/stripe-upe/stripe-upe-payment-strategy.ts
@@ -449,8 +449,11 @@ export default class StripeUPEPaymentStrategy implements PaymentStrategy {
             return this._stripeUPEClient;
         }
 
+        const state = this.paymentIntegrationService.getState();
+
         return this.scriptLoader.getStripeClient(
             initializationData,
+            state.getCartLocale(),
             STRIPE_UPE_CLIENT_BETAS,
             STRIPE_UPE_CLIENT_API_VERSION,
         );
diff --git a/packages/stripe-utils/src/index.ts b/packages/stripe-utils/src/index.ts
@@ -28,6 +28,7 @@ export {
     StripeEvent,
     StripeDisplayName,
     StripeHostWindow,
+    StripeCustomerEvent,
 } from './stripe';
 export {
     getStripeJsMock,
diff --git a/packages/stripe-utils/src/stripe-script-loader.spec.ts b/packages/stripe-utils/src/stripe-script-loader.spec.ts
@@ -87,6 +87,7 @@ describe('StripePayScriptLoader', () => {
         it('get stripe client with all initialization data', async () => {
             await stripeUPEScriptLoader.getStripeClient(
                 defaultInitializationData,
+                'en',
                 defaultBetas,
                 defaultApiVersion,
             );
@@ -95,6 +96,7 @@ describe('StripePayScriptLoader', () => {
                 betas: defaultBetas,
                 stripeAccount: 'STRIPE_CONNECTED_ACCOUNT',
                 apiVersion: defaultApiVersion,
+                locale: 'en',
             });
         });
 
diff --git a/packages/stripe-utils/src/stripe-script-loader.ts b/packages/stripe-utils/src/stripe-script-loader.ts
@@ -18,6 +18,7 @@ export default class StripeScriptLoader {
 
     async getStripeClient(
         initializationData: StripeInitializationData,
+        locale?: string,
         betas?: string[],
         apiVersion?: string,
     ): Promise<StripeClient> {
@@ -29,6 +30,7 @@ export default class StripeScriptLoader {
         const { stripePublishableKey, stripeConnectedAccount } = initializationData;
         const options = {
             ...(stripeConnectedAccount ? { stripeAccount: stripeConnectedAccount } : {}),
+            ...(locale ? { locale } : {}),
             ...(betas ? { betas } : {}),
             ...(apiVersion ? { apiVersion } : {}),
         };

Original file line number	Diff line number	Diff line change
`@@ -35,4 +35,5 @@ export default interface Cart {`
`35`	`35`	`createdTime: string;`
`36`	`36`	`updatedTime: string;`
`37`	`37`	`source?: CartSource;`
	`38`	`+ locale: string;`
`38`	`39`	`}`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,7 @@ export function getCart(): Cart {`
`26`	`26`	`},`
`27`	`27`	`createdTime: '2018-03-06T04:41:49+00:00',`
`28`	`28`	`updatedTime: '2018-03-07T03:44:51+00:00',`
	`29`	`+ locale: 'en',`
`29`	`30`	`};`
`30`	`31`	`}`
`31`	`32`
Original file line number	Diff line number	Diff line change
`@@ -20,4 +20,5 @@ export default interface Cart {`
`20`	`20`	`createdTime: string;`
`21`	`21`	`updatedTime: string;`
`22`	`22`	`source?: CartSource;`
	`23`	`+ locale: string;`
`23`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,7 @@ export default function getCart(): Cart {`
`30`	`30`	`},`
`31`	`31`	`createdTime: '2018-03-06T04:41:49+00:00',`
`32`	`32`	`updatedTime: '2018-03-07T03:44:51+00:00',`
	`33`	`+ locale: 'en',`
`33`	`34`	`};`
`34`	`35`	`}`
`35`	`36`