Skip to content

feat(kyc-controller): one KYC session per vendor - #11275

Closed
georgeweiler wants to merge 3 commits into
mainfrom
gw/kyc-per-vendor-sessions
Closed

georgeweiler wants to merge 3 commits into
mainfrom
gw/kyc-per-vendor-sessions

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

KycController holds 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, vendor and geoCountry are gone, along with the three "already initialized with a different X" guards.

API. Every session method takes { vendor }. There is no active vendor. fetchSessionStatusOnce takes { vendor } instead of a session id. Polling runs per vendor. clearState still wipes everything.

Session decision. New getSessionDecision({ vendor }) returns none | new | pending | approved | rejected | retry. It is RampsController's resolveVbaKycStatus, moved here: those rules had nothing VBA-specific in them, and every feature would otherwise copy them. It is deliberately not called ready: 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 with submitted: false. recordVendorDisclaimers({ vendor }) submits it once a session exists. hasCompletedVendorDisclaimers only counts submitted acceptance.

Other behaviour.

  • Email is only required when creating a session. Resuming no longer fails when the identity token has no email.
  • One SumSub flow is presented at a time; a second launch returns failed without touching state.
  • vendor is now required on KycService.fetchVendorDisclaimers and createUkycSession, which silently defaulted to moonpay.
  • Removed the unused KycPhase and KycProduct types.

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 reads getSessionDecision. VbaKycStatus and VbaOnboardingSnapshot are 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 KycController tests and the ramps hydrateVbaOnboarding tests 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.iron and carry the flow to the email step.

References

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

🤖 Generated with Claude Code

georgeweiler and others added 2 commits November 3, 2026 15:56
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>
…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>
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

1 inactive deployment
default-branch — 7cf90a17 Deployed Nov 4, 2026 by georgeweiler via Determine whether this PR is a release PR #6446
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant