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 the post-checkout callback handling and navigation flow for unified buy (including headless sessions), which could impact order resolution and user routing if callback params are missing or malformed.

Overview
After a successful unified-buy WebView callback, Checkout no longer fetches/creates the order itself; it immediately navigation.resets to RAMPS_ORDER_DETAILS with callbackUrl + providerCode + walletAddress (and optional cryptocurrency) so the user lands on an order-specific screen right away.

OrderDetails now resolves the order from these callback params, bails back to Build Quote when the callback cannot be resolved or returns a bailed status, emits status-change metrics via handleOrderStatusChangedForMetrics, and shows the showV2OrderToast confirmation. The Transak WebView routing hook is updated to follow the same “navigate first, resolve in OrderDetails” pattern for non-headless flows, while headless flows continue to fetch+close session+pop without showing toasts.

Tests are updated/added to reflect the new responsibility split (navigation params, toast/metrics in OrderDetails, and more robust error normalization/handling).

^{Reviewed by Cursor Bugbot for commit 517c9b1. 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.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ 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 c3b4b09. Configure here.}

[amitabh94]

@copilot resolve conflicts

[Copilot]

@copilot resolve conflicts

Conflicts resolved in commit 517c9b1. The only conflict was in Checkout.tsx's import section: our branch used HeaderCompactStandard while main had refactored to HeaderStandard (from the MMDS design system). Resolved by keeping HeaderStandard (already used in the merged body) and dropping the unused temp import.

[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 entirely on the Ramp (fiat on/off-ramp) component area:

1. Checkout.tsx: Refactored the checkout callback flow. In non-headless mode, instead of fetching the order in Checkout and navigating with orderId, it now navigates to RAMPS_ORDER_DETAILS with callbackUrl, providerCode, and walletAddress params, deferring order resolution to OrderDetails. Removed useRampsUnifiedV2Enabled and showV2OrderToast from Checkout.

2. OrderDetails.tsx: Now handles order fetching from callback URL (previously done in Checkout), shows the V2 order toast, fires analytics via handleOrderStatusChangedForMetrics, and improves error handling for non-Error rejections.

3. useTransakRouting.ts: Refactored Transak-specific order processing - headless mode now calls onOrderCreated callback and closes session; non-headless mode navigates to RAMPS_ORDER_DETAILS with callback params (same pattern as unified buy).

4. rampsNavigation.ts: Added cryptocurrency field to RampsOrderDetailsParams interface.

These changes affect the critical checkout completion → order details navigation flow in the ramp stack. The SmokeMoney tag covers ramps flows including onramp-unified-buy.spec.ts, deeplink-to-buy-flow.spec.ts, and deeplink-to-sell-flow.spec.ts, which exercise the checkout and order details screens. No other feature areas (swap, confirmations, wallet platform, etc.) are affected by these changes.

Performance Test Selection:
The changes are refactoring the navigation flow between Checkout and OrderDetails screens in the Ramp stack. There are no changes to rendering performance, list components, data loading patterns, or app initialization. The refactoring moves order fetching from Checkout to OrderDetails but doesn't introduce new async patterns or rendering bottlenecks that would warrant performance testing.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud