feat: add lightweight v2 toast notifications for Ramps orders

[AxelGes]

Description

Introduces new lightweight toast notifications for Ramps orders behind the unifiedBuyV2 feature flag. When enabled, orders display modern Toast-based notifications instead of the legacy NotificationManager.showSimpleNotification approach.

The new toasts accept simple parameters (orderId, cryptocurrency, cryptoAmount, state) rather than the full FiatOrder object, keeping them decoupled from legacy aggregator/deposit code. This makes them easy to maintain and eventually replace the old notifications entirely.

What changed:

• Created v2OrderToast.ts utility with buildV2OrderToastOptions and showV2OrderToast functions
• All four order states are covered: pending (with spinner + Track button), completed (green checkmark), failed (red warning), cancelled (orange warning)
• Icons use AvatarSize.Lg with transparent backgrounds and semantic colors from design tokens
• Gated behind selectRampsUnifiedBuyV2ActiveFlag / useRampsUnifiedV2Enabled - falls back to old notifications when flag is off
• Updated three notification entry points: processFiatOrder, processCustomOrderId (in index.tsx), handleOrderCreated (in Checkout.tsx), and useHandleNewOrder (Deposit flow)
• Added translation strings under ramps_v2.notifications

Changelog

CHANGELOG entry: Added new toast-style notifications for buy order status updates (processing, completed, failed, cancelled) behind the Unified Buy V2 feature flag

Related issues

Refs: Unified Buy V2

Manual testing steps

Feature: V2 Ramps Order Toast Notifications

  Scenario: user sees processing toast when order is created (flag on)
    Given the unifiedBuyV2 feature flag is enabled
    And the user initiates a buy order

    When the order is created
    Then a toast notification appears with a spinner and "Processing your purchase of <crypto>"
    And a "Track" button is visible
    When user taps "Track"
    Then the order details screen opens

  Scenario: user sees success toast when order completes (flag on)
    Given the unifiedBuyV2 feature flag is enabled
    And the user has a pending buy order

    When the order completes
    Then a toast notification appears with a green checkmark and "Your purchase of <amount> <crypto> was successful!"
    And the toast auto-dismisses after a few seconds

  Scenario: user sees old notifications when flag is off
    Given the unifiedBuyV2 feature flag is disabled
    And the user initiates a buy order

    When the order status changes
    Then the legacy NotificationManager notification is shown

Screenshots/Recordings

Before

Legacy NotificationManager.showSimpleNotification banners

After

New Toast notifications with semantic icon colors, and Track navigation button

Aggregator:

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-02-26.at.20.50.38.mov

Native:

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-02-26.at.20.48.36.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.

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 user-facing order status notifications in multiple Ramps entry points (checkout, deposit, polling) and adds navigation from a toast action; regressions could affect notification delivery/timing, though behavior is gated and falls back to legacy notifications when disabled.

Overview
Adds new v2OrderToast utility to show Toast-based Ramps V2 order status notifications (pending/completed/failed/cancelled), including a pending-state Track action that navigates to Routes.RAMP.RAMPS_ORDER_DETAILS.

Updates the main order-notification emitters (Checkout.handleOrderCreated, deposit useHandleNewOrder, and processFiatOrder/processCustomOrderId in Ramp/index.tsx) to conditionally use the new toasts when Unified Buy V2 is enabled, otherwise keeping the existing NotificationManager.showSimpleNotification behavior (some calls deferred with InteractionManager.runAfterInteractions).

Introduces a non-hook isRampsUnifiedV2Enabled(state) helper (with tests) for thunk/plain-function contexts, extends test Babel config to avoid inlining the related env var, and adds new en.json strings under ramps_v2.notifications.

^{Written by Cursor Bugbot for commit 7d84e5f. This will update automatically on new commits. 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.}

[cursor]

Hardcoded light theme colors ignore dark mode

Medium Severity

v2OrderToast.ts imports lightTheme from @metamask/design-tokens and uses lightTheme.colors.success.default, lightTheme.colors.error.default, and lightTheme.colors.warning.default for icon colors. These are hardcoded to the light palette and won't adapt when the app is in dark mode, potentially resulting in poor contrast or invisible icons against a dark background.

 

[AxelGes]

good call

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeRamps
• 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 Ramps (buy/sell crypto) feature, specifically introducing V2 order toast notifications. The modifications affect:

1. Order notification display: When V2 is enabled, a new toast notification system is used instead of the legacy simple notification for order states (pending, completed, failed, cancelled).

2. Files modified:

   • useHandleNewOrder.ts - Hook for handling new orders, now conditionally shows V2 toast
   • Checkout.tsx - Checkout view, now conditionally shows V2 toast
   • index.tsx (Ramp) - Main Ramp component with processFiatOrder and processCustomOrderId functions updated
   • New utility files for V2 feature flag check and toast building

3. Feature flag gated: All changes are behind the MM_RAMPS_UNIFIED_BUY_V2_ENABLED build flag or remote feature flag, meaning existing functionality is preserved when V2 is disabled.

4. UI-only changes: The changes only affect how notifications are displayed, not the core order processing logic.

SmokeRamps is the appropriate tag as it covers:

• Off-ramp token amount input screens
• Deep link navigation into buy/sell flows
• On-ramp flows with regional settings

No other tags are needed because:

• The changes don't affect wallet platform features (SmokeWalletPlatform)
• No confirmations are modified (SmokeConfirmations)
• No account management changes (SmokeAccounts)
• No trading/swap functionality affected (SmokeTrade)

Performance Test Selection:
The changes are UI-only modifications to toast notifications for the Ramps feature. They don't affect: (1) rendering performance - no list rendering or heavy component changes, (2) data loading - no changes to API calls or state management, (3) app startup/login - no initialization changes, (4) critical user flows like swaps or account selection. The toast notification changes are lightweight and don't warrant performance testing.

View GitHub Actions results