feat(ramp): bypass order-processing redirect in headless flows (Phase 6)

When a headless buy session is active, the post-checkout success paths
now hand the orderId to the consumer's `onOrderCreated` callback,
close the session via `closeSession(..., { reason: 'completed' })`,
and unwind the ramp stack via `navigation.getParent()?.pop()` instead
of resetting to `RAMPS_ORDER_DETAILS`. The `showV2OrderToast` surface
is also suppressed for headless flows — the consumer drives its own
notification UI.

Two paths are wired:

- Aggregator / widget: v2 `Checkout.tsx` intercepts the widget
  callback URL. When `params.headlessSessionId` resolves to a live
  session, the success branch fires the callback + closes the session
  + pops the parent stack. `addOrder` and `protectWalletModalVisible`
  still fire so Redux state stays consistent. Non-headless behavior
  is unchanged.

- Native (Transak): `useTransakRouting.ts` extracts
  `headlessSessionId` from `config.baseRouteParams` (the Host
  already threads it through via Phase 4b's parameterization) and
  applies the same branching in `navigateToOrderProcessingCallback`.
  `handleNavigationStateChange`'s toast is suppressed when the
  session is live; `addOrder` + `trackEvent` keep running so Redux
  state and analytics parity are preserved.

`useContinueWithQuote.ts` threads `ctx.headlessSessionId` into
`createCheckoutNavDetails` so the v2 Checkout screen can see it.

Consumer `onOrderCreated` errors are caught and logged so a
consumer-side bug can never break the flow — the session is closed
and the stack popped regardless.

Tests: new `headless session flow` describe blocks in
`Checkout.test.tsx` (+187 lines, 5 cases) and
`useTransakRouting.test.ts` (+219 lines, 4 cases) cover the live
session, missing-session fallback, consumer error swallow, and the
absent-headlessSessionId path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: saustrie-consensys

app/components/UI/Ramp/Views/Checkout/Checkout.test.tsx

@@ -55,6 +55,11 @@ jest.mock('../../utils/v2OrderToast', () => ({
   showV2OrderToast: jest.fn(),
 }));
 
+jest.mock('../../headless/sessionRegistry', () => ({
+  getSession: jest.fn(),
+  closeSession: jest.fn(),
+}));
+
 jest.mock('../../../../../util/Logger', () => ({
   error: jest.fn(),
   log: jest.fn(),
@@ -607,4 +612,184 @@ describe('Checkout', () => {
       );
     });
   });
+
+  describe('headless session flow', () => {
+    const mockGetSession = jest.requireMock('../../headless/sessionRegistry')
+      .getSession as jest.Mock;
+    const mockCloseSession = jest.requireMock('../../headless/sessionRegistry')
+      .closeSession as jest.Mock;
+    const showV2OrderToastMock = jest.requireMock('../../utils/v2OrderToast')
+      .showV2OrderToast as jest.Mock;
+
+    const mockOrder = {
+      providerOrderId: 'headless-order-1',
+      cryptoCurrency: { symbol: 'ETH' },
+      cryptoAmount: '0.5',
+      status: 'Pending',
+    };
+
+    const callbackFlowParams = {
+      url: 'https://provider.example.com/checkout',
+      providerName: 'Test Provider',
+      providerCode: 'moonpay',
+      walletAddress: '0xdeadbeef',
+      headlessSessionId: 'hs-1',
+    };
+
+    let mockParentPop: jest.Mock;
+
+    beforeEach(() => {
+      mockGetSession.mockReset();
+      mockCloseSession.mockReset();
+      mockParentPop = jest.fn();
+      mockNavigation.getParent.mockReturnValue({ pop: mockParentPop });
+      mockGetOrderFromCallback.mockResolvedValue(mockOrder);
+      mockUseRampsUnifiedV2Enabled.mockReturnValue(true);
+    });
+
+    it('fires onOrderCreated, closes the session, and pops the ramp stack when a live session is present', async () => {
+      const onOrderCreated = jest.fn();
+      mockGetSession.mockReturnValue({
+        id: 'hs-1',
+        status: 'continued',
+        callbacks: {
+          onOrderCreated,
+          onError: jest.fn(),
+          onClose: jest.fn(),
+        },
+      });
+      mockUseParams.mockReturnValue(callbackFlowParams);
+
+      const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
+
+      await act(async () => {
+        fireEvent.press(getByTestId('trigger-callback-navigation'));
+      });
+
+      await waitFor(() => {
+        expect(onOrderCreated).toHaveBeenCalledWith('headless-order-1');
+      });
+      expect(mockCloseSession).toHaveBeenCalledWith('hs-1', {
+        reason: 'completed',
+      });
+      expect(mockParentPop).toHaveBeenCalled();
+      expect(mockNavigation.reset).not.toHaveBeenCalled();
+      expect(showV2OrderToastMock).not.toHaveBeenCalled();
+    });
+
+    it('still adds the order to Redux and dispatches protect-wallet when headless', async () => {
+      mockGetSession.mockReturnValue({
+        id: 'hs-1',
+        status: 'continued',
+        callbacks: {
+          onOrderCreated: jest.fn(),
+          onError: jest.fn(),
+          onClose: jest.fn(),
+        },
+      });
+      mockUseParams.mockReturnValue(callbackFlowParams);
+
+      const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
+
+      await act(async () => {
+        fireEvent.press(getByTestId('trigger-callback-navigation'));
+      });
+
+      await waitFor(() => {
+        expect(mockAddOrder).toHaveBeenCalledWith(mockOrder);
+      });
+      expect(mockDispatch).toHaveBeenCalledWith({
+        type: 'PROTECT_WALLET_MODAL_VISIBLE',
+      });
+    });
+
+    it('swallows consumer onOrderCreated errors and still closes + pops', async () => {
+      const Logger = jest.requireMock('../../../../../util/Logger') as {
+        error: jest.Mock;
+      };
+      const throwingCallback = jest.fn(() => {
+        throw new Error('consumer bug');
+      });
+      mockGetSession.mockReturnValue({
+        id: 'hs-1',
+        status: 'continued',
+        callbacks: {
+          onOrderCreated: throwingCallback,
+          onError: jest.fn(),
+          onClose: jest.fn(),
+        },
+      });
+      mockUseParams.mockReturnValue(callbackFlowParams);
+
+      const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
+
+      await act(async () => {
+        fireEvent.press(getByTestId('trigger-callback-navigation'));
+      });
+
+      await waitFor(() => {
+        expect(throwingCallback).toHaveBeenCalled();
+      });
+      expect(Logger.error).toHaveBeenCalledWith(
+        expect.any(Error),
+        'UnifiedCheckout: onOrderCreated callback threw',
+      );
+      expect(mockCloseSession).toHaveBeenCalledWith('hs-1', {
+        reason: 'completed',
+      });
+      expect(mockParentPop).toHaveBeenCalled();
+    });
+
+    it('falls back to the regular reset + toast when session id is present but session is missing from registry', async () => {
+      mockGetSession.mockReturnValue(undefined);
+      mockUseParams.mockReturnValue(callbackFlowParams);
+
+      const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
+
+      await act(async () => {
+        fireEvent.press(getByTestId('trigger-callback-navigation'));
+      });
+
+      await waitFor(() => {
+        expect(showV2OrderToastMock).toHaveBeenCalledWith(
+          expect.objectContaining({ orderId: 'headless-order-1' }),
+        );
+      });
+      expect(mockNavigation.reset).toHaveBeenCalledWith(
+        expect.objectContaining({
+          routes: [
+            expect.objectContaining({
+              params: expect.objectContaining({
+                orderId: 'headless-order-1',
+              }),
+            }),
+          ],
+        }),
+      );
+      expect(mockCloseSession).not.toHaveBeenCalled();
+      expect(mockParentPop).not.toHaveBeenCalled();
+    });
+
+    it('takes the regular non-headless path when headlessSessionId is absent', async () => {
+      mockUseParams.mockReturnValue({
+        url: 'https://provider.example.com/checkout',
+        providerName: 'Test Provider',
+        providerCode: 'moonpay',
+        walletAddress: '0xdeadbeef',
+      });
+
+      const { getByTestId } = renderWithProvider(<Checkout />, {}, true, false);
+
+      await act(async () => {
+        fireEvent.press(getByTestId('trigger-callback-navigation'));
+      });
+
+      await waitFor(() => {
+        expect(mockNavigation.reset).toHaveBeenCalled();
+      });
+      expect(showV2OrderToastMock).toHaveBeenCalled();
+      expect(mockCloseSession).not.toHaveBeenCalled();
+      expect(mockParentPop).not.toHaveBeenCalled();
+    });
+  });
 });

app/components/UI/Ramp/Views/Checkout/Checkout.tsx

@@ -27,6 +27,7 @@ import {
 import HeaderCompactStandard from '../../../../../component-library/components-temp/HeaderCompactStandard';
 import useRampsUnifiedV2Enabled from '../../hooks/useRampsUnifiedV2Enabled';
 import { showV2OrderToast } from '../../utils/v2OrderToast';
+import { closeSession, getSession } from '../../headless/sessionRegistry';
 import { useStyles } from '../../../../hooks/useStyles';
 import styleSheet from './Checkout.styles';
 import Device from '../../../../../util/device';
@@ -56,6 +57,14 @@ interface CheckoutParams {
   providerType?: FIAT_ORDER_PROVIDERS;
   /** Optional callback invoked on navigation state changes after URL de-duplication (e.g. redirect URLs). */
   onNavigationStateChange?: (navState: { url: string }) => void;
+  /**
+   * When set, Checkout is participating in a headless buy session. On
+   * successful callback the screen fires the session's `onOrderCreated`
+   * callback, closes the session, and pops the ramp stack instead of
+   * resetting to `RAMPS_ORDER_DETAILS`. The `showV2OrderToast` surface is
+   * also suppressed — headless consumers drive their own UI.
+   */
+  headlessSessionId?: string;
 }
 
 export const createCheckoutNavDetails = createNavigationDetails<CheckoutParams>(
@@ -87,6 +96,7 @@ const Checkout = () => {
     network,
     userAgent,
     onNavigationStateChange,
+    headlessSessionId,
   } = params ?? {};
   const effectiveOrderId = (orderIdParam ?? customOrderId)?.trim() || null;
 
@@ -178,6 +188,26 @@ const Checkout = () => {
         addOrder(rampsOrder);
         dispatch(protectWalletModalVisible());
 
+        // Headless mode: hand the orderId to the consumer, close the
+        // session, and unwind out of the ramp stack so the caller regains
+        // foreground. Skip the toast + RAMPS_ORDER_DETAILS reset — both
+        // are user-facing UI the headless consumer didn't ask for.
+        const session = getSession(headlessSessionId);
+        if (headlessSessionId && session) {
+          try {
+            session.callbacks.onOrderCreated(rampsOrder.providerOrderId);
+          } catch (callbackError) {
+            Logger.error(
+              callbackError as Error,
+              'UnifiedCheckout: onOrderCreated callback threw',
+            );
+          }
+          closeSession(headlessSessionId, { reason: 'completed' });
+          // @ts-expect-error navigation prop mismatch
+          navigation.getParent()?.pop();
+          return;
+        }
+
         if (isV2Enabled) {
           showV2OrderToast({
             orderId: rampsOrder.providerOrderId,
@@ -217,6 +247,7 @@ const Checkout = () => {
       getOrderFromCallback,
       isV2Enabled,
       params?.cryptocurrency,
+      headlessSessionId,
     ],
   );
 

app/components/UI/Ramp/headless/PLAN.md

@@ -13,7 +13,7 @@
 - [x] **Phase 4c** — Make `useContinueWithQuote` headless-ready — extend `ContinueWithQuoteContext` with optional overrides so callers without controller state (the Host) can drive it from a `Quote`
 - [x] **Phase 5 (revised)** — Quote-first headless start path — `startHeadlessBuy({ quote, redirectUrl? })` creates a session carrying the quote, navigates to Headless Host, Host calls `continueWithQuote(quote, ctx)` and re-orchestrates after auth loops
 - [ ] **Phase 5b (deferred)** — `startHeadlessBuy({ assetId, amount, paymentMethodId, providerId? })` "open BuildQuote / Host fetches quotes" mode — picked up after the quote-first path is stable
-- [ ] **Phase 6** — Bypass order-processing redirect in Transak/aggregator routing when headless; fire `onOrderCreated` and end session
+- [x] **Phase 6** — Bypass order-processing redirect in Transak/aggregator routing when headless; fire `onOrderCreated` and end session
 - [ ] **Phase 7** — Extract UI-coupled error/limit surfacing; route errors through `onError` as typed `HeadlessBuyError`
 - [ ] **Phase 8** — Cancellation + `onClose` semantics (including user-dismissed detection)
 - [ ] **Phase 9** — Expose `getOrder` / `refreshOrder` from hook and show in playground

app/components/UI/Ramp/hooks/useContinueWithQuote.ts

@@ -328,6 +328,7 @@ export function useContinueWithQuote(
             currency: effectiveCurrency,
             cryptocurrency: effectiveCryptoSymbol,
             orderId: buyWidget.orderId?.trim() || undefined,
+            headlessSessionId: ctx.headlessSessionId,
           }),
         );
       } catch (error) {