refactor(ramp): remove checkout callback registry from unified Checkout (#28417)

## **Description**

Removes the **`checkoutCallbackRegistry`** indirection from the unified
Ramp [`Checkout`](app/components/UI/Ramp/Views/Checkout/Checkout.tsx)
screen and
[`useTransakRouting`](app/components/UI/Ramp/hooks/useTransakRouting.ts)
(Transak buy flow). Handlers are passed as **`onNavigationStateChange`**
on Checkout route params;
[`Checkout`](app/components/UI/Ramp/Views/Checkout/Checkout.tsx) applies
URL de-duplication before invoking that callback. The registry module
and its unit tests are deleted.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Refs:

## **Manual testing steps**

```gherkin
Feature: Transak buy payment webview

  Scenario: User opens Checkout after KYC approved
    Given user completes Transak flow until the unified Checkout WebView opens
    When the provider redirects through the expected success or callback URL
    Then order handling and navigation behave as before
```

## **Screenshots/Recordings**

Not applicable — wiring-only change.

### **Before**

N/A

### **After**




https://github.com/user-attachments/assets/e16f92bf-ed0e-459a-9005-90ff8dadc489


## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

## **Labels note**

This PR sets **CHANGELOG entry: null**. If your release or CI workflow
expects it, add the `no-changelog` label on GitHub (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).

`team-money-movement` may already be applied by automation. Add
`team-ramps` if that better matches ownership for Ramp /
`app/components/UI/Ramp` changes.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes how the Checkout WebView callback is wired (route param
function instead of registry) and adds URL de-duplication, which could
affect provider redirect handling if any callers relied on the old
callbackKey behavior.
> 
> **Overview**
> Removes the `checkoutCallbackRegistry` indirection and deletes its
implementation/tests, switching Checkout callback wiring to pass an
`onNavigationStateChange` handler directly via Checkout route params.
> 
> Updates `Checkout` to invoke that param callback only after URL
de-duplication (while keeping the existing callback flow for
`providerCode`/`walletAddress`), and updates `useTransakRouting` and
related tests to use the new param-based callback.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
abb4c3f. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: wachunei

app/components/UI/Ramp/Views/Checkout/Checkout.test.tsx

@@ -3,10 +3,6 @@ import React from 'react';
 import { fireEvent, act, waitFor } from '@testing-library/react-native';
 import Checkout from './Checkout';
 import renderWithProvider from '../../../../../util/test/renderWithProvider';
-import {
-  registerCheckoutCallback,
-  removeCheckoutCallback,
-} from '../../utils/checkoutCallbackRegistry';
 import { MetaMetricsEvents } from '../../../../../core/Analytics';
 import { callbackBaseUrl } from '../../Aggregator/sdk';
 
@@ -352,15 +348,14 @@ describe('Checkout', () => {
     });
   });
 
-  describe('checkout callback registry (297-302)', () => {
-    it('invokes registered callback when callbackKey is set and WebView navigates to new URL', async () => {
+  describe('onNavigationStateChange with URL deduplication', () => {
+    it('invokes param callback when WebView navigates to new URL', async () => {
       const mockCallback = jest.fn();
-      const callbackKey = registerCheckoutCallback(mockCallback);
 
       mockUseParams.mockReturnValue({
         url: 'https://provider.example.com',
         providerName: 'Test',
-        callbackKey,
+        onNavigationStateChange: mockCallback,
       });
 
       const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
@@ -374,18 +369,15 @@ describe('Checkout', () => {
           url: 'https://custom-dedup-url.example.com',
         }),
       );
-
-      removeCheckoutCallback(callbackKey);
     });
 
     it('does not invoke callback on second navigation to same URL (dedup)', async () => {
       const mockCallback = jest.fn();
-      const callbackKey = registerCheckoutCallback(mockCallback);
 
       mockUseParams.mockReturnValue({
         url: 'https://provider.example.com',
         providerName: 'Test',
-        callbackKey,
+        onNavigationStateChange: mockCallback,
       });
 
       const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
@@ -396,8 +388,6 @@ describe('Checkout', () => {
       });
 
       expect(mockCallback).toHaveBeenCalledTimes(1);
-
-      removeCheckoutCallback(callbackKey);
     });
   });
 

app/components/UI/Ramp/Views/Checkout/Checkout.tsx

@@ -32,10 +32,6 @@ import { useStyles } from '../../../../../component-library/hooks';
 import styleSheet from './Checkout.styles';
 import Device from '../../../../../util/device';
 import { shouldStartLoadWithRequest } from '../../../../../util/browser';
-import {
-  getCheckoutCallback,
-  removeCheckoutCallback,
-} from '../../utils/checkoutCallbackRegistry';
 import { CHECKOUT_TEST_IDS } from './Checkout.testIds';
 
 interface CheckoutParams {
@@ -59,12 +55,7 @@ interface CheckoutParams {
   cryptocurrency?: string;
   /** V2: the Redux provider type for this order. Defaults to AGGREGATOR. */
   providerType?: FIAT_ORDER_PROVIDERS;
-  /**
-   * Key into the checkout callback registry. Used by Transak/Deposit flows.
-   * The actual callback lives outside navigation state so that route params stay serializable.
-   */
-  callbackKey?: string;
-  /** Optional callback invoked on every navigation state change (e.g. to intercept redirect URLs). */
+  /** Optional callback invoked on navigation state changes after URL de-duplication (e.g. redirect URLs). */
   onNavigationStateChange?: (navState: { url: string }) => void;
 }
 
@@ -99,24 +90,13 @@ const Checkout = () => {
     network,
     userAgent,
     onNavigationStateChange,
-    callbackKey,
   } = params ?? {};
   const effectiveOrderId = (orderIdParam ?? customOrderId)?.trim() || null;
 
   const initialUriRef = useRef(uri);
-  const callbackKeyRef = useRef(callbackKey);
   const registeredOrderIdsRef = useRef<Set<string>>(new Set());
   const hasCallbackFlow = Boolean(providerCode && walletAddress);
 
-  useEffect(() => {
-    callbackKeyRef.current = callbackKey;
-    return () => {
-      if (callbackKey) {
-        removeCheckoutCallback(callbackKey);
-      }
-    };
-  }, [callbackKey]);
-
   useEffect(() => {
     navigation.setOptions(
       getDepositNavbarOptions(
@@ -291,12 +271,10 @@ const Checkout = () => {
     (navState: { url: string }) => {
       if (navState.url !== previousUrlRef.current) {
         previousUrlRef.current = navState.url;
-        if (callbackKeyRef.current) {
-          getCheckoutCallback(callbackKeyRef.current)?.(navState);
-        }
+        onNavigationStateChange?.(navState);
       }
     },
-    [],
+    [onNavigationStateChange],
   );
 
   const handleShouldStartLoadWithRequest = useCallback(
@@ -380,9 +358,9 @@ const Checkout = () => {
           onNavigationStateChange={
             hasCallbackFlow
               ? handleNavigationStateChange
-              : callbackKey
+              : onNavigationStateChange
                 ? handleNavigationStateChangeWithDedup
-                : onNavigationStateChange
+                : undefined
           }
           onShouldStartLoadWithRequest={handleShouldStartLoadWithRequest}
           testID={CHECKOUT_TEST_IDS.WEBVIEW}

app/components/UI/Ramp/hooks/useTransakRouting.test.ts

@@ -135,28 +135,23 @@ jest.mock('../Deposit/utils', () => ({
   generateThemeParameters: jest.fn(() => ({ theme: 'light' })),
 }));
 
+let capturedHandleNavigationStateChange:
+  | ((nav: { url: string }) => void)
+  | null = null;
+
 jest.mock('../Views/Checkout', () => ({
   createCheckoutNavDetails: jest.fn(
     ({
       url,
       providerName,
-      callbackKey,
+      onNavigationStateChange,
     }: {
       url: string;
       providerName: string;
-      callbackKey?: string;
-    }) => ['Checkout', { url, providerName, callbackKey }],
-  ),
-}));
-
-let capturedHandleNavigationStateChange:
-  | ((nav: { url: string }) => void)
-  | null = null;
-jest.mock('../utils/checkoutCallbackRegistry', () => ({
-  registerCheckoutCallback: jest.fn(
-    (callback: (nav: { url: string }) => void) => {
-      capturedHandleNavigationStateChange = callback;
-      return 'mock-callback-key';
+      onNavigationStateChange?: (nav: { url: string }) => void;
+    }) => {
+      capturedHandleNavigationStateChange = onNavigationStateChange ?? null;
+      return ['Checkout', { url, providerName, onNavigationStateChange }];
     },
   ),
 }));
@@ -188,6 +183,7 @@ const mockQuote = {
 describe('useTransakRouting', () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    capturedHandleNavigationStateChange = null;
     mockUserRegion = {
       country: { currency: 'USD', isoCode: 'US' },
       regionCode: 'us-ca',
@@ -299,6 +295,7 @@ describe('useTransakRouting', () => {
               params: expect.objectContaining({
                 url: 'https://payment.example.com',
                 providerName: 'Transak',
+                onNavigationStateChange: expect.any(Function),
               }),
             }),
           ],

app/components/UI/Ramp/hooks/useTransakRouting.ts

@@ -14,7 +14,6 @@ import { generateThemeParameters } from '../Deposit/utils';
 import { BasicInfoFormData } from '../Deposit/Views/BasicInfo/BasicInfo';
 import { AddressFormData } from '../Deposit/Views/EnterAddress/EnterAddress';
 import { createCheckoutNavDetails } from '../Views/Checkout';
-import { registerCheckoutCallback } from '../utils/checkoutCallbackRegistry';
 import useAnalytics from './useAnalytics';
 import { showV2OrderToast } from '../utils/v2OrderToast';
 import Logger from '../../../../util/Logger';
@@ -49,7 +48,7 @@ interface RampStackParamList {
     url: string;
     providerName: string;
     userAgent?: string;
-    callbackKey?: string;
+    onNavigationStateChange?: (navState: { url: string }) => void;
   };
   [key: string]: object | undefined;
 }
@@ -357,11 +356,10 @@ export const useTransakRouting = (_config?: UseTransakRoutingConfig) => {
 
   const navigateToWebviewModalCallback = useCallback(
     ({ paymentUrl, amount }: { paymentUrl: string; amount?: number }) => {
-      const callbackKey = registerCheckoutCallback(handleNavigationStateChange);
       const [routeName, routeParams] = createCheckoutNavDetails({
         url: paymentUrl,
         providerName: 'Transak',
-        callbackKey,
+        onNavigationStateChange: handleNavigationStateChange,
       });
       navigation.reset({
         index: 1,