@glomopay/react-native-sdk 4.0.0 → 5.0.0

package/src/use-lrs-checkout.tsx

@@ -5,11 +5,27 @@ import { Platform, type NativeSyntheticEvent } from "react-native";
 
 import { type WebViewNavigation, type WebViewMessageEvent, type WebView } from "react-native-webview";
 
-import { InjectionScripts } from "./injections/index";
+import { buildInjectionScripts } 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 { resolveServerConfig, ANALYTICS_PRODUCT, ANALYTICS_SURFACE, type GlomoServer } from "./config/base";
+import {
+    isValidPublicKey,
+    isValidOrderId,
+    isValidUrl,
+    isValidPaymentPayload,
+    missingPaymentFields,
+    safeCallback,
+} from "./utils/validation";
+import { droppedPayloadSdkError, payloadKeysOf } from "./bridge/payment-payload";
+import { toPaymentEventData, toTerminationEventData } from "./utils/event-projections";
+import { resolveDeviceCompliance, blocksCheckout, isComplianceCheckAvailable } from "./utils/device-compliance";
+import { usePermissionRequest, type WebViewPermissionRequest } from "./webview/use-permission-request";
+import { createMessageRouter } from "./bridge/message-router";
+import { createFileSaveHandler } from "./bridge/file-save-handler";
+import { createFileInputHandler } from "./bridge/file-input-handler";
+import { resolveCapabilities, resolveFileSaveAvailability } from "./capabilities/index";
+import { useCapabilityReporting } from "./capabilities/use-capability-reporting";
+import { useSdkSession } from "./utils/use-sdk-session";
 import {
     trackStartAttempt,
     trackStartSuccess,
@@ -24,8 +40,16 @@ import {
     trackEducationStepsFailedToShow,
     trackSdkError,
     trackInvalidMessageReceived,
+    trackIncompletePaymentPayload,
+    trackDroppedPaymentPayload,
+    trackDevicePermissionRefused,
+    trackBackNavigationViaSdkBackButton,
     type SdkError,
 } from "./utils/analytics";
+import { TERMINATION_SOURCES, type GlomoTerminationPayload } from "./types/checkout";
+
+/** Log prefix for everything this flow emits */
+const LOG_PREFIX = "[Glomo-RN-SDK LRS]";
 
 /** LRS checkout statuses */
 export type LrsCheckoutStatus =
@@ -58,11 +82,11 @@ export type LrsCheckoutStatus =
  */
 export type EducationCarouselState = "pending" | "hasContent";
 
-/** The payload for a successful or failed payment */
+/** The payload for a successful or failed payment. See GlomoCheckoutPayload on the optional fields. */
 export interface GlomoLrsCheckoutPayload {
     orderId: string;
-    paymentId: string;
-    signature: string;
+    paymentId?: string;
+    signature?: string;
 }
 
 /** The options for the useLrsCheckout hook */
@@ -73,8 +97,9 @@ export interface UseLrsCheckoutOptions {
     onPaymentSuccess: (payload: GlomoLrsCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoLrsCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
-    onPaymentTerminate?: () => void;
+    onPaymentTerminate?: (payload: GlomoTerminationPayload) => void;
     onSdkError: (error: Array<SdkError>) => void;
+    onUserRefusedDevicePermissions?: () => void;
     devMode?: boolean;
 }
 
@@ -101,12 +126,22 @@ export interface UseLrsCheckoutReturn {
     handleNavigationStateChange: (navState: WebViewNavigation) => void;
     handleModalBackButton: () => void;
     handleFlowBack: () => void;
+    handlePermissionRequest: (request: WebViewPermissionRequest) => void;
     injectedMain?: string;
     injectedFlow?: string;
     injectedEducationCarousel?: string;
 }
 
-/** The main SDK hook for the GlomoPay LRS Checkout flow */
+/**
+ * The main SDK hook for the GlomoPay LRS Checkout flow
+ * Internal options meant to simulate an LRS checkout are for automated tests only.
+ */
+export interface UseLrsCheckoutInternalOptions {
+    _testInjectionScript?: string;
+    _testCarouselInjectionScript?: string;
+    _onEducationCarouselStateChange?: (state: string) => void;
+}
+
 export function useLrsCheckout(
     {
         server,
@@ -117,9 +152,11 @@ export function useLrsCheckout(
         onConnectionError,
         onPaymentTerminate,
         onSdkError,
+        onUserRefusedDevicePermissions,
         devMode = false,
     }: UseLrsCheckoutOptions,
-    mockMode: boolean
+    mockMode: boolean,
+    internalOptions?: UseLrsCheckoutInternalOptions
 ): UseLrsCheckoutReturn {
     // Refs for the WebViews
     const mainWebViewRef = useRef<WebView>(null);
@@ -141,7 +178,9 @@ export function useLrsCheckout(
             const mode = mockMode ? "mock" : "live";
             const params = baseParams.concat(
                 `mode=${encodeURIComponent(mode)}`,
-                `publicKey=${encodeURIComponent(publicKey)}`
+                `publicKey=${encodeURIComponent(publicKey)}`,
+                `product=${encodeURIComponent(ANALYTICS_PRODUCT)}`,
+                `surface=${encodeURIComponent(ANALYTICS_SURFACE)}`
             );
             const queryString = params.join("&");
 
@@ -179,7 +218,9 @@ export function useLrsCheckout(
             const separator = baseEducationCarouselUrl.includes("?") ? "&" : "?";
             const finalUrl =
                 `${baseEducationCarouselUrl}${separator}orderId=${encodeURIComponent(orderId)}` +
-                `&publicKey=${encodeURIComponent(publicKey)}`;
+                `&publicKey=${encodeURIComponent(publicKey)}` +
+                `&product=${encodeURIComponent(ANALYTICS_PRODUCT)}` +
+                `&surface=${encodeURIComponent(ANALYTICS_SURFACE)}`;
 
             if (!isValidUrl(finalUrl)) {
                 if (devMode) {
@@ -208,7 +249,18 @@ export function useLrsCheckout(
 
     const [showFlowWebView, setShowFlowWebView] = useState(false);
     const [flowWebViewUrl, setFlowWebViewUrl] = useState<string>("");
-    const [educationCarouselState, setEducationCarouselState] = useState<EducationCarouselState>("pending");
+    const [educationCarouselState, setEducationCarouselStateRaw] = useState<EducationCarouselState>("pending");
+
+    /** Wrapping the raw state setter to also fire the internal test callback */
+    const testCarouselCallbackRef = useRef(internalOptions?._onEducationCarouselStateChange);
+    testCarouselCallbackRef.current = internalOptions?._onEducationCarouselStateChange;
+
+    const setEducationCarouselState = useCallback((nextState: EducationCarouselState) => {
+        setEducationCarouselStateRaw(nextState);
+        if (__DEV__) {
+            testCarouselCallbackRef.current?.(nextState);
+        }
+    }, []);
 
     useEffect(() => {
         if (devMode) {
@@ -298,16 +350,60 @@ export function useLrsCheckout(
         [devMode]
     );
 
+    // Correlates every event from this mount, and keeps checkoutStatus current on all of them
+    useSdkSession(() => status);
+
+    // Missing optional dependencies reach the host here; start() warns on the console separately
+    useCapabilityReporting({ onSdkError, devMode });
+
+    /**
+     * Handler for `file.input` - the user tapping a file input on a bank's page.
+     *
+     * Registered beside `file.save` on the same WebViews, for the same reason: uploads are not a
+     * property of one flow, and until now this message had no handler anywhere.
+     */
+    const fileInputHandler = useMemo(
+        () =>
+            createFileInputHandler({
+                flowType: "lrs",
+                orderId,
+                publicKey,
+                checkoutUrl,
+                mockMode,
+                devMode,
+            }),
+        [orderId, publicKey, checkoutUrl, mockMode, devMode]
+    );
+
+    /**
+     * Handler for `file.save` - the page asking the SDK to put a document on the device.
+     *
+     * One handler, registered on the main and flow WebViews both. Not on the education carousel:
+     * that renders our own content, which has nothing to gate, and the capability is not advertised
+     * there either.
+     */
+    const fileSaveHandler = useMemo(
+        () =>
+            createFileSaveHandler({
+                flowType: "lrs",
+                orderId,
+                publicKey,
+                checkoutUrl,
+                mockMode,
+                devMode,
+                onSdkError,
+            }),
+        [orderId, publicKey, checkoutUrl, mockMode, devMode, onSdkError]
+    );
+
     // Handler for the main WebView messages
-    const handleMainWebViewMessage = useCallback(
-        (event: WebViewMessageEvent) => {
-            try {
-                const data = event.nativeEvent?.data;
-                if (!data || typeof data !== "string") {
-                    if (devMode) {
-                        console.warn("[Glomo-RN-SDK LRS] Invalid message data from MainWebView");
-                    }
-                    // Tracking invalid message received
+    const handleMainWebViewMessage = useMemo(
+        () =>
+            createMessageRouter({
+                logPrefix: LOG_PREFIX,
+                source: "MainWebView",
+                devMode,
+                onInvalidMessage: (data) => {
                     trackInvalidMessageReceived(
                         "main",
                         data,
@@ -318,158 +414,242 @@ export function useLrsCheckout(
                         mockMode,
                         checkoutUrl
                     );
-                    return;
-                }
-
-                const message = JSON.parse(data);
-                if (devMode) {
-                    console.log("[Glomo-RN-SDK LRS] MainWebView Message received:", message.type, message);
-                }
-
-                if (message.type === "console") {
-                    if (devMode) {
-                        const level = message.level || "log";
-                        console.log(`[Glomo-RN-SDK LRS] [WebView ${level.toUpperCase()}]`, message.message);
-                    }
-                    return;
-                }
+                },
+                handlers: {
+                    "file.save": fileSaveHandler,
+                    "file.input": fileInputHandler,
 
-                if (message.type === "window.open") {
-                    const url = message.url;
-                    if (url && typeof url === "string" && isValidUrl(url)) {
-                        if (devMode) {
-                            console.log(`[Glomo-RN-SDK LRS] window.open called from MainWebView: ${url}`);
-                        }
-                        setFlowWebViewUrl(url);
-                        setShowFlowWebView(true);
-                        setEducationCarouselState("pending");
-                        // Tracking window.open interception
-                        trackWindowOpen("main", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
-                    } else {
+                    console: (message) => {
                         if (devMode) {
-                            console.log(
-                                "[Glomo-RN-SDK LRS] Invalid URL in window.open from MainWebView:",
-                                url,
-                                typeof url === "undefined" ? "undefined" : ""
-                            );
+                            const level = (typeof message.level === "string" && message.level) || "log";
+                            console.log(`${LOG_PREFIX} [WebView ${level.toUpperCase()}]`, message.message);
                         }
-                    }
-                    return;
-                }
-
-                if (message.type === "window.close") {
-                    if (devMode) {
-                        console.log("[Glomo-RN-SDK LRS] Child window close requested from MainWebView");
-                    }
-                    setShowFlowWebView(false);
-                    setFlowWebViewUrl("");
-                    setEducationCarouselState("pending");
-                    // Tracking window.close interception
-                    trackWindowClose("main", orderId, publicKey, devMode, mockMode, checkoutUrl);
-                    return;
-                }
+                    },
 
-                // Handling merchant JS callbacks on flow completion
-                if (message.type === "message" && message.message) {
-                    const messageData = message.message;
-                    const messageType = messageData?.type;
-
-                    if (messageType === "payment.success" || messageType === "payment.complete") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
-
-                        if (isValidPaymentPayload(payload)) {
+                    "window.open": (message) => {
+                        const url = message.url;
+                        if (url && typeof url === "string" && isValidUrl(url)) {
                             if (devMode) {
-                                console.log("[Glomo-RN-SDK LRS] Payment successful via merchant callback!");
+                                console.log(`${LOG_PREFIX} window.open called from MainWebView: ${url}`);
                             }
-                            setShowCheckout(false);
-                            setShowFlowWebView(false);
-                            setFlowWebViewUrl("");
+                            setFlowWebViewUrl(url);
+                            setShowFlowWebView(true);
                             setEducationCarouselState("pending");
-                            setStatus("payment_successful");
-                            safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
-                            // Tracking payment success callback
-                            trackPaymentSuccess(
-                                payload.orderId,
-                                payload.paymentId,
-                                publicKey,
-                                devMode,
-                                mockMode,
-                                checkoutUrl
-                            );
+                            // Tracking window.open interception
+                            trackWindowOpen("main", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
                         } else {
                             if (devMode) {
-                                console.error("[Glomo-RN-SDK LRS] Invalid payment success payload:", payload);
+                                console.log(
+                                    `${LOG_PREFIX} Invalid URL in window.open from MainWebView:`,
+                                    url,
+                                    typeof url === "undefined" ? "undefined" : ""
+                                );
                             }
                         }
-                        return;
-                    }
+                    },
 
-                    if (messageType === "payment.failure" || messageType === "payment.error") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
+                    "window.close": () => {
+                        if (devMode) {
+                            console.log(`${LOG_PREFIX} Child window close requested from MainWebView`);
+                        }
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        setEducationCarouselState("pending");
+                        // Tracking window.close interception
+                        trackWindowClose("main", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    },
+
+                    // Handling merchant JS callbacks on flow completion
+                    message: (message) => {
+                        const messageData = message.message as { type?: string; payload?: unknown } | undefined;
+                        if (!messageData) return;
+                        const messageType = messageData.type;
+
+                        if (messageType === "payment.success" || messageType === "payment.complete") {
+                            const payload = messageData.payload;
+
+                            if (isValidPaymentPayload(payload)) {
+                                if (devMode) {
+                                    console.log(`${LOG_PREFIX} Payment successful via merchant callback!`);
+                                }
+                                setShowCheckout(false);
+                                setShowFlowWebView(false);
+                                setFlowWebViewUrl("");
+                                setEducationCarouselState("pending");
+                                setStatus("payment_successful");
+                                safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
+                                // Tracking payment success callback
+                                trackPaymentSuccess(
+                                    toPaymentEventData(payload),
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl
+                                );
+                                // Fires alongside the callback, not instead of it - the outcome is real, the payload is thin
+                                const missingFields = missingPaymentFields(payload);
+                                if (missingFields.length > 0) {
+                                    trackIncompletePaymentPayload(
+                                        "payment.success",
+                                        missingFields,
+                                        "main",
+                                        payload.orderId,
+                                        publicKey,
+                                        devMode,
+                                        mockMode,
+                                        checkoutUrl,
+                                        "lrs"
+                                    );
+                                }
+                            } else {
+                                /**
+                                 * Reported, not dropped. Before v5 this branch was a devMode-only console.error, so in a
+                                 * release build a terminal payment outcome the SDK could not route left no trace
+                                 * anywhere - no callback, no telemetry, nothing for support to find.
+                                 */
+                                if (devMode) {
+                                    console.error(
+                                        `${LOG_PREFIX} Unroutable payment.success payload from main:`,
+                                        payload
+                                    );
+                                }
+                                trackDroppedPaymentPayload(
+                                    "payment.success",
+                                    payloadKeysOf(payload),
+                                    "main",
+                                    orderId,
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl,
+                                    "lrs"
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.success")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            return;
+                        }
+
+                        if (messageType === "payment.failure" || messageType === "payment.error") {
+                            const payload = messageData.payload;
+
+                            if (isValidPaymentPayload(payload)) {
+                                if (devMode) {
+                                    console.error(`${LOG_PREFIX} Payment failed via merchant callback`);
+                                }
+                                setShowCheckout(false);
+                                setShowFlowWebView(false);
+                                setFlowWebViewUrl("");
+                                setEducationCarouselState("pending");
+                                setStatus("payment_failed");
+                                safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
+                                // Tracking payment failure callback
+                                trackPaymentFailure(
+                                    toPaymentEventData(payload),
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl
+                                );
+                                // Fires alongside the callback, not instead of it - the outcome is real, the payload is thin
+                                const missingFields = missingPaymentFields(payload);
+                                if (missingFields.length > 0) {
+                                    trackIncompletePaymentPayload(
+                                        "payment.failure",
+                                        missingFields,
+                                        "main",
+                                        payload.orderId,
+                                        publicKey,
+                                        devMode,
+                                        mockMode,
+                                        checkoutUrl,
+                                        "lrs"
+                                    );
+                                }
+                            } else {
+                                /**
+                                 * Reported, not dropped. Before v5 this branch was a devMode-only console.error, so in a
+                                 * release build a terminal payment outcome the SDK could not route left no trace
+                                 * anywhere - no callback, no telemetry, nothing for support to find.
+                                 */
+                                if (devMode) {
+                                    console.error(
+                                        `${LOG_PREFIX} Unroutable payment.failure payload from main:`,
+                                        payload
+                                    );
+                                }
+                                trackDroppedPaymentPayload(
+                                    "payment.failure",
+                                    payloadKeysOf(payload),
+                                    "main",
+                                    orderId,
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl,
+                                    "lrs"
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.failure")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            return;
+                        }
 
-                        if (isValidPaymentPayload(payload)) {
+                        // Handling checkout.closed events
+                        if (messageType === "checkout.closed") {
                             if (devMode) {
-                                console.error("[Glomo-RN-SDK LRS] Payment failed via merchant callback");
+                                console.log(`${LOG_PREFIX} Checkout closed event received`);
                             }
                             setShowCheckout(false);
                             setShowFlowWebView(false);
                             setFlowWebViewUrl("");
                             setEducationCarouselState("pending");
-                            setStatus("payment_failed");
-                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
-                            // Tracking payment failure callback
-                            trackPaymentFailure(
-                                payload.orderId,
-                                payload.paymentId,
+                            const termination = { source: TERMINATION_SOURCES.CHECKOUT_CLOSED };
+                            safeCallback(onPaymentTerminate, [termination], "onPaymentTerminate", devMode);
+                            // One object to the host and to telemetry, so the two cannot drift
+                            trackPaymentTerminate(
+                                orderId,
+                                toTerminationEventData(termination),
                                 publicKey,
                                 devMode,
                                 mockMode,
                                 checkoutUrl
                             );
-                        } else {
-                            if (devMode) {
-                                console.error("[Glomo-RN-SDK LRS] Invalid payment failure payload:", payload);
-                            }
                         }
-                        return;
-                    }
-
-                    // Handling checkout.closed events
-                    if (messageType === "checkout.closed") {
-                        if (devMode) {
-                            console.log("[Glomo-RN-SDK LRS] Checkout closed event received");
-                        }
-                        setShowCheckout(false);
-                        setShowFlowWebView(false);
-                        setFlowWebViewUrl("");
-                        setEducationCarouselState("pending");
-                        safeCallback(onPaymentTerminate, [], "onPaymentTerminate", devMode);
-                        // Tracking payment terminate callback
-                        trackPaymentTerminate(orderId, "checkout_closed", publicKey, devMode, mockMode, checkoutUrl);
-                        return;
-                    }
-                }
-            } catch (error) {
-                if (devMode) {
-                    console.error("[Glomo-RN-SDK LRS] Error parsing MainWebView message:", error);
-                }
-            }
-        },
-        [onPaymentSuccess, onPaymentFailure, onPaymentTerminate, devMode, mockMode, orderId, publicKey, checkoutUrl]
+                    },
+                },
+            }),
+        [
+            onPaymentSuccess,
+            onPaymentFailure,
+            onPaymentTerminate,
+            devMode,
+            mockMode,
+            orderId,
+            publicKey,
+            checkoutUrl,
+            fileSaveHandler,
+            onSdkError,
+            fileInputHandler,
+        ]
     );
 
     // Handler for the flow WebView messages
-    const handleFlowWebViewMessage = useCallback(
-        (event: WebViewMessageEvent) => {
-            try {
-                const data = event.nativeEvent?.data;
-                if (!data || typeof data !== "string") {
-                    if (devMode) {
-                        console.warn("[Glomo-RN-SDK LRS] Invalid message data from FlowWebView");
-                    }
-                    // Tracking invalid message received
+    const handleFlowWebViewMessage = useMemo(
+        () =>
+            createMessageRouter({
+                logPrefix: LOG_PREFIX,
+                source: "FlowWebView",
+                devMode,
+                onInvalidMessage: (data) => {
                     trackInvalidMessageReceived(
                         "flow",
                         data,
@@ -480,179 +660,261 @@ export function useLrsCheckout(
                         mockMode,
                         checkoutUrl
                     );
-                    return;
-                }
-
-                const message = JSON.parse(data);
-                if (devMode) {
-                    console.log("[Glomo-RN-SDK LRS] FlowWebView Message received:", message.type, message);
-                }
+                },
+                handlers: {
+                    /**
+                     * Telemetry only, and deliberately not wired to onUserRefusedDevicePermissions.
+                     * The flow injection sees this by watching getUserMedia, so coverage depends on
+                     * whether a given bank uses it - partial coverage on a merchant callback is
+                     * worse than none, because silence would stop being unambiguous.
+                     */
+                    "permission.denied": (message) => {
+                        trackDevicePermissionRefused(
+                            typeof message.resource === "string" ? message.resource : "camera",
+                            "get_user_media",
+                            orderId,
+                            publicKey,
+                            devMode,
+                            mockMode,
+                            checkoutUrl,
+                            "lrs"
+                        );
+                    },
 
-                if (message.type === "console") {
-                    if (devMode) {
-                        console.log(`[Glomo-RN-SDK LRS] [Flow] ${message.message}`);
-                    }
-                    return;
-                }
+                    "file.save": fileSaveHandler,
+                    "file.input": fileInputHandler,
 
-                if (message.type === "window.open") {
-                    const url = message.url;
-                    if (url && typeof url === "string" && isValidUrl(url)) {
+                    console: (message) => {
                         if (devMode) {
-                            console.log(`[Glomo-RN-SDK LRS] window.open called from FlowWebView: ${url}`);
+                            console.log(`${LOG_PREFIX} [Flow] ${message.message}`);
                         }
-                        setFlowWebViewUrl(url);
-                        setEducationCarouselState("pending");
-                        // Tracking window.open interception
-                        trackWindowOpen("flow", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
-                    } else {
-                        if (devMode) {
-                            console.log(
-                                "[Glomo-RN-SDK LRS] Invalid URL in window.open from FlowWebView:",
-                                url,
-                                typeof url === "undefined" ? "undefined" : ""
-                            );
-                        }
-                    }
-                    return;
-                }
-
-                if (message.type === "window.close") {
-                    if (devMode) {
-                        console.log("[Glomo-RN-SDK LRS] FlowWebView close requested");
-                    }
-                    setShowFlowWebView(false);
-                    setFlowWebViewUrl("");
-                    setEducationCarouselState("pending");
-                    // Tracking window.close interception
-                    trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
-                    return;
-                }
-
-                if (message.type === "message" && message.message) {
-                    const messageData = message.message;
-                    const messageType = messageData?.type;
-
-                    if (messageType === "payment.success" || messageType === "payment.complete") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
+                    },
 
-                        if (isValidPaymentPayload(payload)) {
+                    "window.open": (message) => {
+                        const url = message.url;
+                        if (url && typeof url === "string" && isValidUrl(url)) {
                             if (devMode) {
-                                console.log("[Glomo-RN-SDK LRS] Payment successful via FlowWebView callback!");
+                                console.log(`${LOG_PREFIX} window.open called from FlowWebView: ${url}`);
                             }
-                            setShowFlowWebView(false);
-                            setShowCheckout(false);
-                            setFlowWebViewUrl("");
+                            setFlowWebViewUrl(url);
                             setEducationCarouselState("pending");
-                            setStatus("payment_successful");
-                            safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
-                            // Tracking payment success callback
-                            trackPaymentSuccess(
-                                payload.orderId,
-                                payload.paymentId,
-                                publicKey,
-                                devMode,
-                                mockMode,
-                                checkoutUrl
-                            );
+                            // Tracking window.open interception
+                            trackWindowOpen("flow", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
                         } else {
                             if (devMode) {
-                                console.error(
-                                    "[Glomo-RN-SDK LRS] Invalid payment success payload from FlowWebView:",
-                                    payload
+                                console.log(
+                                    `${LOG_PREFIX} Invalid URL in window.open from FlowWebView:`,
+                                    url,
+                                    typeof url === "undefined" ? "undefined" : ""
                                 );
                             }
                         }
-                        return;
-                    }
+                    },
 
-                    if (messageType === "payment.failure" || messageType === "payment.error") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
-
-                        if (isValidPaymentPayload(payload)) {
-                            if (devMode) {
-                                console.error("[Glomo-RN-SDK LRS] Payment failed via FlowWebView callback");
+                    "window.close": () => {
+                        if (devMode) {
+                            console.log(`${LOG_PREFIX} FlowWebView close requested`);
+                        }
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        setEducationCarouselState("pending");
+                        // Tracking window.close interception
+                        trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    },
+
+                    // Handling merchant JS callbacks on flow completion
+                    message: (message) => {
+                        const messageData = message.message as { type?: string; payload?: unknown } | undefined;
+                        if (!messageData) return;
+                        const messageType = messageData.type;
+
+                        if (messageType === "payment.success" || messageType === "payment.complete") {
+                            const payload = messageData.payload;
+
+                            if (isValidPaymentPayload(payload)) {
+                                if (devMode) {
+                                    console.log(`${LOG_PREFIX} Payment successful via FlowWebView callback!`);
+                                }
+                                setShowFlowWebView(false);
+                                setShowCheckout(false);
+                                setFlowWebViewUrl("");
+                                setEducationCarouselState("pending");
+                                setStatus("payment_successful");
+                                safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
+                                // Tracking payment success callback
+                                trackPaymentSuccess(
+                                    toPaymentEventData(payload),
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl
+                                );
+                                // Fires alongside the callback, not instead of it - the outcome is real, the payload is thin
+                                const missingFields = missingPaymentFields(payload);
+                                if (missingFields.length > 0) {
+                                    trackIncompletePaymentPayload(
+                                        "payment.success",
+                                        missingFields,
+                                        "flow",
+                                        payload.orderId,
+                                        publicKey,
+                                        devMode,
+                                        mockMode,
+                                        checkoutUrl,
+                                        "lrs"
+                                    );
+                                }
+                            } else {
+                                /**
+                                 * Reported, not dropped. Before v5 this branch was a devMode-only console.error, so in a
+                                 * release build a terminal payment outcome the SDK could not route left no trace
+                                 * anywhere - no callback, no telemetry, nothing for support to find.
+                                 */
+                                if (devMode) {
+                                    console.error(
+                                        `${LOG_PREFIX} Unroutable payment.success payload from flow:`,
+                                        payload
+                                    );
+                                }
+                                trackDroppedPaymentPayload(
+                                    "payment.success",
+                                    payloadKeysOf(payload),
+                                    "flow",
+                                    orderId,
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl,
+                                    "lrs"
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.success")]],
+                                    "onSdkError",
+                                    devMode
+                                );
                             }
-                            setShowFlowWebView(false);
-                            setShowCheckout(false);
-                            setFlowWebViewUrl("");
-                            setEducationCarouselState("pending");
-                            setStatus("payment_failed");
-                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
-                            // Tracking payment failure callback
-                            trackPaymentFailure(
-                                payload.orderId,
-                                payload.paymentId,
-                                publicKey,
-                                devMode,
-                                mockMode,
-                                checkoutUrl
-                            );
-                        } else {
-                            if (devMode) {
-                                console.error(
-                                    "[Glomo-RN-SDK LRS] Invalid payment failure payload from FlowWebView:",
-                                    payload
+                            return;
+                        }
+
+                        if (messageType === "payment.failure" || messageType === "payment.error") {
+                            const payload = messageData.payload;
+
+                            if (isValidPaymentPayload(payload)) {
+                                if (devMode) {
+                                    console.error(`${LOG_PREFIX} Payment failed via FlowWebView callback`);
+                                }
+                                setShowFlowWebView(false);
+                                setShowCheckout(false);
+                                setFlowWebViewUrl("");
+                                setEducationCarouselState("pending");
+                                setStatus("payment_failed");
+                                safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
+                                // Tracking payment failure callback
+                                trackPaymentFailure(
+                                    toPaymentEventData(payload),
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl
+                                );
+                                // Fires alongside the callback, not instead of it - the outcome is real, the payload is thin
+                                const missingFields = missingPaymentFields(payload);
+                                if (missingFields.length > 0) {
+                                    trackIncompletePaymentPayload(
+                                        "payment.failure",
+                                        missingFields,
+                                        "flow",
+                                        payload.orderId,
+                                        publicKey,
+                                        devMode,
+                                        mockMode,
+                                        checkoutUrl,
+                                        "lrs"
+                                    );
+                                }
+                            } else {
+                                /**
+                                 * Reported, not dropped. Before v5 this branch was a devMode-only console.error, so in a
+                                 * release build a terminal payment outcome the SDK could not route left no trace
+                                 * anywhere - no callback, no telemetry, nothing for support to find.
+                                 */
+                                if (devMode) {
+                                    console.error(
+                                        `${LOG_PREFIX} Unroutable payment.failure payload from flow:`,
+                                        payload
+                                    );
+                                }
+                                trackDroppedPaymentPayload(
+                                    "payment.failure",
+                                    payloadKeysOf(payload),
+                                    "flow",
+                                    orderId,
+                                    publicKey,
+                                    devMode,
+                                    mockMode,
+                                    checkoutUrl,
+                                    "lrs"
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.failure")]],
+                                    "onSdkError",
+                                    devMode
                                 );
                             }
                         }
-                        return;
-                    }
-                }
-            } catch (error) {
-                if (devMode) {
-                    console.error("[Glomo-RN-SDK LRS] Error parsing FlowWebView message:", error);
-                }
-            }
-        },
-        [onPaymentSuccess, onPaymentFailure, devMode, mockMode, orderId, publicKey, flowWebViewUrl, checkoutUrl]
+                    },
+                },
+            }),
+        [
+            onPaymentSuccess,
+            onPaymentFailure,
+            devMode,
+            mockMode,
+            orderId,
+            publicKey,
+            flowWebViewUrl,
+            checkoutUrl,
+            fileSaveHandler,
+            onSdkError,
+            fileInputHandler,
+        ]
     );
 
     // Handler for the education carousel WebView messages
-    const handleEducationCarouselWebViewMessage = useCallback(
-        (event: WebViewMessageEvent) => {
-            try {
-                const data = event.nativeEvent?.data;
-                if (!data || typeof data !== "string") {
-                    if (devMode) {
-                        console.warn("[Glomo-RN-SDK LRS] Invalid message data from EducationCarouselWebView");
-                    }
-                    return;
-                }
-
-                const message = JSON.parse(data);
-                if (devMode) {
-                    console.log("[Glomo-RN-SDK LRS] EducationCarouselWebView Message received:", message.type, message);
-                }
-
-                if (message.type === "console") {
-                    if (devMode) {
-                        console.log(`[Glomo-RN-SDK LRS] [EducationCarousel] ${message.message}`);
-                    }
-                    return;
-                }
+    const handleEducationCarouselWebViewMessage = useMemo(
+        () =>
+            createMessageRouter({
+                logPrefix: LOG_PREFIX,
+                source: "EducationCarouselWebView",
+                devMode,
+                handlers: {
+                    console: (message) => {
+                        if (devMode) {
+                            console.log(`${LOG_PREFIX} [EducationCarousel] ${message.message}`);
+                        }
+                    },
 
-                if (message.type === "lrs.has_education_steps") {
-                    const nextState: EducationCarouselState = "hasContent";
+                    "lrs.has_education_steps": (message) => {
+                        if (devMode) {
+                            console.log(
+                                `${LOG_PREFIX} Education carousel signal received: value=${String(message.value)} source=${message.source || "unknown"} payload=${JSON.stringify(message.payload || {})}`
+                            );
+                        }
 
-                    if (devMode) {
-                        console.log(
-                            `[Glomo-RN-SDK LRS] Education carousel signal received: value=${String(message.value)} source=${message.source || "unknown"} payload=${JSON.stringify(message.payload || {})}`
+                        trackEducationStepsShown(
+                            orderId,
+                            publicKey,
+                            devMode,
+                            mockMode,
+                            checkoutUrl,
+                            typeof message.source === "string" ? message.source : undefined
                         );
-                    }
-
-                    trackEducationStepsShown(orderId, publicKey, devMode, mockMode, checkoutUrl, message.source);
-                    setEducationCarouselState(nextState);
-                    return;
-                }
-            } catch (error) {
-                if (devMode) {
-                    console.error("[Glomo-RN-SDK LRS] Error parsing EducationCarouselWebView message:", error);
-                }
-            }
-        },
+                        setEducationCarouselState("hasContent");
+                    },
+                },
+            }),
         [checkoutUrl, devMode, mockMode, orderId, publicKey]
     );
 
@@ -689,10 +951,26 @@ export function useLrsCheckout(
                     console.log("[Glomo-RN-SDK LRS] 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";
-            trackPaymentTerminate(orderId, terminateSource, publicKey, devMode, mockMode, checkoutUrl);
+            /**
+             * Inferred from the platform rather than read off an event, because `onRequestClose` is
+             * the only wiring here and the two platforms raise it for different gestures: Android
+             * for hardware back and the back gesture, iOS for swipe-down on the pageSheet. Nothing
+             * else routes through it, so the inference is sound - but it is an inference.
+             */
+            const termination = {
+                source:
+                    Platform.OS === "ios" ? TERMINATION_SOURCES.MODAL_DISMISS : TERMINATION_SOURCES.DEVICE_BACK_BUTTON,
+            };
+            safeCallback(onPaymentTerminate, [termination], "onPaymentTerminate", devMode);
+            // One object to the host and to telemetry, so the two cannot drift
+            trackPaymentTerminate(
+                orderId,
+                toTerminationEventData(termination),
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl
+            );
         } catch (error) {
             if (devMode) {
                 console.error("[Glomo-RN-SDK LRS] Error in handleModalBackButton:", error);
@@ -700,6 +978,39 @@ export function useLrsCheckout(
         }
     }, [showFlowWebView, devMode, onPaymentTerminate, status, orderId, publicKey, mockMode, checkoutUrl]);
 
+    /**
+     * Closing the checkout when the user refuses camera access, since the bank page cannot
+     * proceed without it. Kept here rather than inside usePermissionRequest because moving the
+     * status and notifying the merchant are flow concerns.
+     */
+    const handleDevicePermissionDenied = useCallback(() => {
+        setShowCheckout(false);
+        setShowFlowWebView(false);
+        setFlowWebViewUrl("");
+        setEducationCarouselState("pending");
+        if (status === "payment_in_progress") {
+            setStatus("payment_cancelled");
+        }
+        safeCallback(onUserRefusedDevicePermissions, [], "onUserRefusedDevicePermissions", devMode);
+        // The permission hook only reaches here for camera; anything else is denied without notifying
+        trackDevicePermissionRefused(
+            "camera",
+            "permission_request",
+            orderId,
+            publicKey,
+            devMode,
+            mockMode,
+            checkoutUrl,
+            "lrs"
+        );
+    }, [status, onUserRefusedDevicePermissions, devMode, orderId, publicKey, mockMode, checkoutUrl]);
+
+    const handlePermissionRequest = usePermissionRequest({
+        logPrefix: "[Glomo-RN-SDK LRS]",
+        onDenied: handleDevicePermissionDenied,
+        devMode,
+    });
+
     /** Closes the flow WebView and returns to the main checkout */
     const handleFlowBack = useCallback(() => {
         if (devMode) {
@@ -708,7 +1019,7 @@ export function useLrsCheckout(
         setShowFlowWebView(false);
         setFlowWebViewUrl("");
         setEducationCarouselState("pending");
-        trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+        trackBackNavigationViaSdkBackButton(orderId, publicKey, devMode, mockMode, checkoutUrl, "lrs");
     }, [devMode, orderId, publicKey, mockMode, checkoutUrl]);
 
     /**
@@ -728,11 +1039,16 @@ export function useLrsCheckout(
          * 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,
+        const compliance = resolveDeviceCompliance(devMode);
+        const complianceLibraryInstalled = isComplianceCheckAvailable();
+        const fileSave = resolveFileSaveAvailability();
+        const dependencyInfo = {
+            jailbreakDetectionLibraryInstalled: complianceLibraryInstalled,
+            jailbreakDetected: compliance.compromised,
+            complianceSource: compliance.source,
+            complianceSignals: compliance.trippedSignals,
+            fileSaveAvailable: fileSave.available,
+            missingFileSavePackages: fileSave.missing,
         };
 
         if (devMode) {
@@ -740,37 +1056,64 @@ export function useLrsCheckout(
         }
 
         // Tracking start attempt with current status
-        trackStartAttempt(status, orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+        trackStartAttempt(status, orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
+
+        /**
+         * Ungated on purpose, both of them. An absent optional dependency degrades silently by
+         * design, so a console warning is the only thing that reaches a merchant who has not
+         * noticed - and the compliance one now precedes a hard block on live keys.
+         */
+        if (!complianceLibraryInstalled) {
+            console.warn(
+                "[Glomo-RN-SDK LRS] jail-monkey is not installed or its native module is not linked, so " +
+                    "rooted and jailbroken devices cannot be detected. As of v5 this BLOCKS live checkouts. " +
+                    "Install jail-monkey and rebuild the app - see the README."
+            );
+        }
+        if (!fileSave.available) {
+            console.warn(
+                `[Glomo-RN-SDK LRS] Document downloads are disabled: ${fileSave.missing.join(" and ")} ` +
+                    "could not be loaded. Install the package(s) and rebuild the app, or ignore this if your " +
+                    "checkout does not offer downloads - the page falls back to its own behaviour."
+            );
+        }
 
-        if (deviceComplianceCheck === true) {
-            // Device detected as compromised
+        if (blocksCheckout(compliance, publicKey)) {
+            /**
+             * Two conditions, one refusal. `compromised === true` is a rooted or jailbroken device;
+             * `null` is a device we could not check, which on RN overwhelmingly means jail-monkey is
+             * absent rather than that a platform probe failed. Both fail closed on a live key, and
+             * neither fires on a test or mock key.
+             */
+            const unknown = compliance.compromised === null;
             if (devMode) {
-                console.error("[Glomo-RN-SDK LRS] Cannot start checkout. Device is rooted or jailbroken.");
+                console.error(
+                    `[Glomo-RN-SDK LRS] Cannot start checkout. ${
+                        unknown ? "Device security could not be verified." : "Device is rooted or jailbroken."
+                    }`
+                );
             }
             const errors: SdkError[] = [
                 {
                     type: "device_forbidden",
-                    message: "LRS checkout is not allowed on rooted or jailbroken devices.",
+                    message: unknown
+                        ? "LRS checkout could not verify this device's security. Install jail-monkey and rebuild the app."
+                        : "LRS checkout is not allowed on rooted or jailbroken devices.",
                 },
             ];
             safeCallback(onSdkError, [errors], "onSdkError", devMode);
             // Tracking start() failure
             trackStartFailure(
-                "device_forbidden",
+                unknown ? "device_compliance_unknown" : "device_forbidden",
                 orderId,
                 publicKey,
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             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 LRS] 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 LRS checkouts from compromised devices."
-            );
         }
 
         // Enforcing devMode requirement for development servers
@@ -784,15 +1127,7 @@ export function useLrsCheckout(
             ];
             safeCallback(onSdkError, [errors], "onSdkError", devMode);
             trackSdkError(errors, orderId, publicKey, devMode, mockMode, checkoutUrl);
-            trackStartFailure(
-                "validation_error",
-                orderId,
-                publicKey,
-                devMode,
-                mockMode,
-                checkoutUrl,
-                jailbreakDetectionInfo
-            );
+            trackStartFailure("validation_error", orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
             setShowCheckout(false);
             return false;
         }
@@ -840,15 +1175,7 @@ export function useLrsCheckout(
             safeCallback(onSdkError, [errors], "onSdkError", devMode);
             // Tracking start() failure
             trackSdkError(errors, orderId, publicKey, devMode, mockMode, checkoutUrl);
-            trackStartFailure(
-                "validation_error",
-                orderId,
-                publicKey,
-                devMode,
-                mockMode,
-                checkoutUrl,
-                jailbreakDetectionInfo
-            );
+            trackStartFailure("validation_error", orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
             setShowCheckout(false);
             return false;
         }
@@ -860,15 +1187,7 @@ export function useLrsCheckout(
                 );
             }
             // Tracking start() failure
-            trackStartFailure(
-                "payment_successful",
-                orderId,
-                publicKey,
-                devMode,
-                mockMode,
-                checkoutUrl,
-                jailbreakDetectionInfo
-            );
+            trackStartFailure("payment_successful", orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
             setShowCheckout(false);
             return false;
         }
@@ -885,15 +1204,7 @@ export function useLrsCheckout(
                 console.log(`[Glomo-RN-SDK LRS] Cannot start checkout. Unknown status: ${status}.`);
             }
             // Tracking start() failure
-            trackStartFailure(
-                "invalid_status",
-                orderId,
-                publicKey,
-                devMode,
-                mockMode,
-                checkoutUrl,
-                jailbreakDetectionInfo
-            );
+            trackStartFailure("invalid_status", orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
             setShowCheckout(false);
             return false;
         }
@@ -903,15 +1214,7 @@ export function useLrsCheckout(
                 console.error("[Glomo-RN-SDK LRS] Cannot start checkout. Invalid checkout URL.");
             }
             // Tracking start() failure
-            trackStartFailure(
-                "invalid_url",
-                orderId,
-                publicKey,
-                devMode,
-                mockMode,
-                checkoutUrl,
-                jailbreakDetectionInfo
-            );
+            trackStartFailure("invalid_url", orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
             setShowCheckout(false);
             return false;
         }
@@ -926,7 +1229,7 @@ export function useLrsCheckout(
         setStatus("payment_in_progress");
 
         // Tracking successful start
-        trackStartSuccess(orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+        trackStartSuccess(orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
 
         setShowCheckout(true);
         return true;
@@ -970,6 +1273,14 @@ export function useLrsCheckout(
         };
     }, []);
 
+    /**
+     * Scripts injected into each WebView, carrying what this build can advertise.
+     *
+     * Resolved once per mount rather than at module load, so a merchant who never opens a
+     * checkout never pays for the dependency probe.
+     */
+    const injectionScripts = useMemo(() => buildInjectionScripts(resolveCapabilities()), []);
+
     return {
         start,
         status,
@@ -990,8 +1301,15 @@ export function useLrsCheckout(
         handleNavigationStateChange,
         handleModalBackButton,
         handleFlowBack,
-        injectedMain: InjectionScripts.main,
-        injectedFlow: InjectionScripts.flow,
-        injectedEducationCarousel: InjectionScripts.educationCarousel,
+        handlePermissionRequest,
+        injectedMain:
+            __DEV__ && internalOptions?._testInjectionScript
+                ? injectionScripts.main + internalOptions._testInjectionScript
+                : injectionScripts.main,
+        injectedFlow: injectionScripts.flow,
+        injectedEducationCarousel:
+            __DEV__ && internalOptions?._testCarouselInjectionScript
+                ? injectionScripts.educationCarousel + internalOptions._testCarouselInjectionScript
+                : injectionScripts.educationCarousel,
     };
 }