Skip to content

feat(ramps-controller): add customer rail abilities - #11225

Merged
meltingice1337 merged 5 commits into
mainfrom
feat/TRAM-4364-neobank-customer-abilities
Nov 2, 2026
Merged

meltingice1337 merged 5 commits into
mainfrom
feat/TRAM-4364-neobank-customer-abilities

Conversation

@meltingice1337

@meltingice1337 meltingice1337 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

MoonPay rejects an autoramp create with a 422 (Customer is unable to complete the action. Consult the customer abilities API) when the deposit rail it needs is not Active, even when the customer itself is Active. UAT users hit this on USD and land on an error screen. Clients have no way to check the rail before creating, so this adds the customer's rail abilities to @metamask/ramps-controller.

RampsController.refreshCustomerAbilities()
  NeoBankService:getCustomerAbilities
    #resolveCustomerId()                     // shared with getMicrodeposits
    GET /neobank/customers/{id}/abilities    // MoonPay GET /api/customers/{id}/abilities, returned unmodified
  state.vbaCustomerAbilities = abilities     // not persisted

getMusdAutorampDepositRailReadiness(abilities, fiat)
  BRL needs pix + pix_thirdparty
  USD needs ach + ach_thirdparty
  any required rail Unavailable or Blocked     -> 'blocked'
  every required rail Active                   -> 'active'
  otherwise (Pending, Maintenance, missing)    -> 'pending'
  fiat with no required rails                  -> 'active'

Details that may not be obvious:

  • The _thirdparty rail is required because neobank-proxy always sets source_is_third_party: true on the upstream create, whatever the client sends.
  • Unavailable maps to blocked because MoonPay only reports it when its rule-engine preflight has ruled the rail out (blocking_abilities carries the reason). Maintenance maps to pending since it is temporary.
  • The customer id lookup in getMicrodeposits moved into a private #resolveCustomerId() so both methods share one in-flight lookup. It is now keyed by session profile, so after a profile switch the customer is looked up again instead of reusing the first profile's id.
  • vbaCustomerAbilities is not persisted because a rail can change at any time. A failed refresh throws and keeps the stored value. Discarding a VBA session owned by another profile clears it.
  • Breaking: NeoBankService:getCustomerAbilities is added to RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS, so hosts need to delegate it to the RampsController messenger.

Open question: MoonPay still has to confirm which USD rails the create checks for a third-party autoramp. If it is not ach / ach_thirdparty, the rail map in autorampAccount.ts needs updating.

References

Screenshots/Recordings

Before

Clients had no way to read a customer's rail abilities, so a USD autoramp create with an inactive rail failed with MoonPay's 422 and the user landed on an error screen.

After

ScreenRecording_11-02-2026.15-47-54_1.compressed.mp4

New tests in this PR, all passing (package suite 1127/1127, CI green):

NeoBankService.getCustomerAbilities

  • returns the abilities unchanged
  • throws an HttpError when the customer lookup 404s, and carries the upstream body on a 5xx
  • throws on a malformed body (an array, no fiat_deposit, a null fiat_deposit)
  • shares the customer id lookup with getMicrodeposits
  • looks the customer up again after the session profile changes
  • keeps the new profile's lookup when the old profile's lookup fails late

RampsController.refreshCustomerAbilities

  • stores and returns the abilities from NeoBankService
  • keeps the stored abilities when the fetch fails
  • discarding a VBA session owned by another profile clears them

getMusdAutorampDepositRailReadiness

  • active when every BRL (pix, pix_thirdparty) or USD (ach, ach_thirdparty) rail is Active
  • pending when a rail is Pending, Maintenance or missing, or the fiat is missing from the abilities
  • blocked when a rail is Unavailable or Blocked, even if another is pending
  • active for a fiat with no required rails

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

Note

Medium Risk
Breaking messenger delegation requirement for hosts, plus profile-scoped customer lookup changes that affect microdeposits and abilities; logic gates money/autoramp flows but does not alter payment auth.

Overview
Adds MoonPay customer rail abilities to @metamask/ramps-controller so clients can check deposit rails before creating a fiat → mUSD autoramp (avoiding MoonPay 422s when a rail is not Active).

NeoBankService gains getCustomerAbilities (proxy GET …/abilities) plus exported ability types. Customer id resolution moves into #resolveCustomerId(), keyed by session profile and shared with getMicrodeposits—fixing stale customer ids after profile switch.

RampsController adds refreshCustomerAbilities, non-persisted vbaCustomerAbilities, and clears that state when a foreign VBA session is discarded. getMusdAutorampDepositRailReadiness maps abilities to active / pending / blocked for BRL (pix rails) and USD (ach rails).

Breaking: RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS now requires NeoBankService:getCustomerAbilities delegation to RampsController.

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

Add NeoBankService.getCustomerAbilities, RampsController.refreshCustomerAbilities
with a non-persisted vbaCustomerAbilities state, and
getMusdAutorampDepositRailReadiness, so clients can check the deposit rail
before creating a fiat to mUSD autoramp. MoonPay rejects the create with a 422
when the rail it needs is not Active.
@meltingice1337
meltingice1337 requested review from a team as code owners November 2, 2026 10:08

@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 567f24c. Configure here.

…Pay spec

currencies was unknown[], which is not Json, so RampsControllerState no longer satisfied StateConstraint.
georgeweiler
georgeweiler previously approved these changes Nov 2, 2026
…profile

The customer id was cached for the life of NeoBankService, so after a profile switch getCustomerAbilities and getMicrodeposits kept using the first profile's customer.
…king

Moves the RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS change to a BREAKING entry under Changed and notes that customer lookups go through AuthenticationController:getSessionProfile.
@meltingice1337

Copy link
Copy Markdown
Contributor Author

@metamaskbot publish-previews

@meltingice1337
meltingice1337 added this pull request to the merge queue Nov 2, 2026
Merged via the queue into main with commit 703e99a Nov 2, 2026
48 checks passed
@meltingice1337
meltingice1337 deleted the feat/TRAM-4364-neobank-customer-abilities branch November 2, 2026 14:59
@roz0n roz0n mentioned this pull request Nov 2, 2026
4 tasks done
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>
Naz-Ovh pushed a commit to 0x-fork/metamask-core that referenced this pull request Nov 4, 2026
…eased (MetaMask#11257)

## Explanation

MetaMask#10882 (migrate `NeoBankService` to `BaseDataService`) merged right
after Release 1381.0.0 (MetaMask#11248), which had already cut
`@metamask/ramps-controller` 29.0.0. Because of how the changelog
merged, the MetaMask#10882 entries ended up in the released `[29.0.0]` section,
while `[Unreleased]` was left empty.

## References

- Follow-up to MetaMask#10882
- Related to MetaMask#11248

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only changelog reorganization with no runtime or API
changes.
> 
> **Overview**
> Corrects a **Keep a Changelog** mix-up in
`packages/ramps-controller/CHANGELOG.md` after Release 1381.0.0 cut
`29.0.0` while MetaMask#10882 merged: **NeoBankService → `BaseDataService`**
notes (MetaMask#10882) were listed under **`[29.0.0]`** even though they had not
shipped yet.
> 
> This PR **moves** those MetaMask#10882 bullets (Added / Changed / Removed,
including breaking `NeoBankService` and
`RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS` items that belonged to that
work) back into **`[Unreleased]`**, and **leaves `[29.0.0]`** with only
what actually released there (MetaMask#11225 customer abilities /
`refreshCustomerAbilities` / deposit rail readiness, MetaMask#11243 KYC
`finalStatus`, and related fixes). **Wording is unchanged**—only section
placement.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
a2e1a1a. 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: Salah-Eddine Saakoun <salah-eddinesaakoun@Salah-Eddines-MacBook-Pro-2.local>
weitingsun pushed a commit to Poovarasan-Sandhanam/metamask-mobile that referenced this pull request Nov 6, 2026
…mp (MetaMask#38651)

<!--
Please submit this PR as a draft initially.

Do not mark it as "Ready for review" until this PR meets the canonical
Definition of Ready For Review in `docs/readme/ready-for-review.md`.

In short: the template must be materially complete (not just section
titles
present), all status checks must be currently passing, and the only
expected
follow-up commits must be reviewer-driven.
-->
<!--
mms-check directive vocabulary — read by
.github/scripts/shared/pr-template-checks.ts
at module load to build the validation plan. Directives are invisible in
rendered
markdown and must NOT be removed or edited without updating the
validator registry.

  type=text           Section must contain non-placeholder prose.
  type=changelog      Section must have a valid CHANGELOG entry: line.
type=issue-link Section must have a Fixes:/Closes:/Refs: line with a
value.
type=manual-testing Section must have real testing steps or an explicit
N/A.
type=screenshot Section must have evidence (image/URL) or an explicit
N/A.
type=checklist Section must have all checkboxes consciously checked.
required=true|false Whether a missing/invalid section runs the validator
at all.
blocking=true|false Whether a failure of this check fails the CI
workflow.
Default: false — failures are shown as warnings in the sticky
                      comment but do not block the PR.

Sections without a directive are checked for structural presence only.
-->

## **Description**

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

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

MoonPay rejects an autoramp create with a 422 ("Customer is unable to
complete the action. Consult the customer abilities API") when the
customer is Active but the deposit rail the autoramp needs is not. Today
that sends the user to the account-create error screen with "Contact
support", even though the rail usually turns Active on its own shortly
after.

`ensureMusdAutoramp` now reads the customer's rail abilities
(`RampsController.refreshCustomerAbilities` and
`getMusdAutorampDepositRailReadiness` from MetaMask/core#11225) right
before it creates the autoramp, both for the first fiat and for an
additional fiat:

- `active`: creates the autoramp as before.
- `pending`: returns `awaiting_provider`, so VbaDetails keeps the
existing "Waiting for MoonPay to approve your account" screen and
re-checks on its poll. The autoramp is created once the rail turns
Active.
- `blocked`: throws the same account-create error a MoonPay 422
produces, without sending the create.
- Abilities fetch fails: logs the error and creates as before, so a
proxy or MoonPay outage never blocks onboarding.

The NeoBankService messenger now also delegates
`AuthenticationController:getSessionProfile`. NeoBankService needs it to
resolve the MoonPay customer id for the abilities URL. Without it the
abilities call throws inside the app and the check silently falls back
to creating.

**Blocked by MetaMask/core#11225.** `@metamask/ramps-controller` points
at the preview build
`@metamask-previews/ramps-controller@28.1.0-preview-acf55e6fd` until
core releases the change. That release is a major (29.0.0) because
`RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS` gains
`NeoBankService:getCustomerAbilities`, which mobile already picks up by
spreading the constant. This PR stays a draft until the dependency is
switched to `^29.0.0`.

Tested on an iOS device against dev with a local neobank-proxy and a
temporary stub for the abilities response (fresh SRP, Brazil KYC): with
the rail Pending the app polled for about 1.5 minutes and never sent a
create; with Pending twice, then Active, it created the BRL autoramp on
the next poll.

## **Changelog**

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

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: Fixed Money Account bank account setup showing an error
while MoonPay was still enabling the deposit method; the app now waits
and finishes setup once it is ready

## **Related issues**

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

Fixes: https://consensyssoftware.atlassian.net/browse/TRAM-4391

Refs: https://consensyssoftware.atlassian.net/browse/TRAM-4364,
MetaMask/core#11225

## **Manual testing steps**

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

```gherkin
Feature: Wait for the deposit rail before creating the virtual bank account

  Scenario: deposit rail is still pending
    Given a user with approved KYC and an Active MoonPay customer
    And the deposit rail for their fiat is Pending in the customer abilities
    When the user opens bank transfer from Money and reaches account creation
    Then the screen shows "Waiting for MoonPay to approve your account"
    And no autoramp create request is sent while the rail stays Pending

  Scenario: deposit rail turns active while the user waits
    Given the user is on "Waiting for MoonPay to approve your account" because the rail is Pending
    When the deposit rail becomes Active
    Then the autoramp is created on the next poll
    And the bank account details are shown

  Scenario: deposit rail is blocked
    Given the deposit rail for the user's fiat is Unavailable or Blocked
    When the user reaches account creation
    Then the account-create error screen is shown
    And no autoramp create request is sent
```

## **Screenshots/Recordings**

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

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

N/A

### **After**


https://github.com/user-attachments/assets/aafe6288-8b29-4a03-817b-906d45678868


## **Pre-merge author checklist**

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

<!--
Every checklist item must be consciously assessed before marking this PR
as
"Ready for review". A checked box means you deliberately considered that
responsibility, not that you literally performed every action listed.

Unchecked boxes are ambiguous: they are not an implicit "N/A" and they
are not
a silent "skip". See `docs/readme/ready-for-review.md` for the full
checklist
semantics.
-->

- [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**

<!--
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 Money VBA autoramp creation timing and external abilities API
usage; fail-open on fetch errors could still allow a 422 from MoonPay if
abilities are wrong.
> 
> **Overview**
> **`ensureMusdAutoramp`** no longer calls create as soon as KYC/hydrate
says ready. It **refreshes customer abilities**
(`RampsController.refreshCustomerAbilities`) and uses
**`getMusdAutorampDepositRailReadiness`** from
`@metamask/ramps-controller` **29** before every create (first fiat and
additional fiat).
> 
> **Pending** rails return **`awaiting_provider`** so **`VbaDetails`**
keeps the existing “waiting for MoonPay” poll **without** hitting create
(avoids MoonPay **422** when the customer is Active but the deposit
method is not). **Blocked** rails fail like a **422** with analytics,
**without** sending create. If abilities refresh **fails**, behavior
**fails open** (log + create as before).
> 
> Tests add rail-readiness coverage and mock
**`refreshCustomerAbilities`** in **`VbaDetails`** /
**`ensureMusdAutoramp`** tests; test **`initial-background-state`** adds
**`vbaCustomerAbilities`**.
> 
> Dependency bump: **`@metamask/ramps-controller`** **^28 → ^29**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
138a36f. 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: Darius Costolas <10818970+meltingice1337@users.noreply.github.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.

3 participants