From db0fa9f9fd7e8442886a41234e9daa84d6d1f221 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Fri, 31 Oct 2025 12:33:43 +0100
Subject: [PATCH 01/21] Embedded components

---
 example/ios/Podfile.lock                      |  37 ++-
 example/package.json                          |   5 +-
 example/src/App.tsx                           |  18 ++
 .../ConnectAccountOnboardingScreen.tsx        |  14 +
 .../src/screens/ConnectPaymentsListScreen.tsx |  10 +
 .../src/screens/ConnectPayoutsListScreen.tsx  |  10 +
 example/src/screens/ConnectScreen.tsx         |  51 ++++
 example/src/screens/HomeScreen.tsx            |  26 ++
 example/yarn.lock                             |  10 +-
 package.json                                  |   8 +-
 src/connect/Components.tsx                    | 140 +++++++++
 src/connect/ConnectComponentsProvider.tsx     |  41 +++
 src/connect/EmbeddedComponent.tsx             | 265 ++++++++++++++++++
 src/index.tsx                                 |   3 +
 yarn.lock                                     |  15 +-
 15 files changed, 641 insertions(+), 12 deletions(-)
 create mode 100644 example/src/screens/ConnectAccountOnboardingScreen.tsx
 create mode 100644 example/src/screens/ConnectPaymentsListScreen.tsx
 create mode 100644 example/src/screens/ConnectPayoutsListScreen.tsx
 create mode 100644 example/src/screens/ConnectScreen.tsx
 create mode 100644 src/connect/Components.tsx
 create mode 100644 src/connect/ConnectComponentsProvider.tsx
 create mode 100644 src/connect/EmbeddedComponent.tsx

diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
index 7bfdf023e1..be264cd52e 100644
--- a/example/ios/Podfile.lock
+++ b/example/ios/Podfile.lock
@@ -1304,6 +1304,27 @@ PODS:
     - ReactCommon/turbomodule/bridging
     - ReactCommon/turbomodule/core
     - Yoga
+  - react-native-webview (13.16.0):
+    - DoubleConversion
+    - glog
+    - hermes-engine
+    - RCT-Folly (= 2024.11.18.00)
+    - RCTRequired
+    - RCTTypeSafety
+    - React-Core
+    - React-debug
+    - React-Fabric
+    - React-featureflags
+    - React-graphics
+    - React-ImageManager
+    - React-NativeModulesApple
+    - React-RCTFabric
+    - React-rendererdebug
+    - React-utils
+    - ReactCodegen
+    - ReactCommon/turbomodule/bridging
+    - ReactCommon/turbomodule/core
+    - Yoga
   - React-NativeModulesApple (0.78.0):
     - glog
     - hermes-engine
@@ -1691,7 +1712,7 @@ PODS:
     - StripePayments (= 24.24.3)
     - StripePaymentsUI (= 24.24.3)
     - StripeUICore (= 24.24.3)
-  - stripe-react-native (0.54.1):
+  - stripe-react-native (0.55.1):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1712,14 +1733,14 @@ PODS:
     - ReactCommon/turbomodule/bridging
     - ReactCommon/turbomodule/core
     - Stripe (~> 24.24.0)
-    - stripe-react-native/NewArch (= 0.54.1)
+    - stripe-react-native/NewArch (= 0.55.1)
     - StripeApplePay (~> 24.24.0)
     - StripeFinancialConnections (~> 24.24.0)
     - StripePayments (~> 24.24.0)
     - StripePaymentSheet (~> 24.24.0)
     - StripePaymentsUI (~> 24.24.0)
     - Yoga
-  - stripe-react-native/NewArch (0.54.1):
+  - stripe-react-native/NewArch (0.55.1):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1746,7 +1767,7 @@ PODS:
     - StripePaymentSheet (~> 24.24.0)
     - StripePaymentsUI (~> 24.24.0)
     - Yoga
-  - stripe-react-native/Tests (0.54.1):
+  - stripe-react-native/Tests (0.55.1):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1838,6 +1859,7 @@ DEPENDENCIES:
   - React-Mapbuffer (from `../node_modules/react-native/ReactCommon`)
   - React-microtasksnativemodule (from `../node_modules/react-native/ReactCommon/react/nativemodule/microtasks`)
   - react-native-safe-area-context (from `../node_modules/react-native-safe-area-context`)
+  - react-native-webview (from `../node_modules/react-native-webview`)
   - React-NativeModulesApple (from `../node_modules/react-native/ReactCommon/react/nativemodule/core/platform/ios`)
   - React-perflogger (from `../node_modules/react-native/ReactCommon/reactperflogger`)
   - React-performancetimeline (from `../node_modules/react-native/ReactCommon/react/performance/timeline`)
@@ -1965,6 +1987,8 @@ EXTERNAL SOURCES:
     :path: "../node_modules/react-native/ReactCommon/react/nativemodule/microtasks"
   react-native-safe-area-context:
     :path: "../node_modules/react-native-safe-area-context"
+  react-native-webview:
+    :path: "../node_modules/react-native-webview"
   React-NativeModulesApple:
     :path: "../node_modules/react-native/ReactCommon/react/nativemodule/core/platform/ios"
   React-perflogger:
@@ -2075,6 +2099,7 @@ SPEC CHECKSUMS:
   React-Mapbuffer: 3c11cee7737609275c7b66bd0b1de475f094cedf
   React-microtasksnativemodule: 843f352b32aacbe13a9c750190d34df44c3e6c2c
   react-native-safe-area-context: 7e513d737b0b5c1d10bbe0e5fcc9f925a7be144c
+  react-native-webview: b729d1bcf8fbd141237355dcfd6bb65b9a1d3b1a
   React-NativeModulesApple: 88433b6946778bea9c153e27b671de15411bf225
   React-perflogger: 9e8d3c0dc0194eb932162812a168aa5dc662f418
   React-performancetimeline: 5a2d6efef52bdcefac079c7baa30934978acd023
@@ -2110,7 +2135,7 @@ SPEC CHECKSUMS:
   RNScreens: 0d4cb9afe052607ad0aa71f645a88bb7c7f2e64c
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Stripe: ac7d3c4016797553c259eff5def200b1c8cbe4f8
-  stripe-react-native: 4ae717eb5d039bbc63e3d3e1d8b3cd6a786698e3
+  stripe-react-native: cbcce918b434011bbccd7e2fd27c4dfd1734b26c
   StripeApplePay: efa314f02c07b4df2894be0790a85f0245334da0
   StripeCore: 0ebe42adefb26092389443b2a5d0744056a36fac
   StripeFinancialConnections: cc252f040e50aae6924affcf9883a519715a6ba4
@@ -2118,7 +2143,7 @@ SPEC CHECKSUMS:
   StripePaymentSheet: 8f6456410fa2671458292db6b38986d53564e990
   StripePaymentsUI: 5645028620aca78ab5b95fae975379902d860fef
   StripeUICore: 1e8fd6e1eda92ed45bb300b61560ae897a0232fd
-  Yoga: 9b7fb56e7b08cde60e2153344fa6afbd88e5d99f
+  Yoga: afd04ff05ebe0121a00c468a8a3c8080221cb14c
 
 PODFILE CHECKSUM: a2ed964678852d4cc306ff4add3e4fa90be77ea6
 
diff --git a/example/package.json b/example/package.json
index 32ef7f89df..2259b62627 100644
--- a/example/package.json
+++ b/example/package.json
@@ -24,16 +24,17 @@
     "react": "^19.0.0",
     "react-native": "^0.78.0",
     "react-native-safe-area-context": "^5.2.0",
-    "react-native-screens": "^4.9.1"
+    "react-native-screens": "^4.9.1",
+    "react-native-webview": "^13.16.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.26.4",
     "@babel/core": "^7.26.9",
     "@babel/preset-env": "^7.26.9",
     "@babel/runtime": "^7.26.9",
+    "@react-native-community/cli": "15.0.1",
     "@react-native-community/cli-platform-android": "15.0.1",
     "@react-native-community/cli-platform-ios": "15.0.1",
-    "@react-native-community/cli": "15.0.1",
     "@react-native/babel-preset": "0.78.0",
     "@react-native/metro-config": "0.78.0",
     "@react-native/typescript-config": "0.78.0",
diff --git a/example/src/App.tsx b/example/src/App.tsx
index a4f06ba9ee..8aca14a2a8 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -50,6 +50,9 @@ import CustomerSheetScreen from './screens/CustomerSheetScreen';
 import RevolutPayScreen from './screens/RevolutPayScreen';
 import type { EmbeddedPaymentElementResult } from '@stripe/stripe-react-native';
 import PaymentSheetWithPmoSfuScreen from './screens/PaymentSheetWithPmoSfuScreen';
+import ConnectPaymentsListScreen from './screens/ConnectPaymentsListScreen';
+import ConnectAccountOnboardingScreen from './screens/ConnectAccountOnboardingScreen';
+import ConnectPayoutsListScreen from './screens/ConnectPayoutsListScreen';
 
 const Stack = createNativeStackNavigator<RootStackParamList>();
 
@@ -102,6 +105,9 @@ export type RootStackParamList = {
   CustomerSheetScreen: undefined;
   RevolutPayScreen: undefined;
   PaymentSheetWithPmoSfuScreen: undefined;
+  ConnectAccountOnboardingScreen: undefined;
+  ConnectPaymentsListScreen: undefined;
+  ConnectPayoutsListScreen: undefined;
 };
 
 declare global {
@@ -281,6 +287,18 @@ export default function App() {
             name="AlmaPaymentScreen"
             component={AlmaPaymentScreen}
           />
+          <Stack.Screen
+            name="ConnectAccountOnboardingScreen"
+            component={ConnectAccountOnboardingScreen}
+          />
+          <Stack.Screen
+            name="ConnectPaymentsListScreen"
+            component={ConnectPaymentsListScreen}
+          />
+          <Stack.Screen
+            name="ConnectPayoutsListScreen"
+            component={ConnectPayoutsListScreen}
+          />
         </Stack.Navigator>
       </NavigationContainer>
     </>
diff --git a/example/src/screens/ConnectAccountOnboardingScreen.tsx b/example/src/screens/ConnectAccountOnboardingScreen.tsx
new file mode 100644
index 0000000000..ce688ddfa2
--- /dev/null
+++ b/example/src/screens/ConnectAccountOnboardingScreen.tsx
@@ -0,0 +1,14 @@
+import { ConnectAccountOnboarding } from '@stripe/stripe-react-native';
+import ConnectScreen from './ConnectScreen';
+
+export default function ConnectAccountOnboardingScreen() {
+  return (
+    <ConnectScreen>
+      <ConnectAccountOnboarding
+        onExit={() => {
+          console.log('ConnectAccountOnboarding onExit');
+        }}
+      />
+    </ConnectScreen>
+  );
+}
diff --git a/example/src/screens/ConnectPaymentsListScreen.tsx b/example/src/screens/ConnectPaymentsListScreen.tsx
new file mode 100644
index 0000000000..fb23c02f56
--- /dev/null
+++ b/example/src/screens/ConnectPaymentsListScreen.tsx
@@ -0,0 +1,10 @@
+import { ConnectPayments } from '@stripe/stripe-react-native';
+import ConnectScreen from './ConnectScreen';
+
+export default function ConnectPaymentsListScreen() {
+  return (
+    <ConnectScreen>
+      <ConnectPayments />
+    </ConnectScreen>
+  );
+}
diff --git a/example/src/screens/ConnectPayoutsListScreen.tsx b/example/src/screens/ConnectPayoutsListScreen.tsx
new file mode 100644
index 0000000000..15f173b571
--- /dev/null
+++ b/example/src/screens/ConnectPayoutsListScreen.tsx
@@ -0,0 +1,10 @@
+import { ConnectPayouts } from '@stripe/stripe-react-native';
+import ConnectScreen from './ConnectScreen';
+
+export default function ConnectPayoutsListScreen() {
+  return (
+    <ConnectScreen>
+      <ConnectPayouts />
+    </ConnectScreen>
+  );
+}
diff --git a/example/src/screens/ConnectScreen.tsx b/example/src/screens/ConnectScreen.tsx
new file mode 100644
index 0000000000..ef35bcd271
--- /dev/null
+++ b/example/src/screens/ConnectScreen.tsx
@@ -0,0 +1,51 @@
+import { ConnectComponentsProvider } from '@stripe/stripe-react-native';
+import { useEffect, useState } from 'react';
+import { fetchPublishableKey } from '../helpers';
+import { ActivityIndicator, StyleSheet } from 'react-native';
+import { API_URL } from '../Config';
+
+interface Props {
+  children?: React.ReactNode;
+}
+
+const ConnectScreen: React.FC<Props> = ({ children }) => {
+  const [publishableKey, setPublishableKey] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetchPublishableKey().then((pk) => {
+      if (pk) {
+        setPublishableKey(pk);
+      }
+    });
+  }, []);
+
+  return !publishableKey ? (
+    <ActivityIndicator size="large" style={StyleSheet.absoluteFill} />
+  ) : (
+    <ConnectComponentsProvider
+      publishableKey={publishableKey}
+      fetchClientSecret={fetchClientSecret}
+    >
+      {children}
+    </ConnectComponentsProvider>
+  );
+};
+
+export default ConnectScreen;
+
+const fetchClientSecret = async () => {
+  // TODO: use a different endpoint
+  const response = await fetch(`${API_URL}/create-payment-intent`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      currency: 'usd',
+    }),
+  });
+  const json = await response.json();
+  const { clientSecret } = json;
+
+  return clientSecret;
+};
diff --git a/example/src/screens/HomeScreen.tsx b/example/src/screens/HomeScreen.tsx
index 9891cf5323..194e3799ef 100644
--- a/example/src/screens/HomeScreen.tsx
+++ b/example/src/screens/HomeScreen.tsx
@@ -458,6 +458,32 @@ export default function HomeScreen() {
           </View>
         </>
       </Collapse>
+      <Collapse title="Connect embedded components">
+        <View style={styles.buttonContainer}>
+          <Button
+            title="Account onboarding"
+            onPress={() => {
+              navigation.navigate('ConnectAccountOnboardingScreen');
+            }}
+          />
+        </View>
+        <View style={styles.buttonContainer}>
+          <Button
+            title="Payments list"
+            onPress={() => {
+              navigation.navigate('ConnectPaymentsListScreen');
+            }}
+          />
+        </View>
+        <View style={styles.buttonContainer}>
+          <Button
+            title="Payouts list"
+            onPress={() => {
+              navigation.navigate('ConnectPayoutsListScreen');
+            }}
+          />
+        </View>
+      </Collapse>
       <View style={styles.infoContainer}>
         <Text style={styles.infoText}>
           New arch enabled:{' '}
diff --git a/example/yarn.lock b/example/yarn.lock
index 2afbca1924..ebd33a93b4 100644
--- a/example/yarn.lock
+++ b/example/yarn.lock
@@ -3144,7 +3144,7 @@ inherits@2, inherits@2.0.4, inherits@^2.0.3, inherits@^2.0.4, inherits@~2.0.3:
   resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c"
   integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==
 
-invariant@^2.2.4:
+invariant@2.2.4, invariant@^2.2.4:
   version "2.2.4"
   resolved "https://registry.yarnpkg.com/invariant/-/invariant-2.2.4.tgz#610f3c92c9359ce1db616e538008d23ff35158e6"
   integrity sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==
@@ -4379,6 +4379,14 @@ react-native-test-app@^4.2.1:
     semver "^7.3.5"
     uuid "^11.0.0"
 
+react-native-webview@^13.16.0:
+  version "13.16.0"
+  resolved "https://registry.yarnpkg.com/react-native-webview/-/react-native-webview-13.16.0.tgz#c995148f944a7eaf12389f0e6d5c6f5e6a775686"
+  integrity sha512-Nh13xKZWW35C0dbOskD7OX01nQQavOzHbCw9XoZmar4eXCo7AvrYJ0jlUfRVVIJzqINxHlpECYLdmAdFsl9xDA==
+  dependencies:
+    escape-string-regexp "^4.0.0"
+    invariant "2.2.4"
+
 react-native@^0.78.0:
   version "0.78.0"
   resolved "https://registry.yarnpkg.com/react-native/-/react-native-0.78.0.tgz#3e76252c8f8f35e5b7e07f9d8aee775aa8a315a7"
diff --git a/package.json b/package.json
index e307ab6246..8a4b4c14a4 100644
--- a/package.json
+++ b/package.json
@@ -63,11 +63,14 @@
     "url": "https://github.com/stripe/stripe-react-native/issues"
   },
   "homepage": "https://github.com/stripe/stripe-react-native/#readme",
-  "dependencies": {},
+  "dependencies": {
+    "react-native-webview": "^13.16.0"
+  },
   "devDependencies": {
     "@expo/config-plugins": "^9.0.16",
     "@react-native/babel-preset": "^0.78.0",
     "@react-native/eslint-config": "^0.78.0",
+    "@stripe/connect-js": "^3.3.31",
     "@types/jest": "^29.5.14",
     "@types/react": "^19.0.10",
     "eslint": "^8.57.0",
@@ -86,7 +89,8 @@
   "peerDependencies": {
     "expo": ">=46.0.9",
     "react": "*",
-    "react-native": "*"
+    "react-native": "*",
+    "react-native-webview": ">=13.16.0"
   },
   "peerDependenciesMeta": {
     "expo": {
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
new file mode 100644
index 0000000000..c5670c3d64
--- /dev/null
+++ b/src/connect/Components.tsx
@@ -0,0 +1,140 @@
+import type {
+  CollectionOptions,
+  PaymentsListDefaultFilters,
+  StepChange,
+} from '@stripe/connect-js';
+import React, { useMemo } from 'react';
+import { CommonComponentProps, EmbeddedComponent } from './EmbeddedComponent';
+
+export function ConnectAccountOnboarding({
+  onExit,
+  onStepChange,
+  recipientTermsOfServiceUrl,
+  fullTermsOfServiceUrl,
+  privacyPolicyUrl,
+  collectionOptions,
+  onLoaderStart,
+  onLoadError,
+  onPageDidLoad,
+  style,
+}: {
+  onExit: () => void;
+  onStepChange?: (stepChange: StepChange) => void;
+  recipientTermsOfServiceUrl?: string;
+  fullTermsOfServiceUrl?: string;
+  privacyPolicyUrl?: string;
+  collectionOptions?: CollectionOptions;
+} & CommonComponentProps) {
+  const componentProps = useMemo(() => {
+    return {
+      setFullTermsOfServiceUrl: fullTermsOfServiceUrl,
+      setRecipientTermsOfServiceUrl: recipientTermsOfServiceUrl,
+      setPrivacyPolicyUrl: privacyPolicyUrl,
+      setCollectionOptions: collectionOptions,
+    };
+  }, [
+    fullTermsOfServiceUrl,
+    recipientTermsOfServiceUrl,
+    privacyPolicyUrl,
+    collectionOptions,
+  ]);
+
+  const callbacks = useMemo(() => {
+    return {
+      onExit,
+      onStepChange,
+    };
+  }, [onExit, onStepChange]);
+
+  return (
+    <EmbeddedComponent
+      component="account-onboarding"
+      componentProps={componentProps}
+      onLoaderStart={onLoaderStart}
+      onLoadError={onLoadError}
+      onPageDidLoad={onPageDidLoad}
+      callbacks={callbacks}
+      style={style}
+    />
+  );
+}
+
+export function ConnectPayments({
+  defaultFilters,
+  onLoaderStart,
+  onLoadError,
+  onPageDidLoad,
+  style,
+}: {
+  defaultFilters?: PaymentsListDefaultFilters;
+} & CommonComponentProps) {
+  const componentProps = useMemo(() => {
+    return {
+      setDefaultFilters: defaultFilters,
+    };
+  }, [defaultFilters]);
+
+  return (
+    <EmbeddedComponent
+      component="payments"
+      onLoaderStart={onLoaderStart}
+      onLoadError={onLoadError}
+      onPageDidLoad={onPageDidLoad}
+      componentProps={componentProps}
+      style={style}
+    />
+  );
+}
+
+export function ConnectPayouts({
+  onLoaderStart,
+  onLoadError,
+  onPageDidLoad,
+  style,
+}: CommonComponentProps) {
+  return (
+    <EmbeddedComponent
+      component="payouts"
+      onLoaderStart={onLoaderStart}
+      onLoadError={onLoadError}
+      onPageDidLoad={onPageDidLoad}
+      style={style}
+    />
+  );
+}
+
+export function ConnectPaymentDetails({
+  payment,
+  onClose,
+  onLoaderStart,
+  onLoadError,
+  onPageDidLoad,
+  style,
+}: {
+  payment: string;
+  onClose: () => void;
+} & CommonComponentProps) {
+  const componentProps = useMemo(() => {
+    return {
+      setPayment: payment,
+    };
+  }, [payment]);
+
+  const callbacks = useMemo(() => {
+    return {
+      onClose,
+    };
+  }, [onClose]);
+
+  return (
+    <EmbeddedComponent
+      component="payment-details"
+      componentProps={componentProps}
+      callbacks={callbacks}
+      onLoaderStart={onLoaderStart}
+      onLoadError={onLoadError}
+      onPageDidLoad={onPageDidLoad}
+      style={style}
+    />
+  );
+}
diff --git a/src/connect/ConnectComponentsProvider.tsx b/src/connect/ConnectComponentsProvider.tsx
new file mode 100644
index 0000000000..1e3e486909
--- /dev/null
+++ b/src/connect/ConnectComponentsProvider.tsx
@@ -0,0 +1,41 @@
+import React, { JSX, useMemo } from 'react';
+import type { IStripeConnectInitParams } from '@stripe/connect-js';
+
+type ConnectComponentsPayload = {
+  publishableKey: string;
+  fetchClientSecret: IStripeConnectInitParams['fetchClientSecret'];
+  appearance?: IStripeConnectInitParams['appearance'];
+  locale?: IStripeConnectInitParams['locale'];
+  fonts?: IStripeConnectInitParams['fonts'];
+  overrides?: Record<string, string>;
+};
+
+const ConnectComponentsContext =
+  React.createContext<ConnectComponentsPayload | null>(null);
+
+ConnectComponentsContext.displayName = 'ConnectComponents';
+
+export const ConnectComponentsProvider = ({
+  children,
+  ...props
+}: ConnectComponentsPayload & {
+  children: React.ReactNode;
+}): JSX.Element => {
+  const value = useMemo(() => ({ ...props }), [props]);
+
+  return (
+    <ConnectComponentsContext.Provider value={value}>
+      {children}
+    </ConnectComponentsContext.Provider>
+  );
+};
+
+export const useConnectComponents = (): ConnectComponentsPayload => {
+  const context = React.useContext(ConnectComponentsContext);
+  if (!context) {
+    throw new Error(
+      `Could not find a ConnectComponentsContext; You need to wrap your components in an <ConnectComponentsProvider> provider.`
+    );
+  }
+  return context;
+};
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
new file mode 100644
index 0000000000..28161d32e6
--- /dev/null
+++ b/src/connect/EmbeddedComponent.tsx
@@ -0,0 +1,265 @@
+import type { LoadError, LoaderStart } from '@stripe/connect-js';
+import React, { useRef } from 'react';
+import { Platform, StyleProp, ViewStyle } from 'react-native';
+import { WebView } from 'react-native-webview';
+import { useConnectComponents } from './ConnectComponentsProvider';
+import pjson from '../../package.json';
+
+const DEVELOPMENT_MODE = true;
+
+export interface CommonComponentProps {
+  onLoaderStart?: ({ elementTagName }: LoaderStart) => void;
+  onLoadError?: ({ error, elementTagName }: LoadError) => void;
+
+  onPageDidLoad?: () => void;
+
+  style?: StyleProp<ViewStyle>;
+}
+
+type EmbeddedComponentType =
+  | 'invoice-history'
+  | 'transactions-list'
+  | 'payments'
+  | 'payment-details'
+  | 'payment-disputes'
+  | 'payouts'
+  | 'payouts-list'
+  | 'balances'
+  | 'account-management'
+  | 'account-management-form'
+  | 'account-onboarding'
+  | 'disputes-list'
+  | 'instant-payouts'
+  | 'instant-payouts-promotion'
+  | 'notification-banner'
+  | 'debug-utils'
+  | 'debug-ui-config'
+  | 'debug-ui-library'
+  | 'debug-ui-preview'
+  | 'debug-components-list'
+  | 'debug-hosted-dashboard-preview'
+  | 'app-onboarding'
+  | 'app-install'
+  | 'app-viewport'
+  | 'payment-method-settings'
+  | 'capital-financing'
+  | 'capital-financing-application'
+  | 'capital-financing-promotion'
+  | 'capital-overview'
+  | 'terminal-hardware-orders'
+  | 'terminal-hardware-shop'
+  | 'app-settings'
+  | 'instant-payouts-promotion'
+  | 'issuing-cards-list'
+  | 'issuing-card'
+  | 'financial-account'
+  | 'financial-account-transactions'
+  | 'recipients'
+  | 'product-tax-code-selector'
+  | 'check-scanning'
+  | 'tax-threshold-monitoring'
+  | 'export-tax-transactions'
+  | 'tax-settings'
+  | 'tax-registrations'
+  | 'documents'
+  | 'earnings-chart'
+  | 'reporting-chart'
+  | 'payout-details'
+  | 'balance-report'
+  | 'payout-reconciliation-report';
+
+type EmbeddedComponentProps = CommonComponentProps & {
+  component: EmbeddedComponentType;
+  componentProps?: Record<string, unknown>;
+
+  callbacks?: Record<string, ((data: any) => void) | undefined>;
+};
+
+export function EmbeddedComponent(props: EmbeddedComponentProps) {
+  const {
+    publishableKey,
+    fetchClientSecret,
+    appearance,
+    locale,
+    fonts,
+    overrides,
+  } = useConnectComponents();
+
+  const {
+    component,
+    componentProps,
+    onLoadError,
+    onLoaderStart,
+    onPageDidLoad,
+    callbacks,
+    style,
+  } = props;
+
+  const hashParams = {
+    component,
+    publicKey: publishableKey,
+    merchantIdOverride: overrides?.merchantId,
+    platformIdOverride: overrides?.platformId,
+    apiKeyOverride: overrides?.apiKey,
+    livemodeOverride: overrides?.livemode,
+  };
+
+  const hash = Object.entries(hashParams)
+    .filter(([_, value]) => value != null)
+    .map(
+      ([key, value]) =>
+        `${encodeURIComponent(key)}=${encodeURIComponent(value!)}`
+    )
+    .join('&');
+
+  const platform = Platform.OS.toLowerCase();
+  const sdkVersion = pjson.version;
+
+  const baseURL = DEVELOPMENT_MODE
+    ? Platform.select({
+        ios: 'http://localhost:3001',
+        android: 'http://10.0.2.2:3001',
+      })
+    : 'https://connect-js.stripe.com';
+  const connectURL = `${baseURL}/v1.0/${platform}_webview.html#${hash}`;
+
+  const ref = useRef<WebView>(null);
+
+  const [prevAppearance, setPrevAppearance] = React.useState(appearance);
+  if (prevAppearance !== appearance) {
+    setPrevAppearance(appearance);
+
+    ref.current?.injectJavaScript(`
+      (function() {
+        window.updateConnectInstance(${JSON.stringify({ appearance })});
+
+        true;
+      })();
+    `);
+  }
+
+  const [prevLocale, setPrevLocale] = React.useState(locale);
+  if (prevLocale !== locale) {
+    setPrevLocale(locale);
+
+    ref.current?.injectJavaScript(`
+      (function() {
+        window.updateConnectInstance(${JSON.stringify({ locale })});
+        true;
+      })();
+    `);
+  }
+
+  const [prevFonts, setPrevFonts] = React.useState(fonts);
+  if (prevFonts !== fonts) {
+    setPrevFonts(fonts);
+
+    ref.current?.injectJavaScript(`
+      (function() {
+        window.updateConnectInstance(${JSON.stringify({ fonts })});
+        true;
+      })();
+    `);
+  }
+
+  const [prevComponentProps, setPrevComponentProps] =
+    React.useState(componentProps);
+  if (prevComponentProps !== componentProps) {
+    setPrevComponentProps(componentProps);
+
+    Object.entries(componentProps || {}).forEach(([key, value]) => {
+      ref.current?.injectJavaScript(`
+        (function() {
+          window.callSetterWithSerializableValue(${JSON.stringify({
+            setter: key,
+            value,
+          })});
+          true;
+        })();
+      `);
+    });
+  }
+
+  return (
+    <WebView
+      ref={ref}
+      style={style}
+      webviewDebuggingEnabled={DEVELOPMENT_MODE}
+      source={{ uri: connectURL }}
+      userAgent={`Mobile - Stripe ReactNative SDK ${Platform.OS}/${Platform.Version} - stripe-${platform}/${sdkVersion}`}
+      injectedJavaScript={`
+        // add a style witn a sans serif font by default
+        (function() {
+          const style = document.createElement('style');
+          style.innerHTML = \`
+            body {
+              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+                Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+            }
+          \`;
+          document.head.appendChild(style);
+        })();
+      `}
+      injectedJavaScriptObject={{
+        initParams: {
+          appearance,
+          locale,
+          fonts,
+        },
+        initComponentProps: componentProps,
+        appInfo: { applicationId: undefined },
+      }}
+      onMessage={async (event) => {
+        const message = JSON.parse(event.nativeEvent.data) as {
+          type: string;
+          data?: unknown;
+        };
+        console.log('Received message from WebView:', message);
+
+        if (message.type === 'fetchClientSecret') {
+          const clientSecret = await fetchClientSecret();
+
+          ref.current?.injectJavaScript(`
+            window.clientSecretDeferred.resolve(${JSON.stringify(
+              clientSecret
+            )});
+          `);
+        } else if (message.type === 'debug') {
+          // message.data is of type string
+          console.debug(`[EmbeddedComponent ${component}]: ${message.data}`);
+        } else if (message.type === 'pageDidLoad') {
+          onPageDidLoad?.();
+        } else if (message.type === 'accountSessionClaimed') {
+          // message.data is of type {elementTagName: string, merchantId: string}
+        } else if (message.type === 'openFinancialConnections') {
+          // message.data is of type {clientSecret: string; id: string; connectedAccountId: string;}
+        } else if (message.type === 'closeWebView') {
+          console.log('closeWebView');
+        } else if (message.type === 'callSupplementalFunction') {
+          console.log('message:', message);
+          // message.data is of type {[key]: {functionName: string; args: unknown[]; invocationId: string;}}
+        } else if (message.type === 'onSetterFunctionCalled') {
+          const { setter, value } = message.data as {
+            setter: string;
+            value: unknown;
+          };
+
+          if (setter === 'setOnLoaderStart') {
+            onLoaderStart?.(value as LoaderStart);
+          } else if (setter === 'setOnLoadError') {
+            onLoadError?.(value as LoadError);
+          } else {
+            // remove the 'set' prefix and lowercase the first letter
+            const functionName =
+              setter.charAt(3).toLowerCase() + setter.substring(4);
+            callbacks?.[functionName]?.(value);
+          }
+        } else if (message.type === 'openAuthenticatedWebView') {
+          // message.data is of type {id: string; url: string}
+        } else {
+          // unhandled message
+        }
+      }}
+    />
+  );
+}
diff --git a/src/index.tsx b/src/index.tsx
index 8ee15484cd..c1fb912ac5 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -34,3 +34,6 @@ export type { Props as CustomerSheetProps } from './components/CustomerSheet';
 export * from './types/EmbeddedPaymentElement';
 export * from './types/PaymentSheet';
 export * from './types/ConfirmationToken';
+
+export { ConnectComponentsProvider } from './connect/ConnectComponentsProvider';
+export * from './connect/Components';
diff --git a/yarn.lock b/yarn.lock
index 2a864fb8fa..396ad661fc 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1776,6 +1776,11 @@
   dependencies:
     "@sinonjs/commons" "^3.0.0"
 
+"@stripe/connect-js@^3.3.31":
+  version "3.3.31"
+  resolved "https://registry.yarnpkg.com/@stripe/connect-js/-/connect-js-3.3.31.tgz#9c84e85aa15da4099b1dfb4807bf009663f1eee0"
+  integrity sha512-vjsZbatveSMoceOKZHt4eImmlBQla112OV9+enxcZUC1dGziTl2J2E3iH3n01yx9nu9ziesMJnSh/Y2d62TA/Q==
+
 "@tsconfig/node10@^1.0.7":
   version "1.0.11"
   resolved "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.11.tgz"
@@ -3903,7 +3908,7 @@ internal-slot@^1.1.0:
     hasown "^2.0.2"
     side-channel "^1.1.0"
 
-invariant@^2.2.4:
+invariant@2.2.4, invariant@^2.2.4:
   version "2.2.4"
   resolved "https://registry.npmjs.org/invariant/-/invariant-2.2.4.tgz"
   integrity sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==
@@ -5671,6 +5676,14 @@ react-native-monorepo-config@^0.1.8:
     escape-string-regexp "^5.0.0"
     fast-glob "^3.3.3"
 
+react-native-webview@^13.16.0:
+  version "13.16.0"
+  resolved "https://registry.yarnpkg.com/react-native-webview/-/react-native-webview-13.16.0.tgz#c995148f944a7eaf12389f0e6d5c6f5e6a775686"
+  integrity sha512-Nh13xKZWW35C0dbOskD7OX01nQQavOzHbCw9XoZmar4eXCo7AvrYJ0jlUfRVVIJzqINxHlpECYLdmAdFsl9xDA==
+  dependencies:
+    escape-string-regexp "^4.0.0"
+    invariant "2.2.4"
+
 react-native@^0.78.0:
   version "0.78.0"
   resolved "https://registry.npmjs.org/react-native/-/react-native-0.78.0.tgz"

From 070f198172fc9b9873f9561e063c7f1920a8a3aa Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Tue, 4 Nov 2025 18:43:14 +0100
Subject: [PATCH 02/21] Make react-native-webview optional and load it
 dynamically

---
 .../ConnectAccountOnboardingScreen.tsx        |  5 ++
 .../src/screens/ConnectPaymentsListScreen.tsx |  8 +-
 .../src/screens/ConnectPayoutsListScreen.tsx  |  8 +-
 example/src/screens/ConnectScreen.tsx         |  3 +-
 package.json                                  |  5 +-
 src/connect/EmbeddedComponent.tsx             | 75 +++++++++++--------
 6 files changed, 69 insertions(+), 35 deletions(-)

diff --git a/example/src/screens/ConnectAccountOnboardingScreen.tsx b/example/src/screens/ConnectAccountOnboardingScreen.tsx
index ce688ddfa2..d38f243f58 100644
--- a/example/src/screens/ConnectAccountOnboardingScreen.tsx
+++ b/example/src/screens/ConnectAccountOnboardingScreen.tsx
@@ -1,13 +1,18 @@
 import { ConnectAccountOnboarding } from '@stripe/stripe-react-native';
 import ConnectScreen from './ConnectScreen';
+import { Alert } from 'react-native';
 
 export default function ConnectAccountOnboardingScreen() {
   return (
     <ConnectScreen>
       <ConnectAccountOnboarding
+        style={{ paddingVertical: 16 }}
         onExit={() => {
           console.log('ConnectAccountOnboarding onExit');
         }}
+        onLoadError={(err) => {
+          Alert.alert('Error', err.error.message);
+        }}
       />
     </ConnectScreen>
   );
diff --git a/example/src/screens/ConnectPaymentsListScreen.tsx b/example/src/screens/ConnectPaymentsListScreen.tsx
index fb23c02f56..b6394fa500 100644
--- a/example/src/screens/ConnectPaymentsListScreen.tsx
+++ b/example/src/screens/ConnectPaymentsListScreen.tsx
@@ -1,10 +1,16 @@
 import { ConnectPayments } from '@stripe/stripe-react-native';
 import ConnectScreen from './ConnectScreen';
+import { Alert } from 'react-native';
 
 export default function ConnectPaymentsListScreen() {
   return (
     <ConnectScreen>
-      <ConnectPayments />
+      <ConnectPayments
+        style={{ paddingVertical: 16 }}
+        onLoadError={(err) => {
+          Alert.alert('Error', err.error.message);
+        }}
+      />
     </ConnectScreen>
   );
 }
diff --git a/example/src/screens/ConnectPayoutsListScreen.tsx b/example/src/screens/ConnectPayoutsListScreen.tsx
index 15f173b571..efd4980d47 100644
--- a/example/src/screens/ConnectPayoutsListScreen.tsx
+++ b/example/src/screens/ConnectPayoutsListScreen.tsx
@@ -1,10 +1,16 @@
 import { ConnectPayouts } from '@stripe/stripe-react-native';
 import ConnectScreen from './ConnectScreen';
+import { Alert } from 'react-native';
 
 export default function ConnectPayoutsListScreen() {
   return (
     <ConnectScreen>
-      <ConnectPayouts />
+      <ConnectPayouts
+        style={{ paddingVertical: 16 }}
+        onLoadError={(err) => {
+          Alert.alert('Error', err.error.message);
+        }}
+      />
     </ConnectScreen>
   );
 }
diff --git a/example/src/screens/ConnectScreen.tsx b/example/src/screens/ConnectScreen.tsx
index ef35bcd271..5b7be340ed 100644
--- a/example/src/screens/ConnectScreen.tsx
+++ b/example/src/screens/ConnectScreen.tsx
@@ -34,8 +34,7 @@ const ConnectScreen: React.FC<Props> = ({ children }) => {
 export default ConnectScreen;
 
 const fetchClientSecret = async () => {
-  // TODO: use a different endpoint
-  const response = await fetch(`${API_URL}/create-payment-intent`, {
+  const response = await fetch(`${API_URL}/account_session`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
diff --git a/package.json b/package.json
index 8a4b4c14a4..1f27295cc2 100644
--- a/package.json
+++ b/package.json
@@ -90,11 +90,14 @@
     "expo": ">=46.0.9",
     "react": "*",
     "react-native": "*",
-    "react-native-webview": ">=13.16.0"
+    "react-native-webview": "*"
   },
   "peerDependenciesMeta": {
     "expo": {
       "optional": true
+    },
+    "react-native-webview": {
+      "optional": true
     }
   },
   "jest": {
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index 28161d32e6..b8dafd9c64 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -1,11 +1,24 @@
 import type { LoadError, LoaderStart } from '@stripe/connect-js';
-import React, { useRef } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Platform, StyleProp, ViewStyle } from 'react-native';
-import { WebView } from 'react-native-webview';
+import type { WebView } from 'react-native-webview';
 import { useConnectComponents } from './ConnectComponentsProvider';
 import pjson from '../../package.json';
 
 const DEVELOPMENT_MODE = true;
+const DEVELOPMENT_URL =
+  Platform.OS === 'android' ? 'http://10.0.2.2:3001' : 'http://localhost:3001';
+const PRODUCTION_URL = 'https://connect-js.stripe.com';
+const BASE_URL = DEVELOPMENT_MODE ? DEVELOPMENT_URL : PRODUCTION_URL;
+
+const sdkVersion = pjson.version;
+
+// react-native-webview.html will only load versions in the format X.Y.Z
+if (!/^\d+\.\d+\.\d+$/.test(sdkVersion)) {
+  throw new Error(
+    `Invalid SDK version: ${sdkVersion}. Must be in format X.Y.Z`
+  );
+}
 
 export interface CommonComponentProps {
   onLoaderStart?: ({ elementTagName }: LoaderStart) => void;
@@ -76,6 +89,27 @@ type EmbeddedComponentProps = CommonComponentProps & {
 };
 
 export function EmbeddedComponent(props: EmbeddedComponentProps) {
+  const [dynamicWebview, setDynamicWebview] = useState<{
+    WebView: typeof WebView | null;
+  } | null>(null);
+
+  const loadWebViewComponent = useCallback(async () => {
+    if (dynamicWebview) return;
+
+    setDynamicWebview({ WebView: null });
+
+    try {
+      const mod = await import('react-native-webview');
+      setDynamicWebview({ WebView: mod.WebView });
+    } catch (err) {
+      console.error('Failed to import react-native-webview:', err);
+    }
+  }, [dynamicWebview]);
+
+  useEffect(() => {
+    loadWebViewComponent();
+  }, [loadWebViewComponent]);
+
   const {
     publishableKey,
     fetchClientSecret,
@@ -112,16 +146,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     )
     .join('&');
 
-  const platform = Platform.OS.toLowerCase();
-  const sdkVersion = pjson.version;
-
-  const baseURL = DEVELOPMENT_MODE
-    ? Platform.select({
-        ios: 'http://localhost:3001',
-        android: 'http://10.0.2.2:3001',
-      })
-    : 'https://connect-js.stripe.com';
-  const connectURL = `${baseURL}/v1.0/${platform}_webview.html#${hash}`;
+  const connectURL = `${BASE_URL}/v1.0/react_native_webview.html#${hash}`;
 
   const ref = useRef<WebView>(null);
 
@@ -132,7 +157,6 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     ref.current?.injectJavaScript(`
       (function() {
         window.updateConnectInstance(${JSON.stringify({ appearance })});
-
         true;
       })();
     `);
@@ -180,26 +204,17 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     });
   }
 
+  const WebViewComponent = dynamicWebview?.WebView;
+
+  if (!WebViewComponent) return null;
+
   return (
-    <WebView
+    <WebViewComponent
       ref={ref}
       style={style}
       webviewDebuggingEnabled={DEVELOPMENT_MODE}
       source={{ uri: connectURL }}
-      userAgent={`Mobile - Stripe ReactNative SDK ${Platform.OS}/${Platform.Version} - stripe-${platform}/${sdkVersion}`}
-      injectedJavaScript={`
-        // add a style witn a sans serif font by default
-        (function() {
-          const style = document.createElement('style');
-          style.innerHTML = \`
-            body {
-              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
-                Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
-            }
-          \`;
-          document.head.appendChild(style);
-        })();
-      `}
+      userAgent={`Mobile - Stripe ReactNative SDK ${Platform.OS}/${Platform.Version} - stripe-react_native/${sdkVersion}`}
       injectedJavaScriptObject={{
         initParams: {
           appearance,
@@ -209,16 +224,16 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
         initComponentProps: componentProps,
         appInfo: { applicationId: undefined },
       }}
+      // Fixes injectedJavaScriptObject in Android https://github.com/react-native-webview/react-native-webview/issues/3326#issuecomment-3048111789
+      injectedJavaScriptBeforeContentLoaded={'(function() {})();'}
       onMessage={async (event) => {
         const message = JSON.parse(event.nativeEvent.data) as {
           type: string;
           data?: unknown;
         };
-        console.log('Received message from WebView:', message);
 
         if (message.type === 'fetchClientSecret') {
           const clientSecret = await fetchClientSecret();
-
           ref.current?.injectJavaScript(`
             window.clientSecretDeferred.resolve(${JSON.stringify(
               clientSecret

From e4f2e691856acaa0d26cb7cb13cfec645d9eff0e Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Tue, 4 Nov 2025 21:29:30 +0100
Subject: [PATCH 03/21] Extract types from @stripe/connect-js

---
 package.json                              |   1 -
 src/connect/Components.tsx                |   2 +-
 src/connect/ConnectComponentsProvider.tsx |   2 +-
 src/connect/EmbeddedComponent.tsx         |   4 +-
 src/connect/connectTypes.ts               | 602 ++++++++++++++++++++++
 yarn.lock                                 |   5 -
 6 files changed, 606 insertions(+), 10 deletions(-)
 create mode 100644 src/connect/connectTypes.ts

diff --git a/package.json b/package.json
index 1f27295cc2..c9899a0062 100644
--- a/package.json
+++ b/package.json
@@ -70,7 +70,6 @@
     "@expo/config-plugins": "^9.0.16",
     "@react-native/babel-preset": "^0.78.0",
     "@react-native/eslint-config": "^0.78.0",
-    "@stripe/connect-js": "^3.3.31",
     "@types/jest": "^29.5.14",
     "@types/react": "^19.0.10",
     "eslint": "^8.57.0",
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
index c5670c3d64..7a92fb73b9 100644
--- a/src/connect/Components.tsx
+++ b/src/connect/Components.tsx
@@ -2,7 +2,7 @@ import type {
   CollectionOptions,
   PaymentsListDefaultFilters,
   StepChange,
-} from '@stripe/connect-js';
+} from './connectTypes';
 import React, { useMemo } from 'react';
 import { CommonComponentProps, EmbeddedComponent } from './EmbeddedComponent';
 
diff --git a/src/connect/ConnectComponentsProvider.tsx b/src/connect/ConnectComponentsProvider.tsx
index 1e3e486909..5c9be6873e 100644
--- a/src/connect/ConnectComponentsProvider.tsx
+++ b/src/connect/ConnectComponentsProvider.tsx
@@ -1,5 +1,5 @@
 import React, { JSX, useMemo } from 'react';
-import type { IStripeConnectInitParams } from '@stripe/connect-js';
+import type { IStripeConnectInitParams } from './connectTypes';
 
 type ConnectComponentsPayload = {
   publishableKey: string;
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index b8dafd9c64..82a86e410c 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -1,11 +1,11 @@
-import type { LoadError, LoaderStart } from '@stripe/connect-js';
+import type { LoadError, LoaderStart } from './connectTypes';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Platform, StyleProp, ViewStyle } from 'react-native';
 import type { WebView } from 'react-native-webview';
 import { useConnectComponents } from './ConnectComponentsProvider';
 import pjson from '../../package.json';
 
-const DEVELOPMENT_MODE = true;
+const DEVELOPMENT_MODE = false;
 const DEVELOPMENT_URL =
   Platform.OS === 'android' ? 'http://10.0.2.2:3001' : 'http://localhost:3001';
 const PRODUCTION_URL = 'https://connect-js.stripe.com';
diff --git a/src/connect/connectTypes.ts b/src/connect/connectTypes.ts
new file mode 100644
index 0000000000..7dcefd415a
--- /dev/null
+++ b/src/connect/connectTypes.ts
@@ -0,0 +1,602 @@
+// Types copied from @stripe/connect-js 3.3.31
+
+export type LoaderStart = {
+  elementTagName: string;
+};
+
+export type LoadError = {
+  elementTagName: string;
+  error: EmbeddedError;
+};
+
+export type StepChange = {
+  step: string;
+};
+
+export type EmbeddedError = {
+  type: EmbeddedErrorType;
+  message?: string;
+};
+
+export type EmbeddedErrorType =
+  /**
+   * Failure to connect to Stripe's API.
+   */
+  | 'api_connection_error'
+  /**
+   * Failure to perform the authentication flow within Connect Embedded Components
+   */
+  | 'authentication_error'
+  /**
+   * Account session create failed
+   */
+  | 'account_session_create_error'
+  /**
+   * Request failed with an 4xx status code, typically caused by platform configuration issues
+   */
+  | 'invalid_request_error'
+  /**
+   * Too many requests hit the API too quickly.
+   */
+  | 'rate_limit_error'
+  /**
+   * API errors covering any other type of problem (e.g., a temporary problem with Stripe's servers), and are extremely uncommon.
+   */
+  | 'api_error';
+
+export type Status =
+  | 'blocked'
+  | 'canceled'
+  | 'disputed'
+  | 'early_fraud_warning'
+  | 'failed'
+  | 'incomplete'
+  | 'partially_refunded'
+  | 'pending'
+  | 'refund_pending'
+  | 'refunded'
+  | 'successful'
+  | 'uncaptured';
+
+export type PaymentMethod =
+  | 'ach_credit_transfer'
+  | 'ach_debit'
+  | 'acss_debit'
+  | 'affirm'
+  | 'afterpay_clearpay'
+  | 'alipay'
+  | 'alma'
+  | 'amazon_pay'
+  | 'amex_express_checkout'
+  | 'android_pay'
+  | 'apple_pay'
+  | 'au_becs_debit'
+  | 'nz_bank_account'
+  | 'bancontact'
+  | 'bacs_debit'
+  | 'bitcoin_source'
+  | 'bitcoin'
+  | 'blik'
+  | 'boleto'
+  | 'boleto_pilot'
+  | 'card_present'
+  | 'card'
+  | 'cashapp'
+  | 'crypto'
+  | 'customer_balance'
+  | 'demo_pay'
+  | 'dummy_passthrough_card'
+  | 'gbp_credit_transfer'
+  | 'google_pay'
+  | 'eps'
+  | 'fpx'
+  | 'giropay'
+  | 'grabpay'
+  | 'ideal'
+  | 'id_bank_transfer'
+  | 'id_credit_transfer'
+  | 'jp_credit_transfer'
+  | 'interac_present'
+  | 'kakao_pay'
+  | 'klarna'
+  | 'konbini'
+  | 'kr_card'
+  | 'kr_market'
+  | 'link'
+  | 'masterpass'
+  | 'mb_way'
+  | 'meta_pay'
+  | 'multibanco'
+  | 'mobilepay'
+  | 'naver_pay'
+  | 'netbanking'
+  | 'ng_bank'
+  | 'ng_bank_transfer'
+  | 'ng_card'
+  | 'ng_market'
+  | 'ng_ussd'
+  | 'vipps'
+  | 'oxxo'
+  | 'p24'
+  | 'payto'
+  | 'pay_by_bank'
+  | 'paper_check'
+  | 'payco'
+  | 'paynow'
+  | 'paypal'
+  | 'pix'
+  | 'promptpay'
+  | 'revolut_pay'
+  | 'samsung_pay'
+  | 'sepa_credit_transfer'
+  | 'sepa_debit'
+  | 'sofort'
+  | 'south_korea_market'
+  | 'swish'
+  | 'three_d_secure'
+  | 'three_d_secure_2'
+  | 'three_d_secure_2_eap'
+  | 'twint'
+  | 'upi'
+  | 'us_bank_account'
+  | 'visa_checkout'
+  | 'wechat'
+  | 'wechat_pay'
+  | 'zip';
+
+export type PaymentsListDefaultFilters = {
+  amount?:
+    | { equals: number }
+    | { greaterThan: number }
+    | { lessThan: number }
+    | { between: { lowerBound: number; upperBound: number } };
+  date?:
+    | { before: Date }
+    | { after: Date }
+    | { between: { start: Date; end: Date } };
+  status?: Array<Status>;
+  paymentMethod?: PaymentMethod;
+};
+
+export type CollectionOptions = {
+  fields: 'currently_due' | 'eventually_due';
+  futureRequirements?: 'omit' | 'include';
+  requirements?:
+    | {
+        only: string[];
+      }
+    | {
+        exclude: string[];
+      };
+};
+
+/**
+ * Initialization parameters for Connect JS. See https://stripe.com/docs/connect/get-started-connect-embedded-components#configuring-connect-js for more details.
+ */
+export interface IStripeConnectInitParams {
+  /**
+   * The publishable key for the connected account.
+   */
+  publishableKey: string;
+
+  /**
+   * Function that fetches client secret
+   * @returns A promise that resolves with a new client secret.
+   */
+  fetchClientSecret: () => Promise<string>;
+
+  /**
+   * Appearance options for the Connect instance.
+   * @see https://stripe.com/docs/connect/customize-connect-embedded-components
+   */
+  appearance?: AppearanceOptions;
+
+  /**
+   * The locale to use for the Connect instance.
+   */
+  locale?: string;
+
+  /**
+   * An array of custom fonts, which embedded components created from a ConnectInstance can use.
+   */
+  fonts?: Array<CssFontSource | CustomFontSource>;
+}
+
+/**
+ * Appearance options for the Connect instance.
+ */
+export declare type AppearanceOptions = {
+  /**
+   * The type of overlay used throughout the Connect.js design system. Set this to be either a Dialog or Drawer.
+   */
+  overlays?: OverlayOption;
+  variables?: AppearanceVariables;
+};
+
+export declare type AppearanceVariables = {
+  // Commonly used
+
+  /**
+   * The font family value used throughout embedded components. If an embedded component inherits a font-family value from an element on your site in which it’s placed, this setting overrides that inheritance.
+   */
+  fontFamily?: string;
+
+  /**
+   * The baseline font size set on the embedded component root. This scales the value of other font size variables. This supports pixel values only ranging from 1px to 40px, 0.1em to 4em, and 0.1rem to 4rem.
+   */
+  fontSizeBase?: string;
+
+  /**
+   * The base spacing unit that derives all spacing values. Increase or decrease this value to make your layout more or less spacious. This supports pixel values only ranging from 8px to 20px.
+   */
+  spacingUnit?: string;
+
+  /**
+   * The general border radius used in embedded components. This sets the default border radius for all components. This supports pixel values only, with a maximum value of 24px.
+   */
+  borderRadius?: string;
+
+  /**
+   * The primary color used throughout embedded components. Set this to your primary brand color. This accepts hex values or RGB/HSL strings.
+   */
+  colorPrimary?: string;
+
+  /**
+   * The background color for embedded components, including overlays, tooltips, and popovers. This accepts hex values or RGB/HSL strings.
+   */
+  colorBackground?: string;
+
+  /**
+   * The color used for regular text. This accepts hex values or RGB/HSL strings.
+   */
+  colorText?: string;
+
+  /**
+   * The color used to indicate errors or destructive actions. This accepts hex values or RGB/HSL strings.
+   */
+  colorDanger?: string;
+
+  // Less commonly used
+
+  // Primary Button
+  /**
+   * The color used as a background for primary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonPrimaryColorBackground?: string;
+  /**
+   * The border color used for primary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonPrimaryColorBorder?: string;
+  /**
+   * The text color used for primary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonPrimaryColorText?: string;
+
+  // Secondary Button
+  /**
+   * The color used as a background for secondary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonSecondaryColorBackground?: string;
+  /**
+   * The color used as a border for secondary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonSecondaryColorBorder?: string;
+  /**
+   * The text color used for secondary buttons. This accepts hex values or RGB/HSL strings.
+   */
+  buttonSecondaryColorText?: string;
+
+  /**
+   * The color used for secondary text. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  colorSecondaryText?: string;
+  /**
+   * The color used for primary actions and links. This accepts hex values or RGB/HSL strings.
+   */
+  actionPrimaryColorText?: string;
+  /**
+   * The line type used for text decoration of primary actions and links. This accepts a valid text decoration line value.
+   */
+  actionPrimaryTextDecorationLine?: string;
+  /**
+   * The color used for text decoration of primary actions and links. This accepts hex values or RGB/HSL strings.
+   */
+  actionPrimaryTextDecorationColor?: string;
+  /**
+   * The style of text decoration of primary actions and links. This accepts a valid text decoration style value.
+   */
+  actionPrimaryTextDecorationStyle?: string;
+  /**
+   * The thickness of text decoration of primary actions and links. This accepts a valid text decoration thickness value.
+   */
+  actionPrimaryTextDecorationThickness?: string;
+  /**
+   * The color used for secondary actions and links. This accepts hex values or RGB/HSL strings.
+   */
+  actionSecondaryColorText?: string;
+  /**
+   * The line type used for text decoration of secondary actions and links. This accepts a valid text decoration line value.
+   */
+  actionSecondaryTextDecorationLine?: string;
+  /**
+   * The color used for text decoration of secondary actions and links. This accepts hex values or RGB/HSL strings.
+   */
+  actionSecondaryTextDecorationColor?: string;
+  /**
+   * The style of text decoration of secondary actions and links. This accepts a valid text decoration style value.
+   */
+  actionSecondaryTextDecorationStyle?: string;
+  /**
+   * The thickness of text decoration of secondary actions and links. This accepts a valid text decoration thickness value.
+   */
+  actionSecondaryTextDecorationThickness?: string;
+
+  // Neutral Badge Colors
+  /**
+   * The background color used to represent neutral state or lack of state in status badges. This accepts hex values or RGB/HSL strings.
+   */
+  badgeNeutralColorBackground?: string;
+  /**
+   * The text color used to represent neutral state or lack of state in status badges. This accepts hex values or RGB/HSL strings.
+   */
+  badgeNeutralColorText?: string;
+  /**
+   * The border color used to represent neutral state or lack of state in status badges. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  badgeNeutralColorBorder?: string;
+
+  // Success Badge Colors
+  /**
+   * The background color used to reinforce a successful outcome in status badges. This accepts hex values or RGB/HSL strings.
+   */
+  badgeSuccessColorBackground?: string;
+  /**
+   * The text color used to reinforce a successful outcome in status badges. This accepts hex values or RGB/HSL strings.
+   */
+  badgeSuccessColorText?: string;
+  /**
+   * The border color used to reinforce a successful outcome in status badges. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  badgeSuccessColorBorder?: string;
+
+  // Warning Badge Colors
+  /**
+   * The background color used in status badges to highlight things that might require action, but are optional to resolve. This accepts hex values or RGB/HSL strings.
+   */
+  badgeWarningColorBackground?: string;
+  /**
+   * The text color used in status badges to highlight things that might require action, but are optional to resolve. This accepts hex values or RGB/HSL strings.
+   */
+  badgeWarningColorText?: string;
+  /**
+   * The border color used in status badges to highlight things that might require action, but are optional to resolve. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  badgeWarningColorBorder?: string;
+
+  // Danger Badge Colors
+  /**
+   * The background color used in status badges for high-priority, critical situations that the user must address immediately, and to indicate failed or unsuccessful outcomes. This accepts hex values or RGB/HSL strings.
+   */
+  badgeDangerColorBackground?: string;
+  /**
+   * The text color used in status badges for high-priority, critical situations that the user must address immediately, and to indicate failed or unsuccessful outcomes. This accepts hex values or RGB/HSL strings.
+   */
+  badgeDangerColorText?: string;
+  /**
+   * The border color used in status badges for high-priority, critical situations that the user must address immediately, and to indicate failed or unsuccessful outcomes. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  badgeDangerColorBorder?: string;
+
+  // Background
+  /**
+   * The background color used when highlighting information, like the selected row on a table or particular piece of UI. This accepts hex values or RGB/HSL strings.
+   */
+  offsetBackgroundColor?: string;
+  /**
+   * The background color used for form items. This accepts hex values or RGB/HSL strings.
+   */
+  formBackgroundColor?: string;
+
+  /**
+   * The color used for borders throughout the component. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  colorBorder?: string;
+
+  // Form
+  /**
+   * The color used to highlight form items when focused. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  formHighlightColorBorder?: string;
+  /**
+   * The color used for to fill in form items like checkboxes, radio buttons and switches. This accepts hex values or RGB/HSL strings.
+   */
+  formAccentColor?: string;
+
+  // Border Sizing
+  /**
+   * The border radius used for buttons. This supports pixel values only.
+   */
+  buttonBorderRadius?: string;
+  /**
+   * The border radius used for form elements. This supports pixel values only, with a maximum value of 24px.
+   */
+  formBorderRadius?: string;
+  /**
+   * The border radius used for badges. This supports pixel values only, with a maximum value of 24px.
+   */
+  badgeBorderRadius?: string;
+  /**
+   * The border radius used for overlays. This supports pixel values only, with a maximum value of 24px.
+   */
+  overlayBorderRadius?: string;
+
+  // Font Sizing
+
+  // Overlay
+  /**
+   * A z-index to use for the overlay throughout embedded components. Set this number to control the z-order of the overlay.
+   */
+  overlayZIndex?: number;
+  /**
+   * The backdrop color when an overlay is opened. This accepts hex values or RGB/RGBA/HSL strings.
+   */
+  overlayBackdropColor?: string;
+
+  // Body Typography
+  /**
+   * The font size for the medium body typography. Body typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  bodyMdFontSize?: string;
+  /**
+   * The font weight for the medium body typography. Body typography variables accept a valid font weight value.
+   */
+  bodyMdFontWeight?: string;
+  /**
+   * The font size for the small body typography. Body typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  bodySmFontSize?: string;
+  /**
+   * The font weight for the small body typography. Body typography variables accept a valid font weight value.
+   */
+  bodySmFontWeight?: string;
+
+  // Heading Typography
+  /**
+   * The font size for the extra large heading typography. Heading typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  headingXlFontSize?: string;
+  /**
+   * The font weight for the extra large heading typography. Heading typography variables accept a valid font weight value.
+   */
+  headingXlFontWeight?: string;
+  /**
+   * The text transform for the extra large heading typography. Heading typography variables accept a valid text transform value.
+   */
+  headingXlTextTransform?: string;
+  /**
+   * The font size for the large heading typography. Heading typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  headingLgFontSize?: string;
+  /**
+   * The font weight for the large heading typography. Heading typography variables accept a valid font weight value.
+   */
+  headingLgFontWeight?: string;
+  /**
+   * The text transform for the large heading typography. Heading typography variables accept a valid text transform value.
+   */
+  headingLgTextTransform?: string;
+  /**
+   * The font size for the medium heading typography. Heading typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  headingMdFontSize?: string;
+  /**
+   * The font weight for the medium heading typography. Heading typography variables accept a valid font weight value.
+   */
+  headingMdFontWeight?: string;
+  /**
+   * The text transform for the medium heading typography. Heading typography variables accept a valid text transform value.
+   */
+  headingMdTextTransform?: string;
+  /**
+   * The font size for the small heading typography. Heading typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  headingSmFontSize?: string;
+  /**
+   * The font weight for the small heading typography. Heading typography variables accept a valid font weight value.
+   */
+  headingSmFontWeight?: string;
+  /**
+   * The text transform for the small heading typography. Heading typography variables accept a valid text transform value.
+   */
+  headingSmTextTransform?: string;
+  /**
+   * The font size for the extra small heading typography. Heading typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  headingXsFontSize?: string;
+  /**
+   * The font weight for the extra small heading typography. Heading typography variables accept a valid font weight value.
+   */
+  headingXsFontWeight?: string;
+  /**
+   * The text transform for the extra small heading typography. Heading typography variables accept a valid text transform value.
+   */
+  headingXsTextTransform?: string;
+
+  // Label Typography
+  /**
+   * The font size for the medium label typography. Label typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  labelMdFontSize?: string;
+  /**
+   * The font weight for the medium label typography. Label typography variables accept a valid font weight value.
+   */
+  labelMdFontWeight?: string;
+  /**
+   * The text transform for the medium label typography. Label typography variables accept a valid text transform value.
+   */
+  labelMdTextTransform?: string;
+  /**
+   * The font size for the small label typography. Label typography variables accept a valid font size value ranging from 1px to 200px, 0.1em to 12em, and 0.1rem to 12rem.
+   */
+  labelSmFontSize?: string;
+  /**
+   * The font weight for the small label typography. Label typography variables accept a valid font weight value.
+   */
+  labelSmFontWeight?: string;
+  /**
+   * The text transform for the small label typography. Label typography variables accept a valid text transform value.
+   */
+  labelSmTextTransform?: string;
+};
+
+/*
+ * Use a `CssFontSource` to pass custom fonts via a stylesheet URL when initializing a Connect instance.
+ */
+export declare type CssFontSource = {
+  /**
+   * A relative or absolute URL pointing to a CSS file with [@font-face](https://developer.mozilla.org/en/docs/Web/CSS/@font-face) definitions, for example:
+   *
+   *     https://fonts.googleapis.com/css?family=Open+Sans
+   *
+   * Note that if you are using a [content security policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (CSP), [additional directives](https://stripe.com/docs/security#content-security-policy) may be necessary.
+   */
+  cssSrc: string;
+};
+
+/*
+ * Use a `CustomFontSource` to pass custom fonts when initializing a Connect instance.
+ */
+export declare type CustomFontSource = {
+  /**
+   * The name to give the font
+   */
+  family: string;
+
+  /**
+   * A valid [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src) value pointing to your custom font file.
+   * This is usually (though not always) a link to a file with a `.woff` , `.otf`, or `.svg` suffix.
+   */
+  src: string;
+
+  /**
+   * A valid [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) value.
+   */
+  display?: string;
+
+  /**
+   * Defaults to `normal`.
+   */
+  style?: 'normal' | 'italic' | 'oblique';
+
+  /**
+   * A valid [unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range) value.
+   */
+  unicodeRange?: string;
+
+  /**
+   * A valid [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight), as a string.
+   */
+  weight?: string;
+};
+
+export declare type OverlayOption = 'dialog' | 'drawer';
diff --git a/yarn.lock b/yarn.lock
index 396ad661fc..db4c01bada 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1776,11 +1776,6 @@
   dependencies:
     "@sinonjs/commons" "^3.0.0"
 
-"@stripe/connect-js@^3.3.31":
-  version "3.3.31"
-  resolved "https://registry.yarnpkg.com/@stripe/connect-js/-/connect-js-3.3.31.tgz#9c84e85aa15da4099b1dfb4807bf009663f1eee0"
-  integrity sha512-vjsZbatveSMoceOKZHt4eImmlBQla112OV9+enxcZUC1dGziTl2J2E3iH3n01yx9nu9ziesMJnSh/Y2d62TA/Q==
-
 "@tsconfig/node10@^1.0.7":
   version "1.0.11"
   resolved "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.11.tgz"

From c32af78a8f0a6718ac75607617aa6193170c7992 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Wed, 5 Nov 2025 14:56:25 +0100
Subject: [PATCH 04/21] Custom font

---
 example/src/screens/ConnectScreen.tsx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/example/src/screens/ConnectScreen.tsx b/example/src/screens/ConnectScreen.tsx
index 5b7be340ed..5da9bf3e20 100644
--- a/example/src/screens/ConnectScreen.tsx
+++ b/example/src/screens/ConnectScreen.tsx
@@ -25,6 +25,12 @@ const ConnectScreen: React.FC<Props> = ({ children }) => {
     <ConnectComponentsProvider
       publishableKey={publishableKey}
       fetchClientSecret={fetchClientSecret}
+      appearance={{
+        variables: {
+          fontFamily:
+            "-apple-system, 'system-ui', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'",
+        },
+      }}
     >
       {children}
     </ConnectComponentsProvider>

From 8f4d6018794d787576e00e485ebe8e8ed0679dac Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Wed, 12 Nov 2025 10:49:02 +0100
Subject: [PATCH 05/21] Use a modal for the onboarding component

---
 .../ConnectAccountOnboardingScreen.tsx        | 44 ++++++---
 src/connect/Components.tsx                    | 90 ++++++++++++++++---
 src/connect/EmbeddedComponent.tsx             |  6 +-
 src/connect/ModalCloseButton.tsx              | 50 +++++++++++
 4 files changed, 163 insertions(+), 27 deletions(-)
 create mode 100644 src/connect/ModalCloseButton.tsx

diff --git a/example/src/screens/ConnectAccountOnboardingScreen.tsx b/example/src/screens/ConnectAccountOnboardingScreen.tsx
index d38f243f58..8d61e55d1c 100644
--- a/example/src/screens/ConnectAccountOnboardingScreen.tsx
+++ b/example/src/screens/ConnectAccountOnboardingScreen.tsx
@@ -1,19 +1,43 @@
 import { ConnectAccountOnboarding } from '@stripe/stripe-react-native';
+import { Alert, StyleSheet, View } from 'react-native';
 import ConnectScreen from './ConnectScreen';
-import { Alert } from 'react-native';
+import { useState } from 'react';
+import Button from '../components/Button';
+import { colors } from '../colors';
 
 export default function ConnectAccountOnboardingScreen() {
+  const [visible, setVisible] = useState(false);
+
   return (
     <ConnectScreen>
-      <ConnectAccountOnboarding
-        style={{ paddingVertical: 16 }}
-        onExit={() => {
-          console.log('ConnectAccountOnboarding onExit');
-        }}
-        onLoadError={(err) => {
-          Alert.alert('Error', err.error.message);
-        }}
-      />
+      <View style={styles.container}>
+        <Button
+          variant="primary"
+          title="Show Onboarding"
+          onPress={() => setVisible(true)}
+        />
+
+        {visible ? (
+          <ConnectAccountOnboarding
+            onExit={() => {
+              console.log('ConnectAccountOnboarding onExit');
+              setVisible(false);
+            }}
+            onLoadError={(err) => {
+              Alert.alert('Error', err.error.message);
+            }}
+          />
+        ) : null}
+      </View>
     </ConnectScreen>
   );
 }
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: colors.white,
+    paddingTop: 20,
+    paddingHorizontal: 16,
+  },
+});
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
index 7a92fb73b9..f67d751a44 100644
--- a/src/connect/Components.tsx
+++ b/src/connect/Components.tsx
@@ -1,10 +1,19 @@
 import type {
   CollectionOptions,
+  LoaderStart,
   PaymentsListDefaultFilters,
   StepChange,
 } from './connectTypes';
-import React, { useMemo } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 import { CommonComponentProps, EmbeddedComponent } from './EmbeddedComponent';
+import {
+  Modal,
+  SafeAreaView,
+  View,
+  StyleSheet,
+  ActivityIndicator,
+} from 'react-native';
+import ModalCloseButton from './ModalCloseButton';
 
 export function ConnectAccountOnboarding({
   onExit,
@@ -16,7 +25,6 @@ export function ConnectAccountOnboarding({
   onLoaderStart,
   onLoadError,
   onPageDidLoad,
-  style,
 }: {
   onExit: () => void;
   onStepChange?: (stepChange: StepChange) => void;
@@ -24,7 +32,10 @@ export function ConnectAccountOnboarding({
   fullTermsOfServiceUrl?: string;
   privacyPolicyUrl?: string;
   collectionOptions?: CollectionOptions;
-} & CommonComponentProps) {
+} & Omit<CommonComponentProps, 'style'>) {
+  const [visible, setVisible] = useState(true);
+  const [loading, setLoading] = useState(true);
+
   const componentProps = useMemo(() => {
     return {
       setFullTermsOfServiceUrl: fullTermsOfServiceUrl,
@@ -39,23 +50,50 @@ export function ConnectAccountOnboarding({
     collectionOptions,
   ]);
 
+  const onExitCallback = useCallback(() => {
+    setVisible(false);
+    onExit();
+  }, [onExit]);
+
   const callbacks = useMemo(() => {
     return {
-      onExit,
+      onExit: onExitCallback,
       onStepChange,
     };
-  }, [onExit, onStepChange]);
+  }, [onExitCallback, onStepChange]);
+
+  const onLoaderStartCallback = useCallback(
+    (event: LoaderStart) => {
+      setLoading(false);
+      if (onLoaderStart) {
+        onLoaderStart(event);
+      }
+    },
+    [onLoaderStart]
+  );
 
   return (
-    <EmbeddedComponent
-      component="account-onboarding"
-      componentProps={componentProps}
-      onLoaderStart={onLoaderStart}
-      onLoadError={onLoadError}
-      onPageDidLoad={onPageDidLoad}
-      callbacks={callbacks}
-      style={style}
-    />
+    <Modal visible={visible} animationType="slide">
+      <SafeAreaView style={styles.flex1}>
+        <View style={styles.navBar}>
+          <ModalCloseButton onPress={onExitCallback} />
+        </View>
+        <View style={styles.onboardingWrapper}>
+          {loading ? (
+            <ActivityIndicator size="large" style={styles.activityIndicator} />
+          ) : null}
+          <EmbeddedComponent
+            component="account-onboarding"
+            componentProps={componentProps}
+            onLoaderStart={onLoaderStartCallback}
+            onLoadError={onLoadError}
+            onPageDidLoad={onPageDidLoad}
+            callbacks={callbacks}
+            style={styles.flex1}
+          />
+        </View>
+      </SafeAreaView>
+    </Modal>
   );
 }
 
@@ -138,3 +176,27 @@ export function ConnectPaymentDetails({
     />
   );
 }
+
+const styles = StyleSheet.create({
+  navBar: {
+    height: 56,
+    paddingHorizontal: 8,
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    borderBottomWidth: StyleSheet.hairlineWidth,
+  },
+  flex1: {
+    flex: 1,
+  },
+  activityIndicator: {
+    zIndex: 1,
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 48,
+  },
+  onboardingWrapper: {
+    position: 'relative',
+    flex: 1,
+  },
+});
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index 82a86e410c..2902f89313 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -1,9 +1,9 @@
-import type { LoadError, LoaderStart } from './connectTypes';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Platform, StyleProp, ViewStyle } from 'react-native';
 import type { WebView } from 'react-native-webview';
-import { useConnectComponents } from './ConnectComponentsProvider';
 import pjson from '../../package.json';
+import { useConnectComponents } from './ConnectComponentsProvider';
+import type { LoadError, LoaderStart } from './connectTypes';
 
 const DEVELOPMENT_MODE = false;
 const DEVELOPMENT_URL =
@@ -249,7 +249,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
         } else if (message.type === 'openFinancialConnections') {
           // message.data is of type {clientSecret: string; id: string; connectedAccountId: string;}
         } else if (message.type === 'closeWebView') {
-          console.log('closeWebView');
+          // message.data is empty
         } else if (message.type === 'callSupplementalFunction') {
           console.log('message:', message);
           // message.data is of type {[key]: {functionName: string; args: unknown[]; invocationId: string;}}
diff --git a/src/connect/ModalCloseButton.tsx b/src/connect/ModalCloseButton.tsx
new file mode 100644
index 0000000000..087529fadc
--- /dev/null
+++ b/src/connect/ModalCloseButton.tsx
@@ -0,0 +1,50 @@
+import React from 'react';
+import { TouchableOpacity, Text, StyleSheet } from 'react-native';
+
+const size = 36;
+const color = '#333';
+const bg = 'transparent';
+const accessibilityLabel = 'Close';
+
+const hitSlop = { top: 10, bottom: 10, left: 10, right: 10 };
+
+interface ModalCloseButtonProps {
+  onPress: () => void;
+}
+
+export default function ModalCloseButton({ onPress }: ModalCloseButtonProps) {
+  return (
+    <TouchableOpacity
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      hitSlop={hitSlop}
+      style={[
+        styles.button,
+        {
+          width: size,
+          height: size,
+          borderRadius: size / 2,
+          backgroundColor: bg,
+        },
+      ]}
+      activeOpacity={0.7}
+    >
+      <Text style={[styles.cross, { color, fontSize: Math.round(size * 0.6) }]}>
+        ×
+      </Text>
+    </TouchableOpacity>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  cross: {
+    lineHeight: undefined,
+    includeFontPadding: false,
+    textAlign: 'center',
+  },
+});

From 5ea7e9b832503306396d89082c641b01dffb5a44 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Wed, 12 Nov 2025 11:07:45 +0100
Subject: [PATCH 06/21] Update podfile.lcok

---
 example/ios/Podfile.lock | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
index ae906aea0a..467b18e698 100644
--- a/example/ios/Podfile.lock
+++ b/example/ios/Podfile.lock
@@ -1304,6 +1304,27 @@ PODS:
     - ReactCommon/turbomodule/bridging
     - ReactCommon/turbomodule/core
     - Yoga
+  - react-native-webview (13.16.0):
+    - DoubleConversion
+    - glog
+    - hermes-engine
+    - RCT-Folly (= 2024.11.18.00)
+    - RCTRequired
+    - RCTTypeSafety
+    - React-Core
+    - React-debug
+    - React-Fabric
+    - React-featureflags
+    - React-graphics
+    - React-ImageManager
+    - React-NativeModulesApple
+    - React-RCTFabric
+    - React-rendererdebug
+    - React-utils
+    - ReactCodegen
+    - ReactCommon/turbomodule/bridging
+    - ReactCommon/turbomodule/core
+    - Yoga
   - React-NativeModulesApple (0.78.0):
     - glog
     - hermes-engine
@@ -1838,6 +1859,7 @@ DEPENDENCIES:
   - React-Mapbuffer (from `../node_modules/react-native/ReactCommon`)
   - React-microtasksnativemodule (from `../node_modules/react-native/ReactCommon/react/nativemodule/microtasks`)
   - react-native-safe-area-context (from `../node_modules/react-native-safe-area-context`)
+  - react-native-webview (from `../node_modules/react-native-webview`)
   - React-NativeModulesApple (from `../node_modules/react-native/ReactCommon/react/nativemodule/core/platform/ios`)
   - React-perflogger (from `../node_modules/react-native/ReactCommon/reactperflogger`)
   - React-performancetimeline (from `../node_modules/react-native/ReactCommon/react/performance/timeline`)
@@ -1965,6 +1987,8 @@ EXTERNAL SOURCES:
     :path: "../node_modules/react-native/ReactCommon/react/nativemodule/microtasks"
   react-native-safe-area-context:
     :path: "../node_modules/react-native-safe-area-context"
+  react-native-webview:
+    :path: "../node_modules/react-native-webview"
   React-NativeModulesApple:
     :path: "../node_modules/react-native/ReactCommon/react/nativemodule/core/platform/ios"
   React-perflogger:
@@ -2075,6 +2099,7 @@ SPEC CHECKSUMS:
   React-Mapbuffer: 3c11cee7737609275c7b66bd0b1de475f094cedf
   React-microtasksnativemodule: 843f352b32aacbe13a9c750190d34df44c3e6c2c
   react-native-safe-area-context: 7e513d737b0b5c1d10bbe0e5fcc9f925a7be144c
+  react-native-webview: b729d1bcf8fbd141237355dcfd6bb65b9a1d3b1a
   React-NativeModulesApple: 88433b6946778bea9c153e27b671de15411bf225
   React-perflogger: 9e8d3c0dc0194eb932162812a168aa5dc662f418
   React-performancetimeline: 5a2d6efef52bdcefac079c7baa30934978acd023

From e62cd9881c4cb361043b3a332c01852c5f00f3ff Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Wed, 12 Nov 2025 12:50:32 +0100
Subject: [PATCH 07/21] Hide "overrides" from public interface

---
 src/connect/ConnectComponentsProvider.tsx |  3 +--
 src/connect/EmbeddedComponent.tsx         | 33 ++++++++++++++++-------
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/src/connect/ConnectComponentsProvider.tsx b/src/connect/ConnectComponentsProvider.tsx
index 5c9be6873e..763c6a65e0 100644
--- a/src/connect/ConnectComponentsProvider.tsx
+++ b/src/connect/ConnectComponentsProvider.tsx
@@ -1,13 +1,12 @@
 import React, { JSX, useMemo } from 'react';
 import type { IStripeConnectInitParams } from './connectTypes';
 
-type ConnectComponentsPayload = {
+export type ConnectComponentsPayload = {
   publishableKey: string;
   fetchClientSecret: IStripeConnectInitParams['fetchClientSecret'];
   appearance?: IStripeConnectInitParams['appearance'];
   locale?: IStripeConnectInitParams['locale'];
   fonts?: IStripeConnectInitParams['fonts'];
-  overrides?: Record<string, string>;
 };
 
 const ConnectComponentsContext =
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index 2902f89313..ac7a2c2e5f 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -1,8 +1,17 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { Platform, StyleProp, ViewStyle } from 'react-native';
 import type { WebView } from 'react-native-webview';
 import pjson from '../../package.json';
-import { useConnectComponents } from './ConnectComponentsProvider';
+import {
+  ConnectComponentsPayload,
+  useConnectComponents,
+} from './ConnectComponentsProvider';
 import type { LoadError, LoaderStart } from './connectTypes';
 
 const DEVELOPMENT_MODE = false;
@@ -88,6 +97,10 @@ type EmbeddedComponentProps = CommonComponentProps & {
   callbacks?: Record<string, ((data: any) => void) | undefined>;
 };
 
+type ConnectComponentsPayloadInternal = ConnectComponentsPayload & {
+  overrides?: Record<string, string>;
+};
+
 export function EmbeddedComponent(props: EmbeddedComponentProps) {
   const [dynamicWebview, setDynamicWebview] = useState<{
     WebView: typeof WebView | null;
@@ -117,7 +130,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     locale,
     fonts,
     overrides,
-  } = useConnectComponents();
+  } = useConnectComponents() as ConnectComponentsPayloadInternal;
 
   const {
     component,
@@ -147,10 +160,11 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     .join('&');
 
   const connectURL = `${BASE_URL}/v1.0/react_native_webview.html#${hash}`;
+  const source = useMemo(() => ({ uri: connectURL }), [connectURL]);
 
   const ref = useRef<WebView>(null);
 
-  const [prevAppearance, setPrevAppearance] = React.useState(appearance);
+  const [prevAppearance, setPrevAppearance] = useState(appearance);
   if (prevAppearance !== appearance) {
     setPrevAppearance(appearance);
 
@@ -162,7 +176,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     `);
   }
 
-  const [prevLocale, setPrevLocale] = React.useState(locale);
+  const [prevLocale, setPrevLocale] = useState(locale);
   if (prevLocale !== locale) {
     setPrevLocale(locale);
 
@@ -174,7 +188,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     `);
   }
 
-  const [prevFonts, setPrevFonts] = React.useState(fonts);
+  const [prevFonts, setPrevFonts] = useState(fonts);
   if (prevFonts !== fonts) {
     setPrevFonts(fonts);
 
@@ -186,8 +200,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     `);
   }
 
-  const [prevComponentProps, setPrevComponentProps] =
-    React.useState(componentProps);
+  const [prevComponentProps, setPrevComponentProps] = useState(componentProps);
   if (prevComponentProps !== componentProps) {
     setPrevComponentProps(componentProps);
 
@@ -213,7 +226,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
       ref={ref}
       style={style}
       webviewDebuggingEnabled={DEVELOPMENT_MODE}
-      source={{ uri: connectURL }}
+      source={source}
       userAgent={`Mobile - Stripe ReactNative SDK ${Platform.OS}/${Platform.Version} - stripe-react_native/${sdkVersion}`}
       injectedJavaScriptObject={{
         initParams: {
@@ -222,7 +235,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
           fonts,
         },
         initComponentProps: componentProps,
-        appInfo: { applicationId: undefined },
+        appInfo: { applicationId: overrides?.applicationId },
       }}
       // Fixes injectedJavaScriptObject in Android https://github.com/react-native-webview/react-native-webview/issues/3326#issuecomment-3048111789
       injectedJavaScriptBeforeContentLoaded={'(function() {})();'}

From 7d03d7afa3d3b75071d0e63eba14525dab3657e1 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Thu, 13 Nov 2025 12:34:10 +0100
Subject: [PATCH 08/21] Change initialization API. Add toggles to switch
 appearance and locale

---
 example/src/helpers.ts                        |  10 ++
 .../ConnectAccountOnboardingScreen.tsx        |   1 +
 example/src/screens/ConnectScreen.tsx         | 161 ++++++++++++++----
 src/connect/Components.tsx                    |  27 ++-
 src/connect/ConnectComponentsProvider.tsx     |  77 +++++++--
 src/connect/EmbeddedComponent.tsx             |  41 +----
 src/connect/ModalCloseButton.tsx              |   8 +-
 src/connect/connectTypes.ts                   |  28 ++-
 src/index.tsx                                 |  11 +-
 9 files changed, 263 insertions(+), 101 deletions(-)

diff --git a/example/src/helpers.ts b/example/src/helpers.ts
index 3bf7e3b32e..fb0038a291 100644
--- a/example/src/helpers.ts
+++ b/example/src/helpers.ts
@@ -33,3 +33,13 @@ export function getClientSecretParams(
       }
     : { customerEphemeralKeySecret: remainingParams.ephemeralKey };
 }
+
+export async function fetchClientSecret(): Promise<string> {
+  const response = await fetch(`${API_URL}/account_session`, {
+    method: 'POST',
+  });
+  const json = await response.json();
+  const { clientSecret } = json;
+
+  return clientSecret;
+}
diff --git a/example/src/screens/ConnectAccountOnboardingScreen.tsx b/example/src/screens/ConnectAccountOnboardingScreen.tsx
index 8d61e55d1c..23837b9637 100644
--- a/example/src/screens/ConnectAccountOnboardingScreen.tsx
+++ b/example/src/screens/ConnectAccountOnboardingScreen.tsx
@@ -19,6 +19,7 @@ export default function ConnectAccountOnboardingScreen() {
 
         {visible ? (
           <ConnectAccountOnboarding
+            title="Connect Account Onboarding"
             onExit={() => {
               console.log('ConnectAccountOnboarding onExit');
               setVisible(false);
diff --git a/example/src/screens/ConnectScreen.tsx b/example/src/screens/ConnectScreen.tsx
index 5da9bf3e20..1093bdaee4 100644
--- a/example/src/screens/ConnectScreen.tsx
+++ b/example/src/screens/ConnectScreen.tsx
@@ -1,56 +1,143 @@
-import { ConnectComponentsProvider } from '@stripe/stripe-react-native';
+import {
+  ConnectComponentsProvider,
+  loadConnectAndInitialize,
+  StripeConnectInstance,
+  StripeConnectUpdateParams,
+} from '@stripe/stripe-react-native';
 import { useEffect, useState } from 'react';
-import { fetchPublishableKey } from '../helpers';
-import { ActivityIndicator, StyleSheet } from 'react-native';
-import { API_URL } from '../Config';
+import {
+  ActivityIndicator,
+  Alert,
+  StyleSheet,
+  Switch,
+  Text,
+  View,
+} from 'react-native';
+import { fetchClientSecret, fetchPublishableKey } from '../helpers';
+import { colors } from '../colors';
+
+const fontFamily =
+  "-apple-system, 'system-ui', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'";
+
+const defaultAppearance: StripeConnectUpdateParams['appearance'] = {
+  variables: {
+    fontFamily,
+  },
+};
+
+const defaultLocale = 'en_US';
 
 interface Props {
   children?: React.ReactNode;
 }
 
 const ConnectScreen: React.FC<Props> = ({ children }) => {
-  const [publishableKey, setPublishableKey] = useState<string | null>(null);
+  const [stripeConnectInstance, setStripeConnectInstance] =
+    useState<StripeConnectInstance>();
+
+  const [appearance, setAppearance] = useState(defaultAppearance);
+  const [locale, setLocale] = useState(defaultLocale);
 
   useEffect(() => {
-    fetchPublishableKey().then((pk) => {
-      if (pk) {
-        setPublishableKey(pk);
-      }
-    });
+    fetchPublishableKey()
+      .then((publishableKey) => {
+        if (!publishableKey) {
+          Alert.alert('Error', 'Unable to fetch publishable key.');
+          return;
+        }
+
+        setStripeConnectInstance(
+          loadConnectAndInitialize({
+            publishableKey: publishableKey,
+            fetchClientSecret,
+            appearance: defaultAppearance,
+            locale: defaultLocale,
+          })
+        );
+      })
+      .catch((error) => {
+        Alert.alert(
+          'Error',
+          `Unable to fetch publishable key: ${error.message}`
+        );
+      });
   }, []);
 
-  return !publishableKey ? (
+  return !stripeConnectInstance ? (
     <ActivityIndicator size="large" style={StyleSheet.absoluteFill} />
   ) : (
-    <ConnectComponentsProvider
-      publishableKey={publishableKey}
-      fetchClientSecret={fetchClientSecret}
-      appearance={{
-        variables: {
-          fontFamily:
-            "-apple-system, 'system-ui', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'",
-        },
-      }}
-    >
-      {children}
+    <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
+      <View style={styles.switchContainer}>
+        <Text>Switch appearance</Text>
+        <Switch
+          value={appearance !== defaultAppearance}
+          onValueChange={(value) => {
+            const nextAppearance = value
+              ? {
+                  variables: {
+                    colorPrimary: '#537D5D',
+                    colorBackground: '#FFFDF6',
+                    buttonSecondaryColorBackground: '#DEECD4',
+                    buttonSecondaryColorText: '#537D5D',
+                    colorSecondaryText: '#878682',
+                    colorBorder: '#D6D6D6',
+                    colorDanger: '#EC5228',
+                    badgeNeutralColorBackground: '#F5ECD5',
+                    badgeNeutralColorBorder: '#F5ECD5',
+                    badgeSuccessColorBackground: '#DEECD4',
+                    badgeSuccessColorBorder: '#DEECD4',
+                    badgeSuccessColorText: '#537D5D',
+                    badgeWarningColorBackground: '#FBDAB1',
+                    badgeWarningColorBorder: '#FBDAB1',
+                    badgeWarningColorText: '#751F00',
+                    badgeDangerColorBackground: '#EC5228',
+                    badgeDangerColorBorder: '#EC5228',
+                    badgeDangerColorText: '#FFF',
+                    offsetBackgroundColor: '#FAF6E9',
+                    formBackgroundColor: '#FAF6E9',
+                    borderRadius: '24px',
+                    fontFamily,
+                  },
+                }
+              : defaultAppearance;
+
+            setAppearance(nextAppearance);
+            stripeConnectInstance.update({
+              appearance: nextAppearance,
+              locale,
+            });
+          }}
+        />
+      </View>
+
+      <View style={styles.switchContainer}>
+        <Text>Switch locale</Text>
+        <Switch
+          value={locale !== defaultLocale}
+          onValueChange={(value) => {
+            const newLocale = value ? 'es_ES' : defaultLocale;
+            setLocale(newLocale);
+            stripeConnectInstance.update({ locale: newLocale, appearance });
+          }}
+        />
+      </View>
+
+      <View style={styles.main}>{children}</View>
     </ConnectComponentsProvider>
   );
 };
 
 export default ConnectScreen;
 
-const fetchClientSecret = async () => {
-  const response = await fetch(`${API_URL}/account_session`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      currency: 'usd',
-    }),
-  });
-  const json = await response.json();
-  const { clientSecret } = json;
-
-  return clientSecret;
-};
+const styles = StyleSheet.create({
+  switchContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    padding: 16,
+    backgroundColor: colors.white,
+  },
+  main: {
+    flex: 1,
+  },
+});
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
index f67d751a44..0db59c6a16 100644
--- a/src/connect/Components.tsx
+++ b/src/connect/Components.tsx
@@ -1,21 +1,23 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  ActivityIndicator,
+  Modal,
+  SafeAreaView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
 import type {
   CollectionOptions,
   LoaderStart,
   PaymentsListDefaultFilters,
   StepChange,
 } from './connectTypes';
-import React, { useCallback, useMemo, useState } from 'react';
 import { CommonComponentProps, EmbeddedComponent } from './EmbeddedComponent';
-import {
-  Modal,
-  SafeAreaView,
-  View,
-  StyleSheet,
-  ActivityIndicator,
-} from 'react-native';
 import ModalCloseButton from './ModalCloseButton';
 
 export function ConnectAccountOnboarding({
+  title,
   onExit,
   onStepChange,
   recipientTermsOfServiceUrl,
@@ -26,6 +28,7 @@ export function ConnectAccountOnboarding({
   onLoadError,
   onPageDidLoad,
 }: {
+  title?: string;
   onExit: () => void;
   onStepChange?: (stepChange: StepChange) => void;
   recipientTermsOfServiceUrl?: string;
@@ -76,6 +79,8 @@ export function ConnectAccountOnboarding({
     <Modal visible={visible} animationType="slide">
       <SafeAreaView style={styles.flex1}>
         <View style={styles.navBar}>
+          <View style={styles.navBarPlaceholder} />
+          <Text>{title}</Text>
           <ModalCloseButton onPress={onExitCallback} />
         </View>
         <View style={styles.onboardingWrapper}>
@@ -182,9 +187,13 @@ const styles = StyleSheet.create({
     height: 56,
     paddingHorizontal: 8,
     flexDirection: 'row',
-    justifyContent: 'flex-end',
+    alignItems: 'center',
+    justifyContent: 'space-between',
     borderBottomWidth: StyleSheet.hairlineWidth,
   },
+  navBarPlaceholder: {
+    width: 36,
+  },
   flex1: {
     flex: 1,
   },
diff --git a/src/connect/ConnectComponentsProvider.tsx b/src/connect/ConnectComponentsProvider.tsx
index 763c6a65e0..a343b3d3e9 100644
--- a/src/connect/ConnectComponentsProvider.tsx
+++ b/src/connect/ConnectComponentsProvider.tsx
@@ -1,12 +1,39 @@
-import React, { JSX, useMemo } from 'react';
-import type { IStripeConnectInitParams } from './connectTypes';
+import React, { JSX, useMemo, useState } from 'react';
+import type {
+  StripeConnectInitParams,
+  StripeConnectUpdateParams,
+  LoadConnectAndInitialize,
+  StripeConnectInstance,
+} from './connectTypes';
+
+class ConnectInstance implements StripeConnectInstance {
+  initParams: StripeConnectInitParams;
+  onUpdate?: (options: StripeConnectUpdateParams) => void;
+
+  constructor(initParams: StripeConnectInitParams) {
+    this.initParams = initParams;
+  }
+
+  update(options: StripeConnectUpdateParams): void {
+    this.onUpdate?.(options);
+  }
+}
+
+export const loadConnectAndInitialize: LoadConnectAndInitialize = (
+  initParams: StripeConnectInitParams
+): StripeConnectInstance => {
+  return new ConnectInstance(initParams);
+};
+
+type ConnectComponentsProviderProps = {
+  connectInstance: StripeConnectInstance;
+  children: React.ReactNode;
+};
 
 export type ConnectComponentsPayload = {
-  publishableKey: string;
-  fetchClientSecret: IStripeConnectInitParams['fetchClientSecret'];
-  appearance?: IStripeConnectInitParams['appearance'];
-  locale?: IStripeConnectInitParams['locale'];
-  fonts?: IStripeConnectInitParams['fonts'];
+  appearance: StripeConnectInitParams['appearance'];
+  locale: StripeConnectInitParams['locale'];
+  connectInstance: ConnectInstance;
 };
 
 const ConnectComponentsContext =
@@ -16,11 +43,37 @@ ConnectComponentsContext.displayName = 'ConnectComponents';
 
 export const ConnectComponentsProvider = ({
   children,
-  ...props
-}: ConnectComponentsPayload & {
-  children: React.ReactNode;
-}): JSX.Element => {
-  const value = useMemo(() => ({ ...props }), [props]);
+  connectInstance,
+}: ConnectComponentsProviderProps): JSX.Element => {
+  if (!(connectInstance instanceof ConnectInstance)) {
+    throw new Error(
+      'connectInstance must be an instance of ConnectInstance created via loadConnectAndInitialize'
+    );
+  }
+
+  const [appearance, setAppearance] = useState<
+    StripeConnectInitParams['appearance']
+  >(connectInstance.initParams.appearance);
+
+  const [locale, setLocale] = useState<StripeConnectInitParams['locale']>(
+    connectInstance.initParams.locale
+  );
+
+  if (!connectInstance.onUpdate) {
+    connectInstance.onUpdate = (options: StripeConnectUpdateParams) => {
+      if (options.appearance) {
+        setAppearance(options.appearance);
+      }
+      if (options.locale) {
+        setLocale(options.locale);
+      }
+    };
+  }
+
+  const value = useMemo(
+    () => ({ connectInstance, locale, appearance }),
+    [connectInstance, locale, appearance]
+  );
 
   return (
     <ConnectComponentsContext.Provider value={value}>
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index ac7a2c2e5f..e19dad5ce6 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -123,14 +123,10 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     loadWebViewComponent();
   }, [loadWebViewComponent]);
 
-  const {
-    publishableKey,
-    fetchClientSecret,
-    appearance,
-    locale,
-    fonts,
-    overrides,
-  } = useConnectComponents() as ConnectComponentsPayloadInternal;
+  const { connectInstance, appearance, locale, overrides } =
+    useConnectComponents() as ConnectComponentsPayloadInternal;
+  const { fonts, publishableKey, fetchClientSecret } =
+    connectInstance.initParams;
 
   const {
     component,
@@ -165,36 +161,15 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
   const ref = useRef<WebView>(null);
 
   const [prevAppearance, setPrevAppearance] = useState(appearance);
-  if (prevAppearance !== appearance) {
-    setPrevAppearance(appearance);
-
-    ref.current?.injectJavaScript(`
-      (function() {
-        window.updateConnectInstance(${JSON.stringify({ appearance })});
-        true;
-      })();
-    `);
-  }
-
   const [prevLocale, setPrevLocale] = useState(locale);
-  if (prevLocale !== locale) {
-    setPrevLocale(locale);
-
-    ref.current?.injectJavaScript(`
-      (function() {
-        window.updateConnectInstance(${JSON.stringify({ locale })});
-        true;
-      })();
-    `);
-  }
 
-  const [prevFonts, setPrevFonts] = useState(fonts);
-  if (prevFonts !== fonts) {
-    setPrevFonts(fonts);
+  if (prevAppearance !== appearance || prevLocale !== locale) {
+    setPrevAppearance(appearance);
+    setPrevLocale(locale);
 
     ref.current?.injectJavaScript(`
       (function() {
-        window.updateConnectInstance(${JSON.stringify({ fonts })});
+        window.updateConnectInstance(${JSON.stringify({ appearance, locale })});
         true;
       })();
     `);
diff --git a/src/connect/ModalCloseButton.tsx b/src/connect/ModalCloseButton.tsx
index 087529fadc..f53aef9c9a 100644
--- a/src/connect/ModalCloseButton.tsx
+++ b/src/connect/ModalCloseButton.tsx
@@ -2,10 +2,6 @@ import React from 'react';
 import { TouchableOpacity, Text, StyleSheet } from 'react-native';
 
 const size = 36;
-const color = '#333';
-const bg = 'transparent';
-const accessibilityLabel = 'Close';
-
 const hitSlop = { top: 10, bottom: 10, left: 10, right: 10 };
 
 interface ModalCloseButtonProps {
@@ -17,7 +13,6 @@ export default function ModalCloseButton({ onPress }: ModalCloseButtonProps) {
     <TouchableOpacity
       onPress={onPress}
       accessibilityRole="button"
-      accessibilityLabel={accessibilityLabel}
       hitSlop={hitSlop}
       style={[
         styles.button,
@@ -25,12 +20,11 @@ export default function ModalCloseButton({ onPress }: ModalCloseButtonProps) {
           width: size,
           height: size,
           borderRadius: size / 2,
-          backgroundColor: bg,
         },
       ]}
       activeOpacity={0.7}
     >
-      <Text style={[styles.cross, { color, fontSize: Math.round(size * 0.6) }]}>
+      <Text style={[styles.cross, { fontSize: Math.round(size * 0.6) }]}>
         ×
       </Text>
     </TouchableOpacity>
diff --git a/src/connect/connectTypes.ts b/src/connect/connectTypes.ts
index 7dcefd415a..06332d2db8 100644
--- a/src/connect/connectTypes.ts
+++ b/src/connect/connectTypes.ts
@@ -170,10 +170,22 @@ export type CollectionOptions = {
       };
 };
 
+export type StripeConnectUpdateParams = {
+  /**
+   * Appearance options for the Connect instance.
+   */
+  appearance?: AppearanceOptions;
+
+  /**
+   * The locale to use for the Connect instance.
+   */
+  locale?: string;
+};
+
 /**
  * Initialization parameters for Connect JS. See https://stripe.com/docs/connect/get-started-connect-embedded-components#configuring-connect-js for more details.
  */
-export interface IStripeConnectInitParams {
+export type StripeConnectInitParams = {
   /**
    * The publishable key for the connected account.
    */
@@ -200,7 +212,7 @@ export interface IStripeConnectInitParams {
    * An array of custom fonts, which embedded components created from a ConnectInstance can use.
    */
   fonts?: Array<CssFontSource | CustomFontSource>;
-}
+};
 
 /**
  * Appearance options for the Connect instance.
@@ -600,3 +612,15 @@ export declare type CustomFontSource = {
 };
 
 export declare type OverlayOption = 'dialog' | 'drawer';
+
+export interface StripeConnectInstance {
+  /**
+   * Updates the Connect instance with new parameters.
+   * @options New parameters to update the Connect instance with.
+   */
+  update: (options: StripeConnectUpdateParams) => void;
+}
+
+export type LoadConnectAndInitialize = (
+  initParams: StripeConnectInitParams
+) => StripeConnectInstance;
diff --git a/src/index.tsx b/src/index.tsx
index c1fb912ac5..b9a0ebef64 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -35,5 +35,14 @@ export * from './types/EmbeddedPaymentElement';
 export * from './types/PaymentSheet';
 export * from './types/ConfirmationToken';
 
-export { ConnectComponentsProvider } from './connect/ConnectComponentsProvider';
+//connect components
+export {
+  ConnectComponentsProvider,
+  loadConnectAndInitialize,
+} from './connect/ConnectComponentsProvider';
+export type {
+  StripeConnectInstance,
+  StripeConnectInitParams,
+  StripeConnectUpdateParams,
+} from './connect/connectTypes';
 export * from './connect/Components';

From 29f09f9f1440f12cfdda147100c5997a528d3f99 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Thu, 13 Nov 2025 14:03:48 +0100
Subject: [PATCH 09/21] Remove some alerts

---
 example/src/screens/ConnectScreen.tsx | 35 +++++++++------------------
 1 file changed, 12 insertions(+), 23 deletions(-)

diff --git a/example/src/screens/ConnectScreen.tsx b/example/src/screens/ConnectScreen.tsx
index 1093bdaee4..7ada2ba2d9 100644
--- a/example/src/screens/ConnectScreen.tsx
+++ b/example/src/screens/ConnectScreen.tsx
@@ -7,14 +7,13 @@ import {
 import { useEffect, useState } from 'react';
 import {
   ActivityIndicator,
-  Alert,
   StyleSheet,
   Switch,
   Text,
   View,
 } from 'react-native';
-import { fetchClientSecret, fetchPublishableKey } from '../helpers';
 import { colors } from '../colors';
+import { fetchClientSecret, fetchPublishableKey } from '../helpers';
 
 const fontFamily =
   "-apple-system, 'system-ui', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'";
@@ -39,28 +38,18 @@ const ConnectScreen: React.FC<Props> = ({ children }) => {
   const [locale, setLocale] = useState(defaultLocale);
 
   useEffect(() => {
-    fetchPublishableKey()
-      .then((publishableKey) => {
-        if (!publishableKey) {
-          Alert.alert('Error', 'Unable to fetch publishable key.');
-          return;
-        }
+    fetchPublishableKey().then((publishableKey) => {
+      if (!publishableKey) return;
 
-        setStripeConnectInstance(
-          loadConnectAndInitialize({
-            publishableKey: publishableKey,
-            fetchClientSecret,
-            appearance: defaultAppearance,
-            locale: defaultLocale,
-          })
-        );
-      })
-      .catch((error) => {
-        Alert.alert(
-          'Error',
-          `Unable to fetch publishable key: ${error.message}`
-        );
-      });
+      setStripeConnectInstance(
+        loadConnectAndInitialize({
+          publishableKey: publishableKey,
+          fetchClientSecret,
+          appearance: defaultAppearance,
+          locale: defaultLocale,
+        })
+      );
+    });
   }, []);
 
   return !stripeConnectInstance ? (

From e2a597b01e45841388f50a51bc51ebde1639ce6b Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Fri, 14 Nov 2025 14:45:26 +0100
Subject: [PATCH 10/21] Implement secure webviews

---
 android/build.gradle                          |  1 +
 .../reactnativestripesdk/StripeSdkModule.kt   | 30 ++++++++
 .../NativeStripeSdkModuleSpec.java            |  4 +
 example/app.json                              | 16 +++-
 ios/StripeSdk.mm                              |  8 ++
 ios/StripeSdkImpl.swift                       | 74 +++++++++++++++++++
 src/connect/Components.tsx                    |  1 +
 src/connect/EmbeddedComponent.tsx             | 50 ++++++++++++-
 src/specs/NativeStripeSdkModule.ts            |  5 ++
 9 files changed, 184 insertions(+), 5 deletions(-)

diff --git a/android/build.gradle b/android/build.gradle
index fbf6bed308..3287da0a85 100644
--- a/android/build.gradle
+++ b/android/build.gradle
@@ -222,6 +222,7 @@ dependencies {
   implementation 'androidx.appcompat:appcompat:1.4.1'
   implementation 'androidx.legacy:legacy-support-v4:1.0.0'
   implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.0'
+  implementation 'androidx.browser:browser:1.5.0'
 
   // play-services-wallet is already included in stripe-android
   compileOnly "com.google.android.gms:play-services-wallet:19.3.0"
diff --git a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
index 43e9b233a1..516922d08f 100644
--- a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
+++ b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
@@ -1329,6 +1329,36 @@ class StripeSdkModule(
     // noop, iOS only
   }
 
+  @ReactMethod
+  override fun openAuthenticatedWebView(
+    id: String,
+    url: String,
+    promise: Promise,
+  ) {
+    val activity = getCurrentActivityOrResolveWithError(promise) ?: return
+
+    UiThreadUtil.runOnUiThread {
+      try {
+        val uri = android.net.Uri.parse(url)
+        val builder = androidx.browser.customtabs.CustomTabsIntent.Builder()
+
+        // Set toolbar color for better UX
+        builder.setShowTitle(true)
+        builder.setUrlBarHidingEnabled(true)
+
+        val customTabsIntent = builder.build()
+
+        // Note: Custom Tabs doesn't have built-in redirect handling like iOS ASWebAuthenticationSession.
+        // The deep linking will be handled by the ReactNative part.
+        customTabsIntent.launchUrl(activity, uri)
+
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.resolve(createError("Failed", e))
+      }
+    }
+  }
+
   override fun addListener(eventType: String?) {
     // noop, iOS only
   }
diff --git a/android/src/oldarch/java/com/reactnativestripesdk/NativeStripeSdkModuleSpec.java b/android/src/oldarch/java/com/reactnativestripesdk/NativeStripeSdkModuleSpec.java
index 8357744d81..d298aba01b 100644
--- a/android/src/oldarch/java/com/reactnativestripesdk/NativeStripeSdkModuleSpec.java
+++ b/android/src/oldarch/java/com/reactnativestripesdk/NativeStripeSdkModuleSpec.java
@@ -268,6 +268,10 @@ private void invoke(String eventName) {
   @DoNotStrip
   public abstract void setFinancialConnectionsForceNativeFlow(boolean enabled, Promise promise);
 
+  @ReactMethod
+  @DoNotStrip
+  public abstract void openAuthenticatedWebView(String id, String url, Promise promise);
+
   @ReactMethod
   @DoNotStrip
   public abstract void addListener(String eventType);
diff --git a/example/app.json b/example/app.json
index a6f90f6fdf..a63944ccd3 100644
--- a/example/app.json
+++ b/example/app.json
@@ -25,7 +25,12 @@
     "bundleIdentifier": "com.stripe.react.native",
     "codeSignEntitlements": {
       "com.apple.developer.in-app-payments": ["merchant.com.stripe.react.native"]
-    }
+    },
+    "urlTypes": [
+      {
+        "CFBundleURLSchemes": ["stripe-connect"]
+      }
+    ]
   },
   "android": {
     "package": "com.stripe.react.native",
@@ -33,6 +38,15 @@
       "android:name": "com.google.android.gms.wallet.api.enabled",
       "android:value": "true"
     }],
+    "intentFilters": [
+      {
+        "action": "android.intent.action.VIEW",
+        "category": ["android.intent.category.DEFAULT", "android.intent.category.BROWSABLE"],
+        "data": {
+          "scheme": "stripe-connect"
+        }
+      }
+    ],
     "signingConfigs": {
       "debug": {
         "keyAlias": "androiddebugkey",
diff --git a/ios/StripeSdk.mm b/ios/StripeSdk.mm
index 42f396bc11..24fdc13d20 100644
--- a/ios/StripeSdk.mm
+++ b/ios/StripeSdk.mm
@@ -382,6 +382,14 @@ - (instancetype)init
   [StripeSdkImpl.shared setFinancialConnectionsForceNativeFlow:enabled resolver:resolve rejecter:reject];
 }
 
+RCT_EXPORT_METHOD(openAuthenticatedWebView:(nonnull NSString *)id
+                                       url:(nonnull NSString *)url
+                                   resolve:(nonnull RCTPromiseResolveBlock)resolve
+                                    reject:(nonnull RCTPromiseRejectBlock)reject)
+{
+  [StripeSdkImpl.shared openAuthenticatedWebView:id url:url resolver:resolve rejecter:reject];
+}
+
 RCT_EXPORT_METHOD(verifyMicrodeposits:(BOOL)isPaymentIntent
                          clientSecret:(nonnull NSString *)clientSecret
                                params:(nonnull NSDictionary *)params
diff --git a/ios/StripeSdkImpl.swift b/ios/StripeSdkImpl.swift
index 11c0201089..fe09e1c546 100644
--- a/ios/StripeSdkImpl.swift
+++ b/ios/StripeSdkImpl.swift
@@ -1,10 +1,18 @@
 import PassKit
+import AuthenticationServices
 @_spi(DashboardOnly) @_spi(STP) import Stripe
 @_spi(EmbeddedPaymentElementPrivateBeta) @_spi(CustomerSessionBetaAccess) import StripePaymentSheet
 @_spi(STP) @_spi(ConfirmationTokensPublicPreview) import StripePayments
 import StripeFinancialConnections
 import Foundation
 
+@available(iOS 13.0, *)
+class ASWebAuthenticationPresentationContextProvider: NSObject, ASWebAuthenticationPresentationContextProviding {
+    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
+        return RCTKeyWindow() ?? ASPresentationAnchor()
+    }
+}
+
 @objc(StripeSdkImpl)
 public class StripeSdkImpl: NSObject, UIAdaptivePresentationControllerDelegate {
     @objc public static let shared = StripeSdkImpl()
@@ -71,6 +79,9 @@ public class StripeSdkImpl: NSObject, UIAdaptivePresentationControllerDelegate {
     var embeddedInstance: EmbeddedPaymentElement? = nil
     lazy var embeddedInstanceDelegate = StripeSdkEmbeddedPaymentElementDelegate(sdkImpl: self)
 
+    var authenticationSession: ASWebAuthenticationSession? = nil
+    var authenticationContextProvider: Any? = nil
+
     @objc public func getConstants() -> [AnyHashable : Any] {
         return [
             "API_VERSIONS": [
@@ -1179,6 +1190,69 @@ public class StripeSdkImpl: NSObject, UIAdaptivePresentationControllerDelegate {
         resolve(nil)
     }
 
+    @objc(openAuthenticatedWebView:url:resolver:rejecter:)
+    public func openAuthenticatedWebView(
+        id: String,
+        url: String,
+        resolver resolve: @escaping RCTPromiseResolveBlock,
+        rejecter reject: @escaping RCTPromiseRejectBlock
+    ) {
+        guard let url = URL(string: url) else {
+            resolve(Errors.createError(ErrorType.Failed, "Invalid URL"))
+            return
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else {
+                resolve(Errors.createError(ErrorType.Failed, "StripeSdkImpl instance deallocated"))
+                return
+            }
+
+            // Create the authentication session with the configured URL scheme
+            self.authenticationSession = ASWebAuthenticationSession(
+                url: url,
+                callbackURLScheme: nil
+            ) { callbackURL, error in
+                if let error = error {
+                    // User canceled or an error occurred
+                    if (error as NSError).code == ASWebAuthenticationSessionError.canceledLogin.rawValue {
+                        // User canceled - resolve successfully as this is expected behavior
+                        resolve([])
+                    } else {
+                        resolve(Errors.createError(ErrorType.Failed, error as NSError))
+                    }
+                } else if let callbackURL = callbackURL {
+                    // Return the callback URL
+                    let result: [String: Any] = ["url": callbackURL.absoluteString]
+                    resolve(result)
+                } else {
+                    // Session completed successfully without a callback URL
+                    resolve([])
+                }
+
+                // Clean up the session and context provider
+                self.authenticationSession = nil
+                self.authenticationContextProvider = nil
+            }
+
+            // Configure the session for iOS 13+
+            if #available(iOS 13.0, *) {
+                let contextProvider = ASWebAuthenticationPresentationContextProvider()
+                self.authenticationContextProvider = contextProvider
+                self.authenticationSession?.presentationContextProvider = contextProvider
+                self.authenticationSession?.prefersEphemeralWebBrowserSession = false
+            }
+
+            // Start the session
+            guard self.authenticationSession?.start() == true else {
+                resolve(Errors.createError(ErrorType.Failed, "Failed to start authentication session"))
+                self.authenticationSession = nil
+                self.authenticationContextProvider = nil
+                return
+            }
+        }
+    }
+
     public func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
         confirmPaymentResolver?(Errors.createError(ErrorType.Canceled, "FPX Payment has been canceled"))
     }
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
index 0db59c6a16..ec9de871e6 100644
--- a/src/connect/Components.tsx
+++ b/src/connect/Components.tsx
@@ -62,6 +62,7 @@ export function ConnectAccountOnboarding({
     return {
       onExit: onExitCallback,
       onStepChange,
+      onCloseWebView: onExitCallback,
     };
   }, [onExitCallback, onStepChange]);
 
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index e19dad5ce6..85bc63b04b 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -5,7 +5,7 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import { Platform, StyleProp, ViewStyle } from 'react-native';
+import { Linking, Platform, StyleProp, ViewStyle } from 'react-native';
 import type { WebView } from 'react-native-webview';
 import pjson from '../../package.json';
 import {
@@ -13,6 +13,7 @@ import {
   useConnectComponents,
 } from './ConnectComponentsProvider';
 import type { LoadError, LoaderStart } from './connectTypes';
+import NativeStripeSdk from '../specs/NativeStripeSdkModule';
 
 const DEVELOPMENT_MODE = false;
 const DEVELOPMENT_URL =
@@ -123,6 +124,21 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     loadWebViewComponent();
   }, [loadWebViewComponent]);
 
+  // Handle deep links for authenticated webview callbacks (Android)
+  useEffect(() => {
+    // Listen for deep links to handle Android Custom Tabs redirects
+    const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
+      if (url.startsWith('stripe-connect://')) {
+        console.log(`[EmbeddedComponent] Deep link received: ${url}`);
+        // TODO: resolve promise
+      }
+    });
+
+    return () => {
+      linkingSubscription.remove();
+    };
+  }, []);
+
   const { connectInstance, appearance, locale, overrides } =
     useConnectComponents() as ConnectComponentsPayloadInternal;
   const { fonts, publishableKey, fetchClientSecret } =
@@ -192,6 +208,11 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     });
   }
 
+  const handleUnexpectedError = useCallback((error: unknown) => {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error(`Unexpected error: ${errorMessage}`);
+  }, []);
+
   const WebViewComponent = dynamicWebview?.WebView;
 
   if (!WebViewComponent) return null;
@@ -221,7 +242,12 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
         };
 
         if (message.type === 'fetchClientSecret') {
-          const clientSecret = await fetchClientSecret();
+          const clientSecret = await fetchClientSecret().catch((error) => {
+            handleUnexpectedError(error);
+            return null;
+          });
+          if (!clientSecret) return;
+
           ref.current?.injectJavaScript(`
             window.clientSecretDeferred.resolve(${JSON.stringify(
               clientSecret
@@ -238,8 +264,8 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
           // message.data is of type {clientSecret: string; id: string; connectedAccountId: string;}
         } else if (message.type === 'closeWebView') {
           // message.data is empty
+          callbacks?.onCloseWebView?.({});
         } else if (message.type === 'callSupplementalFunction') {
-          console.log('message:', message);
           // message.data is of type {[key]: {functionName: string; args: unknown[]; invocationId: string;}}
         } else if (message.type === 'onSetterFunctionCalled') {
           const { setter, value } = message.data as {
@@ -258,7 +284,23 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
             callbacks?.[functionName]?.(value);
           }
         } else if (message.type === 'openAuthenticatedWebView') {
-          // message.data is of type {id: string; url: string}
+          const { url, id } = message.data as { id: string; url: string };
+
+          NativeStripeSdk.openAuthenticatedWebView(id, url)
+            .then((result) => {
+              // TODO: on Android this resolves immediately, but we should wait
+              // for the deep link to be opened and get the URL from there
+              ref.current?.injectJavaScript(`
+                (function() {
+                  window.returnedFromAuthenticatedWebView(${JSON.stringify({
+                    id,
+                    url: result?.url ?? null,
+                  })});
+                  true;
+                })();
+              `);
+            })
+            .catch(handleUnexpectedError);
         } else {
           // unhandled message
         }
diff --git a/src/specs/NativeStripeSdkModule.ts b/src/specs/NativeStripeSdkModule.ts
index 00a11031e1..31b9d684fc 100644
--- a/src/specs/NativeStripeSdkModule.ts
+++ b/src/specs/NativeStripeSdkModule.ts
@@ -196,6 +196,11 @@ export interface Spec extends TurboModule {
 
   setFinancialConnectionsForceNativeFlow(enabled: boolean): Promise<void>;
 
+  openAuthenticatedWebView(
+    id: string,
+    url: string
+  ): Promise<{ url?: string } | null>;
+
   // Events
   addListener: (eventType: string) => void;
   removeListeners: (count: number) => void;

From c8654e23b1f0f6d1469fbedc848a4e6fec43848b Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Fri, 14 Nov 2025 14:46:03 +0100
Subject: [PATCH 11/21] Implement secure webviews

---
 .../src/main/java/com/reactnativestripesdk/StripeSdkModule.kt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
index 516922d08f..f63c80a5ed 100644
--- a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
+++ b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
@@ -1340,7 +1340,9 @@ class StripeSdkModule(
     UiThreadUtil.runOnUiThread {
       try {
         val uri = android.net.Uri.parse(url)
-        val builder = androidx.browser.customtabs.CustomTabsIntent.Builder()
+        val builder =
+          androidx.browser.customtabs.CustomTabsIntent
+            .Builder()
 
         // Set toolbar color for better UX
         builder.setShowTitle(true)

From 91f52cce3b331b2b790ae5e7118c5ab4dee889b0 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Fri, 14 Nov 2025 22:59:22 +0100
Subject: [PATCH 12/21] Add endpoint to server

---
 example/server/index.ts | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/example/server/index.ts b/example/server/index.ts
index 6b88327214..97d6d43c39 100644
--- a/example/server/index.ts
+++ b/example/server/index.ts
@@ -1029,6 +1029,46 @@ app.post(
   }
 );
 
+app.post('/account_session', async (req, res) => {
+  let stripe = new Stripe(stripeSecretKey, {
+    apiVersion: '2023-10-16',
+    typescript: true,
+  });
+
+  try {
+    const accountSession = await stripe.accountSessions.create({
+      account: process.env.CONNECTED_ACCOUNT_ID || '',
+      components: {
+        account_onboarding: {
+          enabled: true,
+        },
+        payouts: {
+          enabled: true,
+        },
+        payments: {
+          enabled: true,
+          features: {
+            refund_management: true,
+            dispute_management: true,
+            capture_payments: true,
+          },
+        },
+      },
+    });
+
+    res.json({
+      clientSecret: accountSession.client_secret,
+    });
+  } catch (error: any) {
+    console.error(
+      'An error occurred when calling the Stripe API to create an account session',
+      error
+    );
+    res.status(500);
+    res.send({ error: error.message });
+  }
+});
+
 // Mocks a Database. In your code, you should use a persistent database.
 let savedPaymentOptions = new Map<string, string>();
 

From 8e5881911e9dbf254251e9b94b0b3ac78620844e Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Mon, 17 Nov 2025 22:25:23 +0100
Subject: [PATCH 13/21] Improvements for Android

---
 .../reactnativestripesdk/StripeSdkModule.kt   |  3 +-
 example/android/build.gradle                  | 38 ++++++++++++
 example/app.json                              |  9 ---
 src/connect/EmbeddedComponent.tsx             | 62 ++++++++++++++-----
 4 files changed, 87 insertions(+), 25 deletions(-)

diff --git a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
index f63c80a5ed..31019ad463 100644
--- a/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
+++ b/android/src/main/java/com/reactnativestripesdk/StripeSdkModule.kt
@@ -1351,7 +1351,8 @@ class StripeSdkModule(
         val customTabsIntent = builder.build()
 
         // Note: Custom Tabs doesn't have built-in redirect handling like iOS ASWebAuthenticationSession.
-        // The deep linking will be handled by the ReactNative part.
+        // The redirect will be handled via deep linking when the auth server redirects to stripe-connect://
+        // The React Native Linking module will capture the deep link and pass it back to the JS layer.
         customTabsIntent.launchUrl(activity, uri)
 
         promise.resolve(null)
diff --git a/example/android/build.gradle b/example/android/build.gradle
index 41aff0712a..82a30b76cf 100644
--- a/example/android/build.gradle
+++ b/example/android/build.gradle
@@ -42,3 +42,41 @@ allprojects {
         google()
     }
 }
+
+// Fix MainActivity launchMode and add deep link for stripe-connect
+subprojects { subproject ->
+    subproject.afterEvaluate {
+        subproject.tasks.matching { task ->
+            task.name == 'generateAndroidManifest'
+        }.each { task ->
+            task.doLast {
+                def manifestFile = file("${subproject.buildDir}/generated/rnta/src/main/AndroidManifest.xml")
+                if (manifestFile.exists()) {
+                    def manifest = manifestFile.text
+
+                    // Add launchMode="singleTask"
+                    manifest = manifest.replace(
+                        '<activity android:name="com.microsoft.reacttestapp.MainActivity" android:exported="true">',
+                        '<activity android:name="com.microsoft.reacttestapp.MainActivity" android:exported="true" android:launchMode="singleTask">'
+                    )
+
+                    // Add deep link intent filter for stripe-connect
+                    def intentFilterXml = '''<intent-filter>
+        <action android:name="android.intent.action.VIEW"></action>
+        <category android:name="android.intent.category.DEFAULT"></category>
+        <category android:name="android.intent.category.BROWSABLE"></category>
+        <data android:scheme="stripe-connect"></data>
+      </intent-filter>
+      '''
+                    manifest = manifest.replace(
+                        '</intent-filter>\n    </activity>',
+                        '</intent-filter>\n      ' + intentFilterXml + '</activity>'
+                    )
+
+                    manifestFile.text = manifest
+                    println "✓ Updated MainActivity: launchMode=singleTask + stripe-connect deep link"
+                }
+            }
+        }
+    }
+}
diff --git a/example/app.json b/example/app.json
index a63944ccd3..fe13aa0f08 100644
--- a/example/app.json
+++ b/example/app.json
@@ -38,15 +38,6 @@
       "android:name": "com.google.android.gms.wallet.api.enabled",
       "android:value": "true"
     }],
-    "intentFilters": [
-      {
-        "action": "android.intent.action.VIEW",
-        "category": ["android.intent.category.DEFAULT", "android.intent.category.BROWSABLE"],
-        "data": {
-          "scheme": "stripe-connect"
-        }
-      }
-    ],
     "signingConfigs": {
       "debug": {
         "keyAlias": "androiddebugkey",
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index 85bc63b04b..d26dfcfc39 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -8,12 +8,12 @@ import React, {
 import { Linking, Platform, StyleProp, ViewStyle } from 'react-native';
 import type { WebView } from 'react-native-webview';
 import pjson from '../../package.json';
+import NativeStripeSdk from '../specs/NativeStripeSdkModule';
 import {
   ConnectComponentsPayload,
   useConnectComponents,
 } from './ConnectComponentsProvider';
 import type { LoadError, LoaderStart } from './connectTypes';
-import NativeStripeSdk from '../specs/NativeStripeSdkModule';
 
 const DEVELOPMENT_MODE = false;
 const DEVELOPMENT_URL =
@@ -107,6 +107,11 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     WebView: typeof WebView | null;
   } | null>(null);
 
+  // Store pending authenticated webview promise (for Android Custom Tabs)
+  const pendingAuthWebViewPromise = useRef<((url: string) => void) | null>(
+    null
+  );
+
   const loadWebViewComponent = useCallback(async () => {
     if (dynamicWebview) return;
 
@@ -126,14 +131,31 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   // Handle deep links for authenticated webview callbacks (Android)
   useEffect(() => {
-    // Listen for deep links to handle Android Custom Tabs redirects
-    const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
+    const handleDeepLink = (url: string) => {
+      console.log('handleDeepLink url:', url);
       if (url.startsWith('stripe-connect://')) {
         console.log(`[EmbeddedComponent] Deep link received: ${url}`);
-        // TODO: resolve promise
+
+        if (pendingAuthWebViewPromise.current) {
+          const resolve = pendingAuthWebViewPromise.current;
+          pendingAuthWebViewPromise.current = null;
+          resolve(url);
+        }
+      }
+    };
+
+    // Check for initial URL (when app is opened via deep link)
+    Linking.getInitialURL().then((url) => {
+      if (url) {
+        handleDeepLink(url);
       }
     });
 
+    // Listen for deep links while app is running
+    const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
+      handleDeepLink(url);
+    });
+
     return () => {
       linkingSubscription.remove();
     };
@@ -286,19 +308,29 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
         } else if (message.type === 'openAuthenticatedWebView') {
           const { url, id } = message.data as { id: string; url: string };
 
+          // On Android, we need to wait for the deep link callback
+          // On iOS, the promise resolves with the redirect URL
+          const handleAuthWebViewResult = (resultUrl: string | null) => {
+            ref.current?.injectJavaScript(`
+              (function() {
+                window.returnedFromAuthenticatedWebView(${JSON.stringify({
+                  id,
+                  url: resultUrl,
+                })});
+                true;
+              })();
+            `);
+          };
+
           NativeStripeSdk.openAuthenticatedWebView(id, url)
             .then((result) => {
-              // TODO: on Android this resolves immediately, but we should wait
-              // for the deep link to be opened and get the URL from there
-              ref.current?.injectJavaScript(`
-                (function() {
-                  window.returnedFromAuthenticatedWebView(${JSON.stringify({
-                    id,
-                    url: result?.url ?? null,
-                  })});
-                  true;
-                })();
-              `);
+              if (Platform.OS === 'ios') {
+                // iOS returns the redirect URL directly
+                handleAuthWebViewResult(result?.url ?? null);
+              } else {
+                // Android: Store promise to be resolved by deep link listener
+                pendingAuthWebViewPromise.current = handleAuthWebViewResult;
+              }
             })
             .catch(handleUnexpectedError);
         } else {

From a6e2c8786460e3de97423bfd0404fd244331ff77 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Thu, 20 Nov 2025 17:04:46 +0100
Subject: [PATCH 14/21] Extract callback

---
 src/connect/EmbeddedComponent.tsx | 175 ++++++++++++++++--------------
 1 file changed, 94 insertions(+), 81 deletions(-)

diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index d26dfcfc39..d4a6a15270 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -6,7 +6,7 @@ import React, {
   useState,
 } from 'react';
 import { Linking, Platform, StyleProp, ViewStyle } from 'react-native';
-import type { WebView } from 'react-native-webview';
+import type { WebView, WebViewMessageEvent } from 'react-native-webview';
 import pjson from '../../package.json';
 import NativeStripeSdk from '../specs/NativeStripeSdkModule';
 import {
@@ -237,6 +237,98 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   const WebViewComponent = dynamicWebview?.WebView;
 
+  const onMessageCallback = useCallback(
+    async (event: WebViewMessageEvent) => {
+      const message = JSON.parse(event.nativeEvent.data) as {
+        type: string;
+        data?: unknown;
+      };
+
+      if (message.type === 'fetchClientSecret') {
+        const clientSecret = await fetchClientSecret().catch((error) => {
+          handleUnexpectedError(error);
+          return null;
+        });
+        if (!clientSecret) return;
+
+        ref.current?.injectJavaScript(`
+            window.clientSecretDeferred.resolve(${JSON.stringify(
+              clientSecret
+            )});
+          `);
+      } else if (message.type === 'debug') {
+        // message.data is of type string
+        console.debug(`[EmbeddedComponent ${component}]: ${message.data}`);
+      } else if (message.type === 'pageDidLoad') {
+        onPageDidLoad?.();
+      } else if (message.type === 'accountSessionClaimed') {
+        // message.data is of type {elementTagName: string, merchantId: string}
+      } else if (message.type === 'openFinancialConnections') {
+        // message.data is of type {clientSecret: string; id: string; connectedAccountId: string;}
+      } else if (message.type === 'closeWebView') {
+        // message.data is empty
+        callbacks?.onCloseWebView?.({});
+      } else if (message.type === 'callSupplementalFunction') {
+        // message.data is of type {[key]: {functionName: string; args: unknown[]; invocationId: string;}}
+      } else if (message.type === 'onSetterFunctionCalled') {
+        const { setter, value } = message.data as {
+          setter: string;
+          value: unknown;
+        };
+
+        if (setter === 'setOnLoaderStart') {
+          onLoaderStart?.(value as LoaderStart);
+        } else if (setter === 'setOnLoadError') {
+          onLoadError?.(value as LoadError);
+        } else {
+          // remove the 'set' prefix and lowercase the first letter
+          const functionName =
+            setter.charAt(3).toLowerCase() + setter.substring(4);
+          callbacks?.[functionName]?.(value);
+        }
+      } else if (message.type === 'openAuthenticatedWebView') {
+        const { url, id } = message.data as { id: string; url: string };
+
+        // On Android, we need to wait for the deep link callback
+        // On iOS, the promise resolves with the redirect URL
+        const handleAuthWebViewResult = (resultUrl: string | null) => {
+          ref.current?.injectJavaScript(`
+              (function() {
+                window.returnedFromAuthenticatedWebView(${JSON.stringify({
+                  id,
+                  url: resultUrl,
+                })});
+                true;
+              })();
+            `);
+        };
+
+        NativeStripeSdk.openAuthenticatedWebView(id, url)
+          .then((result) => {
+            if (Platform.OS === 'ios') {
+              // iOS returns the redirect URL directly
+              handleAuthWebViewResult(result?.url ?? null);
+            } else {
+              // Android: Store promise to be resolved by deep link listener
+              pendingAuthWebViewPromise.current = handleAuthWebViewResult;
+            }
+          })
+          .catch(handleUnexpectedError);
+      } else {
+        // unhandled message
+      }
+    },
+    [
+      callbacks,
+      component,
+      fetchClientSecret,
+      handleUnexpectedError,
+      onLoadError,
+      onLoaderStart,
+      onPageDidLoad,
+    ]
+  );
+
   if (!WebViewComponent) return null;
 
   return (
@@ -257,86 +349,7 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
       }}
       // Fixes injectedJavaScriptObject in Android https://github.com/react-native-webview/react-native-webview/issues/3326#issuecomment-3048111789
       injectedJavaScriptBeforeContentLoaded={'(function() {})();'}
-      onMessage={async (event) => {
-        const message = JSON.parse(event.nativeEvent.data) as {
-          type: string;
-          data?: unknown;
-        };
-
-        if (message.type === 'fetchClientSecret') {
-          const clientSecret = await fetchClientSecret().catch((error) => {
-            handleUnexpectedError(error);
-            return null;
-          });
-          if (!clientSecret) return;
-
-          ref.current?.injectJavaScript(`
-            window.clientSecretDeferred.resolve(${JSON.stringify(
-              clientSecret
-            )});
-          `);
-        } else if (message.type === 'debug') {
-          // message.data is of type string
-          console.debug(`[EmbeddedComponent ${component}]: ${message.data}`);
-        } else if (message.type === 'pageDidLoad') {
-          onPageDidLoad?.();
-        } else if (message.type === 'accountSessionClaimed') {
-          // message.data is of type {elementTagName: string, merchantId: string}
-        } else if (message.type === 'openFinancialConnections') {
-          // message.data is of type {clientSecret: string; id: string; connectedAccountId: string;}
-        } else if (message.type === 'closeWebView') {
-          // message.data is empty
-          callbacks?.onCloseWebView?.({});
-        } else if (message.type === 'callSupplementalFunction') {
-          // message.data is of type {[key]: {functionName: string; args: unknown[]; invocationId: string;}}
-        } else if (message.type === 'onSetterFunctionCalled') {
-          const { setter, value } = message.data as {
-            setter: string;
-            value: unknown;
-          };
-
-          if (setter === 'setOnLoaderStart') {
-            onLoaderStart?.(value as LoaderStart);
-          } else if (setter === 'setOnLoadError') {
-            onLoadError?.(value as LoadError);
-          } else {
-            // remove the 'set' prefix and lowercase the first letter
-            const functionName =
-              setter.charAt(3).toLowerCase() + setter.substring(4);
-            callbacks?.[functionName]?.(value);
-          }
-        } else if (message.type === 'openAuthenticatedWebView') {
-          const { url, id } = message.data as { id: string; url: string };
-
-          // On Android, we need to wait for the deep link callback
-          // On iOS, the promise resolves with the redirect URL
-          const handleAuthWebViewResult = (resultUrl: string | null) => {
-            ref.current?.injectJavaScript(`
-              (function() {
-                window.returnedFromAuthenticatedWebView(${JSON.stringify({
-                  id,
-                  url: resultUrl,
-                })});
-                true;
-              })();
-            `);
-          };
-
-          NativeStripeSdk.openAuthenticatedWebView(id, url)
-            .then((result) => {
-              if (Platform.OS === 'ios') {
-                // iOS returns the redirect URL directly
-                handleAuthWebViewResult(result?.url ?? null);
-              } else {
-                // Android: Store promise to be resolved by deep link listener
-                pendingAuthWebViewPromise.current = handleAuthWebViewResult;
-              }
-            })
-            .catch(handleUnexpectedError);
-        } else {
-          // unhandled message
-        }
-      }}
+      onMessage={onMessageCallback}
     />
   );
 }

From 146b31c22bc466f8c99bdea6f218e8e084469485 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Thu, 20 Nov 2025 17:05:19 +0100
Subject: [PATCH 15/21] Trying to fix deep linking on Android

---
 .../microsoft/reacttestapp/MainActivity.kt    | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 example/android/app/src/main/java/com/microsoft/reacttestapp/MainActivity.kt

diff --git a/example/android/app/src/main/java/com/microsoft/reacttestapp/MainActivity.kt b/example/android/app/src/main/java/com/microsoft/reacttestapp/MainActivity.kt
new file mode 100644
index 0000000000..c8e669520f
--- /dev/null
+++ b/example/android/app/src/main/java/com/microsoft/reacttestapp/MainActivity.kt
@@ -0,0 +1,40 @@
+package com.microsoft.reacttestapp
+
+import android.content.Intent
+import android.os.Bundle
+import android.util.Log
+
+/**
+ * Custom MainActivity that extends RNTA's base to handle deep links with singleTask.
+ * This file shadows the one in node_modules/react-native-test-app.
+ */
+class MainActivity : com.facebook.react.ReactActivity() {
+
+    companion object {
+        private const val TAG = "MainActivity"
+        const val REQUEST_CODE_PERMISSIONS = 42
+    }
+
+    private val testApp: TestApp
+        get() = application as TestApp
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        Log.d(TAG, "onCreate with intent: ${intent?.dataString}")
+    }
+
+    /**
+     * CRITICAL: This method handles deep links when the app is already running.
+     * With launchMode="singleTask", this is called instead of onCreate when
+     * a deep link brings the app to foreground.
+     */
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent) // ReactActivity handles sending to Linking module
+        Log.d(TAG, "onNewIntent with data: ${intent.dataString}")
+        setIntent(intent) // Update current intent
+    }
+
+    override fun getMainComponentName(): String? {
+        return testApp.manifest.singleApp ?: "example"
+    }
+}

From 3120ef3140da4545ff5a231294982f68bbe5da11 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Sat, 22 Nov 2025 00:04:07 +0100
Subject: [PATCH 16/21] Native navigation bar

---
 .../NavigationBarManager.kt                   |  40 +++++++
 .../reactnativestripesdk/NavigationBarView.kt | 108 ++++++++++++++++++
 .../reactnativestripesdk/StripeSdkPackage.kt  |   1 +
 example/ios/Podfile.lock                      |  10 +-
 ios/NavigationBarManager.m                    |  13 +++
 ios/NavigationBarManager.swift                |  17 +++
 ios/NavigationBarView.swift                   |  65 +++++++++++
 ios/NewArch/NavigationBarComponentView.h      |  10 ++
 ios/NewArch/NavigationBarComponentView.mm     |  86 ++++++++++++++
 package.json                                  |   1 +
 src/connect/Components.tsx                    |  25 ++--
 src/connect/NavigationBar.tsx                 |  29 +++++
 src/specs/NativeNavigationBar.ts              |  16 +++
 13 files changed, 401 insertions(+), 20 deletions(-)
 create mode 100644 android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
 create mode 100644 android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
 create mode 100644 ios/NavigationBarManager.m
 create mode 100644 ios/NavigationBarManager.swift
 create mode 100644 ios/NavigationBarView.swift
 create mode 100644 ios/NewArch/NavigationBarComponentView.h
 create mode 100644 ios/NewArch/NavigationBarComponentView.mm
 create mode 100644 src/connect/NavigationBar.tsx
 create mode 100644 src/specs/NativeNavigationBar.ts

diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
new file mode 100644
index 0000000000..4f7c2e86b5
--- /dev/null
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
@@ -0,0 +1,40 @@
+package com.reactnativestripesdk
+
+import com.facebook.react.bridge.Dynamic
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.viewmanagers.NavigationBarManagerDelegate
+import com.facebook.react.viewmanagers.NavigationBarManagerInterface
+
+@ReactModule(name = NavigationBarManager.REACT_CLASS)
+class NavigationBarManager :
+  SimpleViewManager<NavigationBarView>(),
+  NavigationBarManagerInterface<NavigationBarView> {
+  private val delegate = NavigationBarManagerDelegate(this)
+
+  override fun getName() = REACT_CLASS
+
+  override fun getDelegate() = delegate
+
+  override fun getExportedCustomDirectEventTypeConstants() =
+    mutableMapOf(
+      "onCloseButtonPress" to mutableMapOf("registrationName" to "onCloseButtonPress")
+    )
+
+  @ReactProp(name = "title")
+  override fun setTitle(
+    view: NavigationBarView,
+    title: String?,
+  ) {
+    view.setTitle(title)
+  }
+
+  override fun createViewInstance(reactContext: ThemedReactContext): NavigationBarView =
+    NavigationBarView(reactContext)
+
+  companion object {
+    const val REACT_CLASS = "NavigationBar"
+  }
+}
diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
new file mode 100644
index 0000000000..ea8e39e23a
--- /dev/null
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
@@ -0,0 +1,108 @@
+package com.reactnativestripesdk
+
+import android.annotation.SuppressLint
+import android.graphics.Color
+import android.view.Gravity
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import android.widget.ImageButton
+import android.widget.TextView
+import androidx.appcompat.widget.Toolbar
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.events.Event
+
+@SuppressLint("ViewConstructor")
+class NavigationBarView(
+  private val context: ThemedReactContext,
+) : FrameLayout(context) {
+  private val toolbar: Toolbar
+  private val titleTextView: TextView
+  private var titleText: String? = null
+
+  init {
+    // Create Toolbar
+    toolbar = Toolbar(context).apply {
+      layoutParams = LayoutParams(
+        LayoutParams.MATCH_PARENT,
+        LayoutParams.WRAP_CONTENT
+      )
+      setBackgroundColor(Color.WHITE)
+      elevation = 4f
+    }
+
+    // Create title TextView
+    titleTextView = TextView(context).apply {
+      textSize = 17f
+      setTextColor(Color.BLACK)
+      gravity = Gravity.CENTER
+    }
+
+    // Add title to toolbar
+    val titleParams = Toolbar.LayoutParams(
+      Toolbar.LayoutParams.WRAP_CONTENT,
+      Toolbar.LayoutParams.WRAP_CONTENT
+    ).apply {
+      gravity = Gravity.CENTER
+    }
+    toolbar.addView(titleTextView, titleParams)
+
+    // Create close button
+    val closeButton = ImageButton(context).apply {
+      setImageDrawable(
+        context.resources.getDrawable(
+          android.R.drawable.ic_menu_close_clear_cancel,
+          null
+        )
+      )
+      setBackgroundColor(Color.TRANSPARENT)
+      setOnClickListener {
+        dispatchCloseButtonPress()
+      }
+    }
+
+    // Add close button to toolbar
+    val buttonParams = Toolbar.LayoutParams(
+      Toolbar.LayoutParams.WRAP_CONTENT,
+      Toolbar.LayoutParams.WRAP_CONTENT
+    ).apply {
+      gravity = Gravity.END or Gravity.CENTER_VERTICAL
+      marginEnd = 16
+    }
+    toolbar.addView(closeButton, buttonParams)
+
+    // Add toolbar to this view
+    addView(toolbar)
+  }
+
+  fun setTitle(title: String?) {
+    titleText = title
+    titleTextView.text = title
+  }
+
+  private fun dispatchCloseButtonPress() {
+    val event = CloseButtonPressEvent(
+      context.surfaceId,
+      id
+    )
+    UIManagerHelper.getEventDispatcherForReactTag(context, id)?.dispatchEvent(event)
+  }
+
+  override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+    super.onMeasure(widthMeasureSpec, heightMeasureSpec)
+    // Set a fixed height for the navigation bar
+    val desiredHeight = (56 * resources.displayMetrics.density).toInt()
+    val newHeightMeasureSpec = MeasureSpec.makeMeasureSpec(desiredHeight, MeasureSpec.EXACTLY)
+    super.onMeasure(widthMeasureSpec, newHeightMeasureSpec)
+  }
+
+  private class CloseButtonPressEvent(
+    surfaceId: Int,
+    viewId: Int,
+  ) : Event<CloseButtonPressEvent>(surfaceId, viewId) {
+    override fun getEventName() = "onCloseButtonPress"
+
+    override fun getEventData() = Arguments.createMap()
+  }
+}
diff --git a/android/src/main/java/com/reactnativestripesdk/StripeSdkPackage.kt b/android/src/main/java/com/reactnativestripesdk/StripeSdkPackage.kt
index 35b8ed0988..9a9b08fc13 100644
--- a/android/src/main/java/com/reactnativestripesdk/StripeSdkPackage.kt
+++ b/android/src/main/java/com/reactnativestripesdk/StripeSdkPackage.kt
@@ -50,5 +50,6 @@ class StripeSdkPackage : BaseReactPackage() {
       AddToWalletButtonManager(reactContext),
       AddressSheetViewManager(),
       EmbeddedPaymentElementViewManager(),
+      NavigationBarManager(),
     )
 }
diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
index 467b18e698..e17853feb5 100644
--- a/example/ios/Podfile.lock
+++ b/example/ios/Podfile.lock
@@ -1712,7 +1712,7 @@ PODS:
     - StripePayments (= 25.0.1)
     - StripePaymentsUI (= 25.0.1)
     - StripeUICore (= 25.0.1)
-  - stripe-react-native (0.56.0):
+  - stripe-react-native (0.57.0):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1733,14 +1733,14 @@ PODS:
     - ReactCommon/turbomodule/bridging
     - ReactCommon/turbomodule/core
     - Stripe (~> 25.0.1)
-    - stripe-react-native/NewArch (= 0.56.0)
+    - stripe-react-native/NewArch (= 0.57.0)
     - StripeApplePay (~> 25.0.1)
     - StripeFinancialConnections (~> 25.0.1)
     - StripePayments (~> 25.0.1)
     - StripePaymentSheet (~> 25.0.1)
     - StripePaymentsUI (~> 25.0.1)
     - Yoga
-  - stripe-react-native/NewArch (0.56.0):
+  - stripe-react-native/NewArch (0.57.0):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -1767,7 +1767,7 @@ PODS:
     - StripePaymentSheet (~> 25.0.1)
     - StripePaymentsUI (~> 25.0.1)
     - Yoga
-  - stripe-react-native/Tests (0.56.0):
+  - stripe-react-native/Tests (0.57.0):
     - DoubleConversion
     - glog
     - hermes-engine
@@ -2135,7 +2135,7 @@ SPEC CHECKSUMS:
   RNScreens: 0d4cb9afe052607ad0aa71f645a88bb7c7f2e64c
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
   Stripe: 4728e3e0dd8df134e4a420ab504e929a93a815f0
-  stripe-react-native: e2dac3be3c2668207a7b7700663b852646a0e7d8
+  stripe-react-native: 92258f76847ff71a090d4665204226af84564fd3
   StripeApplePay: 43997281ace138a1c75a8f2d7be11925ea28644c
   StripeCore: 457c30e2fd3a7c4b274a5ad53d1ff03661eef2a0
   StripeFinancialConnections: 8c2e326f767fb014b53174b3a5f8592c0a45fa56
diff --git a/ios/NavigationBarManager.m b/ios/NavigationBarManager.m
new file mode 100644
index 0000000000..93c4a030ce
--- /dev/null
+++ b/ios/NavigationBarManager.m
@@ -0,0 +1,13 @@
+//
+//  NavigationBarManager.m
+//  stripe-react-native
+//
+
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+#import <React/RCTViewManager.h>
+
+@interface RCT_EXTERN_MODULE(NavigationBarManager, RCTViewManager)
+RCT_EXPORT_VIEW_PROPERTY(title, NSString)
+RCT_EXPORT_VIEW_PROPERTY(onCloseButtonPress, RCTDirectEventBlock)
+@end
diff --git a/ios/NavigationBarManager.swift b/ios/NavigationBarManager.swift
new file mode 100644
index 0000000000..90521b9e51
--- /dev/null
+++ b/ios/NavigationBarManager.swift
@@ -0,0 +1,17 @@
+//
+//  NavigationBarManager.swift
+//  stripe-react-native
+//
+
+import Foundation
+
+@objc(NavigationBarManager)
+class NavigationBarManager: RCTViewManager {
+    override func view() -> UIView! {
+        return NavigationBarView()
+    }
+
+    override class func requiresMainQueueSetup() -> Bool {
+        return true
+    }
+}
diff --git a/ios/NavigationBarView.swift b/ios/NavigationBarView.swift
new file mode 100644
index 0000000000..b473555d42
--- /dev/null
+++ b/ios/NavigationBarView.swift
@@ -0,0 +1,65 @@
+//
+//  NavigationBarView.swift
+//  stripe-react-native
+//
+
+import Foundation
+import UIKit
+
+@objc(NavigationBarView)
+public class NavigationBarView: UIView {
+    @objc public var onCloseButtonPress: RCTDirectEventBlock?
+
+    private var navigationBar: UINavigationBar!
+    private var navigationItem: UINavigationItem!
+
+    @objc public var title: NSString? {
+        didSet {
+            navigationItem.title = title as String?
+        }
+    }
+
+    override public init(frame: CGRect) {
+        super.init(frame: frame)
+        setupNavigationBar()
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    private func setupNavigationBar() {
+        // Create navigation bar
+        navigationBar = UINavigationBar(frame: .zero)
+        navigationBar.translatesAutoresizingMaskIntoConstraints = false
+
+        // Create navigation item
+        navigationItem = UINavigationItem()
+        navigationBar.items = [navigationItem]
+
+        // Add close button on the right
+        let closeButton = UIBarButtonItem(
+            barButtonSystemItem: .close,
+            target: self,
+            action: #selector(closeButtonTapped)
+        )
+        navigationItem.rightBarButtonItem = closeButton
+
+        // Add to view
+        addSubview(navigationBar)
+
+        // Setup constraints
+        NSLayoutConstraint.activate([
+            navigationBar.topAnchor.constraint(equalTo: topAnchor),
+            navigationBar.leadingAnchor.constraint(equalTo: leadingAnchor),
+            navigationBar.trailingAnchor.constraint(equalTo: trailingAnchor),
+            navigationBar.bottomAnchor.constraint(equalTo: bottomAnchor)
+        ])
+    }
+
+    @objc private func closeButtonTapped() {
+        if let onCloseButtonPress = onCloseButtonPress {
+            onCloseButtonPress([:])
+        }
+    }
+}
diff --git a/ios/NewArch/NavigationBarComponentView.h b/ios/NewArch/NavigationBarComponentView.h
new file mode 100644
index 0000000000..aabeb6b029
--- /dev/null
+++ b/ios/NewArch/NavigationBarComponentView.h
@@ -0,0 +1,10 @@
+#import <UIKit/UIKit.h>
+#import <React/RCTViewComponentView.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface NavigationBarComponentView : RCTViewComponentView
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/NewArch/NavigationBarComponentView.mm b/ios/NewArch/NavigationBarComponentView.mm
new file mode 100644
index 0000000000..ff81b4e8c1
--- /dev/null
+++ b/ios/NewArch/NavigationBarComponentView.mm
@@ -0,0 +1,86 @@
+#import "NavigationBarComponentView.h"
+
+#import <react/renderer/components/rnstripe/ComponentDescriptors.h>
+#import <react/renderer/components/rnstripe/EventEmitters.h>
+#import <react/renderer/components/rnstripe/Props.h>
+#import <react/renderer/components/rnstripe/RCTComponentViewHelpers.h>
+
+#import <React/RCTConversions.h>
+#import <React/RCTFabricComponentsPlugins.h>
+#import "StripeNewArchConversions.h"
+#import "StripeSwiftInterop.h"
+
+using namespace facebook::react;
+using namespace stripe::react;
+
+@interface NavigationBarComponentView () <RCTNavigationBarViewProtocol>
+@end
+
+@implementation NavigationBarComponentView {
+  NavigationBarView *_view;
+}
+
+// Needed because of this: https://github.com/facebook/react-native/pull/37274
++ (void)load
+{
+  [super load];
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps = std::make_shared<const NavigationBarProps>();
+    _props = defaultProps;
+    [self prepareView];
+  }
+
+  return self;
+}
+
+- (void)prepareView
+{
+  _view = [[NavigationBarView alloc] initWithFrame:self.frame];
+  self.contentView = _view;
+
+  __weak __typeof(self) weakSelf = self;
+
+  _view.onCloseButtonPress = ^(NSDictionary *event) {
+    __typeof(self) strongSelf = weakSelf;
+    if (!strongSelf || !strongSelf->_eventEmitter) {
+      return;
+    }
+    NavigationBarEventEmitter::OnCloseButtonPress emitterEvent = {};
+    std::static_pointer_cast<const NavigationBarEventEmitter>(strongSelf->_eventEmitter)
+        ->onCloseButtonPress(std::move(emitterEvent));
+  };
+}
+
+- (void)updateProps:(const facebook::react::Props::Shared &)props
+           oldProps:(const facebook::react::Props::Shared &)oldProps
+{
+  const auto &newViewProps = *std::static_pointer_cast<const NavigationBarProps>(props);
+
+  _view.title = RCTNSStringFromStringNilIfEmpty(newViewProps.title);
+
+  [super updateProps:props oldProps:oldProps];
+}
+
+#pragma mark - RCTComponentViewProtocol
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<NavigationBarComponentDescriptor>();
+}
+
+- (void)prepareForRecycle
+{
+  [super prepareForRecycle];
+  [self prepareView];
+}
+
+@end
+
+Class<RCTComponentViewProtocol> NavigationBarCls(void)
+{
+  return NavigationBarComponentView.class;
+}
diff --git a/package.json b/package.json
index b6d7655a97..1aeb8cdd9b 100644
--- a/package.json
+++ b/package.json
@@ -174,6 +174,7 @@
         "CardField": "CardFieldComponentView",
         "CardForm": "CardFormComponentView",
         "EmbeddedPaymentElementView": "EmbeddedPaymentElementViewComponentView",
+        "NavigationBar": "NavigationBarComponentView",
         "StripeContainer": "StripeContainerComponentView"
       }
     },
diff --git a/src/connect/Components.tsx b/src/connect/Components.tsx
index ec9de871e6..6f98bf189e 100644
--- a/src/connect/Components.tsx
+++ b/src/connect/Components.tsx
@@ -4,7 +4,6 @@ import {
   Modal,
   SafeAreaView,
   StyleSheet,
-  Text,
   View,
 } from 'react-native';
 import type {
@@ -14,7 +13,11 @@ import type {
   StepChange,
 } from './connectTypes';
 import { CommonComponentProps, EmbeddedComponent } from './EmbeddedComponent';
-import ModalCloseButton from './ModalCloseButton';
+import { NavigationBar } from './NavigationBar';
+
+// Export NavigationBar for external use
+export { NavigationBar } from './NavigationBar';
+export type { NavigationBarProps } from './NavigationBar';
 
 export function ConnectAccountOnboarding({
   title,
@@ -79,11 +82,11 @@ export function ConnectAccountOnboarding({
   return (
     <Modal visible={visible} animationType="slide">
       <SafeAreaView style={styles.flex1}>
-        <View style={styles.navBar}>
-          <View style={styles.navBarPlaceholder} />
-          <Text>{title}</Text>
-          <ModalCloseButton onPress={onExitCallback} />
-        </View>
+        <NavigationBar
+          title={title}
+          onCloseButtonPress={onExitCallback}
+          style={styles.navBar}
+        />
         <View style={styles.onboardingWrapper}>
           {loading ? (
             <ActivityIndicator size="large" style={styles.activityIndicator} />
@@ -186,14 +189,6 @@ export function ConnectPaymentDetails({
 const styles = StyleSheet.create({
   navBar: {
     height: 56,
-    paddingHorizontal: 8,
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    borderBottomWidth: StyleSheet.hairlineWidth,
-  },
-  navBarPlaceholder: {
-    width: 36,
   },
   flex1: {
     flex: 1,
diff --git a/src/connect/NavigationBar.tsx b/src/connect/NavigationBar.tsx
new file mode 100644
index 0000000000..4d2c64708f
--- /dev/null
+++ b/src/connect/NavigationBar.tsx
@@ -0,0 +1,29 @@
+import React, { forwardRef } from 'react';
+import type { ViewProps } from 'react-native';
+import NativeNavigationBar from '../specs/NativeNavigationBar';
+
+export interface NavigationBarProps extends ViewProps {
+  title?: string;
+  onCloseButtonPress?: () => void;
+}
+
+export const NavigationBar = forwardRef<any, NavigationBarProps>(
+  ({ title, onCloseButtonPress, ...rest }, ref) => {
+    return (
+      <NativeNavigationBar
+        ref={ref}
+        title={title}
+        onCloseButtonPress={
+          onCloseButtonPress
+            ? (_event) => {
+                onCloseButtonPress();
+              }
+            : undefined
+        }
+        {...rest}
+      />
+    );
+  }
+);
+
+NavigationBar.displayName = 'NavigationBar';
diff --git a/src/specs/NativeNavigationBar.ts b/src/specs/NativeNavigationBar.ts
new file mode 100644
index 0000000000..a6f75ee6cf
--- /dev/null
+++ b/src/specs/NativeNavigationBar.ts
@@ -0,0 +1,16 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+export type CloseButtonPressEvent = Readonly<{}>;
+
+export interface NativeProps extends ViewProps {
+  title?: string;
+  onCloseButtonPress?: DirectEventHandler<CloseButtonPressEvent>;
+}
+
+type ComponentType = HostComponent<NativeProps>;
+
+export default codegenNativeComponent<NativeProps>(
+  'NavigationBar'
+) as ComponentType;

From ef8630abccd2f813c1466e5476b0cd04cec44d34 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Sat, 22 Nov 2025 00:04:30 +0100
Subject: [PATCH 17/21] Native navigation bar

---
 .../NavigationBarManager.kt                   |  6 +-
 .../reactnativestripesdk/NavigationBarView.kt | 95 +++++++++++--------
 2 files changed, 55 insertions(+), 46 deletions(-)

diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
index 4f7c2e86b5..8c29622d8f 100644
--- a/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
@@ -1,6 +1,5 @@
 package com.reactnativestripesdk
 
-import com.facebook.react.bridge.Dynamic
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.SimpleViewManager
 import com.facebook.react.uimanager.ThemedReactContext
@@ -20,7 +19,7 @@ class NavigationBarManager :
 
   override fun getExportedCustomDirectEventTypeConstants() =
     mutableMapOf(
-      "onCloseButtonPress" to mutableMapOf("registrationName" to "onCloseButtonPress")
+      "onCloseButtonPress" to mutableMapOf("registrationName" to "onCloseButtonPress"),
     )
 
   @ReactProp(name = "title")
@@ -31,8 +30,7 @@ class NavigationBarManager :
     view.setTitle(title)
   }
 
-  override fun createViewInstance(reactContext: ThemedReactContext): NavigationBarView =
-    NavigationBarView(reactContext)
+  override fun createViewInstance(reactContext: ThemedReactContext): NavigationBarView = NavigationBarView(reactContext)
 
   companion object {
     const val REACT_CLASS = "NavigationBar"
diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
index ea8e39e23a..d284a7950b 100644
--- a/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
@@ -3,7 +3,6 @@ package com.reactnativestripesdk
 import android.annotation.SuppressLint
 import android.graphics.Color
 import android.view.Gravity
-import android.view.ViewGroup
 import android.widget.FrameLayout
 import android.widget.ImageButton
 import android.widget.TextView
@@ -23,53 +22,61 @@ class NavigationBarView(
 
   init {
     // Create Toolbar
-    toolbar = Toolbar(context).apply {
-      layoutParams = LayoutParams(
-        LayoutParams.MATCH_PARENT,
-        LayoutParams.WRAP_CONTENT
-      )
-      setBackgroundColor(Color.WHITE)
-      elevation = 4f
-    }
+    toolbar =
+      Toolbar(context).apply {
+        layoutParams =
+          LayoutParams(
+            LayoutParams.MATCH_PARENT,
+            LayoutParams.WRAP_CONTENT,
+          )
+        setBackgroundColor(Color.WHITE)
+        elevation = 4f
+      }
 
     // Create title TextView
-    titleTextView = TextView(context).apply {
-      textSize = 17f
-      setTextColor(Color.BLACK)
-      gravity = Gravity.CENTER
-    }
+    titleTextView =
+      TextView(context).apply {
+        textSize = 17f
+        setTextColor(Color.BLACK)
+        gravity = Gravity.CENTER
+      }
 
     // Add title to toolbar
-    val titleParams = Toolbar.LayoutParams(
-      Toolbar.LayoutParams.WRAP_CONTENT,
-      Toolbar.LayoutParams.WRAP_CONTENT
-    ).apply {
-      gravity = Gravity.CENTER
-    }
+    val titleParams =
+      Toolbar
+        .LayoutParams(
+          Toolbar.LayoutParams.WRAP_CONTENT,
+          Toolbar.LayoutParams.WRAP_CONTENT,
+        ).apply {
+          gravity = Gravity.CENTER
+        }
     toolbar.addView(titleTextView, titleParams)
 
     // Create close button
-    val closeButton = ImageButton(context).apply {
-      setImageDrawable(
-        context.resources.getDrawable(
-          android.R.drawable.ic_menu_close_clear_cancel,
-          null
+    val closeButton =
+      ImageButton(context).apply {
+        setImageDrawable(
+          context.resources.getDrawable(
+            android.R.drawable.ic_menu_close_clear_cancel,
+            null,
+          ),
         )
-      )
-      setBackgroundColor(Color.TRANSPARENT)
-      setOnClickListener {
-        dispatchCloseButtonPress()
+        setBackgroundColor(Color.TRANSPARENT)
+        setOnClickListener {
+          dispatchCloseButtonPress()
+        }
       }
-    }
 
     // Add close button to toolbar
-    val buttonParams = Toolbar.LayoutParams(
-      Toolbar.LayoutParams.WRAP_CONTENT,
-      Toolbar.LayoutParams.WRAP_CONTENT
-    ).apply {
-      gravity = Gravity.END or Gravity.CENTER_VERTICAL
-      marginEnd = 16
-    }
+    val buttonParams =
+      Toolbar
+        .LayoutParams(
+          Toolbar.LayoutParams.WRAP_CONTENT,
+          Toolbar.LayoutParams.WRAP_CONTENT,
+        ).apply {
+          gravity = Gravity.END or Gravity.CENTER_VERTICAL
+          marginEnd = 16
+        }
     toolbar.addView(closeButton, buttonParams)
 
     // Add toolbar to this view
@@ -82,14 +89,18 @@ class NavigationBarView(
   }
 
   private fun dispatchCloseButtonPress() {
-    val event = CloseButtonPressEvent(
-      context.surfaceId,
-      id
-    )
+    val event =
+      CloseButtonPressEvent(
+        context.surfaceId,
+        id,
+      )
     UIManagerHelper.getEventDispatcherForReactTag(context, id)?.dispatchEvent(event)
   }
 
-  override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+  override fun onMeasure(
+    widthMeasureSpec: Int,
+    heightMeasureSpec: Int,
+  ) {
     super.onMeasure(widthMeasureSpec, heightMeasureSpec)
     // Set a fixed height for the navigation bar
     val desiredHeight = (56 * resources.displayMetrics.density).toInt()

From 2001d485cbc602ebbe6c4098aec401321fb7b6ee Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Tue, 25 Nov 2025 12:53:27 +0100
Subject: [PATCH 18/21] Small changes

---
 .../ConnectAccountOnboardingScreen.tsx        | 19 +++--
 src/connect/EmbeddedComponent.tsx             | 77 ++++++++++---------
 2 files changed, 51 insertions(+), 45 deletions(-)

diff --git a/example/src/screens/ConnectAccountOnboardingScreen.tsx b/example/src/screens/ConnectAccountOnboardingScreen.tsx
index 23837b9637..267e575435 100644
--- a/example/src/screens/ConnectAccountOnboardingScreen.tsx
+++ b/example/src/screens/ConnectAccountOnboardingScreen.tsx
@@ -1,13 +1,21 @@
+import { useNavigation } from '@react-navigation/native';
 import { ConnectAccountOnboarding } from '@stripe/stripe-react-native';
+import { useCallback, useState } from 'react';
 import { Alert, StyleSheet, View } from 'react-native';
-import ConnectScreen from './ConnectScreen';
-import { useState } from 'react';
-import Button from '../components/Button';
 import { colors } from '../colors';
+import Button from '../components/Button';
+import ConnectScreen from './ConnectScreen';
 
 export default function ConnectAccountOnboardingScreen() {
+  const navigation = useNavigation();
   const [visible, setVisible] = useState(false);
 
+  const handleOnboardingExit = useCallback(() => {
+    console.log('ConnectAccountOnboarding onExit');
+    setVisible(false);
+    navigation.navigate('ConnectAccountOnboardingScreen');
+  }, [navigation]);
+
   return (
     <ConnectScreen>
       <View style={styles.container}>
@@ -20,10 +28,7 @@ export default function ConnectAccountOnboardingScreen() {
         {visible ? (
           <ConnectAccountOnboarding
             title="Connect Account Onboarding"
-            onExit={() => {
-              console.log('ConnectAccountOnboarding onExit');
-              setVisible(false);
-            }}
+            onExit={handleOnboardingExit}
             onLoadError={(err) => {
               Alert.alert('Error', err.error.message);
             }}
diff --git a/src/connect/EmbeddedComponent.tsx b/src/connect/EmbeddedComponent.tsx
index d4a6a15270..6ab1cbfad4 100644
--- a/src/connect/EmbeddedComponent.tsx
+++ b/src/connect/EmbeddedComponent.tsx
@@ -5,7 +5,13 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import { Linking, Platform, StyleProp, ViewStyle } from 'react-native';
+import {
+  AppState,
+  AppStateStatus,
+  Platform,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
 import type { WebView, WebViewMessageEvent } from 'react-native-webview';
 import pjson from '../../package.json';
 import NativeStripeSdk from '../specs/NativeStripeSdkModule';
@@ -108,9 +114,10 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
   } | null>(null);
 
   // Store pending authenticated webview promise (for Android Custom Tabs)
-  const pendingAuthWebViewPromise = useRef<((url: string) => void) | null>(
-    null
-  );
+  const pendingAuthWebViewPromise = useRef<{
+    id: string;
+    callback: (id: string, url: string | null) => void;
+  } | null>(null);
 
   const loadWebViewComponent = useCallback(async () => {
     if (dynamicWebview) return;
@@ -129,35 +136,26 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
     loadWebViewComponent();
   }, [loadWebViewComponent]);
 
-  // Handle deep links for authenticated webview callbacks (Android)
-  useEffect(() => {
-    const handleDeepLink = (url: string) => {
-      console.log('handleDeepLink url:', url);
-      if (url.startsWith('stripe-connect://')) {
-        console.log(`[EmbeddedComponent] Deep link received: ${url}`);
+  const appState = useRef<AppStateStatus>(AppState.currentState);
 
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (nextAppState) => {
+      if (
+        appState.current.match(/inactive|background/) &&
+        nextAppState === 'active'
+      ) {
         if (pendingAuthWebViewPromise.current) {
-          const resolve = pendingAuthWebViewPromise.current;
+          const { id, callback } = pendingAuthWebViewPromise.current;
           pendingAuthWebViewPromise.current = null;
-          resolve(url);
+          callback(id, null);
         }
       }
-    };
-
-    // Check for initial URL (when app is opened via deep link)
-    Linking.getInitialURL().then((url) => {
-      if (url) {
-        handleDeepLink(url);
-      }
-    });
 
-    // Listen for deep links while app is running
-    const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
-      handleDeepLink(url);
+      appState.current = nextAppState;
     });
 
     return () => {
-      linkingSubscription.remove();
+      subscription.remove();
     };
   }, []);
 
@@ -237,6 +235,18 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
   const WebViewComponent = dynamicWebview?.WebView;
 
+  const handleAuthWebViewResult = (id: string, resultUrl: string | null) => {
+    ref.current?.injectJavaScript(`
+      (function() {
+        window.returnedFromAuthenticatedWebView(${JSON.stringify({
+          id,
+          url: resultUrl,
+        })});
+        true;
+      })();
+    `);
+  };
+
   const onMessageCallback = useCallback(
     async (event: WebViewMessageEvent) => {
       const message = JSON.parse(event.nativeEvent.data) as {
@@ -291,26 +301,17 @@ export function EmbeddedComponent(props: EmbeddedComponentProps) {
 
         // On Android, we need to wait for the deep link callback
         // On iOS, the promise resolves with the redirect URL
-        const handleAuthWebViewResult = (resultUrl: string | null) => {
-          ref.current?.injectJavaScript(`
-              (function() {
-                window.returnedFromAuthenticatedWebView(${JSON.stringify({
-                  id,
-                  url: resultUrl,
-                })});
-                true;
-              })();
-            `);
-        };
-
         NativeStripeSdk.openAuthenticatedWebView(id, url)
           .then((result) => {
             if (Platform.OS === 'ios') {
               // iOS returns the redirect URL directly
-              handleAuthWebViewResult(result?.url ?? null);
+              handleAuthWebViewResult(id, result?.url ?? null);
             } else {
               // Android: Store promise to be resolved by deep link listener
-              pendingAuthWebViewPromise.current = handleAuthWebViewResult;
+              pendingAuthWebViewPromise.current = {
+                id,
+                callback: handleAuthWebViewResult,
+              };
             }
           })
           .catch(handleUnexpectedError);

From 3066e48fe62e5c813735375b12ec498bd92a122c Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Tue, 25 Nov 2025 13:02:12 +0100
Subject: [PATCH 19/21] Remember previous screen

---
 example/src/App.tsx                           | 12 +++-
 example/src/hooks/useNavigationPersistence.ts | 59 +++++++++++++++++++
 2 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 example/src/hooks/useNavigationPersistence.ts

diff --git a/example/src/App.tsx b/example/src/App.tsx
index 96df43eb06..b0402af797 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -4,6 +4,7 @@ import type { EmbeddedPaymentElementResult } from '@stripe/stripe-react-native';
 import React from 'react';
 import { StatusBar } from 'react-native';
 import { colors } from './colors';
+import { useNavigationPersistence } from './hooks/useNavigationPersistence';
 import ACHPaymentScreen from './screens/ACHPaymentScreen';
 import ACHSetupScreen from './screens/ACHSetupScreen';
 import AffirmScreen from './screens/AffirmScreen';
@@ -117,6 +118,12 @@ declare global {
 }
 
 export default function App() {
+  const { isReady, initialState, onStateChange } = useNavigationPersistence();
+
+  if (!isReady) {
+    return null;
+  }
+
   return (
     <>
       <StatusBar
@@ -124,7 +131,10 @@ export default function App() {
         barStyle="light-content"
         translucent
       />
-      <NavigationContainer>
+      <NavigationContainer
+        initialState={initialState}
+        onStateChange={onStateChange}
+      >
         <Stack.Navigator
           screenOptions={{
             headerTintColor: colors.white,
diff --git a/example/src/hooks/useNavigationPersistence.ts b/example/src/hooks/useNavigationPersistence.ts
new file mode 100644
index 0000000000..483e8d7760
--- /dev/null
+++ b/example/src/hooks/useNavigationPersistence.ts
@@ -0,0 +1,59 @@
+import type { InitialState } from '@react-navigation/native';
+import { useEffect, useState } from 'react';
+
+const PERSISTENCE_KEY = 'NAVIGATION_STATE_V1';
+
+// In-memory storage for navigation state
+let memoryStorage: Record<string, string> = {};
+
+// Simple in-memory storage adapter
+const storage = {
+  async getItem(key: string): Promise<string | null> {
+    return memoryStorage[key] || null;
+  },
+  async setItem(key: string, value: string): Promise<void> {
+    memoryStorage[key] = value;
+  },
+};
+
+export function useNavigationPersistence() {
+  const [isReady, setIsReady] = useState(false);
+  const [initialState, setInitialState] = useState<InitialState | undefined>();
+
+  useEffect(() => {
+    const restoreState = async () => {
+      try {
+        const savedStateString = await storage.getItem(PERSISTENCE_KEY);
+        const state = savedStateString
+          ? JSON.parse(savedStateString)
+          : undefined;
+
+        if (state !== undefined) {
+          setInitialState(state);
+        }
+      } catch (error) {
+        console.error('Failed to restore navigation state:', error);
+      } finally {
+        setIsReady(true);
+      }
+    };
+
+    if (!isReady) {
+      restoreState();
+    }
+  }, [isReady]);
+
+  const onStateChange = async (state: InitialState | undefined) => {
+    try {
+      await storage.setItem(PERSISTENCE_KEY, JSON.stringify(state));
+    } catch (error) {
+      console.error('Failed to save navigation state:', error);
+    }
+  };
+
+  return {
+    isReady,
+    initialState,
+    onStateChange,
+  };
+}

From 6f9688bd4adbdc79a566135f85edf22f0818f84f Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <155983930+gimenete-stripe@users.noreply.github.com>
Date: Tue, 25 Nov 2025 22:02:45 +0100
Subject: [PATCH 20/21] Apply suggestions from code review

Co-authored-by: maragues-stripe <maragues@stripe.com>
---
 .../main/java/com/reactnativestripesdk/NavigationBarView.kt | 6 +++---
 example/android/build.gradle                                | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
index d284a7950b..6d1de8183d 100644
--- a/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarView.kt
@@ -14,7 +14,7 @@ import com.facebook.react.uimanager.events.Event
 
 @SuppressLint("ViewConstructor")
 class NavigationBarView(
-  private val context: ThemedReactContext,
+  context: ThemedReactContext,
 ) : FrameLayout(context) {
   private val toolbar: Toolbar
   private val titleTextView: TextView
@@ -91,10 +91,10 @@ class NavigationBarView(
   private fun dispatchCloseButtonPress() {
     val event =
       CloseButtonPressEvent(
-        context.surfaceId,
+        getContext().surfaceId,
         id,
       )
-    UIManagerHelper.getEventDispatcherForReactTag(context, id)?.dispatchEvent(event)
+    UIManagerHelper.getEventDispatcherForReactTag(getContext(), id)?.dispatchEvent(event)
   }
 
   override fun onMeasure(
diff --git a/example/android/build.gradle b/example/android/build.gradle
index 82a30b76cf..31d4160365 100644
--- a/example/android/build.gradle
+++ b/example/android/build.gradle
@@ -48,7 +48,7 @@ subprojects { subproject ->
     subproject.afterEvaluate {
         subproject.tasks.matching { task ->
             task.name == 'generateAndroidManifest'
-        }.each { task ->
+        }.configureEach { task ->
             task.doLast {
                 def manifestFile = file("${subproject.buildDir}/generated/rnta/src/main/AndroidManifest.xml")
                 if (manifestFile.exists()) {

From c3c69f9c3b47a38e81cd2782f615d1c1dd3021e9 Mon Sep 17 00:00:00 2001
From: Alberto Gimeno <gimenete@stripe.com>
Date: Tue, 25 Nov 2025 22:05:36 +0100
Subject: [PATCH 21/21] Make onCloseButtonPress a constant

---
 .../main/java/com/reactnativestripesdk/NavigationBarManager.kt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
index 8c29622d8f..0b96a28c79 100644
--- a/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
+++ b/android/src/main/java/com/reactnativestripesdk/NavigationBarManager.kt
@@ -19,7 +19,7 @@ class NavigationBarManager :
 
   override fun getExportedCustomDirectEventTypeConstants() =
     mutableMapOf(
-      "onCloseButtonPress" to mutableMapOf("registrationName" to "onCloseButtonPress"),
+      EVENT_ON_CLOSE_BUTTON_PRESS to mutableMapOf("registrationName" to EVENT_ON_CLOSE_BUTTON_PRESS),
     )
 
   @ReactProp(name = "title")
@@ -34,5 +34,6 @@ class NavigationBarManager :
 
   companion object {
     const val REACT_CLASS = "NavigationBar"
+    private const val EVENT_ON_CLOSE_BUTTON_PRESS = "onCloseButtonPress"
   }
 }