feat(ramps): open order details immediately after UB2 webview callbacks

[amitabh94]

Description

This PR improves the unified buy (UB2) checkout flow when purchasing via Transak in the WebView: after a successful checkout, the app navigates immediately to Ramps Order Details using callback URL parameters instead of leaving the user on a generic or stale screen.

Order Details now resolves the order from those callback params, surfaces the outcome with a toast, and records metrics so we can observe completion and errors in production.

Motivation: Users should land on a clear, order-specific screen right after Transak completes, with consistent feedback and observability aligned with other ramps flows.

Changelog

CHANGELOG entry: After completing a Transak purchase in unified buy, the app now opens Ramps Order Details with the order resolved from the callback, a confirmation toast, and updated metrics.

Related issues

Fixes: TRAM-3540

Manual testing steps

Feature: Unified buy WebView callback to Ramps Order Details

  Scenario: Transak success navigates to order details with resolved order
    Given the user starts unified buy and opens the Transak WebView checkout
    And checkout completes successfully with callback params that identify the order

    When the WebView returns to the app with the success callback URL
    Then the app navigates to Ramps Order Details for that order
    And the order is resolved and shown without requiring a manual refresh
    And a success toast is shown
    And relevant ramps metrics are emitted for the completed flow

  Scenario: Callback without usable order params still degrades safely
    Given the user returns from the WebView with a callback missing expected order identifiers

    When Order Details attempts to resolve the order
    Then the user sees an appropriate error or empty state (per implementation)
    And no crash occurs; metrics reflect the failure path if applicable

Screenshots/Recordings

Before

Simulator.Screen.Recording.-.Dev1.-.2026-05-01.at.15.24.41.mov

After

Simulator.Screen.Recording.-.Dev1.-.2026-05-01.at.15.14.26.mov

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). 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 to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.

---

Note

Medium Risk
Changes unified-buy checkout and Transak WebView redirect handling to navigate immediately to RAMPS_ORDER_DETAILS and shift callback order resolution/toast+metrics into OrderDetails, which could affect post-checkout navigation and error handling.

Overview
Unified buy WebView callback handling now exits the WebView immediately and resets navigation to RAMPS_ORDER_DETAILS using callbackUrl/providerCode/walletAddress params (optionally passing cryptocurrency), rather than fetching the order inside Checkout/routing hooks.

OrderDetails now owns resolving the order from callback params, including showing the v2 order toast, emitting status-change analytics via handleOrderStatusChangedForMetrics, handling bailed/empty callback results by resetting back to BUILD_QUOTE, and normalizing non-Error rejections to a localized error message. Tests were updated accordingly.

^{Reviewed by Cursor Bugbot for commit 0a9a2cc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeMoney
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are focused on the Ramp/Buy (on-ramp) flow, specifically refactoring the checkout-to-order-details navigation pattern:

1. Checkout.tsx: No longer fetches the order during checkout callback; instead immediately navigates to OrderDetails with callback params (callbackUrl, providerCode, walletAddress, cryptocurrency).

2. OrderDetails.tsx: Now handles order resolution from callback params - fetches order, shows V2 toast, fires analytics metrics for status changes, and handles errors. This is a behavioral shift in responsibility.

3. useTransakRouting.ts: Same pattern applied to Transak native flow - navigates immediately to OrderDetails with callback params instead of fetching order in the hook.

4. rampsNavigation.ts: Minor interface addition (cryptocurrency field).

The E2E test onramp-unified-buy.spec.ts directly tests the Checkout → OrderDetails flow (both new user deposit and returning user buy flows), and deeplink-to-buy-flow.spec.ts also tests buy flows. Both are tagged with SmokeMoney.

This is a medium-risk change because:

• It changes the order resolution flow (where and when the order is fetched)
• The OrderDetails screen now has more responsibility (toast, analytics, error handling)
• The E2E tests validate the full flow including OrderDetails visibility and token amount display
• No other feature areas (confirmations, swaps, accounts, etc.) are affected

No performance tests are needed as these changes are purely about navigation flow and order resolution logic, not UI rendering performance.

Performance Test Selection:
The changes are purely about navigation flow and order resolution logic (where/when the order is fetched after checkout). No UI rendering components, list rendering, animations, or performance-sensitive paths are affected. No performance tests are needed.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0a9a2cc. Configure here.}

[cursor]

Error normalization can show raw strings to users

Low Severity

The error normalization in executeCallbackFetch wraps non-Error values via new Error(String(fetchError)), making normalizedError.message truthy for almost all non-Error exceptions (e.g., String(undefined) → "undefined", String({}) → "[object Object]"). This means the localized fallback at line 152–153 is nearly unreachable for non-Error values, and users could see raw strings like "undefined" or "[object Object]" as error messages. The sibling handleOnRefresh handler (line 232) correctly guards with fetchError instanceof Error && fetchError.message before showing the raw message, falling back to the localized string for all non-Error exceptions.

 

^{Reviewed by Cursor Bugbot for commit 0a9a2cc. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud