Skip to content

fix(neobank): keep VBA KYC pending until provider approval - #38688

Merged
roz0n merged 17 commits into
mainfrom
fix/TRAM-4392-moonpay-limbo
Nov 4, 2026
Merged

roz0n merged 17 commits into
mainfrom
fix/TRAM-4392-moonpay-limbo

Conversation

@roz0n

@roz0n roz0n commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Description

MoonPay relay approval means document processing completed, but the provider can still be reviewing the customer. Mobile previously treated relay-side kycStatus: approved as terminal even when provider-side finalStatus remained pending,

  • This change keeps the KYC pending screen and Money home card active until finalStatus becomes terminal.
  • The pending card now uses the animated design-system spinner and opens the already-known pending destination immediately, without flashing a standalone loading screen.

Note

  • This PR consumes the corrected onboarding snapshot semantics from MetaMask/core#11243.
  • Upgrades @metamask/ramps-controller to 29.0.0 and @metamask/transaction-pay-controller to 30.3.3 to consume the Core fix and maintain compatible dependencies.

Changelog

CHANGELOG entry: Fixed Money Account identity verification advancing before provider approval

Related issues

Refs: https://consensyssoftware.atlassian.net/browse/TRAM-4392

Manual testing steps

Feature: Money Account provider-final KYC approval

  Scenario: relay approval remains pending while the provider reviews the customer
    Given I have submitted Money Account identity verification
    And the relay KYC status is approved
    And the provider final status is pending

    When I open Money
    Then I should see the "Verifying your identity" card
    And its "Verifying" indicator should animate

    When I tap "Verifying"
    Then the "Verifying your identity" screen should open immediately
    And I should not see an intermediate full-screen loader
    And status polling should continue

  Scenario: provider-final approval completes identity verification
    Given I am on the "Verifying your identity" screen

    When the provider final status becomes approved
    Then onboarding should advance from the pending state

Screenshots/Recordings

Before

N/A

After

Screen.Recording.iPhone.17.Pro.11-02-2026.at.5.23.11.PM.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.

Made with Cursor


Note

Medium Risk
Changes Money Account KYC gating and onboarding routing, which are compliance-sensitive, though behavior is narrowed to wait for provider finalization with broad test coverage.

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

Co-authored-by: Cursor <cursoragent@cursor.com>
@roz0n roz0n self-assigned this Nov 2, 2026
@github-actions github-actions Bot added the size-M label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 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.

@metamask-ci metamask-ci Bot added the team-money-movement issues related to Money Movement features label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Smart E2E Test Selection

Selected E2E tags: ALL

AI Confidence: 100

E2E reasoning

Expand to read

This PR contains multiple high-risk changes that warrant running all E2E smoke tests:

  1. @metamask/transaction-controller major version bump (72.3.0 → 73.0.0): This is a major version bump of the transaction controller, which is a core component used across virtually all transaction flows. This affects SmokeConfirmations, SmokeSwap, SmokeStake, SmokeMoney, SmokePerps, SmokePredictions, and any flow that involves sending transactions.

  2. @metamask/core-backend major version bump (^12.3.0 → ^13.0.0): Another major version bump affecting backend services used across the app.

  3. @metamask/assets-controller and @metamask/assets-controllers updates: These affect token detection, NFT detection, and asset management across the wallet.

  4. @metamask/transaction-pay-controller update: Affects transaction payment flows.

  5. app/core/Engine/types.ts changes (CRITICAL path): Significant type restructuring removing several event types (AssetsContractControllerEvents, ConfigRegistryApiServiceEvents, RampsServiceEvents, TransakServiceEvents, NeoBankServiceEvents, ComplianceServiceEvents, etc.) and adding NftDetectionControllerDetectNftsAction. These changes affect the Engine's global event/action bus which is central to all controller communication.

  6. KYC/VBA/Money logic changes: The isApproved check now only uses finalStatus === 'approved' (removing kycStatus === 'approved'), which changes the KYC approval flow for MetaMask Card users. This affects SmokeMoney flows. The MoneyVbaHomeCard CTA handling was refactored to be async with new routing logic.

The combination of major controller version bumps (transaction-controller 72→73, core-backend 12→13) with Engine type changes creates a critical risk level. The transaction-controller major bump alone could break any test that involves transaction submission, confirmation, or gas estimation. The hard rule seed of ALL tags is confirmed as appropriate given these controller version updates.

View run

Copy link
Copy Markdown
Contributor

@roz0n one more spot to cover here: useMoneyMicrodeposits.ts L51-53 still treats kycStatus === 'approved' as approved, so relay-approved users get the microdeposits read before MoonPay's final approval. it came in with #38408 and is already on main. could we switch it to finalStatus in this PR too, so everything gates on the same signal?

const kycApproved =
sessionStatus?.finalStatus === 'approved' ||
sessionStatus?.kycStatus === 'approved';

@roz0n roz0n mentioned this pull request Nov 2, 2026
4 tasks done
Co-authored-by: Cursor <cursoragent@cursor.com>
@roz0n

roz0n commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

@amitabh94 fixed in a08cdfd: microdeposit reads now require provider-final finalStatus === "approved", with a regression test for relay-approved/final-pending sessions. Thanks for catching this.

@github-actions github-actions Bot added size-L and removed size-M labels Nov 3, 2026
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions github-actions Bot added size-M and removed size-L labels Nov 3, 2026
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.87500% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.63%. Comparing base (d830946) to head (25758e3).
⚠️ Report is 70 commits behind head on main.

Files with missing lines Patch % Lines
...y/components/MoneyVbaHomeCard/MoneyVbaHomeCard.tsx 96.55% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #38688      +/-   ##
==========================================
+ Coverage   87.58%   87.63%   +0.05%     
==========================================
  Files        7925     7967      +42     
  Lines      230191   231664    +1473     
  Branches    58385    58695     +310     
==========================================
+ Hits       201603   203014    +1411     
- Misses      16296    16304       +8     
- Partials    12292    12346      +54     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@roz0n
roz0n marked this pull request as ready for review November 3, 2026 14:04
@roz0n
roz0n requested review from a team as code owners November 3, 2026 14:04
@roz0n
roz0n marked this pull request as draft November 3, 2026 14:05

Copy link
Copy Markdown
Contributor

Thanks Arnold, this looks great for the in-session case. One scenario I want to make sure we cover is a reinstall. The user passed Sumsub (relay kycStatus approved), but MoonPay's finalStatus is still pending, and then they reinstall the app, so the local KYC session state is empty. Expected behavior is that tapping the Money card lands them on the 'Verifying your identity' pending screen and Sumsub doesn't open again.

As far as I can tell, that path goes through resolveVbaOnboarding and relies on the snapshot fix in MetaMask/core#11243, but this branch still has @metamask/ramps-controller ^28.0.0. Could you pair the ramps-controller 29.0.0 and transaction-pay-controller ^30.3.3 bump with this PR, or confirm the current version already returns that snapshot? Could you also add a test where local session status is null and the hydrated server state is kycStatus approved with finalStatus pending, asserting the destination is kycPending and the Sumsub/KYC flow isn't started?

Separately, vbaCustomerAbilities: null still looks missing from initial-background-state.json.

Copy link
Copy Markdown
Contributor

Follow-up with more precise detail on the reinstall case: after the ramps-controller 29 bump, hydrate gives kycStatus 'pending' for this user, and the local providerFlowStatus is gone. So the identityVerification step in vbaOnboardingFunnel.ts isn't marked complete, and they get sent back into Sumsub. Could we treat a pending server KYC status with session disclaimers complete as past identityVerification? A getVbaDestinationForSnapshot test for this would be great: sessionExists true, disclaimers complete, kycStatus 'pending', providerFlowStatus not 'submitted', expecting 'kycPending'. Also please add "vbaCustomerAbilities": null to RampsController in app/util/test/initial-background-state.json along with the bump, since without the bump the #11243 fix won't take effect on mobile.

Co-authored-by: Cursor <cursoragent@cursor.com>
@socket-security

socket-security Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

@socket-security

socket-security Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Warning

MetaMask internal reviewing guidelines:

  • Do not ignore-all
  • Each alert has instructions on how to review if you don't know what it means. If lost, ask your Security Liaison or the supply-chain group
  • Copy-paste ignore lines for specific packages or a group of one kind with a note on what research you did to deem it safe.
    @SocketSecurity ignore npm/PACKAGE@VERSION
Priority Alert  (click "▶" to expand/collapse) Action
Low priority
Potential code anomaly (AI signal): npm @metamask/transaction-pay-controller is 96.0% likely to have a medium risk anomaly

Notes: This code implements a server-quote transaction flow and is not clearly malware. It signs quote-provided typed data and sends signatures to a quote-provided endpoint, and submits quote-derived transactions with requireApproval:false; a malicious or compromised quote source could therefore cause unauthorized signing or transaction submission. No fixed domain, URL, IP, credential target, or environment-variable access is present in the fragment. Severity is medium to high depending on validation and trust controls outside this file.

Confidence: 0.96

Severity: 0.63

From: package.json → npm/@metamask/transaction-pay-controller@30.3.3

ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly?

Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev.

Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding.

Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@metamask/transaction-pay-controller@30.3.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

Warn

View full report

Co-authored-by: Cursor <cursoragent@cursor.com>
@roz0n

roz0n commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

@amitabh94 addressed both reinstall comments in fa47ee2 (with the Core bumps in e419494):

  • a reattached kycStatus: pending session with completed disclaimers and no local provider-flow marker now routes to kycPending instead of reopening SumSub
  • the existing providerFlowStatus: abandoned path still reopens verification, so an in-session abandonment remains resumable
  • added both funnel-level and resolveVbaOnboarding reinstall regressions
  • added vbaCustomerAbilities: null to the initial background-state fixture

The two focused suites pass (63 tests), the Engine fixture assertion passed, and TypeScript passes.

@roz0n
roz0n marked this pull request as ready for review November 3, 2026 14:37
@roz0n
roz0n requested a review from georgeweiler November 3, 2026 14:37
@roz0n
roz0n disabled stacked auto-merge November 3, 2026 21:24
@roz0n
roz0n added this pull request to stack #38808 November 3, 2026 21:24
@roz0n
roz0n enabled stacked auto-merge November 3, 2026 21:25

@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.

Stale Bugbot comment from a previous run.

… round trip

An approved account with a usable autoramp already has local account
state. The CTA was awaiting resolveVbaOnboarding before navigating,
which stutters and flashes a button spinner even though the details
load instantly from the View Account Details action elsewhere on Money
home. Route this case through openVbaEntry's fast path instead, which
opens details immediately and hydrates in the background.

Co-authored-by: Cursor <cursoragent@cursor.com>

@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.

Stale Bugbot comment from a previous run.

…ramp

account_is_ready also covers provider-final KYC before an autoramp exists.
openVbaEntry only skips the loader for an Approved autoramp, so that tap
was presenting the standalone loading screen and a second tap could mount
it again. Use the persisted-details check, and leave the reentry guard set.

Co-authored-by: Cursor <cursoragent@cursor.com>

@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 using default effort 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 890d841. Configure here.

The persisted-details tap left the reentry guard set, so the CTA stayed dead after returning to Money.

Co-authored-by: Cursor <cursoragent@cursor.com>
Matt561
Matt561 previously approved these changes Nov 3, 2026
A throw while starting the journey was dropping the Mixpanel click.

Co-authored-by: Cursor <cursoragent@cursor.com>
georgeweiler
georgeweiler previously approved these changes Nov 3, 2026
@roz0n
roz0n dismissed stale reviews from georgeweiler and Matt561 via 02c055c November 3, 2026 22:44
@sonarqubecloud

sonarqubecloud Bot commented Nov 3, 2026

Copy link
Copy Markdown

@roz0n
roz0n requested review from Matt561 and georgeweiler November 3, 2026 23:36
Comment thread app/core/Engine/types.ts

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.

Why do we need this change?

@Cal-L Cal-L 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.

LGTM

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>
Naz-Ovh pushed a commit to 0x-fork/metamask-core that referenced this pull request Nov 4, 2026
## Explanation

Releases:
- `@metamask/ramps-controller` @ `29.0.0`
- `@metamask/transaction-pay-controller` @ `30.3.3`

This release includes the VBA KYC final-status fix from MetaMask#11243 and
customer rail abilities from MetaMask#11225. The major bump reflects the new
required `NeoBankService:getCustomerAbilities` messenger action.

## References

- MetaMask#11243
- MetaMask#11225
- Consumer update: MetaMask/metamask-mobile#38688

## 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
- [x] I’ve introduced breaking changes in this PR and have prepared a
draft pull request for clients and consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> The diff is low-risk versioning, but it publishes ramps-controller
29.0.0 with a breaking messenger delegation requirement that downstream
clients must adopt before upgrading.
> 
> **Overview**
> This PR **cuts release 1381.0.0** by bumping versions and lockfile
entries only—no application source changes in the diff.
> 
> **`@metamask/ramps-controller`** goes **28.1.0 → 29.0.0** (major). The
changelog section for **29.0.0** is finalized from `[Unreleased]`,
documenting what ships with this tag: customer rail abilities
APIs/state, deposit-rail readiness helpers, a **breaking** requirement
to delegate **`NeoBankService:getCustomerAbilities`**, plus VBA KYC
**`finalStatus`** and microdeposits session-profile fixes from earlier
PRs.
> 
> **`@metamask/transaction-pay-controller`** is patched to **30.3.3**
with **`@metamask/ramps-controller` ^29.0.0** and a matching changelog
entry. Root **`package.json`** moves to **1381.0.0**; **`yarn.lock`**
reflects the ramps-controller resolution bump.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
1272c95. 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>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@roz0n
roz0n added this pull request to the merge queue Nov 4, 2026
Merged via the queue into main with commit 66b390e Nov 4, 2026
133 of 134 checks passed
@roz0n
roz0n deleted the fix/TRAM-4392-moonpay-limbo branch November 4, 2026 14:45
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 4, 2026
@metamask-ci metamask-ci Bot added the release-8.20.0 Issue or pull request that will be included in release 8.20.0 label Nov 4, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants