feat: add logout button to BasicInfo error banner for Transak phone already registered error (MetaMask#22183)

## **Description**

This PR adds a logout button to the BasicInfo screen's error banner when
users encounter Transak error code 2020 (phone number already registered
with a different email). This allows users to logout and return to the
email input screen to authenticate with the correct email address.

**What is the reason for the change?**
When users authenticate with the wrong email in the Transak deposit
flow, if they enter a phone number that's already registered to a
different email, they see an error message but have no way to logout and
try again with the correct email. This forces them to restart the entire
app or navigate to settings to logout manually.

**What is the improvement/solution?**
- Added error code 2020 detection from Transak API response structure
- Added localized error message that extracts and displays the
registered email
- Added "Log in with email" button in the error banner that appears only
for error code 2020
- Clicking the button clears authentication and navigates back to email
input screen
- Reuses existing logout functionality and localization strings
- Added comprehensive test coverage

## **Changelog**

CHANGELOG entry: Added logout button to Transak deposit flow when phone
number is already registered

## **Related issues**

Fixes:
[TRAM-2799](https://consensyssoftware.atlassian.net/browse/TRAM-2799)

## **Manual testing steps**

### Option 1: Testing with Real Transak (E2E Validation)

```gherkin
Feature: Logout on Transak phone already registered error

  Scenario: user logs out when encountering phone already registered error
    Given user has authenticated with email A in Transak deposit flow
    And user navigates to BasicInfo screen
    And user enters a phone number already registered to email B

    When user submits the form
    Then error banner displays with message "This phone number is already in use by {masked_email}. Log in using this email to continue."
    And "Log in with email" button is visible in the error banner

    When user clicks the "Log in with email" button
    Then user is logged out from Transak
    And user is navigated back to the email input screen
    And user can now enter the correct email to authenticate
```

**Note:** Requires two Transak accounts with the same phone number
registered to different emails.

---

### Option 2: Testing with Mock Error (Quick Validation)

**1. Add temporary mock** in `BasicInfo.tsx` around line 212:

```typescript
try {
  // TEMPORARY: Simulate Transak error code 2020
  const mockError = Object.assign(new Error('API Error'), {
    error: {
      errorCode: 2020,
      message: 'This phone number is already registered. It has been used by an account created with k****@pedalsup.com. Login with this email to continue.',
    },
  });
  throw mockError;
  
  // Comment out original code for testing:
  // setLoading(true);
  // const { ssn, ...formDataWithoutSsn } = formData;
  // await postKycForm({ personalDetails: { ... } });
```

**2. Run on simulator:**

```bash
yarn watch
# Press 'i' for iOS or 'a' for Android
```

**3. Test the flow:**
- Navigate to Deposit → Verify Identity → BasicInfo
- Fill in form with any valid data
- Click "Continue"
- ✅ Verify error banner shows: "This phone number is already in use by
k****@pedalsup.com. Log in using this email to continue."
- ✅ Verify button shows: "Log in with email"
- Click the button
- ✅ Verify navigation back to email input screen
- ✅ Verify no console errors

**4. Clean up:** Remove the mock code before committing

## **Screenshots/Recordings**

### **Before**
Error banner without logout button - user had no way to logout and try
with correct email

<img width="787" height="1704" alt="image"
src="https://github.com/user-attachments/assets/58285702-078c-4c00-99b9-d36300e6649e"
/>


### **After**

**Error Object From Transak** 

<img width="2174" height="1330" alt="image"
src="https://github.com/user-attachments/assets/3c175ebd-3df9-4447-8fac-3a3cbcca8e34"
/>

**Error banner with "Log in with email" button as shown in design
mockup**


https://github.com/user-attachments/assets/476ae836-beaf-454b-9806-9350920f3cfb


## **Pre-merge author checklist**

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

## **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.

[TRAM-2799]:
https://consensyssoftware.atlassian.net/browse/TRAM-2799?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds detection of Transak error 2020 on BasicInfo, displaying a
localized message with the masked email and a "Log in with email" action
that logs out and navigates to EnterEmail.
> 
> - **Deposit › Verify Identity (`BasicInfo.tsx`)**:
> - Detects Transak API `error.errorCode === 2020` (phone already
registered).
> - Extracts masked email from `error.message` and shows localized error
`deposit.basic_info.phone_already_registered`.
> - Displays BannerAlert action button "Log in with email" (`testID:
"basic-info-logout-button"`).
> - On click, calls `logoutFromProvider(false)` and navigates to
`...createEnterEmailNavDetails()`.
> - Resets error/UI flags on retry and field changes; integrates
`logoutFromProvider` from `useDepositSDK`.
> - **Tests (`BasicInfo.test.tsx`)**:
> - Adds cases for: showing logout button on `2020` errors, formatting
message with email, no action for generic errors, successful logout +
navigation, and graceful logout failure logging.
> - **Localization (`locales/languages/en.json`)**:
> - Adds `deposit.basic_info.phone_already_registered` and
`deposit.basic_info.login_with_email`; keeps `unexpected_error`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
6bf8336. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: amitabh94

app/components/UI/Ramp/Deposit/Views/BasicInfo/BasicInfo.test.tsx

@@ -373,4 +373,235 @@ describe('BasicInfo Component', () => {
     render(BasicInfo);
     expect(screen.toJSON()).toMatchSnapshot();
   });
+
+  describe('when phone already registered error occurs', () => {
+    const mockLogoutFromProvider = jest.fn();
+
+    beforeEach(() => {
+      mockLogoutFromProvider.mockResolvedValue(undefined);
+      mockPostKycForm.mockResolvedValue(undefined);
+      mockSubmitSsnDetails.mockResolvedValue(undefined);
+      mockUseDepositSDK.mockReturnValue({
+        selectedRegion: mockSelectedRegion,
+        logoutFromProvider: mockLogoutFromProvider,
+      });
+    });
+
+    afterEach(() => {
+      mockLogoutFromProvider.mockClear();
+    });
+
+    it('displays logout button when error has errorCode 2020', async () => {
+      // Mock Transak API error structure: { error: { errorCode: 2020, message: "..." } }
+      const error2020 = Object.assign(new Error('API Error'), {
+        error: {
+          errorCode: 2020,
+          message:
+            'This phone number is already registered. It has been used by an account created with k****@pedalsup.com. Login with this email to continue.',
+        },
+      });
+      mockPostKycForm.mockRejectedValueOnce(error2020);
+
+      render(BasicInfo);
+
+      fireEvent.changeText(screen.getByTestId('first-name-input'), 'John');
+      fireEvent.changeText(screen.getByTestId('last-name-input'), 'Smith');
+      fireEvent.changeText(
+        screen.getByTestId('deposit-phone-field-test-id'),
+        '234567890',
+      );
+      fireEvent.changeText(
+        screen.getByTestId('date-of-birth-input'),
+        '01/01/1990',
+      );
+      fireEvent.changeText(screen.getByTestId('ssn-input'), '123456789');
+
+      await act(async () => {
+        fireEvent.press(screen.getByTestId('continue-button'));
+      });
+
+      // Wait for error message to appear
+      await screen.findByText(
+        'This phone number is already in use by k****@pedalsup.com. Log in using this email to continue.',
+      );
+
+      // Verify logout button with correct label is displayed
+      const logoutButton = await screen.findByTestId(
+        'basic-info-logout-button',
+      );
+      expect(logoutButton).toBeOnTheScreen();
+      expect(screen.getByText('Log in with email')).toBeOnTheScreen();
+    });
+
+    it('displays formatted error message for errorCode 2020', async () => {
+      // Mock Transak API error structure with email in message
+      const error2020 = Object.assign(new Error('API Error'), {
+        error: {
+          errorCode: 2020,
+          message:
+            'This phone number is already registered. It has been used by an account created with k****@pedalsup.com. Login with this email to continue.',
+        },
+      });
+      mockPostKycForm.mockRejectedValueOnce(error2020);
+
+      render(BasicInfo);
+
+      fireEvent.changeText(screen.getByTestId('first-name-input'), 'John');
+      fireEvent.changeText(screen.getByTestId('last-name-input'), 'Smith');
+      fireEvent.changeText(
+        screen.getByTestId('deposit-phone-field-test-id'),
+        '234567890',
+      );
+      fireEvent.changeText(
+        screen.getByTestId('date-of-birth-input'),
+        '01/01/1990',
+      );
+      fireEvent.changeText(screen.getByTestId('ssn-input'), '123456789');
+
+      await act(async () => {
+        fireEvent.press(screen.getByTestId('continue-button'));
+      });
+
+      // Verify formatted error message is displayed with localized string
+      await screen.findByText(
+        'This phone number is already in use by k****@pedalsup.com. Log in using this email to continue.',
+      );
+
+      // Verify logout button with correct label is displayed
+      const logoutButton = await screen.findByTestId(
+        'basic-info-logout-button',
+      );
+      expect(logoutButton).toBeOnTheScreen();
+      expect(screen.getByText('Log in with email')).toBeOnTheScreen();
+    });
+
+    it('does not display logout button for generic errors', async () => {
+      const genericError = new Error('Network error');
+      mockPostKycForm.mockRejectedValueOnce(genericError);
+
+      render(BasicInfo);
+
+      fireEvent.changeText(screen.getByTestId('first-name-input'), 'John');
+      fireEvent.changeText(screen.getByTestId('last-name-input'), 'Smith');
+      fireEvent.changeText(
+        screen.getByTestId('deposit-phone-field-test-id'),
+        '234567890',
+      );
+      fireEvent.changeText(
+        screen.getByTestId('date-of-birth-input'),
+        '01/01/1990',
+      );
+      fireEvent.changeText(screen.getByTestId('ssn-input'), '123456789');
+
+      await act(async () => {
+        fireEvent.press(screen.getByTestId('continue-button'));
+      });
+
+      // Wait for generic error to appear
+      await screen.findByText('Network error');
+
+      // Verify logout button is NOT displayed for generic errors
+      expect(screen.queryByTestId('basic-info-logout-button')).toBeNull();
+    });
+
+    it('calls logoutFromProvider and navigates to EnterEmail on logout click', async () => {
+      const error2020 = Object.assign(new Error('API Error'), {
+        error: {
+          errorCode: 2020,
+          message:
+            'This phone number is already registered. It has been used by an account created with test@gmail.com. Login with this email to continue.',
+        },
+      });
+      mockPostKycForm.mockRejectedValueOnce(error2020);
+
+      render(BasicInfo);
+
+      fireEvent.changeText(screen.getByTestId('first-name-input'), 'John');
+      fireEvent.changeText(screen.getByTestId('last-name-input'), 'Smith');
+      fireEvent.changeText(
+        screen.getByTestId('deposit-phone-field-test-id'),
+        '234567890',
+      );
+      fireEvent.changeText(
+        screen.getByTestId('date-of-birth-input'),
+        '01/01/1990',
+      );
+      fireEvent.changeText(screen.getByTestId('ssn-input'), '123456789');
+
+      await act(async () => {
+        fireEvent.press(screen.getByTestId('continue-button'));
+      });
+
+      // Wait for error and logout button to appear
+      const logoutButton = await screen.findByTestId(
+        'basic-info-logout-button',
+      );
+
+      await act(async () => {
+        fireEvent.press(logoutButton);
+      });
+
+      expect(mockLogoutFromProvider).toHaveBeenCalledWith(false);
+      expect(mockNavigate).toHaveBeenCalledWith(
+        Routes.DEPOSIT.ENTER_EMAIL,
+        undefined,
+      );
+    });
+
+    it('handles logout error gracefully', async () => {
+      const mockLoggerError = jest.spyOn(Logger, 'error');
+      const logoutError = new Error('Logout failed');
+      mockLogoutFromProvider.mockRejectedValueOnce(logoutError);
+
+      const error2020 = Object.assign(new Error('API Error'), {
+        error: {
+          errorCode: 2020,
+          message:
+            'This phone number is already registered. It has been used by an account created with d***@example.com. Login with this email to continue.',
+        },
+      });
+      mockPostKycForm.mockRejectedValueOnce(error2020);
+
+      render(BasicInfo);
+
+      fireEvent.changeText(screen.getByTestId('first-name-input'), 'John');
+      fireEvent.changeText(screen.getByTestId('last-name-input'), 'Smith');
+      fireEvent.changeText(
+        screen.getByTestId('deposit-phone-field-test-id'),
+        '234567890',
+      );
+      fireEvent.changeText(
+        screen.getByTestId('date-of-birth-input'),
+        '01/01/1990',
+      );
+      fireEvent.changeText(screen.getByTestId('ssn-input'), '123456789');
+
+      await act(async () => {
+        fireEvent.press(screen.getByTestId('continue-button'));
+      });
+
+      // Wait for error and logout button to appear
+      const logoutButton = await screen.findByTestId(
+        'basic-info-logout-button',
+      );
+
+      await act(async () => {
+        fireEvent.press(logoutButton);
+      });
+
+      expect(mockLogoutFromProvider).toHaveBeenCalled();
+      expect(mockNavigate).not.toHaveBeenCalled();
+      expect(mockLoggerError).toHaveBeenCalledWith(
+        logoutError,
+        'Error logging out from BasicInfo error banner',
+      );
+
+      // Error message stays visible
+      await screen.findByText(
+        'This phone number is already in use by d***@example.com. Log in using this email to continue.',
+      );
+
+      mockLoggerError.mockRestore();
+    });
+  });
 });

app/components/UI/Ramp/Deposit/Views/BasicInfo/BasicInfo.tsx

@@ -25,6 +25,7 @@ import {
   createEnterAddressNavDetails,
 } from '../EnterAddress/EnterAddress';
 import { createSsnInfoModalNavigationDetails } from '../Modals/SsnInfoModal';
+import { createEnterEmailNavDetails } from '../EnterEmail/EnterEmail';
 import { BuyQuote } from '@consensys/native-ramps-sdk';
 import { useDepositSDK } from '../../sdk';
 import { VALIDATION_REGEX } from '../../constants/constants';
@@ -70,9 +71,10 @@ const BasicInfo = (): JSX.Element => {
   const { styles, theme } = useStyles(styleSheet, {});
   const trackEvent = useAnalytics();
   const { quote, previousFormData } = useParams<BasicInfoParams>();
-  const { selectedRegion } = useDepositSDK();
+  const { selectedRegion, logoutFromProvider } = useDepositSDK();
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [isPhoneRegisteredError, setIsPhoneRegisteredError] = useState(false);
 
   const firstNameInputRef = useRef<TextInput>(null);
   const lastNameInputRef = useRef<TextInput>(null);
@@ -197,6 +199,7 @@ const BasicInfo = (): JSX.Element => {
 
     // Clear any previous errors when retrying
     setError(null);
+    setIsPhoneRegisteredError(false);
 
     trackEvent('RAMPS_BASIC_INFO_ENTERED', {
       region: selectedRegion?.isoCode || '',
@@ -227,11 +230,34 @@ const BasicInfo = (): JSX.Element => {
         }),
       );
     } catch (submissionError) {
-      setError(
-        submissionError instanceof Error && submissionError.message
-          ? submissionError.message
-          : strings('deposit.basic_info.unexpected_error'),
-      );
+      // Check for Transak error code 2020 (phone already registered)
+      // API returns: { error: { errorCode: 2020, message: "..." } }
+      const errorWithCode = submissionError as unknown as {
+        error?: { errorCode?: number; message?: string };
+      };
+      const isPhoneError = errorWithCode?.error?.errorCode === 2020;
+
+      setIsPhoneRegisteredError(isPhoneError);
+
+      // For error code 2020, extract email from message and format it
+      let errorMessage = '';
+      if (isPhoneError && errorWithCode?.error?.message) {
+        // Extract email from message like "...created with k****@pedalsup.com..."
+        const emailMatch = errorWithCode.error.message.match(
+          /[\w*]+@[\w*]+(?:\.[\w*]+)*/,
+        );
+        const email = emailMatch ? emailMatch[0] : '';
+        errorMessage = email
+          ? strings('deposit.basic_info.phone_already_registered', { email })
+          : errorWithCode.error.message;
+      } else {
+        errorMessage =
+          submissionError instanceof Error && submissionError.message
+            ? submissionError.message
+            : strings('deposit.basic_info.unexpected_error');
+      }
+
+      setError(errorMessage);
       Logger.error(
         submissionError as Error,
         'Unexpected error during basic info form submission',
@@ -240,17 +266,32 @@ const BasicInfo = (): JSX.Element => {
       setLoading(false);
     }
   }, [
-    previousFormData,
     validateFormData,
     formData,
     postKycForm,
     submitSsnDetails,
     navigation,
     quote,
+    previousFormData,
     selectedRegion?.isoCode,
     trackEvent,
   ]);
 
+  const handleLogout = useCallback(async () => {
+    try {
+      await logoutFromProvider(false); // false = no server invalidation needed
+
+      // Navigate back to email entry screen
+      navigation.navigate(...createEnterEmailNavDetails());
+    } catch (logoutError) {
+      Logger.error(
+        logoutError as Error,
+        'Error logging out from BasicInfo error banner',
+      );
+      // Keep error visible if logout fails
+    }
+  }, [logoutFromProvider, navigation]);
+
   const focusNextField = useCallback(
     (nextRef: React.RefObject<TextInput>) => () => {
       nextRef.current?.focus();
@@ -262,6 +303,7 @@ const BasicInfo = (): JSX.Element => {
     (field: keyof BasicInfoFormData, nextAction?: () => void) =>
       (value: string) => {
         setError(null);
+        setIsPhoneRegisteredError(false);
         const currentValue = formData[field] || '';
         const isAutofill = value.length - currentValue.length > 1;
 
@@ -298,6 +340,17 @@ const BasicInfo = (): JSX.Element => {
                 <BannerAlert
                   description={error}
                   severity={BannerAlertSeverity.Error}
+                  actionButtonProps={
+                    isPhoneRegisteredError
+                      ? {
+                          variant: ButtonVariants.Link,
+                          label: strings('deposit.basic_info.login_with_email'),
+                          onPress: handleLogout,
+                          labelTextVariant: TextVariant.BodyMD,
+                          testID: 'basic-info-logout-button',
+                        }
+                      : undefined
+                  }
                 />
               </View>
             )}

locales/languages/en.json

@@ -776,7 +776,9 @@
       "dob_required": "Date of birth is required",
       "dob_invalid": "Please enter a valid date of birth",
       "ssn_required": "Social security number is required",
-      "unexpected_error": "An unexpected error occurred. Please try again."
+      "unexpected_error": "An unexpected error occurred. Please try again.",
+      "phone_already_registered": "This phone number is already in use by {{email}}. Log in using this email to continue.",
+      "login_with_email": "Log in with email"
     },
     "enter_address": {
       "navbar_title": "Verify your identity",