Repository navigation
fix(ramps): handle VBA KYC geoCountry mismatch without losing session - #39238
Conversation
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.
|
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. |
PR template — items to address before "Ready for review"Warnings — informational, address before merging:
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.
Smart E2E Test SelectionSelected E2E tags: No E2E tests selected AI Confidence: 80 E2E reasoningExpand to readThe changes are confined to the KYC and Virtual Bank Account (VBA) onboarding code, plus their unit tests. EmailAdapter and useVbaOnboardingRouting now call a new |
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.
…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.
|



Description
When a VBA user resumes KYC and their persisted session was started under a different geoCountry than the current one,
KycController.startSessionthrowsKycController 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).needsCapabilityAuthorizationRefreshfrom kyc-controller), the error is ignored and onboarding continues with that session. Its email,providerFlowStatus, vendor terms, and storedgeoCountrystay. Hydrate does not callstartSession, so it does not hit the check.neworexpiredand not approved or rejected), the app callsKycController.reset()and runsstartSessiononce more. That reattaches the server session and refreshes its authorization before Sumsub.Sumsub consents:
useLaunchSumSubanduseKycSessionDisclaimersnow load the session disclaimer catalog for the storedKycControllergeoCountry, 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:
providerFlowStatusreturns tonot_startedand local vendor-disclaimer acceptance is cleared (wallet-saved terms are re-recorded on hydrate). Aretryuser who had already resubmitted can land on the failure screen until the server status updates.state.geoCountry, while the server session keeps the residence country it was created with. The storedgeoCountrytherefore matches the creation country only for sessions created on this device that were never reattached.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
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)
trace()for usage andaddTokenfor an exampleFor performance guidelines and tooling, see the Performance Guide.
Pre-merge reviewer checklist
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
startVbaKycSessionso VBA onboarding no longer dies onalready initialized with a different geoCountry. Email and Money-home resume now call this helper instead ofKycController.startSessiondirectly.On that mismatch, a stored session with valid capability auth is kept and onboarding continues; otherwise the controller resets once and
startSessionretries. 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.