Description

This PR closes Phase 6 of the incremental Unified Buy (v2) headless buy plan (app/components/UI/Ramp/headless/PLAN.md): when a flow produces an orderId under a live headless session, the consumer's onOrderCreated callback fires and the ramp stack unwinds — no more redirect to RAMPS_ORDER_DETAILS, no showV2OrderToast the consumer didn't ask for.

Reason

• Phase 5 (#29338) introduced the Headless Host and quote-first session API, but the flow still ended on RAMPS_ORDER_DETAILS with a toast — there was no way for external UIs to know an order was created. Phase 6 closes the loop so consumers can actually react to completion.

What changed

• app/components/UI/Ramp/Views/Checkout/Checkout.tsx — adds headlessSessionId to CheckoutParams. When the widget callback URL resolves and getSession(headlessSessionId) returns a live session, the screen fires session.callbacks.onOrderCreated(orderId), calls closeSession(id, { reason: 'completed' }), and pops the parent stack. addOrder and protectWalletModalVisible still dispatch so Redux stays consistent; showV2OrderToast is suppressed. Non-headless behavior is unchanged.
• app/components/UI/Ramp/hooks/useTransakRouting.ts — extracts headlessSessionId from config.baseRouteParams (already threaded by the Host via Phase 5's parameterization) and applies the same branching inside navigateToOrderProcessingCallback. handleNavigationStateChange's toast is suppressed when the session is live; addOrder + trackEvent keep firing so Redux + analytics parity are preserved.
• app/components/UI/Ramp/hooks/useContinueWithQuote.ts — threads ctx.headlessSessionId into createCheckoutNavDetails so the v2 Checkout screen can see it on the aggregator/widget branch.
• Error safety — consumer onOrderCreated errors are caught and logged via Logger.error; the session still closes and the stack still pops, so a consumer-side bug can never break the flow.
• PLAN.md — Phase 6 ticked.

References

• Stacked on Phase 5: #29338 (Headless Host + quote-first start). This PR's base is poc/headless-buy-phase-5; when feat(ramp): add Headless Host + quote-first startHeadlessBuy (Phase 5) #29338 merges, GitHub will auto-retarget the base to main so the final diff is Phase 6-only.
• Continues from Phase 4 merged to main: #29213 (useContinueWithQuote extraction).

Tests

• New headless session flow describe block in app/components/UI/Ramp/Views/Checkout/Checkout.test.tsx (5 cases): live-session success, addOrder + protectWalletModalVisible side-effect preservation, consumer onOrderCreated error swallow, missing-session fallback, absent-headlessSessionId unchanged path.
• New headless session flow describe block in app/components/UI/Ramp/hooks/useTransakRouting.test.ts (4 cases): the same shape exercised through the Transak native callback path.
• Regressed green locally: sessionRegistry.test.ts, useContinueWithQuote.test.ts, HeadlessHost.test.tsx. 101/101 pass across the five suites.

Changelog

CHANGELOG entry: null

Related issues

Fixes: No GitHub issue — incremental POC on branch poc/headless-buy-phase-6.

Continuity: #29338 (Phase 5 — Headless Host + quote-first start). #29213 (Phase 4 — useContinueWithQuote).

Manual testing steps

Feature: Headless Buy Phase 6 (onOrderCreated + stack unwind on order success)

  Scenario: Aggregator order success fires onOrderCreated and pops out of the ramp stack
    Given the app is an internal build and I am signed in
    And I open Settings → Fiat on-ramp → Headless Buy playground
    When I fetch quotes, tap "Start headless buy" on an aggregator (e.g. MoonPay) quote
    And I complete a sandbox order inside the Checkout WebView
    Then the playground event log should show `onOrderCreated(orderId)` followed by `onClose({ reason: 'completed' })`
    And the app should return to the playground (no RAMPS_ORDER_DETAILS flash, no toast)

  Scenario: Native Transak order success fires onOrderCreated and pops out of the ramp stack
    Given I am on the playground with a Transak native quote selected
    When I complete the native OTP + KYC + webview flow through to order creation
    Then the event log should show `onOrderCreated(orderId)` and `onClose({ reason: 'completed' })`
    And I should be returned to the playground

  Scenario: Non-headless Buy flow is unchanged
    Given I open Wallet → Buy through the regular flow
    When I complete an aggregator order
    Then the order-details screen should render with the usual toast
    And no headless callback should fire

  Scenario: Missing session falls back gracefully
    Given a headless order is produced after the session has been cancelled
    When the success callback resolves
    Then the flow falls back to the regular reset + toast (no dangling state)

Screenshots/Recordings

Before

N/A — Phase 6 wires the existing callback contract; no UI changes.

After

MoonPay succeeds (similar to Phase)

Can't provide a video for Transak since Transak KYC keeps asking me to submit a live selfie for my iOS simulator (even though my purchase amount is under $30)

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

Performance checks (if applicable)

• I've tested on Android
• I've tested with a power user scenario
• I've instrumented key operations with Sentry traces for production performance metrics

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.