@glomopay/react-native-sdk 4.1.0 → 5.0.0

package/src/use-standard-checkout.tsx

@@ -1,26 +1,52 @@
 /** 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 { 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 { type SdkError, type CheckoutAnalyticsTrackers, standardCheckoutTrackers } from "./utils/analytics";
-
-import { ASYNC_PAYMENT_EVENTS, type GlomoUserJourneyCompletedPayload } from "./types/checkout";
+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, toJourneyEventData } from "./utils/event-projections";
+import { resolveDeviceCompliance, blocksCheckout, isComplianceCheckAvailable } from "./utils/device-compliance";
+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 { usePermissionRequest, type WebViewPermissionRequest } from "./webview/use-permission-request";
+import {
+    trackIncompletePaymentPayload,
+    trackDroppedPaymentPayload,
+    trackDevicePermissionRefused,
+    trackBackNavigationViaSdkBackButton,
+    type SdkError,
+    type FlowType,
+    type CheckoutAnalyticsTrackers,
+    standardCheckoutTrackers,
+} from "./utils/analytics";
+
+import {
+    ASYNC_PAYMENT_EVENTS,
+    TERMINATION_SOURCES,
+    type GlomoTerminationPayload,
+    type GlomoUserJourneyCompletedPayload,
+} 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;
-}
+/** Log prefix for everything this flow emits */
+const LOG_PREFIX = "[Glomo-RN-SDK Standard]";
 
 /** The options for the useStandardCheckout hook */
 export interface UseStandardCheckoutOptions {
@@ -30,10 +56,10 @@ export interface UseStandardCheckoutOptions {
     onPaymentSuccess: (payload: GlomoStandardCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoStandardCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
-    onPaymentTerminate?: () => void;
+    onPaymentTerminate?: (payload: GlomoTerminationPayload) => void;
     onSdkError: (error: Array<SdkError>) => void;
     onUserJourneyCompleted?: (payload: GlomoUserJourneyCompletedPayload) => void;
-    onUserRefusedCameraPermissions?: () => void;
+    onUserRefusedDevicePermissions?: () => void;
     devMode?: boolean;
 }
 
@@ -68,6 +94,19 @@ export interface UseStandardCheckoutReturn {
  */
 export interface UseStandardCheckoutInternalOptions {
     analyticsTrackers?: CheckoutAnalyticsTrackers;
+
+    /**
+     * Which flow this hook is serving, for the telemetry that is not routed through
+     * analyticsTrackers.
+     *
+     * The tracker map cannot answer this: its whole purpose is that the caller picks a set of
+     * flow-specific functions, so a flow-indifferent event has nothing to look up there. File saves
+     * are the first of those - the capability is advertised to every WebView regardless of flow -
+     * and putting them in the map would re-couple a capability to a flow, which is the thing v5
+     * exists to undo.
+     */
+    flowType?: FlowType;
+
     _skipOrderIdValidation?: boolean;
     _testInjectionScript?: string;
 }
@@ -84,7 +123,7 @@ export function useStandardCheckout(
         onPaymentTerminate,
         onSdkError,
         onUserJourneyCompleted,
-        onUserRefusedCameraPermissions,
+        onUserRefusedDevicePermissions,
         devMode = false,
     }: UseStandardCheckoutOptions,
     mockMode: boolean,
@@ -92,6 +131,7 @@ export function useStandardCheckout(
 ): UseStandardCheckoutReturn {
     // Resolving analytics trackers - defaults to standard, subscription flow overrides
     const trackers = internalOptions?.analyticsTrackers ?? standardCheckoutTrackers;
+    const flowType = internalOptions?.flowType ?? "standard";
     // Refs for the WebViews
     const mainWebViewRef = useRef<WebView>(null);
     const flowWebViewRef = useRef<WebView>(null);
@@ -113,7 +153,9 @@ export function useStandardCheckout(
             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("&");
 
@@ -237,22 +279,65 @@ export function useStandardCheckout(
         [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: flowType,
+                orderId,
+                publicKey,
+                checkoutUrl,
+                mockMode,
+                devMode,
+            }),
+        [orderId, publicKey, checkoutUrl, mockMode, devMode, flowType]
+    );
+
+    /**
+     * 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,
+                orderId,
+                publicKey,
+                checkoutUrl,
+                mockMode,
+                devMode,
+                onSdkError,
+            }),
+        [flowType, orderId, publicKey, checkoutUrl, mockMode, devMode, onSdkError]
+    );
+
     /**
      * 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
+    const handleMainWebViewMessage = useMemo(
+        () =>
+            createMessageRouter({
+                logPrefix: LOG_PREFIX,
+                source: "MainWebView",
+                devMode,
+                onInvalidMessage: (data) => {
                     trackers.trackInvalidMessageReceived(
                         "main",
                         data,
@@ -263,216 +348,295 @@ export function useStandardCheckout(
                         mockMode,
                         checkoutUrl
                     );
-                    return;
-                }
+                },
+                handlers: {
+                    "file.save": fileSaveHandler,
+                    "file.input": fileInputHandler,
 
-                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
+                    console: (message) => {
+                        if (devMode) {
+                            const level = (typeof message.level === "string" && message.level) || "log";
+                            console.log(`${LOG_PREFIX} [WebView ${level.toUpperCase()}]`, message.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
+                    "window.open": (message) => {
+                        const url = message.url;
+                        if (url && typeof url === "string" && isValidUrl(url)) {
+                            if (devMode) {
+                                console.log(`${LOG_PREFIX} 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(
+                                    `${LOG_PREFIX} Invalid URL in window.open from MainWebView:`,
+                                    url,
+                                    typeof url === "undefined" ? "undefined" : ""
+                                );
+                            }
+                        }
+                    },
 
-                // 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)) {
+                    // Intercepting window.close calls - closing the flow WebView overlay
+                    "window.close": () => {
                         if (devMode) {
-                            console.log(`[Glomo-RN-SDK Standard] window.open called from MainWebView: ${url}`);
+                            console.log(`${LOG_PREFIX} Child window close requested from MainWebView`);
                         }
-                        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" : ""
-                            );
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        // Tracking window.close interception
+                        trackers.trackWindowClose("main", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    },
+
+                    // Handling merchant JS callbacks on flow completion (payment events, lifecycle events)
+                    message: (message) => {
+                        const messageData = message.message as
+                            | { type?: string; payload?: Record<string, string | undefined> }
+                            | undefined;
+                        if (!messageData) return;
+                        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(
+                                    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,
+                                        flowType
+                                    );
+                                }
+                            } 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,
+                                    flowType
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.success")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            return;
                         }
-                    }
-                    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;
+                        // 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(
+                                    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,
+                                        flowType
+                                    );
+                                }
+                            } 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,
+                                    flowType
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.failure")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            return;
+                        }
 
-                        if (isValidPaymentPayload(payload)) {
+                        // 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] Payment successful via merchant callback!");
+                                console.log("[Glomo-RN-SDK Standard] Bank transfer submitted:", payload);
                             }
                             setShowCheckout(false);
                             setShowFlowWebView(false);
                             setFlowWebViewUrl("");
-                            setStatus("payment_successful");
-                            safeCallback(onPaymentSuccess, [payload], "onPaymentSuccess", devMode);
-                            // Tracking payment success callback
-                            trackers.trackPaymentSuccess(
-                                payload.orderId,
-                                payload.paymentId,
+                            setStatus("bank_transfer_submitted");
+                            const journeyPayload: GlomoUserJourneyCompletedPayload = {
+                                journeyType: ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED,
+                                orderId: payload?.orderId,
+                                senderAccountNumber: payload?.senderAccountNumber,
+                                transactionReference: payload?.transactionReference,
+                            };
+                            safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", devMode);
+                            trackers.trackBankTransferSubmitted(
+                                orderId,
+                                toJourneyEventData(journeyPayload),
                                 publicKey,
                                 devMode,
                                 mockMode,
                                 checkoutUrl
                             );
-                        } else {
-                            if (devMode) {
-                                console.error("[Glomo-RN-SDK Standard] Invalid payment success payload:", payload);
-                            }
+                            return;
                         }
-                        return;
-                    }
 
-                    // Handling payment failure - closing checkout and notifying the merchant
-                    if (messageType === "payment.failure" || messageType === "payment.error") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
+                        /**
+                         * 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;
 
-                        if (isValidPaymentPayload(payload)) {
+                            const payload = messageData?.payload;
                             if (devMode) {
-                                console.error("[Glomo-RN-SDK Standard] Payment failed via merchant callback");
+                                console.log("[Glomo-RN-SDK Standard] Pay via bank completed via MainWebView:", payload);
                             }
-                            setShowCheckout(false);
                             setShowFlowWebView(false);
+                            setShowCheckout(false);
                             setFlowWebViewUrl("");
-                            setStatus("payment_failed");
-                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
-                            // Tracking payment failure callback
-                            trackers.trackPaymentFailure(
-                                payload.orderId,
-                                payload.paymentId,
+                            setStatus("pay_via_bank_completed");
+                            const journeyPayload: GlomoUserJourneyCompletedPayload = {
+                                journeyType: ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED,
+                                orderId: payload?.orderId,
+                                status: payload?.status ?? "unknown",
+                            };
+                            safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", devMode);
+                            trackers.trackPayViaBankCompleted(
+                                orderId,
+                                toJourneyEventData(journeyPayload),
                                 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);
+                            return;
                         }
-                        setShowCheckout(false);
-                        setShowFlowWebView(false);
-                        setFlowWebViewUrl("");
-                        setStatus("bank_transfer_submitted");
-                        const journeyPayload: GlomoUserJourneyCompletedPayload = {
-                            journeyType: ASYNC_PAYMENT_EVENTS.BANK_TRANSFER_SUBMITTED,
-                            orderId: payload?.orderId,
-                            senderAccountNumber: payload?.senderAccountNumber,
-                            transactionReference: payload?.transactionReference,
-                        };
-                        safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", devMode);
-                        trackers.trackBankTransferSubmitted(orderId, publicKey, 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) {
+                        // Handling checkout.closed events
+                        if (messageType === "checkout.closed") {
                             if (devMode) {
-                                console.log(
-                                    "[Glomo-RN-SDK Standard] Pay via bank completed already handled, ignoring duplicate"
-                                );
+                                console.log("[Glomo-RN-SDK Standard] Checkout closed event received");
                             }
+                            setShowCheckout(false);
+                            setShowFlowWebView(false);
+                            setFlowWebViewUrl("");
+                            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
+                            trackers.trackPaymentTerminate(
+                                orderId,
+                                toTerminationEventData(termination),
+                                publicKey,
+                                devMode,
+                                mockMode,
+                                checkoutUrl
+                            );
                             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");
-                        const journeyPayload: GlomoUserJourneyCompletedPayload = {
-                            journeyType: ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED,
-                            orderId: payload?.orderId,
-                            status: payload?.status ?? "unknown",
-                        };
-                        safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", 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,
@@ -484,6 +648,10 @@ export function useStandardCheckout(
             publicKey,
             checkoutUrl,
             trackers,
+            fileSaveHandler,
+            flowType,
+            onSdkError,
+            fileInputHandler,
         ]
     );
 
@@ -492,16 +660,13 @@ export function useStandardCheckout(
      * 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
+    const handleFlowWebViewMessage = useMemo(
+        () =>
+            createMessageRouter({
+                logPrefix: LOG_PREFIX,
+                source: "FlowWebView",
+                devMode,
+                onInvalidMessage: (data) => {
                     trackers.trackInvalidMessageReceived(
                         "flow",
                         data,
@@ -512,173 +677,257 @@ export function useStandardCheckout(
                         mockMode,
                         checkoutUrl
                     );
-                    return;
-                }
-
-                const message = JSON.parse(data);
-                if (devMode) {
-                    console.log("[Glomo-RN-SDK Standard] 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,
+                            flowType
+                        );
+                    },
 
-                // 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;
-                }
+                    "file.save": fileSaveHandler,
+                    "file.input": fileInputHandler,
 
-                // 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 {
+                    // Forwarding console messages from the flow WebView's injected script
+                    console: (message) => {
                         if (devMode) {
-                            console.log(
-                                "[Glomo-RN-SDK Standard] Invalid URL in window.open from FlowWebView:",
-                                url,
-                                typeof url === "undefined" ? "undefined" : ""
-                            );
+                            console.log(`${LOG_PREFIX} [Flow] ${message.message}`);
                         }
-                    }
-                    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)) {
+                    // Intercepting window.open calls from the flow WebView - navigating within the same overlay
+                    "window.open": (message) => {
+                        const url = message.url;
+                        if (url && typeof url === "string" && isValidUrl(url)) {
                             if (devMode) {
-                                console.log("[Glomo-RN-SDK Standard] Payment successful via FlowWebView callback!");
+                                console.log(`${LOG_PREFIX} window.open called from FlowWebView: ${url}`);
                             }
-                            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
-                            );
+                            setFlowWebViewUrl(url);
+                            // Tracking window.open interception
+                            trackers.trackWindowOpen("flow", url, orderId, publicKey, devMode, mockMode, checkoutUrl);
                         } else {
                             if (devMode) {
-                                console.error(
-                                    "[Glomo-RN-SDK Standard] Invalid payment success payload from FlowWebView:",
-                                    payload
+                                console.log(
+                                    `${LOG_PREFIX} Invalid URL in window.open from FlowWebView:`,
+                                    url,
+                                    typeof url === "undefined" ? "undefined" : ""
                                 );
                             }
                         }
-                        return;
-                    }
+                    },
+
+                    // Intercepting window.close calls from the flow WebView - closing the overlay
+                    "window.close": () => {
+                        if (devMode) {
+                            console.log(`${LOG_PREFIX} FlowWebView close requested`);
+                        }
+                        setShowFlowWebView(false);
+                        setFlowWebViewUrl("");
+                        // Tracking window.close interception
+                        trackers.trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
+                    },
+
+                    // Handling merchant JS callbacks from the flow WebView (payment events, lifecycle events)
+                    message: (message) => {
+                        const messageData = message.message as
+                            | { type?: string; payload?: Record<string, string | undefined> }
+                            | undefined;
+                        if (!messageData) return;
+                        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(
+                                    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,
+                                        flowType
+                                    );
+                                }
+                            } 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,
+                                    flowType
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.success")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            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(
+                                    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,
+                                        flowType
+                                    );
+                                }
+                            } 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,
+                                    flowType
+                                );
+                                safeCallback(
+                                    onSdkError,
+                                    [[droppedPayloadSdkError("payment.failure")]],
+                                    "onSdkError",
+                                    devMode
+                                );
+                            }
+                            return;
+                        }
 
-                    // Handling payment failure from the flow WebView
-                    if (messageType === "payment.failure" || messageType === "payment.error") {
-                        const paymentMessage = messageData;
-                        const payload = paymentMessage?.payload;
+                        // 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;
 
-                        if (isValidPaymentPayload(payload)) {
+                            const payload = messageData?.payload;
                             if (devMode) {
-                                console.error("[Glomo-RN-SDK Standard] Payment failed via FlowWebView callback");
+                                console.log("[Glomo-RN-SDK Standard] Pay via bank completed via FlowWebView:", payload);
                             }
                             setShowFlowWebView(false);
                             setShowCheckout(false);
                             setFlowWebViewUrl("");
-                            setStatus("payment_failed");
-                            safeCallback(onPaymentFailure, [payload], "onPaymentFailure", devMode);
-                            // Tracking payment failure callback
-                            trackers.trackPaymentFailure(
-                                payload.orderId,
-                                payload.paymentId,
+                            setStatus("pay_via_bank_completed");
+                            const journeyPayload: GlomoUserJourneyCompletedPayload = {
+                                journeyType: ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED,
+                                orderId: payload?.orderId,
+                                status: payload?.status ?? "unknown",
+                            };
+                            safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", devMode);
+                            trackers.trackPayViaBankCompleted(
+                                orderId,
+                                toJourneyEventData(journeyPayload),
                                 publicKey,
                                 devMode,
                                 mockMode,
                                 checkoutUrl
                             );
-                        } else {
-                            if (devMode) {
-                                console.error(
-                                    "[Glomo-RN-SDK Standard] Invalid payment failure payload from FlowWebView:",
-                                    payload
-                                );
-                            }
-                        }
-                        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");
-                        const journeyPayload: GlomoUserJourneyCompletedPayload = {
-                            journeyType: ASYNC_PAYMENT_EVENTS.PAY_VIA_BANK_COMPLETED,
-                            orderId: payload?.orderId,
-                            status: payload?.status ?? "unknown",
-                        };
-                        safeCallback(onUserJourneyCompleted, [journeyPayload], "onUserJourneyCompleted", 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,
@@ -690,6 +939,10 @@ export function useStandardCheckout(
             flowWebViewUrl,
             checkoutUrl,
             trackers,
+            fileSaveHandler,
+            flowType,
+            onSdkError,
+            fileInputHandler,
         ]
     );
 
@@ -724,10 +977,26 @@ export function useStandardCheckout(
                     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);
+            /**
+             * 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
+            trackers.trackPaymentTerminate(
+                orderId,
+                toTerminationEventData(termination),
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl
+            );
         } catch (error) {
             if (devMode) {
                 console.error("[Glomo-RN-SDK Standard] Error in handleModalBackButton:", error);
@@ -742,93 +1011,46 @@ export function useStandardCheckout(
         }
         setShowFlowWebView(false);
         setFlowWebViewUrl("");
-        trackers.trackWindowClose("flow", orderId, publicKey, devMode, mockMode, checkoutUrl);
-    }, [devMode, orderId, publicKey, mockMode, checkoutUrl, trackers]);
+        trackBackNavigationViaSdkBackButton(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType);
+    }, [devMode, orderId, publicKey, mockMode, checkoutUrl, flowType]);
 
     /**
-     * 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.
+     * 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.
+     *
+     * Resets the flow overlay as well as the modal, matching the LRS handler. The prompt is raised
+     * from a bank page inside that overlay, so this is the one close path where the flow state is
+     * guaranteed non-default. Nothing visible depends on it today - the overlay renders inside the
+     * Modal and unmounts with it - but "every close path resets derived state" should not hold in
+     * one flow and not the other.
      */
-    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");
-                }
+    const handleCameraPermissionDenied = useCallback(() => {
+        setShowCheckout(false);
+        setShowFlowWebView(false);
+        setFlowWebViewUrl("");
+        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,
+            flowType
+        );
+    }, [status, onUserRefusedDevicePermissions, devMode, orderId, publicKey, mockMode, checkoutUrl, flowType]);
 
-                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]
-    );
+    const handlePermissionRequest = usePermissionRequest({
+        logPrefix: "[Glomo-RN-SDK Standard]",
+        onDenied: handleCameraPermissionDenied,
+        devMode,
+    });
 
     /**
      * Initiator method for the Standard Checkout flow.
@@ -847,11 +1069,16 @@ export function useStandardCheckout(
          * 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) {
@@ -861,37 +1088,64 @@ export function useStandardCheckout(
         }
 
         // Tracking start attempt with current status
-        trackers.trackStartAttempt(status, orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+        trackers.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 Standard] 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 Standard] 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 Standard] Cannot start checkout. Device is rooted or jailbroken.");
+                console.error(
+                    `[Glomo-RN-SDK Standard] Cannot start checkout. ${
+                        unknown ? "Device security could not be verified." : "Device is rooted or jailbroken."
+                    }`
+                );
             }
             const errors: SdkError[] = [
                 {
                     type: "device_forbidden",
-                    message: "Standard checkout is not allowed on rooted or jailbroken devices.",
+                    message: unknown
+                        ? "Standard checkout could not verify this device's security. Install jail-monkey and rebuild the app."
+                        : "Standard checkout is not allowed on rooted or jailbroken devices.",
                 },
             ];
             safeCallback(onSdkError, [errors], "onSdkError", devMode);
             // Tracking start() failure
             trackers.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 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
@@ -912,7 +1166,7 @@ export function useStandardCheckout(
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             setShowCheckout(false);
             return false;
@@ -968,7 +1222,7 @@ export function useStandardCheckout(
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             setShowCheckout(false);
             return false;
@@ -988,7 +1242,7 @@ export function useStandardCheckout(
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             setShowCheckout(false);
             return false;
@@ -1013,7 +1267,7 @@ export function useStandardCheckout(
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             setShowCheckout(false);
             return false;
@@ -1031,7 +1285,7 @@ export function useStandardCheckout(
                 devMode,
                 mockMode,
                 checkoutUrl,
-                jailbreakDetectionInfo
+                dependencyInfo
             );
             setShowCheckout(false);
             return false;
@@ -1048,7 +1302,7 @@ export function useStandardCheckout(
         setStatus("payment_in_progress");
 
         // Tracking successful start
-        trackers.trackStartSuccess(orderId, publicKey, devMode, mockMode, checkoutUrl, jailbreakDetectionInfo);
+        trackers.trackStartSuccess(orderId, publicKey, devMode, mockMode, checkoutUrl, dependencyInfo);
 
         // Opening the checkout modal
         setShowCheckout(true);
@@ -1104,6 +1358,14 @@ export function useStandardCheckout(
         };
     }, []);
 
+    /**
+     * 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,
@@ -1123,8 +1385,8 @@ export function useStandardCheckout(
         handleFlowBack,
         injectedMain:
             __DEV__ && internalOptions?._testInjectionScript
-                ? InjectionScripts.standard + internalOptions._testInjectionScript
-                : InjectionScripts.standard,
-        injectedFlow: InjectionScripts.flow,
+                ? injectionScripts.standard + internalOptions._testInjectionScript
+                : injectionScripts.standard,
+        injectedFlow: injectionScripts.flow,
     };
 }