feat: add support for fiat payment methods in PayWithModal (#30184)

<!--
Please submit this PR as a draft initially.

Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.

In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->

## **Description**

Adds a **Bank and card** section to the redesigned Pay With bottom sheet
so users can pay a confirmation with a fiat payment method (Debit/Credit
card, Apple Pay, Google Pay, etc.) in addition to crypto. The new
section wraps the existing `useFiatPaymentHighlightedActions` hook so it
inherits the same gating and selection behavior the legacy
`PayWithModal` already uses for fiat methods — same data source, same
controller writes, new UI surface.
When a user taps a fiat method, the controller's
`selectedPaymentMethodId` updates and the bottom sheet closes. Tapping
an already-selected fiat row just dismisses the sheet without
deselecting. The section renders above the existing Crypto section.
When the new bottom sheet is enabled, the legacy `PayWithModal` no
longer surfaces fiat highlighted items — it continues to serve as the
underlying token picker reachable via "Other assets". The Bank and card
section becomes the single source of truth for fiat payment methods in
this flow.
A few related fixes that surfaced during integration:
- **Mutually-exclusive selection between fiat and crypto.** When a fiat
method is selected, crypto rows in the same sheet no longer show a
checkmark. This mirrors the existing legacy modal behavior so selection
semantics stay consistent between the old and new pickers.
- **Sheet dismissal coordination.** Both pay-token and fiat-payment
changes can dismiss the sheet; a shared latch ensures only one dismissal
fires per controller write, preventing the sheet from popping the screen
behind it when both values change at once.
- **Icon color consistency.** Fiat payment method icons now render with
the same token color as other secondary icons in the sheet for visual
parity.

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: null

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/CONF-1364

## **Manual testing steps**

```gherkin
Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]
```

## **Screenshots/Recordings**



https://github.com/user-attachments/assets/55109bed-881c-448c-9334-9fd396186bea



<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

<!--
Every checklist item must be consciously assessed before marking this PR
as
"Ready for review". A checked box means you deliberately considered that
responsibility, not that you literally performed every action listed.

Unchecked boxes are ambiguous: they are not an implicit "N/A" and they
are not
a silent "skip". See `docs/readme/ready-for-review.md` for the full
checklist
semantics.
-->

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
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](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **Pre-merge reviewer checklist**

<!--
Reviewer checklist items follow the same semantics as the author
checklist: an
unchecked box is ambiguous, a checked box means the reviewer consciously
assessed that responsibility. See `docs/readme/ready-for-review.md`.
-->

- [ ] 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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate UI/state-flow changes in the confirmations payment picker:
selection semantics and navigation dismissal now react to both token and
fiat method changes, which could cause regressions in how pay methods
are applied or screens are popped.
> 
> **Overview**
> Adds a new **Bank and card** section to the redesigned Pay With bottom
sheet via `usePayWithFiatSection`, mapping
`useFiatPaymentHighlightedActions` into selectable rows (with
`PaymentMethodIcon`) and ordering it before the crypto section.
> 
> Updates crypto-row selection behavior to be *mutually exclusive* with
fiat selection (hides/clears crypto checkmarks/rows when a fiat method
is selected) and replaces `useDismissOnPayTokenChange` with
`useDismissOnPaymentChange` so the bottom sheet dismisses once on either
pay-token or fiat-method changes.
> 
> When the new bottom sheet is enabled (`isPayWithBottomSheetEnabled`),
`PayWithModal` now suppresses fiat highlighted actions so it functions
only as the “Other assets” token picker; tests and the `en.json` string
for `confirm.pay_with_bottom_sheet.bank_and_card` are added/updated
accordingly.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
cfde84e. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: vinistevam

app/components/Views/confirmations/components/modals/pay-with-bottom-sheet/pay-with-bottom-sheet.test.tsx

@@ -12,7 +12,7 @@ jest.mock('../../../../../../../locales/i18n', () => ({
 }));
 
 jest.mock('../../../hooks/pay/usePayWithSections');
-jest.mock('../../../hooks/pay/useDismissOnPayTokenChange');
+jest.mock('../../../hooks/pay/useDismissOnPaymentChange');
 
 jest.mock('@react-navigation/native', () => ({
   ...jest.requireActual('@react-navigation/native'),

app/components/Views/confirmations/components/modals/pay-with-bottom-sheet/pay-with-bottom-sheet.tsx

@@ -10,7 +10,7 @@ import {
 } from '@metamask/design-system-react-native';
 import { strings } from '../../../../../../../locales/i18n';
 import PayWithSection from '../../UI/pay-with-section';
-import { useDismissOnPayTokenChange } from '../../../hooks/pay/useDismissOnPayTokenChange';
+import { useDismissOnPaymentChange } from '../../../hooks/pay/useDismissOnPaymentChange';
 import { usePayWithSections } from '../../../hooks/pay/usePayWithSections';
 
 export const PAY_WITH_BOTTOM_SHEET_TEST_ID = 'pay-with-bottom-sheet';
@@ -19,7 +19,7 @@ export function PayWithBottomSheet() {
   const sheetRef = useRef<BottomSheetRef>(null);
   const navigation = useNavigation();
   const { sections } = usePayWithSections();
-  useDismissOnPayTokenChange();
+  useDismissOnPaymentChange();
 
   const handleGoBack = useCallback(() => {
     navigation.goBack();

app/components/Views/confirmations/components/modals/pay-with-modal/pay-with-modal.test.tsx

@@ -29,7 +29,10 @@ import { EthAccountType, SolAccountType } from '@metamask/keyring-api';
 import { Hex } from '@metamask/utils';
 import { useTransactionMetadataRequest } from '../../../hooks/transactions/useTransactionMetadataRequest';
 import { EMPTY_ADDRESS } from '../../../../../../constants/transaction';
-import { getAvailableTokens } from '../../../utils/transaction-pay';
+import {
+  getAvailableTokens,
+  isPayWithBottomSheetEnabled,
+} from '../../../utils/transaction-pay';
 import { useWithdrawTokenFilter } from '../../../hooks/pay/useWithdrawTokenFilter';
 import { usePerpsPaymentToken } from '../../../../../UI/Perps/hooks/usePerpsPaymentToken';
 import { usePerpsBalanceTokenFilter } from '../../../../../UI/Perps/hooks/usePerpsBalanceTokenFilter';
@@ -59,7 +62,11 @@ jest.mock('../../../hooks/pay/useTransactionPayWithdraw');
 jest.mock('../../../hooks/pay/useFiatPaymentHighlightedActions');
 jest.mock('../../../hooks/pay/useWithdrawTokenFilter');
 jest.mock('../../../hooks/transactions/useTransactionMetadataRequest');
-jest.mock('../../../utils/transaction-pay');
+jest.mock('../../../utils/transaction-pay', () => ({
+  ...jest.requireActual('../../../utils/transaction-pay'),
+  getAvailableTokens: jest.fn(),
+  isPayWithBottomSheetEnabled: jest.fn(),
+}));
 jest.mock('../../../../../UI/Perps/hooks/usePerpsPaymentToken');
 jest.mock('../../../../../UI/Perps/hooks/usePerpsBalanceTokenFilter');
 jest.mock('../../../../../UI/Predict/hooks/usePredictPaymentToken');
@@ -210,6 +217,9 @@ describe('PayWithModal', () => {
   const useTransactionPayTokenMock = jest.mocked(useTransactionPayToken);
   const useTransactionPayWithdrawMock = jest.mocked(useTransactionPayWithdraw);
   const getAvailableTokensMock = jest.mocked(getAvailableTokens);
+  const isPayWithBottomSheetEnabledMock = jest.mocked(
+    isPayWithBottomSheetEnabled,
+  );
   const useWithdrawTokenFilterMock = jest.mocked(useWithdrawTokenFilter);
   const useTransactionPayRequiredTokensMock = jest.mocked(
     useTransactionPayRequiredTokens,
@@ -238,6 +248,7 @@ describe('PayWithModal', () => {
     jest.mocked(useTransactionPayFiatPayment).mockReturnValue(undefined);
     jest.mocked(useFiatPaymentHighlightedActions).mockReturnValue([]);
 
+    isPayWithBottomSheetEnabledMock.mockReturnValue(false);
     getAvailableTokensMock.mockReturnValue(TOKENS_MOCK);
     useWithdrawTokenFilterMock.mockReturnValue(
       jest.fn((tokens: AssetType[]) => tokens),
@@ -548,5 +559,26 @@ describe('PayWithModal', () => {
 
       expect(getByText('Credit Card')).toBeDefined();
     });
+
+    it('suppresses fiat highlighted actions when the new Pay With bottom sheet is enabled', () => {
+      const fiatAction = {
+        position: 'outside_of_asset_list' as const,
+        icon: 'card-icon',
+        paymentType: 'debit-credit-card',
+        name: 'Credit Card',
+        name_description: '5-10 min',
+        action: jest.fn(),
+        isSelected: false,
+      };
+
+      jest
+        .mocked(useFiatPaymentHighlightedActions)
+        .mockReturnValue([fiatAction]);
+      isPayWithBottomSheetEnabledMock.mockReturnValue(true);
+
+      const { queryByText } = render();
+
+      expect(queryByText('Credit Card')).toBeNull();
+    });
   });
 });

app/components/Views/confirmations/components/modals/pay-with-modal/pay-with-modal.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useRef } from 'react';
+import React, { useCallback, useMemo, useRef } from 'react';
 import { Hex } from '@metamask/utils';
 import Engine from '../../../../../../core/Engine';
 import { useTransactionPayToken } from '../../../hooks/pay/useTransactionPayToken';
@@ -21,7 +21,10 @@ import {
   useTransactionPayRequiredTokens,
 } from '../../../hooks/pay/useTransactionPayData';
 import { useFiatPaymentHighlightedActions } from '../../../hooks/pay/useFiatPaymentHighlightedActions';
-import { getAvailableTokens } from '../../../utils/transaction-pay';
+import {
+  getAvailableTokens,
+  isPayWithBottomSheetEnabled,
+} from '../../../utils/transaction-pay';
 import { useTransactionPayBlockedTokens } from '../../../hooks/pay/useTransactionPayBlockedTokens';
 import { useTransactionMetadataRequest } from '../../../hooks/transactions/useTransactionMetadataRequest';
 import { TransactionType } from '@metamask/transaction-controller';
@@ -48,6 +51,17 @@ export function PayWithModal() {
   const requiredTokens = useTransactionPayRequiredTokens();
   const fiatPayment = useTransactionPayFiatPayment();
   const fiatHighlightedActions = useFiatPaymentHighlightedActions();
+  /**
+   * Suppress fiat highlighted items in the modal when the new Pay With
+   * bottom sheet is enabled. In that mode the Bank/Card section is the single
+   * source of truth for fiat payment methods, while this modal continues to
+   * serve as the crypto/tokens picker via the "Other assets" entry point.
+   * Remove this gate at CONF-1313 GA along with the env util.
+   */
+  const effectiveFiatHighlightedActions = useMemo(
+    () => (isPayWithBottomSheetEnabled() ? [] : fiatHighlightedActions),
+    [fiatHighlightedActions],
+  );
   const bottomSheetRef = useRef<BottomSheetRef>(null);
   const { filterAllowedTokens: musdTokenFilter } = useMusdConversionTokens();
   const { onPaymentTokenChange: onMusdPaymentTokenChange } =
@@ -200,14 +214,14 @@ export function PayWithModal() {
 
       const wrappedTokens = wrapHighlightedItemCallbacks(filteredTokens);
       const wrappedFiatActions = wrapHighlightedItemCallbacks(
-        fiatHighlightedActions,
+        effectiveFiatHighlightedActions,
       );
 
       return [...wrappedFiatActions, ...wrappedTokens];
     },
     [
       blockedTokens,
-      fiatHighlightedActions,
+      effectiveFiatHighlightedActions,
       fiatPayment,
       withdrawTokenFilter,
       musdTokenFilter,

app/components/Views/confirmations/hooks/pay/sections/index.ts

@@ -1 +1,2 @@
 export { usePayWithCryptoSection } from './usePayWithCryptoSection';
+export { usePayWithFiatSection } from './usePayWithFiatSection';

app/components/Views/confirmations/hooks/pay/sections/usePayWithCryptoSection.test.tsx

@@ -12,6 +12,8 @@ import { useTransactionMetadataRequest } from '../../transactions/useTransaction
 import { useLastUsedPaymentMethod } from '../useLastUsedPaymentMethod';
 import { usePayWithPreferredToken } from '../usePayWithPreferredToken';
 import { usePayWithSelectedToken } from '../usePayWithSelectedToken';
+import { useTransactionPayFiatPayment } from '../useTransactionPayData';
+import { useTransactionPayToken } from '../useTransactionPayToken';
 import { usePayWithCryptoSection } from './usePayWithCryptoSection';
 
 jest.mock('@react-navigation/native', () => ({
@@ -38,6 +40,8 @@ jest.mock('../../transactions/useTransactionMetadataRequest');
 jest.mock('../useLastUsedPaymentMethod');
 jest.mock('../usePayWithPreferredToken');
 jest.mock('../usePayWithSelectedToken');
+jest.mock('../useTransactionPayData');
+jest.mock('../useTransactionPayToken');
 
 const TOKEN_MOCK: TransactionPaymentToken = {
   address: '0x1234567890abcdef1234567890abcdef12345678' as Hex,
@@ -67,9 +71,14 @@ describe('usePayWithCryptoSection', () => {
   const usePayWithPreferredTokenMock = jest.mocked(usePayWithPreferredToken);
   const usePayWithSelectedTokenMock = jest.mocked(usePayWithSelectedToken);
   const useLastUsedPaymentMethodMock = jest.mocked(useLastUsedPaymentMethod);
+  const useTransactionPayFiatPaymentMock = jest.mocked(
+    useTransactionPayFiatPayment,
+  );
+  const useTransactionPayTokenMock = jest.mocked(useTransactionPayToken);
   const navigateMock = jest.fn();
   const goBackMock = jest.fn();
   const selectTokenMock = jest.fn();
+  const setPayTokenMock = jest.fn();
   const isLastUsedMock = jest.fn().mockReturnValue(false);
 
   beforeEach(() => {
@@ -102,6 +111,11 @@ describe('usePayWithCryptoSection', () => {
       lastUsedToken: undefined,
       isLastUsed: isLastUsedMock,
     });
+    useTransactionPayFiatPaymentMock.mockReturnValue(undefined);
+    useTransactionPayTokenMock.mockReturnValue({
+      payToken: TOKEN_MOCK,
+      setPayToken: setPayTokenMock,
+    });
   });
 
   it('passes route preferred payment token params to both pay-with hooks', () => {
@@ -381,7 +395,7 @@ describe('usePayWithCryptoSection', () => {
       result.current?.rows[0].onPress?.();
     });
 
-    expect(selectTokenMock).toHaveBeenCalledWith({
+    expect(setPayTokenMock).toHaveBeenCalledWith({
       address: TOKEN_MOCK.address,
       chainId: TOKEN_MOCK.chainId,
     });
@@ -395,7 +409,25 @@ describe('usePayWithCryptoSection', () => {
       result.current?.rows[0].onPress?.();
     });
 
-    expect(selectTokenMock).toHaveBeenCalledWith({
+    expect(setPayTokenMock).toHaveBeenCalledWith({
+      address: TOKEN_MOCK.address,
+      chainId: TOKEN_MOCK.chainId,
+    });
+    expect(goBackMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears the fiat selection when the preferred token row is pressed while a fiat method is active', () => {
+    useTransactionPayFiatPaymentMock.mockReturnValue({
+      selectedPaymentMethodId: 'pm-card',
+    });
+
+    const { result } = renderHook(() => usePayWithCryptoSection());
+
+    act(() => {
+      result.current?.rows[0].onPress?.();
+    });
+
+    expect(setPayTokenMock).toHaveBeenCalledWith({
       address: TOKEN_MOCK.address,
       chainId: TOKEN_MOCK.chainId,
     });
@@ -513,4 +545,53 @@ describe('usePayWithCryptoSection', () => {
 
     expect(otherAssetsRow?.isLastUsed ?? false).toBe(false);
   });
+
+  it('suppresses the preferred token row checkmark when a fiat payment method is selected', () => {
+    useTransactionPayFiatPaymentMock.mockReturnValue({
+      selectedPaymentMethodId: 'pm-card',
+    });
+
+    const { result } = renderHook(() => usePayWithCryptoSection());
+
+    const preferredRow = result.current?.rows.find(
+      (row) => row.id === 'crypto-preferred-token',
+    );
+
+    expect(preferredRow).toEqual(
+      expect.objectContaining({
+        isSelected: false,
+        trailingElement: 'none',
+      }),
+    );
+  });
+
+  it('hides the user-selected token row when a fiat payment method is selected', () => {
+    const distinctSelectedToken = {
+      ...TOKEN_MOCK,
+      address: SELECTED_TOKEN_MOCK.address,
+      symbol: SELECTED_TOKEN_MOCK.symbol,
+      balanceUsd: SELECTED_TOKEN_MOCK.balanceUsd,
+    };
+    usePayWithPreferredTokenMock.mockReturnValue({
+      hasTokens: true,
+      preferredToken: TOKEN_MOCK,
+      selectedToken: distinctSelectedToken,
+    });
+    usePayWithSelectedTokenMock.mockReturnValue({
+      isSelectedDistinctFromAutomatic: true,
+      selectedToken: SELECTED_TOKEN_MOCK,
+      selectToken: selectTokenMock,
+    });
+    useTransactionPayFiatPaymentMock.mockReturnValue({
+      selectedPaymentMethodId: 'pm-card',
+    });
+
+    const { result } = renderHook(() => usePayWithCryptoSection());
+
+    const selectedRow = result.current?.rows.find(
+      (row) => row.id === 'crypto-selected-token',
+    );
+
+    expect(selectedRow).toBeUndefined();
+  });
 });

app/components/Views/confirmations/hooks/pay/sections/usePayWithCryptoSection.ts

@@ -24,6 +24,8 @@ import { SetPayTokenRequest } from '../useAutomaticTransactionPayToken';
 import { useLastUsedPaymentMethod } from '../useLastUsedPaymentMethod';
 import { usePayWithPreferredToken } from '../usePayWithPreferredToken';
 import { usePayWithSelectedToken } from '../usePayWithSelectedToken';
+import { useTransactionPayFiatPayment } from '../useTransactionPayData';
+import { useTransactionPayToken } from '../useTransactionPayToken';
 import { useTransactionMetadataRequest } from '../../transactions/useTransactionMetadataRequest';
 
 interface PayWithCryptoSectionParams {
@@ -59,9 +61,11 @@ export function usePayWithCryptoSection(): PayWithSectionConfig | null {
   const {
     isSelectedDistinctFromAutomatic,
     selectedToken: selectedTokenDisplay,
-    selectToken,
   } = usePayWithSelectedToken({ preferredToken: resolvedPreferredToken });
+  const { setPayToken } = useTransactionPayToken();
   const { isLastUsed } = useLastUsedPaymentMethod();
+  const fiatPayment = useTransactionPayFiatPayment();
+  const hasFiatPaymentSelected = Boolean(fiatPayment?.selectedPaymentMethodId);
 
   const handleOtherAssetsPress = useCallback(() => {
     navigation.navigate(Routes.CONFIRMATION_PAY_WITH_MODAL);
@@ -71,12 +75,12 @@ export function usePayWithCryptoSection(): PayWithSectionConfig | null {
     if (!preferredToken) {
       return;
     }
-    selectToken({
+    setPayToken({
       address: preferredToken.address,
       chainId: preferredToken.chainId,
     });
     navigation.goBack();
-  }, [navigation, preferredToken, selectToken]);
+  }, [navigation, preferredToken, setPayToken]);
 
   const preferredTokenBalance = useMemo(
     () => formatFiat(new BigNumber(preferredToken?.balanceUsd ?? '0')),
@@ -96,10 +100,9 @@ export function usePayWithCryptoSection(): PayWithSectionConfig | null {
     const rows: PayWithRowConfig[] = [];
 
     if (preferredToken) {
-      const isPreferredTokenSelected = isMatchingPayToken(
-        selectedToken,
-        preferredToken,
-      );
+      const isPreferredTokenSelected =
+        !hasFiatPaymentSelected &&
+        isMatchingPayToken(selectedToken, preferredToken);
 
       rows.push({
         id: 'crypto-preferred-token',
@@ -120,7 +123,11 @@ export function usePayWithCryptoSection(): PayWithSectionConfig | null {
       });
     }
 
-    if (isSelectedDistinctFromAutomatic && selectedTokenDisplay) {
+    if (
+      isSelectedDistinctFromAutomatic &&
+      selectedTokenDisplay &&
+      !hasFiatPaymentSelected
+    ) {
       rows.push({
         id: 'crypto-selected-token',
         icon: React.createElement(TokenIcon, {
@@ -167,6 +174,7 @@ export function usePayWithCryptoSection(): PayWithSectionConfig | null {
   }, [
     handleOtherAssetsPress,
     handlePreferredTokenPress,
+    hasFiatPaymentSelected,
     hasTokens,
     isLastUsed,
     isSelectedDistinctFromAutomatic,