feat: add getPaymentMethodsForContext to ramps-controller

packages/ramps-controller/CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `getPaymentMethodsForContext(options)` and `RampsController:getPaymentMethodsForContext` messenger action for context-scoped payment-method retrieval aligned with `getQuotes` provider resolution ([#9801](https://github.com/MetaMask/core/pull/9801))
+  - Supports explicit `providers`, selected-provider (UB2) context, and headless auto-select / restrict paths, including `moneyHeadlessAllProviders` widening with allowlist pick-survivor intersection.
+  - Request-only by default (`updateState` unset/false): does not mutate Buy `paymentMethods.data` / `.selected`.
+  - Fans out per contributing provider, dedupes by canonical payment id, and merges collision metadata (conservative delay, best score, deterministic name/icon).
+  - Partial provider failures still return methods from successful fetches.
 - Export `TERMINAL_ORDER_STATUSES` and `isTerminalOrderStatus()` so consuming clients can share the controller's terminal order status set instead of maintaining duplicate copies. ([#9679](https://github.com/MetaMask/core/pull/9679))
 
 ## [20.0.0]

packages/ramps-controller/src/RampsController-method-action-types.ts

@@ -207,6 +207,48 @@ export type RampsControllerGetPaymentMethodsAction = {
   handler: RampsController['getPaymentMethods'];
 };
 
+/**
+ * Fetches payment methods for a quoting context without coupling callers to
+ * the Buy flow's globally selected provider/token catalog.
+ *
+ * Provider contribution mirrors {@link getQuotes}:
+ * - explicit `providers` (optionally filtered when
+ * `restrictToKnownOrNativeProviders` is set)
+ * - auto-select / restrict path, including `moneyHeadlessAllProviders`
+ * widening: flag off uses the restricted/native resolver; flag on uses
+ * supporting providers, intersected with the flag allowlist when that
+ * allowlist is non-empty (pick-survivor set for picker methods)
+ * - when those resolution flags and `providers` are omitted, uses only
+ * `providers.selected` (UB2 selected-provider context)
+ *
+ * By default this is request-only: it does **not** mutate
+ * `paymentMethods.data` or `paymentMethods.selected`. Pass `updateState:
+ * true` only when the caller explicitly wants Buy-catalog write semantics
+ * (UB2). Headless / MM Pay selection stays TPC-owned.
+ *
+ * Methods are request-eligible for the resolved provider set; they are not
+ * guaranteed to produce a quote for every amount (provider fiat limits still
+ * apply at quote time).
+ *
+ * @param options - Context for the payment-method fetch.
+ * @param options.region - Region code. Defaults to `userRegion`.
+ * @param options.assetId - Required CAIP-19 quoting asset.
+ * @param options.providers - Explicit provider ids.
+ * @param options.autoSelectProvider - Resolve providers like `getQuotes`.
+ * @param options.preferredProviderIds - Preferred ids for auto-selection.
+ * @param options.restrictToKnownOrNativeProviders - Headless gating.
+ * @param options.updateState - When true, write `paymentMethods` state.
+ * @param options.preferPaymentMethodId - Preserve this id when still present.
+ * @param options.forceRefresh - Bypass request cache for provider fetches.
+ * @param options.ttl - Custom TTL for provider payment-method fetches.
+ * @returns Deduped methods, a request-only suggested selection, and the
+ * provider ids that contributed.
+ */
+export type RampsControllerGetPaymentMethodsForContextAction = {
+  type: `RampsController:getPaymentMethodsForContext`;
+  handler: RampsController['getPaymentMethodsForContext'];
+};
+
 /**
  * Sets the user's selected payment method.
  *
@@ -685,6 +727,7 @@ export type RampsControllerMethodActions =
   | RampsControllerSetSelectedTokenAction
   | RampsControllerGetProvidersAction
   | RampsControllerGetPaymentMethodsAction
+  | RampsControllerGetPaymentMethodsForContextAction
   | RampsControllerSetSelectedPaymentMethodAction
   | RampsControllerGetQuotesAction
   | RampsControllerAddOrderAction