Skip to content

fix(ramps-controller): treat relay-approved KYC as approved in hydrate - #10497

Merged
georgeweiler merged 4 commits into
mainfrom
fix/vba-hydrate-relay-kyc-gate
Sep 28, 2026
Merged

georgeweiler merged 4 commits into
mainfrom
fix/vba-hydrate-relay-kyc-gate

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

RampsController.hydrateVbaOnboarding maps the VBA onboarding snapshot's kycStatus from the KYC session, but it derived it only from the vendor-side finalStatus:

kycStatus: toVbaKycStatus(session.finalStatus)

The UKYC session exposes two decision fields: the relay-side kycStatus and the vendor-side finalStatus. When the relay has approved a customer (kycStatus: 'approved') but the vendor is still finalizing (finalStatus: 'pending', e.g. Iron vendorStatus: 'new'), the snapshot resolved to pending, so the host stranded a fully relay-approved user on the "verification in progress" screen indefinitely (the vendor status may never advance in some environments).

This mirrors the UKYC backend's own definition of "already approved" (va-mmcx-kyc-api), which is:

finalStatus === 'approved' || kycStatus === 'approved'

The client was stricter than its own backend. This change maps the snapshot kycStatus to 'approved' when either field is 'approved'; all other statuses continue to derive from finalStatus.

Note: the separate autoramp-reconciliation fix (dropping the unsupported GET /neobank/autoramps list call) is being handled in its own PR so it can adopt a customer-id lookup rather than a create-rejection fallback. This PR is scoped to the KYC gate only.

References

  • Surfaced while debugging VBA onboarding: a sandbox-approved user was held on "verification in progress" because the backend returned kycStatus: approved / finalStatus: pending.

Changelog

@metamask/ramps-controller

  • FIXED: Treat a relay-approved KYC session as approved in hydrateVbaOnboarding even when the vendor-side finalStatus is still pending.

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated the changelog
  • I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

🤖 Generated with Claude Code


Note

Medium Risk
Changes KYC approval gating for VBA onboarding and can advance users past pending when only relay kycStatus is approved, though behavior is aligned with the backend and limited to the hydration snapshot.

Overview
hydrateVbaOnboarding no longer treats VBA onboarding as pending when the relay has already approved KYC but the vendor finalStatus is still pending. Snapshot kycStatus is set to approved when either session.finalStatus or session.kycStatus is approved; otherwise it still comes from toVbaKycStatus(session.finalStatus). That matches the UKYC backend’s “already approved” rule and lets wallet registration and autoramp setup continue instead of leaving users on the verification-in-progress screen.

Tests add coverage for the relay-approved / vendor-pending split and align the sessionWithStatus helper so relay and vendor statuses stay consistent in other cases. The unreleased changelog documents the fix.

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

`hydrateVbaOnboarding` mapped the VBA snapshot `kycStatus` solely from the
vendor-side `finalStatus`. When the relay has approved a session
(`kycStatus: 'approved'`) but the vendor is still finalizing
(`finalStatus: 'pending'`), this left relay-approved users stranded on the
pending screen indefinitely.

Map `kycStatus` to `'approved'` when either `finalStatus` or the relay-side
`kycStatus` is `'approved'`, mirroring the UKYC backend's own
`isKycAlreadyApproved` check (`finalStatus === 'approved' || kycStatus === 'approved'`).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…t call

`hydrateVbaOnboarding` called `NeoBankService:getAutoramps` to list the
customer's autoramps, but the neobank proxy (and MoonPay) expose autoramps by
id only — there is no list-by-customer endpoint — so the call always 404'd and
provisioning fell into `retryable_failure` ("couldn't create your account").

Reconcile the autoramps already known for the wallet by refreshing each by id
instead of listing, and treat a duplicate-create conflict (MoonPay allows one
autoramp per customer) as already provisioned rather than a failure. Remove
`NeoBankService:getAutoramps` from the controller's required service actions
since it is no longer called.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@georgeweiler georgeweiler changed the title fix(ramps-controller): treat relay-approved KYC as approved in hydrate fix(ramps-controller): fix VBA onboarding provisioning (relay KYC gating + autoramp reconcile) Sep 28, 2026

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit b46bc03. Configure here.

@georgeweiler georgeweiler changed the title fix(ramps-controller): fix VBA onboarding provisioning (relay KYC gating + autoramp reconcile) fix(ramps-controller): treat relay-approved KYC as approved in hydrate Sep 28, 2026
@georgeweiler
georgeweiler added this pull request to the merge queue Sep 28, 2026
Merged via the queue into main with commit 4ac8715 Sep 28, 2026
47 checks passed
@georgeweiler
georgeweiler deleted the fix/vba-hydrate-relay-kyc-gate branch September 28, 2026 12:58
@georgeweiler georgeweiler mentioned this pull request Sep 28, 2026
georgeweiler added a commit to MetaMask/metamask-mobile that referenced this pull request Sep 28, 2026
Pulls in the VBA KYC gating fix (relay-approved sessions treated as approved
in hydrateVbaOnboarding) released in @metamask/ramps-controller@26.0.1
(MetaMask/core#10497), so the onboarding "complete" path this screen renders
is reachable end to end.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
pull Bot pushed a commit to Reality2byte/metamask-mobile that referenced this pull request Sep 28, 2026
…ask#36916)

## **Description**

<!-- mms-check: type=text required=true -->

When VBA onboarding finishes provisioning the Money account
(`hydrateVbaOnboarding` returns `autorampStatus: 'ready'` →
`destinationId: 'complete'`), the coordinator navigated straight to
Money Home. Since the user is already in the Money area, a successful
account creation looked like **nothing happened** — the onboarding sheet
just closed with no confirmation.

This adds a terminal **"Virtual bank account"** details screen and
routes to it on completion instead of silently returning to Money Home.
It's currently a stub (title + description + a **Done** button that
returns to Money Home); real account details will render here in a
follow-up.

### Changes

- New screen `VbaDetails.tsx` (+ `VbaDetails.test.tsx`)
- Register `VbaOnboardingRoutes.DETAILS` in `routes.ts` and
`VbaOnboardingNavigator.tsx`
- `useVbaOnboardingRouting` `complete` destination now navigates to the
details screen (was Money Home)
- `virtual_bank_account.vba_details` strings
- Bump `@metamask/ramps-controller` to `^26.0.1` (relay-approved KYC
gating fix from MetaMask/core#10497)

## **Changelog**

<!-- mms-check: type=changelog required=true blocking=true -->

CHANGELOG entry: Added a Virtual bank account details screen shown when
VBA onboarding completes

## **Related issues**

<!-- mms-check: type=issue-link required=true -->

Refs: MetaMask/core#10497 — `@metamask/ramps-controller` fix
(relay-approved KYC gating) required for the `complete` path to be
reachable end-to-end. This client PR is independent and self-contained;
the full flow lands now that ramps-controller is bumped to `26.0.1`.

## **Manual testing steps**

<!-- mms-check: type=manual-testing required=true -->

```gherkin
Feature: VBA onboarding completion

  Scenario: user completes VBA onboarding with a provisioned autoramp
    Given the user is KYC-approved and has a provisioned autoramp
    And the user is on Money Home

    When the user completes the VBA onboarding flow
    Then the "Virtual bank account" details screen is shown
    And the user is not silently returned to Money Home

  Scenario: user dismisses the VBA details screen
    Given the user is on the "Virtual bank account" details screen

    When the user taps "Done"
    Then the user is returned to Money Home
```

## **Screenshots/Recordings**

<!-- mms-check: type=screenshot required=true -->

### **Before**

N/A — on completion the onboarding sheet closed and the user was
returned to Money Home with no confirmation screen.

### **After**

N/A — stub screen (title, description, **Done** button); real account
details will be added in a follow-up.

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

- [x] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [x] 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
- [x] 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**

- [ ] 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]
> **Low Risk**
> Scoped VBA onboarding navigation and a placeholder UI; no auth or
payment logic changes beyond the ramps-controller patch bump.
> 
> **Overview**
> When VBA onboarding finishes provisioning (`destinationId: 'complete'`
/ `autorampStatus: 'ready'`), users now land on a new **Virtual bank
account** confirmation screen instead of being sent straight to Money
Home (which felt like nothing happened).
> 
> The PR adds stub screen `VbaDetails` (title, copy, **Done** → Money
Home), registers `VbaOnboardingRoutes.DETAILS` on the onboarding stack,
and updates `navigateToVbaOnboardingDestination` and
`useOpenVbaOnboarding` tests to route there. Adds
`virtual_bank_account.vba_details` strings and bumps
`@metamask/ramps-controller` to **26.0.1**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
fb615ae. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
pull Bot pushed a commit to Reality2byte/core that referenced this pull request Sep 29, 2026
## Explanation

Scoped release cutting **`@metamask/ramps-controller` 26.0.0 → 26.0.1**
(patch) to ship the VBA KYC gating fix so MetaMask Mobile can pick it
up.

Includes:
- **`@metamask/ramps-controller` 26.0.1** — Fixed: treat a
relay-approved KYC session as approved in `hydrateVbaOnboarding` even
when the vendor-side `finalStatus` is still `pending` (MetaMask#10497).

Other packages with unreleased changes are intentionally deferred to a
later release; ramps-controller's changed dependencies
(`base-controller`, `controller-utils`, `messenger`,
`profile-sync-controller`, `remote-feature-flag-controller`) are marked
`intentionally-skip` — ramps-controller keeps its existing dependency
ranges. `transaction-pay-controller`'s `package.json` dependency range
on ramps-controller is bumped automatically.

## References

- Ships MetaMask#10497

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Release-only version and dependency bumps with no code changes in this
diff; downstream risk is limited to adopting the already-shipped
ramps-controller patch.
> 
> **Overview**
> **Monorepo release 1296.0.0** publishes a scoped patch of
**`@metamask/ramps-controller` 26.0.0 → 26.0.1** so clients (e.g.
MetaMask Mobile) can consume the VBA onboarding fix from MetaMask#10497.
> 
> This PR only updates **version numbers**, **`ramps-controller`
CHANGELOG** (documents treating relay-approved KYC as approved in
`hydrateVbaOnboarding` when vendor `finalStatus` is still `pending`),
**`transaction-pay-controller`**’s dependency on `^26.0.1`, and
**`yarn.lock`**. No application source changes appear in the diff—the
behavioral fix is assumed already merged.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
7f613cc. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Naz-Ovh pushed a commit to 0x-fork/metamask-core that referenced this pull request Nov 4, 2026
## Explanation

`RampsController.hydrateVbaOnboarding` currently treats either the
relay-side `kycStatus` or the provider-side `finalStatus` as final KYC
approval.

MoonPay/Iron clarified that relay approval only represents document
processing; it does not confirm that the provider has accepted the
customer.

This change makes `finalStatus === 'approved'` the only approval gate. A
session with `kycStatus: 'approved'` and `finalStatus: 'pending'` now
stays pending and does not begin customer or autoramp setup.

This intentionally supersedes the behavior introduced in MetaMask#10497.

**Demo with mobile changes applied:**


https://github.com/user-attachments/assets/8f8fcf94-c5af-45d6-bedb-0636af3ac455


## References

- [TRAM-4392](https://consensyssoftware.atlassian.net/browse/TRAM-4392)
- Mobile consumer:
[MetaMask/metamask-mobile#38688](MetaMask/metamask-mobile#38688)
- Related: MetaMask#10497

## Verification

- `yarn workspace @metamask/ramps-controller test --run` (1,128 tests)
- `yarn workspace @metamask/ramps-controller build`
- `yarn lint:oxlint packages/ramps-controller/src/RampsController.ts
packages/ramps-controller/src/RampsController.test.ts`
- `yarn lint:misc --check
packages/ramps-controller/src/RampsController.ts
packages/ramps-controller/src/RampsController.test.ts`

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes when VBA onboarding reports KYC approved and unlocks
wallet/autoramp steps, which affects money-account UX and reverses prior
relay-first behavior.
> 
> **Overview**
> **VBA onboarding now treats only provider `finalStatus: 'approved'` as
KYC approved**, reversing the behavior from MetaMask#10497 where relay
`kycStatus: 'approved'` could advance users while the vendor was still
pending.
> 
> `resolveVbaKycStatus` no longer ORs in relay approval; relay-approved
sessions with a pending `finalStatus` stay **`kycStatus: 'pending'`**,
so `hydrateVbaOnboarding` returns early and does not surface
`needs_wallet_registration` or other post-approval autoramp states. When
the provider has approved but relay `kycStatus` still lags,
**`finalStatus` still wins** and onboarding can proceed.
> 
> Tests and the changelog document the relay/vendor divergence cases.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
015df72. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
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.

2 participants