react-native-fincra-checkout 1.0.1 → 1.0.2

package/README.md

@@ -17,7 +17,7 @@ A **production-ready**, **100% TypeScript** React Native SDK for [Fincra Checkou
 - ✅ **Imperative API**: `await FincraCheckout.openWebView({...})` from anywhere
 - ✅ **Declarative API**: `<FincraWebViewCheckout />` and `<FincraInlineCheckout />`
 - ✅ **Strongly-typed result**: Discriminated union — `success | error | cancelled`
-- ✅ **URL interception**: Redirect URL prefix match + query-param fallback
+- ✅ **URL interception**: Strict redirect URL match (scheme, host, port, path boundary) + query-param fallback
 - ✅ **15-second init timeout** for the Inline mode
 - ✅ **Modern SafeAreaView** via `react-native-safe-area-context`
 - ✅ **Built-in Error Recovery & Offline Retry UI** with custom `renderError` prop support
@@ -55,6 +55,38 @@ cd ios && pod install
 > - For **Inline Checkout**: Only your **public key** (`pk_...`) is used. This is safe to bundle.
 >
 > Storing secret keys in client code exposes them to reverse engineering and can lead to fraudulent transactions.
+>
+> **Expo users:** every `EXPO_PUBLIC_*` environment variable is inlined into the JS bundle. Never give your secret key that prefix.
+
+## ⚠️ Verify every payment server-side
+
+> The SDK result is a **UX signal, not proof of payment.** A redirect or a JS callback can be missing data or be tampered with on the device, and in WebView mode a redirect **without** a `status` / `payment_status` parameter is reported as `success` (the Fincra sandbox omits it).
+>
+> **Before fulfilling an order, always verify the transaction on your backend** — via the Fincra API (look up the `reference`) or your Fincra webhook.
+
+---
+
+## Creating a hosted checkout link (server-side)
+
+WebView mode needs a hosted checkout link, created **on your server** with your secret key:
+
+```http
+POST https://sandboxapi.fincra.com/checkout/payments   (production: https://api.fincra.com/checkout/payments)
+api-key: <your SECRET key>
+x-pub-key: <your PUBLIC key>
+content-type: application/json
+
+{
+  "amount": 5000,
+  "currency": "NGN",
+  "customer": { "name": "Jane Doe", "email": "jane@example.com" },
+  "redirectUrl": "https://api.yourapp.com/payment/callback",
+  "reference": "ORDER-001",        // optional
+  "feeBearer": "business"          // optional
+}
+```
+
+The link is in the response at `data.link`. Return it to the app and pass it as `checkoutUrl`, with the same `redirectUrl`. The example app ships a script for this: `cd example && npm run checkout-link`.
 
 ---
 
@@ -142,7 +174,7 @@ async function handleInlinePayment() {
     currency: 'NGN',
     customerEmail: 'customer@example.com',
     customerName: 'Jane Doe',
-    customerPhoneNumber: '08012345678',
+    customerPhoneNumber: '08012345678', // optional
     feeBearer: 'customer',
     reference: 'ORDER-001', // optional — Fincra generates one if omitted
     paymentMethods: ['card', 'bank_transfer'], // optional
@@ -203,7 +235,6 @@ function InlinePaymentScreen() {
       currency="NGN"
       customerEmail="customer@example.com"
       customerName="John Doe"
-      customerPhoneNumber="08099887766"
       feeBearer="business"
       onSuccess={(response) => console.log(response)}
       onFailed={(error) => console.error(error)}
@@ -229,9 +260,9 @@ import type {
 } from 'react-native-fincra-checkout';
 
 // Discriminated union result
-const result: FincraCheckoutResult =
+type FincraCheckoutResult =
   | { type: 'success'; response: FincraPaymentResponse }
-  | { type: 'error';   error: FincraPaymentError }
+  | { type: 'error'; error: FincraPaymentError }
   | { type: 'cancelled' };
 ```
 
@@ -255,7 +286,9 @@ const result: FincraCheckoutResult =
 | `headerTintColor` | `string` | `'#000000'` | Nav bar text/icon color |
 | `showCancelConfirmationDialog` | `boolean` | `false` | Show Alert before closing |
 | `loadingComponent` | `ReactNode` | `ActivityIndicator` | Custom loading spinner |
+| `showCloseButton` | `boolean` | `true` | Show the ✕ in the header. If hidden, iOS users can't leave while the page loads or hangs (the error screen's Cancel and Android back still work) |
 | `closeIcon` | `ReactNode` | `✕` text | Custom close button content |
+| `renderError` | `(error, retry) => ReactNode` | built-in | Custom load-error screen |
 
 ### `WebViewCheckoutConfig`
 
@@ -269,11 +302,11 @@ const result: FincraCheckoutResult =
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `publicKey` | `string` | ✅ | Your Fincra public key (`pk_...`) |
-| `amount` | `number` | ✅ | Amount in smallest currency unit |
+| `amount` | `number` | ✅ | Amount to charge (a number, not a string) |
 | `currency` | `FincraCurrency` | ✅ | Payment currency |
 | `customerEmail` | `string` | ✅ | Customer email |
 | `customerName` | `string` | ✅ | Customer full name |
-| `customerPhoneNumber` | `string` | ✅ | Customer phone number |
+| `customerPhoneNumber` | `string` | — | Customer phone number. Trimmed; omitted from the request when blank |
 | `feeBearer` | `FeeBearer` | ✅ | `'business'` or `'customer'` |
 | `reference` | `string` | — | Custom transaction reference |
 | `paymentMethods` | `string[]` | — | Restrict to specific methods |
@@ -284,8 +317,17 @@ const result: FincraCheckoutResult =
 
 The WebView mode intercepts navigation requests:
 
-1. **If `redirectUrl` is set**: Any URL starting with `redirectUrl` triggers completion (prefix match — mirrors Flutter's `url.startsWith(redirectUrl)`).
-2. **Fallback** (no `redirectUrl`): Completion is detected when both `status` (or `payment_status`) **and** `reference` query params are present.
+1. **If `redirectUrl` is set**, a URL completes the checkout only if it matches strictly:
+   - same scheme, host (case-insensitive) and port (`:443` / `:80` defaults normalised);
+   - path equal to the redirect path, or continuing it at a `/` (`/callback`, `/callback/`, `/callback/done` match; `/callbacks-other` does not);
+   - query string and fragment are ignored; a redirect URL with no path matches any path on that host.
+
+   Lookalike hosts such as `https://myapp.com.evil.io/callback` never match.
+2. **Fallback** (no `redirectUrl`): completion is detected when both `status` (or `payment_status`) **and** `reference` query params are present.
+
+The status is read from `status`, falling back to `payment_status`. `success` / `successful` → `onSuccess`; any other value → `onFailed` with `code` = the status and `message` = the `message` param (or `'Payment failed'`). A **missing** status is treated as success — see **Verify every payment server-side** above.
+
+Page-load errors (main frame only) show a Retry / Cancel screen; they never report the payment as failed.
 
 Response parameters are normalized:
 - `customerReference` → `reference` (preferred)
@@ -300,7 +342,7 @@ Response parameters are normalized:
 npm test
 ```
 
-Tests cover `UrlHandler` (URL detection, param extraction, reference normalization) and `JsBridge` (event parsing, data coercion, malformed input handling) — no device or emulator required.
+Tests cover `UrlHandler` (strict redirect matching, status extraction, reference normalization), `JsBridge` (event parsing, data normalization), the inline HTML/options builder, and the checkout components and host (settle-once, late callbacks, back button) — no device or emulator required.
 
 ---
 

package/lib/commonjs/checkout/FincraCheckout.js

@@ -62,64 +62,61 @@ const FincraInlineCheckout_1 = require("../components/FincraInlineCheckout");
 exports.FincraCheckoutHost = (0, react_1.forwardRef)(function FincraCheckoutHost(_props, ref) {
     const [modalState, setModalState] = (0, react_1.useState)({ mode: null });
     const resolveRef = (0, react_1.useRef)(null);
-    // ── Resolve and dismiss ────────────────────────────────────────────────────
-    const resolve = (0, react_1.useCallback)((result) => {
-        setModalState({ mode: null });
-        resolveRef.current?.(result);
+    // Id of the session that may still settle; null once it has settled.
+    const activeSessionRef = (0, react_1.useRef)(null);
+    const nextSessionIdRef = (0, react_1.useRef)(0);
+    // ── Settle and dismiss ─────────────────────────────────────────────────────
+    // Single exit point. A session settles at most once: a late callback (e.g. a
+    // bridge message after the Android back button closed the modal) is
+    // ignored, so the merchant's callbacks never fire twice.
+    const settleSession = (0, react_1.useCallback)((sessionId, result, notify) => {
+        if (activeSessionRef.current !== sessionId)
+            return;
+        activeSessionRef.current = null;
+        const res = resolveRef.current;
         resolveRef.current = null;
-    }, []);
+        setModalState({ mode: null });
+        notify?.();
+        res?.(result);
+    }, [setModalState]);
     // ── Expose imperative methods via ref ──────────────────────────────────────
-    (0, react_1.useImperativeHandle)(ref, () => ({
+    (0, react_1.useImperativeHandle)(ref, () => {
         // Fix #1: guard against double-open — reject instead of orphaning the
         // pending Promise and silently clobbering resolveRef.
-        _openWebView(config) {
-            if (resolveRef.current) {
-                return Promise.reject(new Error('[FincraCheckout] A checkout session is already open. ' +
-                    'Await the current session before opening another.'));
-            }
-            return new Promise((res) => {
-                resolveRef.current = res;
-                setModalState({ mode: 'webview', webViewConfig: config });
-            });
-        },
-        _openInline(config) {
+        const open = (next) => {
             if (resolveRef.current) {
                 return Promise.reject(new Error('[FincraCheckout] A checkout session is already open. ' +
                     'Await the current session before opening another.'));
             }
             return new Promise((res) => {
+                const sessionId = ++nextSessionIdRef.current;
+                activeSessionRef.current = sessionId;
                 resolveRef.current = res;
-                setModalState({ mode: 'inline', inlineConfig: config });
+                setModalState({ ...next, sessionId });
             });
-        },
-    }), [ /* resolve not needed — used via resolveRef */]);
+        };
+        return {
+            _openWebView: (config) => open({ mode: 'webview', webViewConfig: config }),
+            _openInline: (config) => open({ mode: 'inline', inlineConfig: config }),
+        };
+    }, [setModalState]);
     const isVisible = modalState.mode !== null;
+    const sessionId = modalState.sessionId ?? -1;
     // ── Shared callback builders ───────────────────────────────────────────────
-    const buildCallbacks = (0, react_1.useCallback)((config) => ({
-        onSuccess: (response) => {
-            config.onSuccess?.(response);
-            resolve({ type: 'success', response });
-        },
-        onFailed: (error) => {
-            config.onFailed?.(error);
-            resolve({ type: 'error', error });
-        },
-        onCancelled: () => {
-            config.onCancelled?.();
-            resolve({ type: 'cancelled' });
-        },
-    }), [resolve]);
-    return (react_1.default.createElement(react_native_1.Modal, { visible: isVisible, animationType: "slide", presentationStyle: "fullScreen", statusBarTranslucent: true, onRequestClose: () => {
-            // Android hardware back — treat as cancellation
-            const cfg = modalState.webViewConfig ?? modalState.inlineConfig;
-            if (cfg) {
-                cfg.onCancelled?.();
-            }
-            resolve({ type: 'cancelled' });
-        } },
+    const buildCallbacks = (config) => ({
+        onSuccess: (response) => settleSession(sessionId, { type: 'success', response }, () => config.onSuccess?.(response)),
+        onFailed: (error) => settleSession(sessionId, { type: 'error', error }, () => config.onFailed?.(error)),
+        onCancelled: () => settleSession(sessionId, { type: 'cancelled' }, () => config.onCancelled?.()),
+    });
+    // Android hardware back (Modal intercepts it) — settles as cancelled.
+    const handleRequestClose = () => {
+        const cfg = modalState.webViewConfig ?? modalState.inlineConfig;
+        settleSession(sessionId, { type: 'cancelled' }, () => cfg?.onCancelled?.());
+    };
+    return (react_1.default.createElement(react_native_1.Modal, { visible: isVisible, animationType: "slide", presentationStyle: "fullScreen", statusBarTranslucent: true, onRequestClose: handleRequestClose },
         react_1.default.createElement(react_native_1.View, { style: styles.fullscreen },
-            modalState.mode === 'webview' && modalState.webViewConfig && (react_1.default.createElement(FincraWebViewCheckout_1.FincraWebViewCheckout, { ...modalState.webViewConfig, ...buildCallbacks(modalState.webViewConfig) })),
-            modalState.mode === 'inline' && modalState.inlineConfig && (react_1.default.createElement(FincraInlineCheckout_1.FincraInlineCheckout, { ...modalState.inlineConfig, ...buildCallbacks(modalState.inlineConfig) })))));
+            modalState.mode === 'webview' && modalState.webViewConfig && (react_1.default.createElement(FincraWebViewCheckout_1.FincraWebViewCheckout, { key: sessionId, ...modalState.webViewConfig, ...buildCallbacks(modalState.webViewConfig) })),
+            modalState.mode === 'inline' && modalState.inlineConfig && (react_1.default.createElement(FincraInlineCheckout_1.FincraInlineCheckout, { key: sessionId, ...modalState.inlineConfig, ...buildCallbacks(modalState.inlineConfig) })))));
 });
 // ─── Singleton Ref ─────────────────────────────────────────────────────────────
 // A module-level ref that FincraCheckout.open*() calls are routed through.
@@ -163,7 +160,6 @@ function _unregisterHostRef() {
  *   currency: 'NGN',
  *   customerEmail: 'user@example.com',
  *   customerName: 'Jane Doe',
- *   customerPhoneNumber: '08012345678',
  *   feeBearer: 'customer',
  * });
  *

package/lib/commonjs/components/FincraInlineCheckout.js

@@ -61,43 +61,63 @@ const INIT_TIMEOUT_MS = 15000;
  *   currency="NGN"
  *   customerEmail="user@example.com"
  *   customerName="John Doe"
- *   customerPhoneNumber="08012345678"
  *   feeBearer="customer"
  *   onSuccess={(res) => console.log(res.reference)}
  *   onCancelled={() => navigation.goBack()}
  * />
  * ```
  */
-function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroundColor = '#FFFFFF', headerTintColor = '#000000', showCancelConfirmationDialog = false, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, 
+function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroundColor = '#FFFFFF', headerTintColor = '#000000', showCancelConfirmationDialog = false, showCloseButton = true, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, 
 // Payment fields — everything the HTML generator needs
 ...paymentConfig }) {
     const [isLoading, setIsLoading] = (0, react_1.useState)(true);
     const [errorState, setErrorState] = (0, react_1.useState)(null);
     const [reloadKey, setReloadKey] = (0, react_1.useState)(0);
     const webViewRef = (0, react_1.useRef)(null);
-    const hasCompleted = (0, react_1.useRef)(false);
+    // `settledRef`: a result (success / error / cancel) has been delivered.
+    // `isMountedRef`: late bridge messages after unmount must be ignored.
+    const settledRef = (0, react_1.useRef)(false);
+    const isMountedRef = (0, react_1.useRef)(false);
     const timeoutRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+    /** True while callbacks may still update state or deliver a result. */
+    const isActive = (0, react_1.useCallback)(() => isMountedRef.current && !settledRef.current, []);
+    const clearInitTimeout = (0, react_1.useCallback)(() => {
+        if (timeoutRef.current)
+            clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+    }, []);
+    /** Single exit point — delivers at most one result per session. */
+    const settle = (0, react_1.useCallback)((deliver) => {
+        if (!isMountedRef.current || settledRef.current)
+            return;
+        settledRef.current = true;
+        clearInitTimeout();
+        deliver();
+    }, [clearInitTimeout]);
     // Fix #3: Memoize HTML generation — prevents WebView reload on parent re-renders.
     // The HTML is intentionally generated once per mount; payment params are immutable.
     const configJson = JSON.stringify(paymentConfig);
     const html = (0, react_1.useMemo)(() => (0, htmlGenerator_1.generateInlineHtml)(JSON.parse(configJson)), [configJson]);
-    // ── 15-second init timeout ──────────────────────────────────────────────────
+    // ── 15-second init timeout (re-armed on every Retry) ────────────────────────
     (0, react_1.useEffect)(() => {
         timeoutRef.current = setTimeout(() => {
-            if (!hasCompleted.current) {
-                const err = {
-                    code: 'timeout',
-                    message: 'Fincra Checkout failed to load. Please check your internet connection.',
-                };
-                setErrorState(err);
-                setIsLoading(false);
-            }
+            if (!isActive())
+                return;
+            const err = {
+                code: 'timeout',
+                message: 'Fincra Checkout failed to load. Please check your internet connection.',
+            };
+            setErrorState(err);
+            setIsLoading(false);
         }, INIT_TIMEOUT_MS);
-        return () => {
-            if (timeoutRef.current)
-                clearTimeout(timeoutRef.current);
-        };
-    }, []);
+        return clearInitTimeout;
+    }, [reloadKey, isActive, clearInitTimeout]);
     // Fix #10: Stable ref for handleCancellation so the BackHandler effect
     // doesn't need it as a dependency and never captures a stale closure.
     const handleCancellationRef = (0, react_1.useRef)(() => { });
@@ -111,30 +131,26 @@ function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroun
         });
         return () => subscription.remove();
     }, []); // safe: always calls through the ref
-    // ── WebView error ───────────────────────────────────────────────────────────
-    const handleError = (0, react_1.useCallback)((syntheticEvent) => {
-        if (hasCompleted.current)
+    // ── Load errors (main frame only — see FincraWebViewCheckout) ───────────────
+    const showLoadError = (0, react_1.useCallback)((err) => {
+        if (!isActive())
             return;
-        const { nativeEvent } = syntheticEvent;
-        const err = {
-            code: String(nativeEvent.code ?? 'webview_error'),
-            message: nativeEvent.description ?? 'A WebView error occurred.',
-        };
+        clearInitTimeout();
         setErrorState(err);
         setIsLoading(false);
-    }, [setErrorState, setIsLoading]);
-    // ── HTTP error ──────────────────────────────────────────────────────────────
-    const handleHttpError = (0, react_1.useCallback)((syntheticEvent) => {
-        if (hasCompleted.current)
-            return;
-        const { nativeEvent } = syntheticEvent;
-        const err = {
+    }, [isActive, clearInitTimeout, setErrorState, setIsLoading]);
+    const handleError = (0, react_1.useCallback)(({ nativeEvent }) => {
+        showLoadError({
+            code: String(nativeEvent.code ?? 'webview_error'),
+            message: nativeEvent.description ?? 'A WebView error occurred.',
+        });
+    }, [showLoadError]);
+    const handleHttpError = (0, react_1.useCallback)(({ nativeEvent }) => {
+        showLoadError({
             code: String(nativeEvent.statusCode ?? 'http_error'),
             message: nativeEvent.description ?? 'A WebView HTTP error occurred.',
-        };
-        setErrorState(err);
-        setIsLoading(false);
-    }, [setErrorState, setIsLoading]);
+        });
+    }, [showLoadError]);
     // ── Retry handler ───────────────────────────────────────────────────────────
     const handleRetry = (0, react_1.useCallback)(() => {
         setErrorState(null);
@@ -142,46 +158,36 @@ function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroun
         setReloadKey((key) => key + 1);
     }, [setErrorState, setIsLoading, setReloadKey]);
     // ── JS Bridge message handler ───────────────────────────────────────────────
+    // Messages that arrive after the session settled (e.g. closed via the
+    // Android back button) or after unmount are ignored.
     const handleMessage = (0, react_1.useCallback)((event) => {
-        if (hasCompleted.current)
+        if (!isActive())
             return;
         const msg = (0, JsBridge_1.parseMessage)(event.nativeEvent.data);
         switch (msg.event) {
             case JsBridge_1.FincraBridgeEvent.Ready:
                 // SDK loaded — clear timeout and hide the loading spinner
-                if (timeoutRef.current)
-                    clearTimeout(timeoutRef.current);
+                clearInitTimeout();
                 setIsLoading(false);
                 break;
-            case JsBridge_1.FincraBridgeEvent.Success:
-                hasCompleted.current = true;
-                if (timeoutRef.current)
-                    clearTimeout(timeoutRef.current);
-                if (msg.data && 'reference' in msg.data) {
-                    onSuccess?.(msg.data);
-                }
-                else {
-                    onCancelled?.();
-                }
+            case JsBridge_1.FincraBridgeEvent.Success: {
+                // Always a success, even without data (empty references).
+                const response = msg.data;
+                settle(() => onSuccess?.(response));
                 break;
+            }
             case JsBridge_1.FincraBridgeEvent.Closed:
-                hasCompleted.current = true;
-                if (timeoutRef.current)
-                    clearTimeout(timeoutRef.current);
-                onCancelled?.();
+                settle(() => onCancelled?.());
                 break;
             case JsBridge_1.FincraBridgeEvent.Error: {
-                hasCompleted.current = true;
-                if (timeoutRef.current)
-                    clearTimeout(timeoutRef.current);
-                const errorMessage = msg.data && 'message' in msg.data
+                const errorMessage = msg.data && 'message' in msg.data && msg.data.message
                     ? msg.data.message
                     : 'An unknown error occurred';
                 const err = {
                     code: 'fincra_sdk_error',
                     message: errorMessage,
                 };
-                onFailed?.(err);
+                settle(() => onFailed?.(err));
                 break;
             }
             case JsBridge_1.FincraBridgeEvent.Unknown:
@@ -189,11 +195,19 @@ function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroun
                 // Ignore — mirrors Flutter's `case FincraBridgeEvent.unknown: break;`
                 break;
         }
-    }, [onSuccess, onFailed, onCancelled, setIsLoading]);
+    }, [
+        isActive,
+        clearInitTimeout,
+        settle,
+        setIsLoading,
+        onSuccess,
+        onFailed,
+        onCancelled,
+    ]);
     // ── Cancellation ────────────────────────────────────────────────────────────
     // Fix #4: Use static Alert import — no dynamic require() needed.
     const handleCancellation = (0, react_1.useCallback)(() => {
-        if (hasCompleted.current)
+        if (!isActive())
             return;
         if (showCancelConfirmationDialog) {
             react_native_1.Alert.alert('Cancel Payment?', 'Are you sure you want to cancel this payment?', [
@@ -201,24 +215,15 @@ function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroun
                 {
                     text: 'Yes',
                     style: 'destructive',
-                    onPress: () => {
-                        if (!hasCompleted.current) {
-                            hasCompleted.current = true;
-                            if (timeoutRef.current)
-                                clearTimeout(timeoutRef.current);
-                            onCancelled?.();
-                        }
-                    },
+                    // May fire after unmount — settle() ignores it then.
+                    onPress: () => settle(() => onCancelled?.()),
                 },
             ]);
         }
         else {
-            hasCompleted.current = true;
-            if (timeoutRef.current)
-                clearTimeout(timeoutRef.current);
-            onCancelled?.();
+            settle(() => onCancelled?.());
         }
-    }, [showCancelConfirmationDialog, onCancelled]);
+    }, [isActive, showCancelConfirmationDialog, settle, onCancelled]);
     // Keep the ref in sync with the latest handleCancellation (Fix #10)
     (0, react_1.useEffect)(() => {
         handleCancellationRef.current = handleCancellation;
@@ -226,30 +231,35 @@ function FincraInlineCheckout({ headerTitle = 'Secure Checkout', headerBackgroun
     // ── Computed status bar style (Fix #11) ─────────────────────────────────────
     const statusBarStyle = headerTintColor === '#000000' ? 'dark-content' : 'light-content';
     // ── Render ──────────────────────────────────────────────────────────────────
-    return (react_1.default.createElement(react_native_safe_area_context_1.SafeAreaView, { style: styles.container },
-        react_1.default.createElement(react_native_1.StatusBar, { barStyle: statusBarStyle, backgroundColor: headerBackgroundColor }),
-        react_1.default.createElement(react_native_1.View, { style: [styles.header, { backgroundColor: headerBackgroundColor }] },
-            react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.closeButton, onPress: handleCancellation, accessibilityLabel: "Close checkout", accessibilityRole: "button", hitSlop: { top: 10, bottom: 10, left: 10, right: 10 } }, closeIcon ?? (react_1.default.createElement(react_native_1.Text, { style: [styles.closeIcon, { color: headerTintColor }] }, "\u2715"))),
-            react_1.default.createElement(react_native_1.Text, { style: [styles.headerTitle, { color: headerTintColor }], numberOfLines: 1 }, headerTitle),
-            react_1.default.createElement(react_native_1.View, { style: styles.closeButton })),
-        react_1.default.createElement(react_native_1.View, { style: styles.webViewContainer },
-            react_1.default.createElement(react_native_webview_1.WebView, { key: reloadKey, ref: webViewRef, 
-                // Fix #14: restrict to HTTPS + about:blank only (removed wildcard)
-                originWhitelist: ['https://*', 'about:blank'], source: { html }, style: styles.webView, javaScriptEnabled: true, domStorageEnabled: true, onMessage: handleMessage, onError: handleError, onHttpError: handleHttpError, 
-                // Inject the ReactNativeWebView bridge shim so older WKWebView versions work
-                injectedJavaScriptBeforeContentLoaded: WEBVIEW_BRIDGE_SHIM, 
-                // Allow the external CDN script to load
-                mixedContentMode: "always" }),
-            isLoading && !errorState && (react_1.default.createElement(react_native_1.View, { style: styles.loadingOverlay },
-                react_1.default.createElement(react_native_1.View, { style: styles.loadingCard }, loadingComponent ?? (react_1.default.createElement(react_native_1.ActivityIndicator, { size: "large", color: "#0066FF" }))))),
-            errorState && (react_1.default.createElement(react_native_1.View, { style: styles.errorOverlay }, renderError ? (renderError(errorState, handleRetry)) : (react_1.default.createElement(react_native_1.View, { style: styles.errorContainer },
-                react_1.default.createElement(react_native_1.Text, { style: styles.errorIcon }, "\u26A0\uFE0F"),
-                react_1.default.createElement(react_native_1.Text, { style: styles.errorTitle }, "Connection Error"),
-                react_1.default.createElement(react_native_1.Text, { style: styles.errorMessage }, errorState.message),
-                react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.retryButton, onPress: handleRetry, accessibilityRole: "button", accessibilityLabel: "Retry loading checkout" },
-                    react_1.default.createElement(react_native_1.Text, { style: styles.retryButtonText }, "Retry")),
-                react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.cancelButton, onPress: handleCancellation, accessibilityRole: "button", accessibilityLabel: "Cancel checkout" },
-                    react_1.default.createElement(react_native_1.Text, { style: styles.cancelButtonText }, "Cancel")))))))));
+    // Own SafeAreaProvider: SafeAreaView reads insets from the nearest provider,
+    // and a Modal (FincraCheckoutHost) is a separate native tree. Without one the
+    // insets are 0 and the header sits under the status bar / Dynamic Island,
+    // where iOS swallows taps. Nested providers are fine if the app has its own.
+    return (react_1.default.createElement(react_native_safe_area_context_1.SafeAreaProvider, { style: styles.provider },
+        react_1.default.createElement(react_native_safe_area_context_1.SafeAreaView, { style: styles.container },
+            react_1.default.createElement(react_native_1.StatusBar, { barStyle: statusBarStyle, backgroundColor: headerBackgroundColor }),
+            react_1.default.createElement(react_native_1.View, { style: [styles.header, { backgroundColor: headerBackgroundColor }] },
+                showCloseButton ? (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.closeButton, onPress: handleCancellation, accessibilityLabel: "Close checkout", accessibilityRole: "button", hitSlop: { top: 10, bottom: 10, left: 10, right: 10 } }, closeIcon ?? (react_1.default.createElement(react_native_1.Text, { style: [styles.closeIcon, { color: headerTintColor }] }, "\u2715")))) : (react_1.default.createElement(react_native_1.View, { style: styles.closeButton })),
+                react_1.default.createElement(react_native_1.Text, { style: [styles.headerTitle, { color: headerTintColor }], numberOfLines: 1 }, headerTitle),
+                react_1.default.createElement(react_native_1.View, { style: styles.closeButton })),
+            react_1.default.createElement(react_native_1.View, { style: styles.webViewContainer },
+                react_1.default.createElement(react_native_webview_1.WebView, { key: reloadKey, ref: webViewRef, 
+                    // Fix #14: restrict to HTTPS + about:blank only (removed wildcard)
+                    originWhitelist: ['https://*', 'about:blank'], source: { html }, style: styles.webView, javaScriptEnabled: true, domStorageEnabled: true, onMessage: handleMessage, onError: handleError, onHttpError: handleHttpError, 
+                    // Inject the ReactNativeWebView bridge shim so older WKWebView versions work
+                    injectedJavaScriptBeforeContentLoaded: WEBVIEW_BRIDGE_SHIM, 
+                    // Allow the external CDN script to load
+                    mixedContentMode: "always" }),
+                isLoading && !errorState && (react_1.default.createElement(react_native_1.View, { style: styles.loadingOverlay },
+                    react_1.default.createElement(react_native_1.View, { style: styles.loadingCard }, loadingComponent ?? (react_1.default.createElement(react_native_1.ActivityIndicator, { size: "large", color: "#0066FF" }))))),
+                errorState && (react_1.default.createElement(react_native_1.View, { style: styles.errorOverlay }, renderError ? (renderError(errorState, handleRetry)) : (react_1.default.createElement(react_native_1.View, { style: styles.errorContainer },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.errorIcon }, "\u26A0\uFE0F"),
+                    react_1.default.createElement(react_native_1.Text, { style: styles.errorTitle }, "Connection Error"),
+                    react_1.default.createElement(react_native_1.Text, { style: styles.errorMessage }, errorState.message),
+                    react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.retryButton, onPress: handleRetry, accessibilityRole: "button", accessibilityLabel: "Retry loading checkout" },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.retryButtonText }, "Retry")),
+                    react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.cancelButton, onPress: handleCancellation, accessibilityRole: "button", accessibilityLabel: "Cancel checkout" },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.cancelButtonText }, "Cancel"))))))))));
 }
 // ─── WebView Bridge Shim ───────────────────────────────────────────────────────
 // Ensures `window.ReactNativeWebView` is available before page scripts run.
@@ -269,6 +279,9 @@ const WEBVIEW_BRIDGE_SHIM = `
 `;
 // ─── Styles ────────────────────────────────────────────────────────────────────
 const styles = react_native_1.StyleSheet.create({
+    provider: {
+        flex: 1,
+    },
     container: {
         flex: 1,
         backgroundColor: '#FFFFFF',