feat(ramps-controller): add unified getOrder to RampsService

packages/ramps-controller/src/RampsController.ts

@@ -20,6 +20,7 @@ import type {
   Quote,
   RampsToken,
   RampsServiceActions,
+  RampsOrder,
 } from './RampsService';
 import type {
   RampsServiceGetGeolocationAction,
@@ -29,6 +30,7 @@ import type {
   RampsServiceGetPaymentMethodsAction,
   RampsServiceGetQuotesAction,
   RampsServiceGetBuyWidgetUrlAction,
+  RampsServiceGetOrderAction,
 } from './RampsService-method-action-types';
 import type {
   RequestCache as RequestCacheType,
@@ -71,6 +73,7 @@ export const RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS: readonly RampsServiceAct
     'RampsService:getPaymentMethods',
     'RampsService:getQuotes',
     'RampsService:getBuyWidgetUrl',
+    'RampsService:getOrder',
   ];
 
 /**
@@ -337,7 +340,8 @@ type AllowedActions =
   | RampsServiceGetProvidersAction
   | RampsServiceGetPaymentMethodsAction
   | RampsServiceGetQuotesAction
-  | RampsServiceGetBuyWidgetUrlAction;
+  | RampsServiceGetBuyWidgetUrlAction
+  | RampsServiceGetOrderAction;
 
 /**
  * Published when the state of {@link RampsController} changes.
@@ -1638,4 +1642,26 @@ export class RampsController extends BaseController<
       return null;
     }
   }
+
+  /**
+   * Fetches an order from the unified V2 API endpoint.
+   * Returns a normalized RampsOrder for all provider types (aggregator and native).
+   *
+   * @param providerCode - The provider code (e.g., "transak", "transak-native", "moonpay").
+   * @param orderCode - The order identifier.
+   * @param wallet - The wallet address associated with the order.
+   * @returns The unified order data.
+   */
+  async getOrder(
+    providerCode: string,
+    orderCode: string,
+    wallet: string,
+  ): Promise<RampsOrder> {
+    return await this.messenger.call(
+      'RampsService:getOrder',
+      providerCode,
+      orderCode,
+      wallet,
+    );
+  }
 }

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

@@ -109,6 +109,20 @@ export type RampsServiceGetBuyWidgetUrlAction = {
   handler: RampsService['getBuyWidgetUrl'];
 };
 
+/**
+ * Fetches an order from the unified V2 API endpoint.
+ * Returns a normalized RampsOrder for all provider types.
+ *
+ * @param providerCode - The provider code (e.g., "transak", "transak-native", "moonpay").
+ * @param orderCode - The order identifier.
+ * @param wallet - The wallet address associated with the order.
+ * @returns The unified order data.
+ */
+export type RampsServiceGetOrderAction = {
+  type: `RampsService:getOrder`;
+  handler: RampsService['getOrder'];
+};
+
 /**
  * Union of all RampsService action types.
  */
@@ -119,4 +133,5 @@ export type RampsServiceMethodActions =
   | RampsServiceGetProvidersAction
   | RampsServiceGetPaymentMethodsAction
   | RampsServiceGetQuotesAction
-  | RampsServiceGetBuyWidgetUrlAction;
+  | RampsServiceGetBuyWidgetUrlAction
+  | RampsServiceGetOrderAction;

packages/ramps-controller/src/RampsService.ts

@@ -482,6 +482,92 @@ export type TokensResponse = {
   allTokens: RampsToken[];
 };
 
+// === ORDER TYPES ===
+
+/**
+ * Possible statuses for a ramps order.
+ */
+export enum RampsOrderStatus {
+  Unknown = 'UNKNOWN',
+  Precreated = 'PRECREATED',
+  Created = 'CREATED',
+  Pending = 'PENDING',
+  Failed = 'FAILED',
+  Completed = 'COMPLETED',
+  Cancelled = 'CANCELLED',
+  IdExpired = 'ID_EXPIRED',
+}
+
+/**
+ * Network information associated with an order.
+ */
+export type RampsOrderNetwork = {
+  name: string;
+  chainId: string;
+};
+
+/**
+ * Crypto currency information associated with an order.
+ */
+export type RampsOrderCryptoCurrency = {
+  assetId?: string;
+  name?: string;
+  chainId?: string;
+  decimals?: number;
+  iconUrl?: string;
+  symbol: string;
+};
+
+/**
+ * Payment method information associated with an order.
+ */
+export type RampsOrderPaymentMethod = {
+  id: string;
+  name?: string;
+  shortName?: string;
+  duration?: string;
+  icon?: string;
+  isManualBankTransfer?: boolean;
+};
+
+/**
+ * A unified order type returned from the V2 API.
+ * The V2 endpoint normalizes all provider responses into this shape.
+ */
+export type RampsOrder = {
+  id?: string;
+  isOnlyLink: boolean;
+  provider?: string;
+  success: boolean;
+  cryptoAmount: string | number;
+  fiatAmount: number;
+  cryptoCurrency?: string | RampsOrderCryptoCurrency;
+  fiatCurrency?: string;
+  providerOrderId: string;
+  providerOrderLink: string;
+  createdAt: number;
+  paymentMethod?: string | RampsOrderPaymentMethod;
+  totalFeesFiat: number;
+  txHash: string;
+  walletAddress: string;
+  status: RampsOrderStatus;
+  network: string | RampsOrderNetwork;
+  canBeUpdated: boolean;
+  idHasExpired: boolean;
+  idExpirationDate?: number;
+  excludeFromPurchases: boolean;
+  timeDescriptionPending: string;
+  fiatAmountInUsd?: number;
+  feesInUsd?: number;
+  region?: string;
+  orderType: string;
+  exchangeRate?: number;
+  pollingSecondsMinimum?: number;
+  statusDescription?: string;
+  partnerFees?: number;
+  networkFees?: number;
+};
+
 /**
  * The SDK version to send with API requests. (backwards-compatibility)
  */
@@ -529,6 +615,7 @@ const MESSENGER_EXPOSED_METHODS = [
   'getPaymentMethods',
   'getQuotes',
   'getBuyWidgetUrl',
+  'getOrder',
 ] as const;
 
 /**
@@ -1190,4 +1277,44 @@ export class RampsService {
 
     return response;
   }
+
+  /**
+   * Fetches an order from the unified V2 API endpoint.
+   * This endpoint returns a normalized `RampsOrder` (DepositOrder shape)
+   * for all provider types, including both aggregator and native providers.
+   *
+   * @param providerCode - The provider code (e.g., "transak", "transak-native", "moonpay").
+   * @param orderCode - The order identifier.
+   * @param wallet - The wallet address associated with the order.
+   * @returns The unified order data.
+   */
+  async getOrder(
+    providerCode: string,
+    orderCode: string,
+    wallet: string,
+  ): Promise<RampsOrder> {
+    const url = new URL(
+      getApiPath(`providers/${providerCode}/orders/${orderCode}`),
+      this.#getBaseUrl(RampsApiService.Orders),
+    );
+    this.#addCommonParams(url);
+    url.searchParams.set('wallet', wallet);
+
+    const response = await this.#policy.execute(async () => {
+      const fetchResponse = await this.#fetch(url);
+      if (!fetchResponse.ok) {
+        throw new HttpError(
+          fetchResponse.status,
+          `Fetching '${url.toString()}' failed with status '${fetchResponse.status}'`,
+        );
+      }
+      return fetchResponse.json() as Promise<RampsOrder>;
+    });
+
+    if (!response || typeof response !== 'object') {
+      throw new Error('Malformed response received from order API');
+    }
+
+    return response;
+  }
 }

packages/ramps-controller/src/index.ts

@@ -40,6 +40,11 @@ export type {
   RampsToken,
   TokensResponse,
   BuyWidget,
+  RampsOrder,
+  RampsOrderStatus,
+  RampsOrderNetwork,
+  RampsOrderCryptoCurrency,
+  RampsOrderPaymentMethod,
 } from './RampsService';
 export {
   RampsService,
@@ -53,6 +58,7 @@ export type {
   RampsServiceGetPaymentMethodsAction,
   RampsServiceGetQuotesAction,
   RampsServiceGetBuyWidgetUrlAction,
+  RampsServiceGetOrderAction,
 } from './RampsService-method-action-types';
 export type {
   RequestCache,