react-native-fincra-checkout 1.0.0 → 1.0.2

package/lib/commonjs/components/FincraWebViewCheckout.js

@@ -53,12 +53,30 @@ const UrlHandler_1 = require("../utils/UrlHandler");
  * />
  * ```
  */
-function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure Checkout', headerBackgroundColor = '#FFFFFF', headerTintColor = '#000000', showCancelConfirmationDialog = false, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }) {
+function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure Checkout', headerBackgroundColor = '#FFFFFF', headerTintColor = '#000000', showCancelConfirmationDialog = false, showCloseButton = true, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }) {
     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 native callbacks after unmount must be ignored.
+    const settledRef = (0, react_1.useRef)(false);
+    const isMountedRef = (0, react_1.useRef)(false);
+    (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, []);
+    /** 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;
+        deliver();
+    }, []);
     // Fix #10: Stable ref for handleCancellation — the BackHandler effect
     // always calls through this ref, never capturing a stale closure.
     const handleCancellationRef = (0, react_1.useRef)(() => { });
@@ -74,24 +92,23 @@ function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure
     }, []); // safe: always calls through the ref
     // ── Completion handler ──────────────────────────────────────────────────────
     const handleCompletion = (0, react_1.useCallback)((url) => {
-        if (hasCompleted.current)
-            return;
-        hasCompleted.current = true;
         const params = UrlHandler_1.UrlHandler.extractResponseParams(url);
-        // Safely assume success if status is missing (matches Flutter behaviour)
-        const rawStatus = params['status']?.toLowerCase() ?? 'success';
-        if (UrlHandler_1.UrlHandler.isSuccessStatus(rawStatus)) {
-            const response = UrlHandler_1.UrlHandler.parsePaymentResponse(params);
-            onSuccess?.(response);
-        }
-        else {
-            const err = {
-                code: rawStatus,
-                message: params['message'] ?? 'Payment failed',
-            };
-            onFailed?.(err);
-        }
-    }, [onSuccess, onFailed]);
+        // `status` or `payment_status`; missing → success (sandbox omits it).
+        // Merchants must verify every payment server-side.
+        const rawStatus = UrlHandler_1.UrlHandler.extractStatus(params);
+        settle(() => {
+            if (UrlHandler_1.UrlHandler.isSuccessStatus(rawStatus)) {
+                onSuccess?.(UrlHandler_1.UrlHandler.parsePaymentResponse(params));
+            }
+            else {
+                const err = {
+                    code: rawStatus,
+                    message: params['message'] ?? 'Payment failed',
+                };
+                onFailed?.(err);
+            }
+        });
+    }, [settle, onSuccess, onFailed]);
     // ── URL interception ────────────────────────────────────────────────────────
     const onShouldStartLoadWithRequest = (0, react_1.useCallback)((request) => {
         if (UrlHandler_1.UrlHandler.isCompletionUrl(request.url, redirectUrl)) {
@@ -102,7 +119,7 @@ function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure
     }, [redirectUrl, handleCompletion]);
     // ── Cancellation ────────────────────────────────────────────────────────────
     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?', [
@@ -110,42 +127,44 @@ function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure
                 {
                     text: 'Yes',
                     style: 'destructive',
-                    onPress: () => {
-                        if (!hasCompleted.current) {
-                            hasCompleted.current = true;
-                            onCancelled?.();
-                        }
-                    },
+                    // May fire after unmount — settle() ignores it then.
+                    onPress: () => settle(() => onCancelled?.()),
                 },
             ]);
         }
         else {
-            hasCompleted.current = true;
-            onCancelled?.();
+            settle(() => onCancelled?.());
         }
-    }, [showCancelConfirmationDialog, onCancelled]);
+    }, [isActive, showCancelConfirmationDialog, settle, onCancelled]);
     // Keep the ref in sync after every render (Fix #10)
     (0, react_1.useEffect)(() => {
         handleCancellationRef.current = handleCancellation;
     });
-    // ── WebView error ───────────────────────────────────────────────────────────
-    const handleError = (0, react_1.useCallback)((syntheticEvent) => {
-        if (hasCompleted.current)
+    // ── Load errors ─────────────────────────────────────────────────────────────
+    // react-native-webview only reports main-frame failures via onError /
+    // onHttpError (sub-resource errors are filtered natively). Load errors never
+    // settle the payment: they show the recoverable Retry/Cancel overlay.
+    // Errors for the redirect URL are expected (we block that navigation).
+    const showLoadError = (0, react_1.useCallback)((url, err) => {
+        if (!isActive())
+            return;
+        if (url && UrlHandler_1.UrlHandler.isCompletionUrl(url, redirectUrl))
             return;
-        const { nativeEvent } = syntheticEvent;
-        const err = {
-            code: String(nativeEvent.code ?? 'webview_error'),
-            message: nativeEvent.description ?? 'A WebView error occurred.',
-        };
         setErrorState(err);
         setIsLoading(false);
-    }, []);
-    // ── HTTP error (non-completion URLs only) ───────────────────────────────────
-    const handleHttpError = (0, react_1.useCallback)((e) => {
-        if (!UrlHandler_1.UrlHandler.isCompletionUrl(e.nativeEvent.url, redirectUrl)) {
-            handleError(e);
-        }
-    }, [redirectUrl, handleError]);
+    }, [isActive, redirectUrl]);
+    const handleError = (0, react_1.useCallback)(({ nativeEvent }) => {
+        showLoadError(nativeEvent.url, {
+            code: String(nativeEvent.code ?? 'webview_error'),
+            message: nativeEvent.description ?? 'A WebView error occurred.',
+        });
+    }, [showLoadError]);
+    const handleHttpError = (0, react_1.useCallback)(({ nativeEvent }) => {
+        showLoadError(nativeEvent.url, {
+            code: String(nativeEvent.statusCode ?? 'http_error'),
+            message: nativeEvent.description || `HTTP error ${nativeEvent.statusCode}`,
+        });
+    }, [showLoadError]);
     // ── Retry handler ───────────────────────────────────────────────────────────
     const handleRetry = (0, react_1.useCallback)(() => {
         setErrorState(null);
@@ -155,45 +174,53 @@ function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure
     // ── Navigation state change (iOS fallback) ──────────────────────────────────
     // Fix #2: guard setIsLoading — don't flip loading state after completion.
     const onNavigationStateChange = (0, react_1.useCallback)((navState) => {
-        if (hasCompleted.current)
+        if (!isActive())
             return;
         if (navState.url &&
             UrlHandler_1.UrlHandler.isCompletionUrl(navState.url, redirectUrl)) {
             handleCompletion(navState.url);
         }
-    }, [redirectUrl, handleCompletion]);
+    }, [isActive, redirectUrl, handleCompletion]);
     // ── 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, source: { uri: checkoutUrl }, style: styles.webView, javaScriptEnabled: true, domStorageEnabled: true, startInLoadingState: false, onLoadStart: () => {
-                    if (!hasCompleted.current)
-                        setIsLoading(true);
-                }, onLoadEnd: () => {
-                    if (!hasCompleted.current)
-                        setIsLoading(false);
-                }, onError: handleError, onHttpError: handleHttpError, onShouldStartLoadWithRequest: onShouldStartLoadWithRequest, onNavigationStateChange: onNavigationStateChange, 
-                // Fix #14: restrict to HTTPS + about:blank — prevents intent:// and
-                // other dangerous scheme navigations in a payment context.
-                originWhitelist: ['https://*', 'about:blank'] }),
-            isLoading && !errorState && (react_1.default.createElement(react_native_1.View, { style: styles.loadingOverlay, pointerEvents: "none" }, 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, source: { uri: checkoutUrl }, style: styles.webView, javaScriptEnabled: true, domStorageEnabled: true, startInLoadingState: false, onLoadStart: () => {
+                        if (isActive())
+                            setIsLoading(true);
+                    }, onLoadEnd: () => {
+                        if (isActive())
+                            setIsLoading(false);
+                    }, onError: handleError, onHttpError: handleHttpError, onShouldStartLoadWithRequest: onShouldStartLoadWithRequest, onNavigationStateChange: onNavigationStateChange, 
+                    // Fix #14: restrict to HTTPS + about:blank — prevents intent:// and
+                    // other dangerous scheme navigations in a payment context.
+                    originWhitelist: ['https://*', 'about:blank'] }),
+                isLoading && !errorState && (react_1.default.createElement(react_native_1.View, { style: styles.loadingOverlay, pointerEvents: "none" }, 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"))))))))));
 }
 // ─── Styles ────────────────────────────────────────────────────────────────────
 const styles = react_native_1.StyleSheet.create({
+    provider: {
+        flex: 1,
+    },
     container: {
         flex: 1,
         backgroundColor: '#FFFFFF',

package/lib/commonjs/inline/JsBridge.js

@@ -40,22 +40,15 @@ function parseMessage(jsonString) {
         }
         const eventStr = typeof map['event'] === 'string' ? map['event'] : null;
         const event = _parseEvent(eventStr);
-        if (event === FincraBridgeEvent.Success &&
-            map['data'] != null &&
-            typeof map['data'] === 'object' &&
-            !Array.isArray(map['data'])) {
-            // Fix #5: use a spread copy instead of mutating the JSON.parse result
+        if (event === FincraBridgeEvent.Success) {
+            // A success event is always a success — even with missing/malformed
+            // data (empty references), so a real payment is never hidden.
             const rawData = map['data'];
-            const dataMap = { ...rawData };
-            // Ensure status is always set for the response
-            if (!dataMap['status']) {
-                dataMap['status'] = 'success';
-            }
-            // Coerce all values to strings (mirrors Flutter's `.map((k,v) => MapEntry(k, v.toString()))`)
-            const params = {};
-            for (const [k, v] of Object.entries(dataMap)) {
-                params[k] = String(v);
-            }
+            const params = rawData != null && typeof rawData === 'object' && !Array.isArray(rawData)
+                ? normalizeSuccessData(rawData)
+                : {};
+            if (!params['status'])
+                params['status'] = 'success';
             return { event, data: UrlHandler_1.UrlHandler.parsePaymentResponse(params) };
         }
         if (event === FincraBridgeEvent.Error &&
@@ -75,6 +68,19 @@ function parseMessage(jsonString) {
     }
 }
 // ── Internal ──────────────────────────────────────────────────────────────────
+/**
+ * Converts success data to a string map: objects/arrays are JSON-encoded,
+ * other values stringified, and `null`/`undefined` values dropped.
+ */
+function normalizeSuccessData(data) {
+    const params = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (v == null)
+            continue;
+        params[k] = typeof v === 'object' ? JSON.stringify(v) : String(v);
+    }
+    return params;
+}
 function _parseEvent(eventStr) {
     switch (eventStr) {
         case 'ready':

package/lib/commonjs/inline/htmlGenerator.js

@@ -1,14 +1,60 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildInlineOptions = buildInlineOptions;
+exports.toScriptJson = toScriptJson;
 exports.generateInlineHtml = generateInlineHtml;
 // ─── HTML Generator ────────────────────────────────────────────────────────────
 //
 // Mirrors `_generateHtml()` in flutter_fincra_checkout/lib/src/inline/inline_checkout.dart
 //
-// Security: ALL user-supplied string values are encoded via JSON.stringify(),
-// which escapes special characters and wraps in double-quotes, preventing
-// HTML/JS injection attacks (same approach as the Flutter implementation).
+// Security: the whole options object is encoded via toScriptJson() — JSON
+// plus escaping of `<`, `>`, `&`, U+2028 and U+2029 — so no input value can
+// inject JS or close the surrounding <script> element.
 const FINCRA_CDN_URL = 'https://unpkg.com/@fincra-engineering/checkout@2.2.0/dist/inline.min.js';
+/**
+ * Builds the plain options object for `Fincra.initialize()`.
+ *
+ * Optional fields are omitted entirely when absent. `customer.phoneNumber`
+ * is optional in Fincra's API: it is trimmed, and left out when blank.
+ *
+ * Pure function — internal, not part of the package's public API.
+ */
+function buildInlineOptions(config) {
+    const customer = {
+        name: config.customerName,
+        email: config.customerEmail,
+    };
+    const phone = config.customerPhoneNumber?.trim();
+    if (phone)
+        customer.phoneNumber = phone;
+    const options = {
+        key: config.publicKey,
+        amount: config.amount,
+        currency: config.currency.toUpperCase(),
+        feeBearer: config.feeBearer,
+        customer,
+    };
+    if (config.reference != null)
+        options.reference = config.reference;
+    if (config.paymentMethods != null && config.paymentMethods.length > 0) {
+        options.paymentMethods = config.paymentMethods;
+    }
+    return options;
+}
+/**
+ * JSON-encodes a value for embedding inside an inline `<script>` block.
+ * Besides JSON escaping, `<`, `>` and `&` are escaped so a value containing
+ * `</script>` or `<!--` cannot break out of the script element, and
+ * U+2028/U+2029 are escaped for older JS engines.
+ */
+function toScriptJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
 /**
  * Generates the self-contained HTML page that loads the Fincra inline JS SDK,
  * initializes it with the provided config, and posts lifecycle events back to
@@ -21,21 +67,8 @@ const FINCRA_CDN_URL = 'https://unpkg.com/@fincra-engineering/checkout@2.2.0/dis
  * @returns A complete HTML string to be loaded into a WebView.
  */
 function generateInlineHtml(config) {
-    // ── Safe encoding — all string values JSON-encoded to prevent injection ──
-    const key = JSON.stringify(config.publicKey);
-    const amount = config.amount; // numeric — safe to embed directly
-    const currency = JSON.stringify(config.currency.toUpperCase());
-    const name = JSON.stringify(config.customerName);
-    const email = JSON.stringify(config.customerEmail);
-    const phone = JSON.stringify(config.customerPhoneNumber);
-    const feeBearer = JSON.stringify(config.feeBearer);
-    // Optional fields — only emit the JS property if the value is present
-    const referenceLine = config.reference != null
-        ? `reference: ${JSON.stringify(config.reference)},`
-        : '';
-    const paymentMethodsLine = config.paymentMethods != null && config.paymentMethods.length > 0
-        ? `paymentMethods: ${JSON.stringify(config.paymentMethods)},`
-        : '';
+    // ── Safe encoding — every value goes through toScriptJson() ──
+    const optionsJson = toScriptJson(buildInlineOptions(config));
     return `<!DOCTYPE html>
 <html>
 <head>
@@ -81,25 +114,14 @@ function generateInlineHtml(config) {
       // SDK is available — signal "ready" so the host hides the loading spinner
       postToRN('ready', null);
 
-      var options = {
-        key: ${key},
-        amount: ${amount},
-        currency: ${currency},
-        ${referenceLine}
-        ${paymentMethodsLine}
-        feeBearer: ${feeBearer},
-        customer: {
-          name: ${name},
-          email: ${email},
-          phoneNumber: ${phone},
-        },
+      var options = Object.assign(${optionsJson}, {
         onClose: function() {
           postToRN('closed', null);
         },
         onSuccess: function(data) {
           postToRN('success', data);
         },
-      };
+      });
 
       Fincra.initialize(options);
     }

package/lib/commonjs/utils/UrlHandler.js

@@ -5,6 +5,7 @@ exports.UrlHandler = void 0;
 //
 // Direct TypeScript port of flutter_fincra_checkout/lib/src/utils/url_handler.dart
 // Mirrors UrlHandler.isCompletionUrl() and UrlHandler.extractResponseParams()
+const DEFAULT_PORTS = { http: '80', https: '443' };
 /**
  * Utilities for detecting Fincra payment completion URLs and
  * extracting normalized response parameters.
@@ -14,7 +15,8 @@ class UrlHandler {
      * Returns `true` if the given URL signals a Fincra payment completion.
      *
      * Logic (mirrors Flutter):
-     * 1. If `expectedRedirectUrl` is provided, check `url.startsWith(expectedRedirectUrl)`.
+     * 1. If `expectedRedirectUrl` is provided, the URL must match it strictly —
+     *    see {@link UrlHandler.matchesRedirectUrl}.
      * 2. Fallback: Fincra appends `status` (or `payment_status`) AND `reference` as query params.
      *
      * @param url - The URL being navigated to.
@@ -24,7 +26,7 @@ class UrlHandler {
         if (!url)
             return false;
         if (expectedRedirectUrl && expectedRedirectUrl.length > 0) {
-            return url.startsWith(expectedRedirectUrl);
+            return UrlHandler.matchesRedirectUrl(url, expectedRedirectUrl);
         }
         // Fallback: detect via query parameters
         try {
@@ -37,6 +39,47 @@ class UrlHandler {
             return false;
         }
     }
+    /**
+     * Strictly matches `url` against the expected redirect URL.
+     *
+     * - Scheme, host (case-insensitive) and port (default ports normalised) must be equal.
+     * - The path must equal the expected path or continue it at a `/` boundary
+     *   (trailing slashes ignored). An empty expected path matches any path.
+     * - Query string and fragment are ignored.
+     * - Falls back to `startsWith` only if the expected URL cannot be parsed.
+     *
+     * Prevents lookalike hosts such as `https://google.com.evil.io` matching
+     * `https://google.com`.
+     */
+    static matchesRedirectUrl(url, expectedRedirectUrl) {
+        const expected = UrlHandler._parseUrl(expectedRedirectUrl);
+        if (!expected)
+            return url.startsWith(expectedRedirectUrl);
+        const actual = UrlHandler._parseUrl(url);
+        if (!actual)
+            return false;
+        if (actual.scheme !== expected.scheme ||
+            actual.host !== expected.host ||
+            actual.port !== expected.port) {
+            return false;
+        }
+        if (expected.path === '')
+            return true;
+        return (actual.path === expected.path ||
+            actual.path.startsWith(`${expected.path}/`));
+    }
+    /**
+     * Reads the payment status from completion params, accepting either
+     * `status` or `payment_status`. Returns lower-case.
+     *
+     * A missing status is treated as `'success'` because the sandbox redirect
+     * omits it. **Always verify the payment on your backend** (Fincra API or
+     * webhook) before fulfilling an order.
+     */
+    static extractStatus(params) {
+        const raw = params['status'] ?? params['payment_status'];
+        return raw?.toLowerCase() ?? 'success';
+    }
     /**
      * Extracts all query parameters from the URL as a `Record<string, string>`.
      *
@@ -72,7 +115,7 @@ class UrlHandler {
         return {
             reference: finalRef,
             transactionId: finalTxId ?? '',
-            status: params['status'] ?? 'unknown',
+            status: params['status'] ?? params['payment_status'] ?? 'unknown',
             message: params['message'],
             rawResponse: params,
         };
@@ -87,6 +130,22 @@ class UrlHandler {
         return normalized === 'success' || normalized === 'successful';
     }
     // ── Internal ────────────────────────────────────────────────────────────────
+    /**
+     * Minimal absolute-URL parser. React Native's `URL` polyfill does not
+     * implement `hostname`/`port`, so this is done by hand.
+     * Returns `null` if the string is not an absolute `scheme://host` URL.
+     */
+    static _parseUrl(url) {
+        const match = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/?#]*@)?(\[[^\]]*\]|[^:/?#]*)(?::(\d*))?([^?#]*)/i.exec(url.trim());
+        if (!match || !match[2])
+            return null;
+        const scheme = match[1].toLowerCase();
+        const defaultPort = DEFAULT_PORTS[scheme] ?? '';
+        const port = match[3] || defaultPort;
+        // Normalise trailing slashes so `/callback/` equals `/callback`
+        const path = match[4].replace(/\/+$/, '');
+        return { scheme, host: match[2].toLowerCase(), port, path };
+    }
     /**
      * Parses URL query string into a `URLSearchParams`-like `Map`.
      * Works in React Native (no DOM `URL` API available).

package/lib/typescript/checkout/FincraCheckout.d.ts

@@ -61,7 +61,6 @@ export declare function _unregisterHostRef(): void;
  *   currency: 'NGN',
  *   customerEmail: 'user@example.com',
  *   customerName: 'Jane Doe',
- *   customerPhoneNumber: '08012345678',
  *   feeBearer: 'customer',
  * });
  *

package/lib/typescript/components/FincraInlineCheckout.d.ts

@@ -11,11 +11,10 @@ import type { InlineCheckoutConfig } from '../types';
  *   currency="NGN"
  *   customerEmail="user@example.com"
  *   customerName="John Doe"
- *   customerPhoneNumber="08012345678"
  *   feeBearer="customer"
  *   onSuccess={(res) => console.log(res.reference)}
  *   onCancelled={() => navigation.goBack()}
  * />
  * ```
  */
-export declare function FincraInlineCheckout({ headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, ...paymentConfig }: InlineCheckoutConfig): React.JSX.Element;
+export declare function FincraInlineCheckout({ headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, showCloseButton, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, ...paymentConfig }: InlineCheckoutConfig): React.JSX.Element;

package/lib/typescript/components/FincraWebViewCheckout.d.ts

@@ -15,4 +15,4 @@ export type FincraWebViewCheckoutProps = WebViewCheckoutConfig;
  * />
  * ```
  */
-export declare function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }: FincraWebViewCheckoutProps): React.JSX.Element;
+export declare function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, showCloseButton, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }: FincraWebViewCheckoutProps): React.JSX.Element;

package/lib/typescript/inline/JsBridge.d.ts

@@ -15,7 +15,10 @@ export declare enum FincraBridgeEvent {
 /** A parsed message posted by the Fincra JS SDK via `postMessage`. */
 export interface FincraBridgeMessage {
     event: FincraBridgeEvent;
-    /** Populated only for `success` and `error` events. */
+    /**
+     * Always populated for `success` events; populated for `error` events
+     * that carry a data object.
+     */
     data?: FincraPaymentResponse | {
         message: string;
     };

package/lib/typescript/inline/htmlGenerator.d.ts

@@ -7,6 +7,36 @@ import type { InlineCheckoutConfig } from '../types';
  * Fix #8: use a Pick instead of the full InlineCheckoutConfig.
  */
 export type InlinePaymentConfig = Pick<InlineCheckoutConfig, 'publicKey' | 'amount' | 'currency' | 'customerName' | 'customerEmail' | 'customerPhoneNumber' | 'feeBearer' | 'reference' | 'paymentMethods'>;
+/** Options passed to `Fincra.initialize()` (callbacks are added in the page). */
+export interface InlineSdkOptions {
+    key: string;
+    amount: number;
+    currency: string;
+    feeBearer: string;
+    reference?: string;
+    paymentMethods?: string[];
+    customer: {
+        name: string;
+        email: string;
+        phoneNumber?: string;
+    };
+}
+/**
+ * Builds the plain options object for `Fincra.initialize()`.
+ *
+ * Optional fields are omitted entirely when absent. `customer.phoneNumber`
+ * is optional in Fincra's API: it is trimmed, and left out when blank.
+ *
+ * Pure function — internal, not part of the package's public API.
+ */
+export declare function buildInlineOptions(config: InlinePaymentConfig): InlineSdkOptions;
+/**
+ * JSON-encodes a value for embedding inside an inline `<script>` block.
+ * Besides JSON escaping, `<`, `>` and `&` are escaped so a value containing
+ * `</script>` or `<!--` cannot break out of the script element, and
+ * U+2028/U+2029 are escaped for older JS engines.
+ */
+export declare function toScriptJson(value: unknown): string;
 /**
  * Generates the self-contained HTML page that loads the Fincra inline JS SDK,
  * initializes it with the provided config, and posts lifecycle events back to

package/lib/typescript/types/index.d.ts

@@ -37,7 +37,8 @@ export interface FincraPaymentResponse {
     /**
      * Full raw response map. All values are strings.
      * For inline mode, numeric/boolean fields from Fincra (e.g. `amount`) are
-     * coerced to strings to match the URL-params format used in WebView mode.
+     * coerced to strings to match the URL-params format used in WebView mode;
+     * nested objects/arrays are JSON-encoded and `null` values are dropped.
      */
     rawResponse: Record<string, string>;
 }
@@ -93,6 +94,13 @@ export interface BaseCheckoutProps {
     showCancelConfirmationDialog?: boolean;
     /** Custom loading indicator to display while the WebView is loading. */
     loadingComponent?: ReactNode;
+    /**
+     * Show the ✕ close button in the header. Default: true.
+     * If you hide it, users can still leave via the error screen's Cancel
+     * button and the Android back button — but on iOS there is no other way to
+     * leave while the page is loading, or if it hangs.
+     */
+    showCloseButton?: boolean;
     /** Custom close icon/element for the header. */
     closeIcon?: ReactNode;
     /** Custom error screen renderer for network/loading recovery. */
@@ -131,8 +139,11 @@ export interface InlineCheckoutConfig extends BaseCheckoutProps {
     customerEmail: string;
     /** Customer's full name. */
     customerName: string;
-    /** Customer's phone number. */
-    customerPhoneNumber: string;
+    /**
+     * Customer's phone number (optional in Fincra's API). Trimmed; when blank
+     * it is not sent to Fincra at all.
+     */
+    customerPhoneNumber?: string;
     /** Who bears the Fincra processing fee. */
     feeBearer: FeeBearer;
     /** Optional unique transaction reference. Fincra generates one if omitted. */