fix: correctly handle the deep link order redirects (#29858)

<!--
Please submit this PR as a draft initially.

Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.

In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->

## **Description**

Adds a deeplink handler for the on-ramp provider return flow. When an
external ramp provider (e.g. Transak) redirects the user back into the
app after a purchase, the deeplink now lands on the Ramps Order Details
screen for the corresponding order instead of being dropped or routed
through the unrelated buy-intent flow.

The change introduces a new `on-ramp` deeplink action distinct from the
existing `buy` / `buy-crypto` actions. The new action represents the
*return* leg of an external purchase (an order to inspect), whereas
`buy` represents an *intent* to start a new purchase. The two collapse
into the same `DeepLinkRoute.BUY` analytics bucket so the funnel stays
unchanged.

A URL of the form `https://link.metamask.io/on-ramp?orderId=<id>` (or
the `metamask://on-ramp?orderId=<id>` scheme) parses `orderId` from the
query string and navigates to `Routes.RAMP.RAMPS_ORDER_DETAILS` with
`showCloseButton: true`. Errors during URL parsing are caught and
logged.

## **Changelog**

CHANGELOG entry: Added handling for on-ramp provider return deeplinks so
users land directly on their order details after completing or canceling
a purchase with an external provider.

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TRAM-3533

## **Manual testing steps**

```gherkin
Feature: On-ramp return deeplink

  Scenario: user is redirected back to the app with an orderId
    Given the user has started a buy with an external ramp provider
    And the provider has issued a return URL with an orderId

    When the app opens the deeplink "https://link.metamask.io/on-ramp?orderId=<id>"
    Then the Ramps Order Details screen opens for that order
    And the screen shows the close button

  Scenario: user opens an on-ramp deeplink without an orderId
    Given the user opens a malformed or stripped on-ramp deeplink

    When the app opens the deeplink "https://link.metamask.io/on-ramp"
    Then the Ramps Order Details screen opens with no orderId
    And the screen handles the missing id gracefully (loading or empty state)

  Scenario: user opens an on-ramp deeplink with malformed input
    Given the deeplink contains an unparseable URL fragment

    When the app receives the deeplink
    Then no navigation occurs
    And the error is logged via Logger.error
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

<img width="511" height="1136" alt="image"
src="https://github.com/user-attachments/assets/1fc31477-616f-45b7-9c94-ae3eace6a78e"
/>


### **After**

<!-- [screenshots/recordings] -->


https://github.com/user-attachments/assets/b4f629fd-5b1d-4c42-abd2-66225af25915


## **Pre-merge author checklist**

<!--
Every checklist item must be consciously assessed before marking this PR
as
"Ready for review". A checked box means you deliberately considered that
responsibility, not that you literally performed every action listed.

Unchecked boxes are ambiguous: they are not an implicit "N/A" and they
are not
a silent "skip". See `docs/readme/ready-for-review.md` for the full
checklist
semantics.
-->

- [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
- [ ] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [ ] 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.

#### Performance checks (if applicable)

- [ ] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [ ] I've tested with a power user scenario
- Use these [power-user
SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **Pre-merge reviewer checklist**

<!--
Reviewer checklist items follow the same semantics as the author
checklist: an
unchecked box is ambiguous, a checked box means the reviewer consciously
assessed that responsibility. See `docs/readme/ready-for-review.md`.
-->

- [ ] 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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it extends universal-link parsing/routing and
navigation for a new deep link action; mistakes could misroute users or
break existing ramp deeplinks, but changes are scoped and covered by
unit tests.
> 
> **Overview**
> Adds a new `on-ramp` deep link action to handle external on-ramp
provider return redirects.
> 
> Universal-link handling now routes `.../on-ramp...` to a new
`handleRampReturnUrl` helper which parses `orderId` from the query
string and navigates to `Routes.RAMP.RAMPS_ORDER_DETAILS` (with
`showCloseButton: true`), logging and aborting on malformed URLs.
Analytics mapping buckets `on-ramp` under the existing `BUY` route, and
tests were added/updated to cover the new handler and routing.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
bb9767d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Darius Costolas <10818970+meltingice1337@users.noreply.github.com>

Author: meltingice1337

app/components/UI/Ramp/deeplink/handleRampReturnUrl.test.ts

@@ -0,0 +1,83 @@
+import Routes from '../../../../constants/navigation/Routes';
+import handleRampReturnUrl from './handleRampReturnUrl';
+import NavigationService from '../../../../core/NavigationService';
+import Logger from '../../../../util/Logger';
+
+jest.mock('../../../../core/NavigationService', () => ({
+  navigation: {
+    navigate: jest.fn(),
+  },
+}));
+
+jest.mock('../../../../util/Logger', () => ({
+  error: jest.fn(),
+}));
+
+describe('handleRampReturnUrl', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('navigates to RAMPS_ORDER_DETAILS with orderId from query string', () => {
+    handleRampReturnUrl({ rampReturnPath: '?orderId=abc123' });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: 'abc123', showCloseButton: true },
+    );
+  });
+
+  it('parses orderId from a path with leading slash', () => {
+    handleRampReturnUrl({ rampReturnPath: '/return?orderId=order-42' });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: 'order-42', showCloseButton: true },
+    );
+  });
+
+  it('parses orderId from an absolute URL', () => {
+    handleRampReturnUrl({
+      rampReturnPath: 'https://example.com/return?orderId=zzz',
+    });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: 'zzz', showCloseButton: true },
+    );
+  });
+
+  it('navigates with undefined orderId when the query parameter is absent', () => {
+    handleRampReturnUrl({ rampReturnPath: '?other=value' });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: undefined, showCloseButton: true },
+    );
+  });
+
+  it('navigates with undefined orderId when there is no query string', () => {
+    handleRampReturnUrl({ rampReturnPath: '/some-path' });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: undefined, showCloseButton: true },
+    );
+  });
+
+  it('navigates with undefined orderId for an empty path', () => {
+    handleRampReturnUrl({ rampReturnPath: '' });
+
+    expect(NavigationService.navigation.navigate).toHaveBeenCalledWith(
+      Routes.RAMP.RAMPS_ORDER_DETAILS,
+      { orderId: undefined, showCloseButton: true },
+    );
+  });
+
+  it('logs an error and does not navigate when the URL constructor throws', () => {
+    handleRampReturnUrl({ rampReturnPath: 'http://[' });
+
+    expect(Logger.error).toHaveBeenCalled();
+    expect(NavigationService.navigation.navigate).not.toHaveBeenCalled();
+  });
+});

app/components/UI/Ramp/deeplink/handleRampReturnUrl.ts

@@ -0,0 +1,26 @@
+import Routes from '../../../../constants/navigation/Routes';
+import NavigationService from '../../../../core/NavigationService';
+import Logger from '../../../../util/Logger';
+
+interface HandleRampReturnUrlParams {
+  rampReturnPath: string;
+}
+
+export default function handleRampReturnUrl({
+  rampReturnPath,
+}: HandleRampReturnUrlParams) {
+  try {
+    const parsed = new URL(rampReturnPath, 'https://placeholder.local');
+    const orderId = parsed.searchParams.get('orderId') ?? undefined;
+
+    NavigationService.navigation.navigate(Routes.RAMP.RAMPS_ORDER_DETAILS, {
+      orderId,
+      showCloseButton: true,
+    });
+  } catch (error) {
+    Logger.error(error as Error, {
+      message: 'Error in handleRampReturnUrl',
+      rampReturnPath,
+    });
+  }
+}

app/constants/deeplinks.ts

@@ -50,6 +50,7 @@ export enum ACTIONS {
   SOCIAL_TRADER_POSITION = 'social-trader-position',
   EARN_MUSD = 'earn-musd',
   NFT = 'nft',
+  ON_RAMP = 'on-ramp',
 }
 
 export const PREFIXES = {
@@ -86,5 +87,6 @@ export const PREFIXES = {
   [ACTIONS.SOCIAL_TRADER_POSITION]: '',
   [ACTIONS.EARN_MUSD]: '',
   [ACTIONS.NFT]: '',
+  [ACTIONS.ON_RAMP]: '',
   METAMASK: 'metamask://',
 };

app/core/DeeplinkManager/handlers/legacy/__tests__/handleUniversalLink.test.ts

@@ -15,6 +15,7 @@ import handleDeepLinkModalDisplay from '../handleDeepLinkModalDisplay';
 import handleBrowserUrl from '../handleBrowserUrl';
 import { DeepLinkModalLinkType } from '../../../../../components/UI/DeepLinkModal';
 import handleMetaMaskDeeplink from '../handleMetaMaskDeeplink';
+import handleRampReturnUrl from '../handleRampReturnUrl';
 import { SHIELD_WEBSITE_URL } from '../../../../../constants/shield';
 import { handleSocialLeaderboardUrl } from '../handleSocialLeaderboardUrl';
 import { handleSocialTraderPositionUrl } from '../handleSocialTraderPositionUrl';
@@ -33,6 +34,7 @@ jest.mock('../../../../NativeModules', () => ({
 }));
 jest.mock('../handleDeepLinkModalDisplay');
 jest.mock('../handleRampUrl');
+jest.mock('../handleRampReturnUrl');
 jest.mock('../handleHomeUrl');
 jest.mock('../handleSwapUrl');
 jest.mock('../handleBrowserUrl');
@@ -207,6 +209,32 @@ describe('handleUniversalLink', () => {
     });
   });
 
+  describe('ACTIONS.ON_RAMP', () => {
+    it('calls handleRampReturnUrl with the path after the action', async () => {
+      const onRampPath = '/return?orderId=order-99';
+      url = `https://${AppConstants.MM_UNIVERSAL_LINK_HOST}/${ACTIONS.ON_RAMP}${onRampPath}`;
+      urlObj = {
+        hostname: AppConstants.MM_UNIVERSAL_LINK_HOST,
+        pathname: `/${ACTIONS.ON_RAMP}${onRampPath}`,
+        href: url,
+      } as ReturnType<typeof extractURLParams>['urlObj'];
+
+      await handleUniversalLink({
+        instance,
+        handled,
+        urlObj,
+        browserCallBack: mockBrowserCallBack,
+        url,
+        source: 'test-source',
+      });
+
+      expect(handleRampReturnUrl).toHaveBeenCalledWith({
+        rampReturnPath: onRampPath,
+      });
+      expect(handled).toHaveBeenCalled();
+    });
+  });
+
   describe('ACTIONS.SELL_CRYPTO', () => {
     it('calls instance._handleSellCrypto if action is ACTIONS.SELL_CRYPTO', async () => {
       urlObj = {

app/core/DeeplinkManager/handlers/legacy/handleRampReturnUrl.ts

@@ -0,0 +1 @@
+export { default } from '../../../../components/UI/Ramp/deeplink/handleRampReturnUrl';

app/core/DeeplinkManager/handlers/legacy/handleUniversalLink.ts

@@ -18,6 +18,7 @@ import handleDeepLinkModalDisplay from './handleDeepLinkModalDisplay';
 import handleMetaMaskDeeplink from './handleMetaMaskDeeplink';
 import { capitalize } from '../../../../util/general';
 import handleRampUrl from './handleRampUrl';
+import handleRampReturnUrl from './handleRampReturnUrl';
 import { navigateToHomeUrl } from './handleHomeUrl';
 import { handleSwapUrl } from './handleSwapUrl';
 import handleBrowserUrl from './handleBrowserUrl';
@@ -91,6 +92,7 @@ const SUPPORTED_ACTIONS = {
   SHIELD: ACTIONS.SHIELD,
   EARN_MUSD: ACTIONS.EARN_MUSD,
   NFT: ACTIONS.NFT,
+  ON_RAMP: ACTIONS.ON_RAMP,
   // MetaMask SDK specific actions
   ANDROID_SDK: ACTIONS.ANDROID_SDK,
   CONNECT: ACTIONS.CONNECT,
@@ -124,6 +126,7 @@ const WHITELISTED_ACTIONS: SUPPORTED_ACTIONS[] = [
   SUPPORTED_ACTIONS.SOCIAL_TRADER_POSITION,
   SUPPORTED_ACTIONS.SHIELD,
   SUPPORTED_ACTIONS.EARN_MUSD,
+  SUPPORTED_ACTIONS.ON_RAMP,
 ];
 
 /**
@@ -521,6 +524,10 @@ async function handleUniversalLink({
       });
       break;
     }
+    case SUPPORTED_ACTIONS.ON_RAMP: {
+      handleRampReturnUrl({ rampReturnPath: actionBasedRampPath });
+      break;
+    }
     case SUPPORTED_ACTIONS.HOME:
       navigateToHomeUrl({ homePath: actionBasedRampPath });
       return;

app/core/DeeplinkManager/types/deepLink.types.ts

@@ -138,6 +138,7 @@ export const SUPPORTED_ACTIONS = [
   ACTIONS.CARD_HOME,
   ACTIONS.SHIELD,
   ACTIONS.NFT,
+  ACTIONS.ON_RAMP,
 ] as const satisfies readonly ACTIONS[];
 
 export type SupportedAction = (typeof SUPPORTED_ACTIONS)[number];

app/core/DeeplinkManager/util/deeplinks/deepLinkAnalytics.test.ts

@@ -421,6 +421,7 @@ describe('deepLinkAnalytics', () => {
     it.each([
       [ACTIONS.BUY, DeepLinkRoute.BUY],
       [ACTIONS.BUY_CRYPTO, DeepLinkRoute.BUY],
+      [ACTIONS.ON_RAMP, DeepLinkRoute.BUY],
     ] as const)('maps buy action %s to BUY route', (action, expectedRoute) => {
       // Arrange & Act
       const result = mapSupportedActionToRoute(action);

app/core/DeeplinkManager/util/deeplinks/deepLinkAnalytics.ts

@@ -571,6 +571,7 @@ export const mapSupportedActionToRoute = (
       return DeepLinkRoute.TRANSACTION;
     case ACTIONS.BUY:
     case ACTIONS.BUY_CRYPTO:
+    case ACTIONS.ON_RAMP:
       return DeepLinkRoute.BUY;
     case ACTIONS.SELL:
     case ACTIONS.SELL_CRYPTO: