Repository navigation
feat(kyc-controller): one KYC session per vendor - #11275
Closed
georgeweiler wants to merge 3 commits into
Closed
georgeweiler wants to merge 3 commits into
georgeweiler wants to merge 3 commits into
Conversation
Replace the single-session KycController state with `sessions`, keyed by
vendor, so a second vendor (e.g. Kalshi) can hold its own session next to
Iron. Every session method takes `{ vendor }`; there is no active vendor.
- Add getSessionDecision (none/new/pending/approved/rejected/retry), moved
from RampsController's resolveVbaKycStatus
- Add acceptVendorDisclaimers so vendor terms accepted before a session
exists are stored on the controller, then submitted by
recordVendorDisclaimers({ vendor })
- Drop the stored email/vendor/geoCountry and their 'different X' guards;
email is only required when creating a session
- One SumSub flow on screen at a time; per-vendor polling loops
- Make vendor required on KycService.fetchVendorDisclaimers and
createUkycSession
- Remove dead KycPhase / KycProduct types
- RampsController passes vendor 'iron' and reads getSessionDecision
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 3, 2026
…ions Also require a session id in the controller's session lookup, stop recordVendorDisclaimers recreating an entry cleared mid-request, and update ARCHITECTURE.md's state and selectors sections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
georgeweiler
temporarily deployed
to
default-branch
November 4, 2026 02:51 — with
GitHub Actions
Inactive
4 tasks done
weitingsun
pushed a commit
to Poovarasan-Sandhanam/metamask-mobile
that referenced
this pull request
Nov 10, 2026
…MetaMask#39238) ## **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** <!-- mms-check: type=changelog required=true blocking=true --> CHANGELOG entry: Fixed an error that blocked account setup when the detected country had changed. ## **Related issues** <!-- mms-check: type=issue-link required=true --> Fixes: TRAM-4399 Refs: TRAM-4449 (error UI for other VBA onboarding failures, out of scope here) ## **Manual testing steps** <!-- mms-check: type=manual-testing required=true --> ```gherkin 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** <!-- mms-check: type=screenshot required=true --> 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** <!-- [screenshots/recordings] --> https://github.com/user-attachments/assets/d00d40e0-b816-459b-ab2b-f0332ecbb998 ### **After** <!-- [screenshots/recordings] --> https://github.com/user-attachments/assets/beefe553-4f47-455d-843b-45e7e5649431 ## **Pre-merge author checklist** <!-- mms-check: type=checklist required=true --> - [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** > 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. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit ed81451. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
KycControllerholds exactly one KYC session: one vendor, one email, one country, one status. Starting a session for a second vendor throws, so a feature like Predict can't add Kalshi next to VBA's Iron session. kyc-api already keys sessions by user and vendor; this brings the client controller in line.State. The flat fields are replaced by
sessions, keyed by vendor. Each entry holds that vendor's session status, provider-flow status, the country it was created with, terms acceptance and consents.email,vendorandgeoCountryare gone, along with the three "already initialized with a different X" guards.API. Every session method takes
{ vendor }. There is no active vendor.fetchSessionStatusOncetakes{ vendor }instead of a session id. Polling runs per vendor.clearStatestill wipes everything.Session decision. New
getSessionDecision({ vendor })returnsnone | new | pending | approved | rejected | retry. It isRampsController'sresolveVbaKycStatus, moved here: those rules had nothing VBA-specific in them, and every feature would otherwise copy them. It is deliberately not calledready: approval says nothing about work a vendor needs afterwards (e.g. Iron account activation).Vendor terms. Terms are shown before a session exists and can only be submitted once one does. VBA kept that acceptance in its own mobile storage. New
acceptVendorDisclaimers({ vendor, country, disclaimerIds })stores it on the vendor's entry withsubmitted: false.recordVendorDisclaimers({ vendor })submits it once a session exists.hasCompletedVendorDisclaimersonly counts submitted acceptance.Other behaviour.
failedwithout touching state.vendoris now required onKycService.fetchVendorDisclaimersandcreateUkycSession, which silently defaulted tomoonpay.KycPhaseandKycProducttypes.ramps-controller changes in the same PR because it keeps local copies of the KycController action types. Without this, core tests stay green while mobile breaks at runtime. It now passes
vendor: 'iron'and readsgetSessionDecision.VbaKycStatusandVbaOnboardingSnapshotare unchanged.This builds the state that the requirement-graph design in #11252 would sit on; it does not build that evaluator.
First pass. New behaviour is covered by focused tests (per-vendor sessions, terms acceptance, decision parity with the old ramps rules, single SumSub launch). The existing single-session
KycControllertests and the rampshydrateVbaOnboardingtests still assert the old shape and fail. They need updating before this leaves draft.Verified end to end by overlaying the built packages into a local mobile build: Engine loads, migration 161 runs, VBA hydrate reads the new state, and terms accepted on the VBA screen land on
sessions.ironand carry the flow to the email step.References
Checklist
🤖 Generated with Claude Code