Skip to content

fix(ramps): handle VBA KYC geoCountry mismatch without losing session - #39238

Merged
saustrie-consensys merged 6 commits into
mainfrom
fix/vba-geocountry-reset
Nov 10, 2026
Merged

saustrie-consensys merged 6 commits into
mainfrom
fix/vba-geocountry-reset

Conversation

@saustrie-consensys

@saustrie-consensys saustrie-consensys commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Description

When a VBA user resumes KYC and their persisted session was started under a different geoCountry than the current one, KycController.startSession throws KycController already initialized with a different geoCountry. VBA onboarding caught that error and showed the full-screen "Couldn't open your account" error, which gives no reason and only offers Try again.

This PR handles that one error in startVbaKycSession (app/components/UI/Ramp/Views/VirtualBankAccount/vbaKycSession.ts), which both entry points use: resuming from the Money home VBA card (resumePersistedKycSession) and the email step (EmailAdapter).

  • If a KYC session is stored on the device and its capability authorization does not need a refresh (needsCapabilityAuthorizationRefresh from kyc-controller), the error is ignored and onboarding continues with that session. Its email, providerFlowStatus, vendor terms, and stored geoCountry stay. Hydrate does not call startSession, so it does not hit the check.
  • Otherwise (no stored session, or a stored session whose authorization is new or expired and not approved or rejected), the app calls KycController.reset() and runs startSession once more. That reattaches the server session and refreshes its authorization before Sumsub.
  • Email and vendor mismatches, and every other error, still fail as before.

Sumsub consents: useLaunchSumSub and useKycSessionDisclaimers now load the session disclaimer catalog for the stored KycController geoCountry, falling back to the IP lookup. A kept session therefore records consents for its own country, not the one the user is currently in.

The check lives in kyc-controller, unchanged up to 0.16.0. Removing it needs a core release; MetaMask/core#11275 drops it as part of per-vendor sessions and is still open. This change is mobile-only.

Known costs, accepted for this change:

  • The reset branch clears local state: providerFlowStatus returns to not_started and local vendor-disclaimer acceptance is cleared (wallet-saved terms are re-recorded on hydrate). A retry user who had already resubmitted can land on the failure screen until the server status updates.
  • The reset branch writes the current country to state.geoCountry, while the server session keeps the residence country it was created with. The stored geoCountry therefore matches the creation country only for sessions created on this device that were never reattached.
  • The reset branch clears the stored email. If partner-identity minting then returns HTTP 422, the retry throws "missing verified email" until a token with a verified email is available.
  • Two overlapping calls that both reset can clear the session the other just stored. No concurrent caller was found in the code; it needs two entries at the same moment.

Out of scope: the error screen layout and copy for other VBA failures (TRAM-4449).

Changelog

CHANGELOG entry: Fixed an error that blocked account setup when the detected country had changed.

Related issues

Fixes: TRAM-4399
Refs: TRAM-4449 (error UI for other VBA onboarding failures, out of scope here)

Manual testing steps

Feature: VBA KYC resumes after a geoCountry change

  Scenario: user resumes KYC after the detected country changed
    Given the user has a persisted VBA KYC session started under one country
    And the current detected country is different
    When the user taps Continue on the Money home VBA card
    Then the user stays in VBA onboarding
    And the "Couldn't open your account" error is not shown

  Scenario: user reaches the email step after the detected country changed
    Given the user has no saved vendor session and a partly started KYC session
    And the detected country has changed since that session started
    When the user completes email verification
    Then the email step advances without showing an error

Used a VPN app to ensure the reproducibility of Maggie error using a VPN.

Screenshots/Recordings

N/A: logic-only change. The error screen is unchanged and no new UI is added. The before state is the "Couldn't open your account" error described above.

Before

Screen_Recording_20261109_101738_MetaMask.mp4

After

Screen_Recording_20261109_102237_MetaMask.mp4

Pre-merge author checklist

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 to import wallets with many accounts and tokens
  • I've instrumented key operations with Sentry traces for production performance metrics

For performance guidelines and tooling, see the Performance Guide.

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 KYC session resume, reset, and consent country selection in VBA onboarding—sensitive identity flow with edge cases (reset clears local state) but scoped and well-tested.

Overview
Adds startVbaKycSession so VBA onboarding no longer dies on already initialized with a different geoCountry. Email and Money-home resume now call this helper instead of KycController.startSession directly.

On that mismatch, a stored session with valid capability auth is kept and onboarding continues; otherwise the controller resets once and startSession retries. Email/vendor mismatches and other errors still propagate.

SumSub consents and the identity terms catalog prefer KycController.state.geoCountry, falling back to IP detection, so a retained session records disclaimers for its original country. Tests cover the helper, routing, email step, and disclaimer hooks.

Reviewed by Cursor Bugbot for commit ed81451. Bugbot is set up for automated code reviews on this repo. Configure here.

When a persisted KYC session was started under a different geoCountry,
KycController.startSession throws and VBA onboarding showed the generic
"Couldn't open your account" error. Reset the controller and start the
session again instead, in both the Continue path and the email step.

Reset also clears providerFlowStatus and local disclaimer acceptance, so
users who already submitted SumSub can be routed back into the flow until
the server status reloads.
@saustrie-consensys saustrie-consensys added the team-money-movement issues related to Money Movement features label Nov 9, 2026
@saustrie-consensys saustrie-consensys self-assigned this Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions github-actions Bot added size-M pr-not-ready-for-e2e Skip E2E and block merging. Remove this label once the PR is ready to run the E2E tests. labels Nov 9, 2026
@metamask-ci

metamask-ci Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

  • Pre-merge author checklist has unchecked items (e.g. "I've tested on Android"). Every box must be consciously checked — see docs/readme/ready-for-review.md.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

…rop it

Resetting on a geoCountry mismatch deletes the only email startSession can use after a partner-identity 422. Skip that reset unless a fresh partner token still carries a verified email, and keep a different AAL2 token on its own attempt.
@github-actions github-actions Bot added size-L and removed size-M labels Nov 9, 2026
@saustrie-consensys saustrie-consensys removed the pr-not-ready-for-e2e Skip E2E and block merging. Remove this label once the PR is ready to run the E2E tests. label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Smart E2E Test Selection

Selected E2E tags: No E2E tests selected

AI Confidence: 80

E2E reasoning

Expand to read

The changes are confined to the KYC and Virtual Bank Account (VBA) onboarding code, plus their unit tests. EmailAdapter and useVbaOnboardingRouting now call a new startVbaKycSession helper instead of calling KycController.startSession directly. useLaunchSumSub now reads the geo country from KycController.state first and falls back to KycService.getGeoCountry(). I did not check how startVbaKycSession is implemented in vbaKycSession.ts. The importer search found no smoke tests that reference the KYC or VBA screens. My search of the e2e specs failed on a missing e2e/ directory, so the "no coverage" result is not fully confirmed. These flows sit behind specific feature flags and are not part of the general SmokeMoney ramp and Card smoke specs. No shared UI surfaces, controllers or navigation were touched, so none of the available smoke tags covers them.

View run

Reset only when no session is stored on the device, so a country change no longer clears the email, provider-flow status, or vendor terms of an existing session. Drops the partner-token email check and the in-flight map.
@github-actions github-actions Bot added size-M and removed size-L labels Nov 9, 2026
@saustrie-consensys saustrie-consensys changed the title fix(ramps): reset VBA KYC session on geoCountry mismatch fix(ramps): handle VBA KYC geoCountry mismatch without losing session Nov 9, 2026
…y for Sumsub consents

A kept session whose capability authorization needs a refresh is reset and reattached instead, so Sumsub does not launch with an expired authorization. Session disclaimers are loaded for the stored KYC geoCountry, falling back to the IP lookup, so consents match the kept session.
Main renamed VbaEmailAdapter to KycEmailAdapter; the merge left two test
usages on the old name.
@sonarqubecloud

Copy link
Copy Markdown

@saustrie-consensys
saustrie-consensys added this pull request to the merge queue Nov 10, 2026
Merged via the queue into main with commit 200233e Nov 10, 2026
121 checks passed
@saustrie-consensys
saustrie-consensys deleted the fix/vba-geocountry-reset branch November 10, 2026 16:37
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 10, 2026
@metamask-ci metamask-ci Bot added the release-8.21.0 Issue or pull request that will be included in release 8.21.0 label Nov 10, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

release-8.21.0 Issue or pull request that will be included in release 8.21.0 size-M team-money-movement issues related to Money Movement features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants