@glomopay/react-native-sdk 2.0.2 → 3.1.0

package/src/use-standard-checkout.tsx

@@ -0,0 +1,1203 @@
+/** Main SDK hook for the GlomoPay Standard Checkout flow */
+
+import React, { useState, useRef, useMemo, useCallback, useEffect } from "react";
+import { Platform, PermissionsAndroid, type NativeSyntheticEvent } from "react-native";
+
+import { type WebViewNavigation, type WebViewMessageEvent, type WebView } from "react-native-webview";
+
+import { InjectionScripts } from "./injections/index";
+import { initializeSegment } from "./config/segment";
+import { resolveServerConfig, type GlomoServer } from "./config/base";
+import { isValidPublicKey, isValidOrderId, isValidUrl, isValidPaymentPayload, safeCallback } from "./utils/validation";
+import { checkDeviceCompliance, isComplianceCheckAvailable } from "./utils/device-compliance";
+import { type SdkError, type CheckoutAnalyticsTrackers, standardCheckoutTrackers } from "./utils/analytics";
+
+import { type GlomoBankTransferPayload, type GlomoPayViaBankConnectionPayload } from "./types/checkout";
+import { type StandardCheckoutStatus, type GlomoStandardCheckoutPayload } from "./types/standard-checkout";
+
+/** Android-only WebView permission request, not yet in react-native-webview type definitions */
+export interface WebViewPermissionRequest {
+    nativeEvent: { resources: string[] };
+    grant: (resources: string[]) => void;
+    deny: () => void;
+}
+
+/** The options for the useStandardCheckout hook */
+export interface UseStandardCheckoutOptions {
+    server?: GlomoServer;
+    publicKey: string;
+    orderId: string;
+    onPaymentSuccess: (payload: GlomoStandardCheckoutPayload) => void;
+    onPaymentFailure: (payload: GlomoStandardCheckoutPayload) => void;
+    onConnectionError?: (error: unknown) => void;
+    onPaymentTerminate?: () => void;
+    onSdkError?: (error: Array<SdkError>) => void;
+    onBankTransferSubmitted?: (payload: GlomoBankTransferPayload | null | undefined) => void;
+    onPayViaBankCompleted?: (payload: { status: string }) => void;
+    onPayViaBankBankConnectionSuccessful?: (payload: GlomoPayViaBankConnectionPayload | null | undefined) => void;
+    onUserRefusedCameraPermissions?: () => void;
+    devMode?: boolean;
+}
+
+/** The return values for the useStandardCheckout hook */
+export interface UseStandardCheckoutReturn {
+    start: () => boolean;
+    status: StandardCheckoutStatus;
+    showCheckout: boolean;
+    flowWebViewUrl: string;
+    showFlowWebView: boolean;
+    checkoutUrl: string;
+    mainWebViewRef: React.RefObject<WebView>;
+    flowWebViewRef: React.RefObject<WebView>;
+    handleMainWebViewMessage: (event: WebViewMessageEvent) => void;
+    handleFlowWebViewMessage: (event: WebViewMessageEvent) => void;
+    handleError: (
+        syntheticEvent: NativeSyntheticEvent<{ code?: number; domain?: string; description?: string }>
+    ) => void;
+    handleHttpError: (syntheticEvent: NativeSyntheticEvent<{ statusCode: number; description?: string }>) => void;
+    handleNavigationStateChange: (navState: WebViewNavigation) => void;
+    handlePermissionRequest: (request: WebViewPermissionRequest) => void;
+    handleModalBackButton: () => void;
+    handleFlowBack: () => void;
+    injectedMain?: string;
+    injectedFlow?: string;
+}
+
+/**
+ * Internal options for useStandardCheckout.
+ * Used by subscription checkout to inject subscription-specific analytics trackers.
+ * Not exported to merchants.
+ */
+export interface UseStandardCheckoutInternalOptions {
+    analyticsTrackers?: CheckoutAnalyticsTrackers;
+    _skipOrderIdValidation?: boolean;
+}
+
+/** The main SDK hook for the GlomoPay Standard Checkout flow */
+export function useStandardCheckout(
+    {
+        server,
+        publicKey,
+        orderId,
+        onPaymentSuccess,
+        onPaymentFailure,
+        onConnectionError,
+        onPaymentTerminate,
+        onSdkError,
+        onBankTransferSubmitted,
+        onPayViaBankCompleted,
+        onPayViaBankBankConnectionSuccessful,
+        onUserRefusedCameraPermissions,
+        devMode = false,
+    }: UseStandardCheckoutOptions,
+    mockMode: boolean,
+    internalOptions?: UseStandardCheckoutInternalOptions
+): UseStandardCheckoutReturn {
+    // Resolving analytics trackers - defaults to standard, subscription flow overrides
+    const trackers = internalOptions?.analyticsTrackers ?? standardCheckoutTrackers;
+    // Refs for the WebViews
+    const mainWebViewRef = useRef<WebView>(null);
+    const flowWebViewRef = useRef<WebView>(null);
+
+    // Deduplication guard - prevents firing onPayViaBankCompleted twice when both main and flow WebViews emit the event
+    const payViaBankCompletedHandledRef = useRef(false);
+
+    // Resolving checkout URL from the selected SDK server
+    const serverConfig = useMemo(() => resolveServerConfig(server), [server]);
+    const baseCheckoutUrl = serverConfig.baseUrl.standardCheckout;
+
+    /**
+     * The main checkout URL for the standard flow
+     */
+    const checkoutUrl = useMemo(() => {
+        try {
+            // Building the query string manually since URLSearchParams is not fully supported in React Native
+            const baseParams = [`orderId=${encodeURIComponent(orderId)}`];
+            const mode = mockMode ? "mock" : "live";
+            const params = baseParams.concat(
+                `mode=${encodeURIComponent(mode)}`,
+                `publicKey=${encodeURIComponent(publicKey)}`
+            );
+            const queryString = params.join("&");
+
+            // Handling base URL with or without existing query parameters
+            const separator = baseCheckoutUrl.includes("?") ? "&" : "?";
+            const finalUrl = `${baseCheckoutUrl}${separator}${queryString}`;
+
+            // Validating the final URL
+            if (!isValidUrl(finalUrl)) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Generated invalid checkout URL:", finalUrl);
+                }
+                return "";
+            }
+
+            if (devMode) {
+                console.log("[Glomo-RN-SDK Standard] Checkout URL:", finalUrl);
+            }
+            return finalUrl;
+        } catch (error) {
+            if (devMode) {
+                console.error("[Glomo-RN-SDK Standard] Error building checkout URL:", error);
+            }
+            return "";
+        }
+    }, [baseCheckoutUrl, orderId, publicKey, mockMode, devMode]);
+
+    // Checkout status state
+    const [status, setStatus] = useState<StandardCheckoutStatus>("ready");
+
+    // Visibility state for the main checkout modal
+    const [showCheckout, setShowCheckout] = useState(false);
+
+    const [showFlowWebView, setShowFlowWebView] = useState(false);
+    const [flowWebViewUrl, setFlowWebViewUrl] = useState<string>("");
+
+    useEffect(() => {
+        if (devMode) {
+            console.log(
+                `[Glomo-RN-SDK Standard] State snapshot: status=${status}, showCheckout=${showCheckout}, showFlowWebView=${showFlowWebView}, flowWebViewUrl=${flowWebViewUrl || "<empty>"}`
+            );
+        }
+    }, [devMode, status, showCheckout, showFlowWebView, flowWebViewUrl]);
+
+    // Handler for the WebView errors
+    const handleError = useCallback(
+        (syntheticEvent: NativeSyntheticEvent<{ code?: number; domain?: string; description?: string }>) => {
+            try {
+                const { nativeEvent } = syntheticEvent;
+
+                // Now checking for connection errors
+
+                // iOS: NSURLErrorDomain errors
+                const isIOSConnectionError =
+                    nativeEvent?.domain === "NSURLErrorDomain" &&
+                    (nativeEvent?.code === -1004 || // Could not connect to the server
+                        nativeEvent?.code === -1009 || // The Internet connection appears to be offline
+                        nativeEvent?.code === -1001 || // The request timed out
+                        nativeEvent?.code === -1003); // Cannot find host
+
+                // Android: Network errors
+                const description = nativeEvent?.description || "";
+                const isAndroidConnectionError =
+                    typeof description === "string" &&
+                    (description.includes("ERR_EMPTY_RESPONSE") || // Server unreachable
+                        description.includes("ERR_CONNECTION_REFUSED") || // Connection refused
+                        description.includes("ERR_NAME_NOT_RESOLVED") || // DNS resolution failed
+                        description.includes("ERR_INTERNET_DISCONNECTED") || // No internet
+                        description.includes("ERR_CONNECTION_TIMED_OUT") || // Connection timeout
+                        description.includes("ERR_NETWORK_CHANGED")); // Network changed
+
+                if (isIOSConnectionError || isAndroidConnectionError) {
+                    if (devMode) {
+                        console.error("[Glomo-RN-SDK Standard] Connection error:", nativeEvent);
+                    }
+
+                    // Closing the checkout modal
+                    setShowCheckout(false);
+                    setShowFlowWebView(false);
+                    setFlowWebViewUrl("");
+
+                    // Calling onConnectionError callback if provided
+                    safeCallback(onConnectionError, [nativeEvent], "onConnectionError", devMode);
+                    // Tracking connection error
+                    trackers.trackConnectionError(
+                        orderId,
+                        nativeEvent?.code,
+                        publicKey,
+                        devMode,
+                        mockMode,
+                        checkoutUrl
+                    );
+                } else {
+                    if (devMode) {
+                        console.error("[Glomo-RN-SDK Standard] WebView error:", nativeEvent);
+                    }
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Error in handleError:", error);
+                }
+            }
+        },
+        [devMode, onConnectionError, checkoutUrl, orderId, publicKey, mockMode, trackers]
+    );
+
+    // Handler for the WebView HTTP errors
+    const handleHttpError = useCallback(
+        (syntheticEvent: NativeSyntheticEvent<{ statusCode: number; description?: string }>) => {
+            try {
+                const { nativeEvent } = syntheticEvent;
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] WebView HTTP error:", nativeEvent);
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Error in handleHttpError:", error);
+                }
+            }
+        },
+        [devMode]
+    );
+
+    /**
+     * Handler for the main WebView messages.
+     * The main WebView hosts the checkout page. Messages arrive as JSON strings from the injected
+     * JavaScript bridge and include console logs, window.open/close interceptions, and payment
+     * lifecycle events (success, failure, terminate, bank transfer, pay via bank).
+     */
+    const handleMainWebViewMessage = useCallback(
+        (event: WebViewMessageEvent) => {
+            try {
+                // Extracting and validating the raw message data from the WebView event
+                const data = event.nativeEvent?.data;
+                if (!data || typeof data !== "string") {
+                    if (devMode) {
+                        console.warn("[Glomo-RN-SDK Standard] Invalid message data from MainWebView");
+                    }
+                    // Tracking invalid message received
+                    trackers.trackInvalidMessageReceived(
+                        "main",
+                        data,
+                        checkoutUrl,
+                        orderId,
+                        publicKey,
+                        devMode,
+                        mockMode,
+                        checkoutUrl
+                    );
+                    return;
+                }
+
+                const message = JSON.parse(data);
+                if (devMode) {
+                    console.log("[Glomo-RN-SDK Standard] MainWebView Message received:", message.type, message);
+                }
+
+                // Forwarding console messages from the injected script to the React Native console
+                if (message.type === "console") {
+                    if (devMode) {
+                        const level = message.level || "log";
+                        console.log(`[Glomo-RN-SDK Standard] [WebView ${level.toUpperCase()}]`, message.message);
+                    }
+                    return;
+                }
+
+                // Intercepting window.open calls - opening the target URL in the flow WebView overlay
+                if (message.type === "window.open") {
+                    const url = message.url;
+                    if (url && typeof url === "string" && isValidUrl(url)) {
+                        if (devMode) {
+                            console.log(`[Glomo-RN-SDK Standard] window.open called from MainWebView: ${url}`);
+                        }
+                        setFlowWebViewUrl(url);
+                        setShowFlowWebView(true);
+                        // Tracking window.open interception
+                        trackers.trackWindowOpen("main", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    } else {
+                        if (devMode) {
+                            console.log(
+                                "[Glomo-RN-SDK Standard] Invalid URL in window.open from MainWebView:",
+                                url,
+                                typeof url === "undefined" ? "undefined" : ""
+                            );
+                        }
+                    }
+                    return;
+                }
+
+                // Intercepting window.close calls - closing the flow WebView overlay
+                if (message.type === "window.close") {
+                    if (devMode) {
+                        console.log("[Glomo-RN-SDK Standard] Child window close requested from MainWebView");
+                    }
+                    setShowFlowWebView(false);
+                    setFlowWebViewUrl("");
+                    // Tracking window.close interception
+                    trackers.trackWindowClose("main", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    return;
+                }
+
+                // Handling merchant JS callbacks on flow completion (payment events, lifecycle events)
+                if (message.type === "message" && message.message) {
+                    const messageData = message.message;
+                    const messageType = messageData?.type;
+
+                    // Handling payment success - closing checkout and notifying the merchant
+                    if (messageType === "payment.success" || messageType === "payment.complete") {
+                        const paymentMessage = messageData;
+                        const payload = paymentMessage?.payload;
+
+                        if (isValidPaymentPayload(payload)) {
+                            if (devMode) {
+                                console.log("[Glomo-RN-SDK Standard] Payment successful via merchant callback!");
+                            }
+                            setShowCheckout(false);
+                            setShowFlowWebView(false);
+                            setFlowWebViewUrl("");
+                            setStatus("payment_successful");
+                            safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
+                            // Tracking payment success callback
+                            trackers.trackPaymentSuccess(
+                                payload.orderId,
+                                payload.paymentId,
+                                publicKey,
+                                devMode,
+                                mockMode,
+                                checkoutUrl
+                            );
+                        } else {
+                            if (devMode) {
+                                console.error("[Glomo-RN-SDK Standard] Invalid payment success payload:", payload);
+                            }
+                        }
+                        return;
+                    }
+
+                    // Handling payment failure - closing checkout and notifying the merchant
+                    if (messageType === "payment.failure" || messageType === "payment.error") {
+                        const paymentMessage = messageData;
+                        const payload = paymentMessage?.payload;
+
+                        if (isValidPaymentPayload(payload)) {
+                            if (devMode) {
+                                console.error("[Glomo-RN-SDK Standard] Payment failed via merchant callback");
+                            }
+                            setShowCheckout(false);
+                            setShowFlowWebView(false);
+                            setFlowWebViewUrl("");
+                            setStatus("payment_failed");
+                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
+                            // Tracking payment failure callback
+                            trackers.trackPaymentFailure(
+                                payload.orderId,
+                                payload.paymentId,
+                                publicKey,
+                                devMode,
+                                mockMode,
+                                checkoutUrl
+                            );
+                        } else {
+                            if (devMode) {
+                                console.error("[Glomo-RN-SDK Standard] Invalid payment failure payload:", payload);
+                            }
+                        }
+                        return;
+                    }
+
+                    // Handling bank transfer submission - user has submitted transfer details
+                    if (messageType === "payment.bank_transfer_submitted") {
+                        const payload = messageData?.payload;
+                        if (devMode) {
+                            console.log("[Glomo-RN-SDK Standard] Bank transfer submitted:", payload);
+                        }
+                        setShowCheckout(false);
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        setStatus("bank_transfer_submitted");
+                        safeCallback(
+                            onBankTransferSubmitted,
+                            [
+                                {
+                                    orderId: payload?.orderId ?? "",
+                                    senderAccountNumber: payload?.senderAccountNumber ?? "",
+                                    transactionReference: payload?.transactionReference ?? "",
+                                },
+                            ],
+                            "onBankTransferSubmitted",
+                            devMode
+                        );
+                        trackers.trackBankTransferSubmitted(orderId, publicKey, devMode, mockMode, checkoutUrl);
+                        return;
+                    }
+
+                    // Handling pay via bank - bank connection successful event (informational, no status change)
+                    if (messageType === "pay_via_bank.bank.connection_successful") {
+                        const payload = messageData?.payload;
+                        if (devMode) {
+                            console.log("[Glomo-RN-SDK Standard] Pay via bank - bank connection successful:", payload);
+                        }
+                        safeCallback(
+                            onPayViaBankBankConnectionSuccessful,
+                            [
+                                {
+                                    bankIdentifier: payload?.bankIdentifier ?? "",
+                                    cooldownPeriodInMinutes: payload?.cooldownPeriodInMinutes ?? 0,
+                                    bankName: payload?.bankName ?? "",
+                                    bankImageSrc: payload?.bankImageSrc ?? "",
+                                    bankImageAlt: payload?.bankImageAlt ?? "",
+                                },
+                            ],
+                            "onPayViaBankBankConnectionSuccessful",
+                            devMode
+                        );
+                        trackers.trackPayViaBankBankConnectionSuccessful(
+                            orderId,
+                            publicKey,
+                            payload?.bankIdentifier ?? "",
+                            devMode,
+                            mockMode,
+                            checkoutUrl
+                        );
+                        return;
+                    }
+
+                    /**
+                     * Handling the generic glomoCheckoutJourneyTerminate event.
+                     * This event is fired by the checkout page when the pay via bank (lean/open finance)
+                     * flow completes. The deduplication ref prevents firing the callback twice when both
+                     * main and flow WebViews emit this event.
+                     */
+                    if (messageType === "glomoCheckoutJourneyTerminate") {
+                        // Deduplication - both main and flow WebViews can emit this event
+                        if (payViaBankCompletedHandledRef.current) {
+                            if (devMode) {
+                                console.log(
+                                    "[Glomo-RN-SDK Standard] Pay via bank completed already handled, ignoring duplicate"
+                                );
+                            }
+                            return;
+                        }
+                        payViaBankCompletedHandledRef.current = true;
+
+                        const payload = messageData?.payload;
+                        if (devMode) {
+                            console.log("[Glomo-RN-SDK Standard] Pay via bank completed via MainWebView:", payload);
+                        }
+                        setShowFlowWebView(false);
+                        setShowCheckout(false);
+                        setFlowWebViewUrl("");
+                        setStatus("pay_via_bank_completed");
+                        safeCallback(
+                            onPayViaBankCompleted,
+                            [{ status: payload?.status ?? "unknown" }],
+                            "onPayViaBankCompleted",
+                            devMode
+                        );
+                        trackers.trackPayViaBankCompleted(
+                            orderId,
+                            publicKey,
+                            payload?.status ?? "unknown",
+                            devMode,
+                            mockMode,
+                            checkoutUrl
+                        );
+                        return;
+                    }
+
+                    // Handling checkout.closed events
+                    if (messageType === "checkout.closed") {
+                        if (devMode) {
+                            console.log("[Glomo-RN-SDK Standard] Checkout closed event received");
+                        }
+                        setShowCheckout(false);
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        safeCallback(onPaymentTerminate, [], "onPaymentTerminate", devMode);
+                        // Tracking payment terminate callback
+                        trackers.trackPaymentTerminate(
+                            orderId,
+                            "checkout_closed",
+                            publicKey,
+                            devMode,
+                            mockMode,
+                            checkoutUrl
+                        );
+                        return;
+                    }
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Error parsing MainWebView message:", error);
+                }
+            }
+        },
+        [
+            onPaymentSuccess,
+            onPaymentFailure,
+            onPaymentTerminate,
+            onBankTransferSubmitted,
+            onPayViaBankCompleted,
+            onPayViaBankBankConnectionSuccessful,
+            devMode,
+            mockMode,
+            orderId,
+            publicKey,
+            checkoutUrl,
+            trackers,
+        ]
+    );
+
+    /**
+     * Handler for the flow WebView messages.
+     * The flow WebView hosts child pages opened via window.open (e.g. 3DS, bank redirects).
+     * Message structure mirrors the main WebView handler but operates on the overlay WebView.
+     */
+    const handleFlowWebViewMessage = useCallback(
+        (event: WebViewMessageEvent) => {
+            try {
+                // Extracting and validating the raw message data from the flow WebView event
+                const data = event.nativeEvent?.data;
+                if (!data || typeof data !== "string") {
+                    if (devMode) {
+                        console.warn("[Glomo-RN-SDK Standard] Invalid message data from FlowWebView");
+                    }
+                    // Tracking invalid message received
+                    trackers.trackInvalidMessageReceived(
+                        "flow",
+                        data,
+                        flowWebViewUrl,
+                        orderId,
+                        publicKey,
+                        devMode,
+                        mockMode,
+                        checkoutUrl
+                    );
+                    return;
+                }
+
+                const message = JSON.parse(data);
+                if (devMode) {
+                    console.log("[Glomo-RN-SDK Standard] FlowWebView Message received:", message.type, message);
+                }
+
+                // Forwarding console messages from the flow WebView's injected script
+                if (message.type === "console") {
+                    if (devMode) {
+                        console.log(`[Glomo-RN-SDK Standard] [Flow] ${message.message}`);
+                    }
+                    return;
+                }
+
+                // Intercepting window.open calls from the flow WebView - navigating within the same overlay
+                if (message.type === "window.open") {
+                    const url = message.url;
+                    if (url && typeof url === "string" && isValidUrl(url)) {
+                        if (devMode) {
+                            console.log(`[Glomo-RN-SDK Standard] window.open called from FlowWebView: ${url}`);
+                        }
+                        setFlowWebViewUrl(url);
+                        // Tracking window.open interception
+                        trackers.trackWindowOpen("flow", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    } else {
+                        if (devMode) {
+                            console.log(
+                                "[Glomo-RN-SDK Standard] Invalid URL in window.open from FlowWebView:",
+                                url,
+                                typeof url === "undefined" ? "undefined" : ""
+                            );
+                        }
+                    }
+                    return;
+                }
+
+                // Intercepting window.close calls from the flow WebView - closing the overlay
+                if (message.type === "window.close") {
+                    if (devMode) {
+                        console.log("[Glomo-RN-SDK Standard] FlowWebView close requested");
+                    }
+                    setShowFlowWebView(false);
+                    setFlowWebViewUrl("");
+                    // Tracking window.close interception
+                    trackers.trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    return;
+                }
+
+                // Handling merchant JS callbacks from the flow WebView (payment events, lifecycle events)
+                if (message.type === "message" && message.message) {
+                    const messageData = message.message;
+                    const messageType = messageData?.type;
+
+                    // Handling payment success from the flow WebView
+                    if (messageType === "payment.success" || messageType === "payment.complete") {
+                        const paymentMessage = messageData;
+                        const payload = paymentMessage?.payload;
+
+                        if (isValidPaymentPayload(payload)) {
+                            if (devMode) {
+                                console.log("[Glomo-RN-SDK Standard] Payment successful via FlowWebView callback!");
+                            }
+                            setShowFlowWebView(false);
+                            setShowCheckout(false);
+                            setFlowWebViewUrl("");
+                            setStatus("payment_successful");
+                            safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
+                            // Tracking payment success callback
+                            trackers.trackPaymentSuccess(
+                                payload.orderId,
+                                payload.paymentId,
+                                publicKey,
+                                devMode,
+                                mockMode,
+                                checkoutUrl
+                            );
+                        } else {
+                            if (devMode) {
+                                console.error(
+                                    "[Glomo-RN-SDK Standard] Invalid payment success payload from FlowWebView:",
+                                    payload
+                                );
+                            }
+                        }
+                        return;
+                    }
+
+                    // Handling payment failure from the flow WebView
+                    if (messageType === "payment.failure" || messageType === "payment.error") {
+                        const paymentMessage = messageData;
+                        const payload = paymentMessage?.payload;
+
+                        if (isValidPaymentPayload(payload)) {
+                            if (devMode) {
+                                console.error("[Glomo-RN-SDK Standard] Payment failed via FlowWebView callback");
+                            }
+                            setShowFlowWebView(false);
+                            setShowCheckout(false);
+                            setFlowWebViewUrl("");
+                            setStatus("payment_failed");
+                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
+                            // Tracking payment failure callback
+                            trackers.trackPaymentFailure(
+                                payload.orderId,
+                                payload.paymentId,
+                                publicKey,
+                                devMode,
+                                mockMode,
+                                checkoutUrl
+                            );
+                        } else {
+                            if (devMode) {
+                                console.error(
+                                    "[Glomo-RN-SDK Standard] Invalid payment failure payload from FlowWebView:",
+                                    payload
+                                );
+                            }
+                        }
+                        return;
+                    }
+
+                    // Handling pay via bank - bank connection successful event from the flow WebView
+                    if (messageType === "pay_via_bank.bank.connection_successful") {
+                        const payload = messageData?.payload;
+                        if (devMode) {
+                            console.log(
+                                "[Glomo-RN-SDK Standard] Pay via bank - bank connection successful via FlowWebView:",
+                                payload
+                            );
+                        }
+                        safeCallback(
+                            onPayViaBankBankConnectionSuccessful,
+                            [
+                                {
+                                    bankIdentifier: payload?.bankIdentifier ?? "",
+                                    cooldownPeriodInMinutes: payload?.cooldownPeriodInMinutes ?? 0,
+                                    bankName: payload?.bankName ?? "",
+                                    bankImageSrc: payload?.bankImageSrc ?? "",
+                                    bankImageAlt: payload?.bankImageAlt ?? "",
+                                },
+                            ],
+                            "onPayViaBankBankConnectionSuccessful",
+                            devMode
+                        );
+                        trackers.trackPayViaBankBankConnectionSuccessful(
+                            orderId,
+                            publicKey,
+                            payload?.bankIdentifier ?? "",
+                            devMode,
+                            mockMode,
+                            checkoutUrl
+                        );
+                        return;
+                    }
+
+                    // Handling glomoCheckoutJourneyTerminate from the flow WebView (pay via bank completion)
+                    if (messageType === "glomoCheckoutJourneyTerminate") {
+                        // Deduplication - both main and flow WebViews can emit this event
+                        if (payViaBankCompletedHandledRef.current) {
+                            if (devMode) {
+                                console.log(
+                                    "[Glomo-RN-SDK Standard] Pay via bank completed already handled, ignoring duplicate"
+                                );
+                            }
+                            return;
+                        }
+                        payViaBankCompletedHandledRef.current = true;
+
+                        const payload = messageData?.payload;
+                        if (devMode) {
+                            console.log("[Glomo-RN-SDK Standard] Pay via bank completed via FlowWebView:", payload);
+                        }
+                        setShowFlowWebView(false);
+                        setShowCheckout(false);
+                        setFlowWebViewUrl("");
+                        setStatus("pay_via_bank_completed");
+                        safeCallback(
+                            onPayViaBankCompleted,
+                            [{ status: payload?.status ?? "unknown" }],
+                            "onPayViaBankCompleted",
+                            devMode
+                        );
+                        trackers.trackPayViaBankCompleted(
+                            orderId,
+                            publicKey,
+                            payload?.status ?? "unknown",
+                            devMode,
+                            mockMode,
+                            checkoutUrl
+                        );
+                        return;
+                    }
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Error parsing FlowWebView message:", error);
+                }
+            }
+        },
+        [
+            onPaymentSuccess,
+            onPaymentFailure,
+            onPayViaBankCompleted,
+            onPayViaBankBankConnectionSuccessful,
+            devMode,
+            mockMode,
+            orderId,
+            publicKey,
+            flowWebViewUrl,
+            checkoutUrl,
+            trackers,
+        ]
+    );
+
+    // Handler for the navigation state changes
+    const handleNavigationStateChange = useCallback(
+        (navState: WebViewNavigation) => {
+            if (devMode) {
+                console.log("[Glomo-RN-SDK Standard] Navigation state:", navState);
+            }
+        },
+        [devMode]
+    );
+
+    // Handler for the modal back button press events
+    const handleModalBackButton = useCallback(() => {
+        try {
+            if (devMode) {
+                console.log("[Glomo-RN-SDK Standard] Modal dismissed/back button pressed");
+            }
+            if (showFlowWebView) {
+                setShowFlowWebView(false);
+                setFlowWebViewUrl("");
+            }
+            setShowCheckout(false);
+            if (status === "payment_in_progress") {
+                if (devMode) {
+                    console.log("[Glomo-RN-SDK Standard] In progress payment cancelled");
+                }
+                setStatus("payment_cancelled");
+            } else {
+                if (devMode) {
+                    console.log("[Glomo-RN-SDK Standard] Ignoring checkout status update for: " + status);
+                }
+            }
+            safeCallback(onPaymentTerminate, [], "onPaymentTerminate", devMode);
+            // Tracking payment terminate callback (user dismiss/back button)
+            const terminateSource = Platform.OS === "ios" ? "user_dismiss" : "back_button";
+            trackers.trackPaymentTerminate(orderId, terminateSource, publicKey, devMode, mockMode, checkoutUrl);
+        } catch (error) {
+            if (devMode) {
+                console.error("[Glomo-RN-SDK Standard] Error in handleModalBackButton:", error);
+            }
+        }
+    }, [showFlowWebView, devMode, onPaymentTerminate, status, orderId, publicKey, mockMode, checkoutUrl, trackers]);
+
+    /** Closes the flow WebView and returns to the main checkout */
+    const handleFlowBack = useCallback(() => {
+        if (devMode) {
+            console.log("[Glomo-RN-SDK Standard] Flow WebView back button pressed");
+        }
+        setShowFlowWebView(false);
+        setFlowWebViewUrl("");
+        trackers.trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+    }, [devMode, orderId, publicKey, mockMode, checkoutUrl, trackers]);
+
+    /**
+     * Handler for WebView permission requests (e.g. camera access for bank authentication).
+     * On Android, prompts the user for camera permission via PermissionsAndroid.
+     * On iOS, grants camera access automatically (iOS handles its own permission prompt).
+     * Non-camera permissions are denied by default.
+     */
+    const handlePermissionRequest = useCallback(
+        async (request: WebViewPermissionRequest) => {
+            try {
+                const { resources } = request.nativeEvent;
+                // Checking if the requested permission is camera-related
+                const isCameraPermissionRequest = resources.some(
+                    (resource: string) => resource === "camera" || resource.toLowerCase().includes("camera")
+                );
+
+                if (!isCameraPermissionRequest) {
+                    if (devMode) {
+                        console.log("[Glomo-RN-SDK Standard] Non-camera permission requested, denying:", resources);
+                    }
+                    request.deny();
+                    return;
+                }
+
+                if (devMode) {
+                    console.log("[Glomo-RN-SDK Standard] Camera permission requested by webpage");
+                }
+
+                if (Platform.OS === "android") {
+                    try {
+                        const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA, {
+                            title: "Camera Permission",
+                            message: "This app needs camera access for identity verification during checkout",
+                            buttonNeutral: "Ask Me Later",
+                            buttonNegative: "Cancel",
+                            buttonPositive: "OK",
+                        });
+
+                        if (granted === PermissionsAndroid.RESULTS.GRANTED) {
+                            if (devMode) {
+                                console.log("[Glomo-RN-SDK Standard] Camera permission granted");
+                            }
+                            request.grant(resources);
+                        } else {
+                            if (devMode) {
+                                console.log("[Glomo-RN-SDK Standard] Camera permission denied by user");
+                            }
+                            setShowCheckout(false);
+                            if (status === "payment_in_progress") {
+                                setStatus("payment_cancelled");
+                            }
+                            safeCallback(onUserRefusedCameraPermissions, [], "onUserRefusedCameraPermissions", devMode);
+                            request.deny();
+                        }
+                    } catch (err) {
+                        if (devMode) {
+                            console.error("[Glomo-RN-SDK Standard] Error requesting camera permission:", err);
+                        }
+                        setShowCheckout(false);
+                        if (status === "payment_in_progress") {
+                            setStatus("payment_cancelled");
+                        }
+                        safeCallback(onUserRefusedCameraPermissions, [], "onUserRefusedCameraPermissions", devMode);
+                        request.deny();
+                    }
+                } else if (Platform.OS === "ios") {
+                    if (devMode) {
+                        console.log("[Glomo-RN-SDK Standard] Granting camera permission request on iOS");
+                    }
+                    request.grant(resources);
+                } else {
+                    if (devMode) {
+                        console.warn("[Glomo-RN-SDK Standard] Unsupported platform for camera permissions");
+                    }
+                    request.deny();
+                }
+            } catch (error) {
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK Standard] Error in handlePermissionRequest:", error);
+                }
+                request.deny();
+            }
+        },
+        [devMode, status, onUserRefusedCameraPermissions]
+    );
+
+    /**
+     * Initiator method for the Standard Checkout flow.
+     * Using a ref, the standard flow can be started by calling this method.
+     * Example:
+     *   const checkoutRef = useRef<GlomoStandardCheckoutRef>(null);
+     *   checkoutRef.current?.start();
+     *
+     * The standard checkout can only be started if
+     * - The status is "ready", "payment_cancelled", or "payment_failed"
+     * - The status is NOT "payment_successful"
+     * - Input validation passes
+     */
+    const start = useCallback((): boolean => {
+        /**
+         * Checking device security compliance (if peerDependencies are available)
+         * A null value indicates that recommended security dependencies were not installed and compliance checks will be skipped in this case
+         */
+        const deviceComplianceCheck = checkDeviceCompliance(devMode);
+        const jailbreakDetectionLibraryInstalled = isComplianceCheckAvailable();
+        const jailbreakDetectionInfo = {
+            jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: deviceComplianceCheck,
+        };
+
+        if (devMode) {
+            console.log(
+                `[Glomo-RN-SDK Standard] Attempting to start checkout of ${checkoutUrl} from status: ${status}`
+            );
+        }
+
+        // Tracking start attempt with current status
+        trackers.trackStartAttempt(status, orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+
+        if (deviceComplianceCheck === true) {
+            // Device detected as compromised
+            if (devMode) {
+                console.error("[Glomo-RN-SDK Standard] Cannot start checkout. Device is rooted or jailbroken.");
+            }
+            const errors: SdkError[] = [
+                {
+                    type: "device_forbidden",
+                    message: "Standard checkout is not allowed on rooted or jailbroken devices.",
+                },
+            ];
+            safeCallback(onSdkError, [errors], "onSdkError", devMode);
+            // Tracking start() failure
+            trackers.trackStartFailure(
+                "device_forbidden",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        } else if (deviceComplianceCheck === null) {
+            // This warning was intentionally not gated behind a devMode check to ensure merchants are aware of the strong recommendation to install jail-monkey for enhanced security compliance.
+            console.warn(
+                "[Glomo-RN-SDK Standard] Device security library not installed - the SDK won't be able to automatically detect rooted/jailbroken devices. It is HIGHLY recommended to install jail-monkey as per the README, and prevent standard checkouts from compromised devices."
+            );
+        }
+
+        // Enforcing devMode requirement for development servers
+        const resolvedServer = server || "prod";
+        if (!devMode && resolvedServer !== "prod") {
+            const errors: SdkError[] = [
+                {
+                    type: "validation_error",
+                    message: "Development servers can only be used when devMode is enabled.",
+                },
+            ];
+            safeCallback(onSdkError, [errors], "onSdkError", devMode);
+            trackers.trackSdkError(errors, orderId, publicKey, devMode, mockMode, checkoutUrl);
+            trackers.trackStartFailure(
+                "validation_error",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        }
+
+        // Checking validation errors with detailed field-level messages
+        const errors: SdkError[] = [];
+
+        if (!isValidPublicKey(publicKey)) {
+            const error: SdkError = {
+                type: "validation_error",
+                message: "Invalid publicKey: must start with 'live_', 'mock_', or 'test_' and be a valid string",
+                field: "publicKey",
+            };
+            errors.push(error);
+        }
+
+        if (!internalOptions?._skipOrderIdValidation && !isValidOrderId(orderId)) {
+            const error: SdkError = {
+                type: "validation_error",
+                message: "Invalid orderId: must start with 'order_' and be a valid string",
+                field: "orderId",
+            };
+            errors.push(error);
+        }
+
+        if (!isValidUrl(checkoutUrl)) {
+            const error: SdkError = !isValidUrl(baseCheckoutUrl)
+                ? {
+                      type: "validation_error",
+                      message: "Invalid baseCheckoutUrl: must be a valid HTTP or HTTPS URL",
+                      field: "baseCheckoutUrl",
+                  }
+                : {
+                      type: "validation_error",
+                      message: "Invalid checkoutUrl: must be a valid HTTP or HTTPS URL",
+                      field: "generatedCheckoutUrl",
+                  };
+            errors.push(error);
+        }
+
+        if (errors.length > 0) {
+            if (devMode) {
+                console.error(`[Glomo-RN-SDK Standard] Cannot start checkout. Validation failed.`);
+            }
+            safeCallback(onSdkError, [errors], "onSdkError", devMode);
+            // Tracking start() failure
+            trackers.trackSdkError(errors, orderId, publicKey, devMode, mockMode, checkoutUrl);
+            trackers.trackStartFailure(
+                "validation_error",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        }
+
+        if (status === "payment_successful") {
+            if (devMode) {
+                console.log(
+                    `[Glomo-RN-SDK Standard] Cannot start checkout. Current status: ${status}. Payment already successful.`
+                );
+            }
+            // Tracking start() failure
+            trackers.trackStartFailure(
+                "payment_successful",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        }
+
+        if (
+            status !== "ready" &&
+            status !== "payment_cancelled" &&
+            status !== "payment_failed" &&
+            status !== "payment_in_progress" &&
+            status !== "bank_transfer_submitted" &&
+            status !== "pay_via_bank_completed"
+        ) {
+            if (devMode) {
+                console.log(`[Glomo-RN-SDK Standard] Cannot start checkout. Unknown status: ${status}.`);
+            }
+            // Tracking start() failure
+            trackers.trackStartFailure(
+                "invalid_status",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        }
+
+        if (!checkoutUrl) {
+            if (devMode) {
+                console.error("[Glomo-RN-SDK Standard] Cannot start checkout. Invalid checkout URL.");
+            }
+            // Tracking start() failure
+            trackers.trackStartFailure(
+                "invalid_url",
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                jailbreakDetectionInfo
+            );
+            setShowCheckout(false);
+            return false;
+        }
+
+        if (devMode) {
+            console.log("[Glomo-RN-SDK Standard] Starting checkout from previous state: " + status);
+        }
+
+        // Resetting any stale state from a previous checkout attempt before starting a new one
+        setShowFlowWebView(false);
+        setFlowWebViewUrl("");
+        payViaBankCompletedHandledRef.current = false;
+        setStatus("payment_in_progress");
+
+        // Tracking successful start
+        trackers.trackStartSuccess(orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+
+        // Opening the checkout modal
+        setShowCheckout(true);
+        return true;
+    }, [
+        devMode,
+        status,
+        publicKey,
+        orderId,
+        baseCheckoutUrl,
+        checkoutUrl,
+        mockMode,
+        onSdkError,
+        server,
+        trackers,
+        internalOptions,
+    ]);
+
+    // Initializing Segment analytics
+    useEffect(() => {
+        initializeSegment(devMode);
+    }, [devMode]);
+
+    // Resetting checkout flow if orderId or publicKey are changed
+    useEffect(() => {
+        if (orderId && publicKey) {
+            // Only resetting the checkout flow if the current status is that of a terminal state
+            if (
+                status === "payment_successful" ||
+                status === "payment_failed" ||
+                status === "payment_cancelled" ||
+                status === "bank_transfer_submitted" ||
+                status === "pay_via_bank_completed"
+            ) {
+                if (devMode) {
+                    console.log(
+                        `[Glomo-RN-SDK Standard] Resetting checkout status ${status} for new orderId ${orderId} and publicKey ${publicKey}`
+                    );
+                }
+                setStatus("ready");
+            }
+        }
+    }, [orderId, publicKey, status, devMode]);
+
+    // Cleaning up on unmount
+    useEffect(() => {
+        return () => {
+            // Cleaning up - resetting state on unmount
+            setStatus("ready");
+            setShowCheckout(false);
+            setShowFlowWebView(false);
+            setFlowWebViewUrl("");
+        };
+    }, []);
+
+    return {
+        start,
+        status,
+        showCheckout,
+        flowWebViewUrl,
+        showFlowWebView,
+        checkoutUrl,
+        mainWebViewRef,
+        flowWebViewRef,
+        handleMainWebViewMessage,
+        handleFlowWebViewMessage,
+        handleError,
+        handleHttpError,
+        handlePermissionRequest,
+        handleNavigationStateChange,
+        handleModalBackButton,
+        handleFlowBack,
+        injectedMain: InjectionScripts.standard,
+        injectedFlow: InjectionScripts.flow,
+    };
+}