feat: Add support for listing saved payment methods in module and Stripe (#10994)

packages/core/types/src/payment/common.ts

@@ -1,6 +1,7 @@
 import { BaseFilterable } from "../dal"
 import { OperatorMap } from "../dal/utils"
 import { BigNumberValue } from "../totals"
+import { PaymentProviderContext } from "./provider"
 /* ********** PAYMENT COLLECTION ********** */
 
 export type PaymentCollectionStatus =
@@ -245,6 +246,22 @@ export interface FilterableRefundProps extends BaseFilterable<RefundDTO> {
    */
   deleted_at?: OperatorMap<string>
 }
+
+/**
+ * The filters to apply on the retrieved payment sessions.
+ */
+export interface FilterablePaymentMethodProps {
+  /**
+   * Filter the payment methods by provider.
+   */
+  provider_id: string
+
+  /**
+   * Filter the payment methods by the context of their associated payment provider.
+   */
+  context: PaymentProviderContext
+}
+
 /* ********** PAYMENT ********** */
 export interface PaymentDTO {
   /**
@@ -568,6 +585,18 @@ export interface PaymentProviderDTO {
   is_enabled: boolean
 }
 
+export interface PaymentMethodDTO {
+  /**
+   * The ID of the payment method in the payment provider's system.
+   */
+  id: string
+
+  /**
+   * The data of the payment method, as returned by the payment provider.
+   */
+  data: Record<string, unknown>
+}
+
 /**
  * The filters to apply on the retrieved payment providers.
  */

packages/core/types/src/payment/provider.ts

@@ -135,6 +135,11 @@ export type PaymentProviderAuthorizeResponse = {
   data: PaymentProviderSessionResponse["data"]
 }
 
+export type PaymentMethodResponse = {
+  id: string
+  data: Record<string, unknown>
+}
+
 /**
  * @interface
  *
@@ -249,6 +254,10 @@ export interface IPaymentProvider {
     paymentSessionData: Record<string, unknown>
   ): Promise<PaymentProviderError | PaymentProviderSessionResponse["data"]>
 
+  listPaymentMethods(
+    context: PaymentProviderContext
+  ): Promise<PaymentMethodResponse[]>
+
   getPaymentStatus(
     paymentSessionData: Record<string, unknown>
   ): Promise<PaymentSessionStatus>

packages/core/utils/src/payment/abstract-payment-provider.ts

@@ -1,6 +1,8 @@
 import {
   CreatePaymentProviderSession,
   IPaymentProvider,
+  PaymentMethodResponse,
+  PaymentProviderContext,
   PaymentProviderError,
   PaymentProviderSessionResponse,
   PaymentSessionStatus,
@@ -623,6 +625,59 @@ export abstract class AbstractPaymentProvider<TConfig = Record<string, unknown>>
     context: UpdatePaymentProviderSession
   ): Promise<PaymentProviderError | PaymentProviderSessionResponse>
 
+  /**
+   * List the payment methods associated with the context (eg. customer) of the payment provider, if any.
+   *
+   * @param context - The context for which the payment methods are listed. Usually the customer should be provided.
+   * @returns An object whose `payment_methods` property is set to the data returned by the payment provider.
+   *
+   * @example
+   * // other imports...
+   * import {
+   *   PaymentProviderContext,
+   *   PaymentProviderError,
+   *   PaymentMethodResponse
+   *   PaymentProviderSessionResponse,
+   * } from "@medusajs/framework/types"
+   *
+   *
+   * class MyPaymentProviderService extends AbstractPaymentProvider<
+   *   Options
+   * > {
+   *   async listPaymentMethods(
+   *     context: PaymentProviderContext
+   *   ): Promise<PaymentMethodResponse> {
+   *     const {
+   *       customer,
+   *     } = context
+   *     const externalCustomerId = customer.metadata.stripe_id
+   *
+   *     try {
+   *       // assuming you have a client that updates the payment
+   *       const response = await this.client.listPaymentMethods(
+   *         {customer: externalCustomerId}
+   *       )
+   *
+   *       return response.map((method) => ({
+   *         id: method.id,
+   *         data: method
+   *       }))
+   *     } catch (e) {
+   *       return {
+   *         error: e,
+   *         code: "unknown",
+   *         detail: e
+   *       }
+   *     }
+   *   }
+   *
+   *   // ...
+   * }
+   */
+  abstract listPaymentMethods(
+    context: PaymentProviderContext
+  ): Promise<PaymentMethodResponse[]>
+
   /**
    * This method is executed when a webhook event is received from the third-party payment provider. Use it
    * to process the action of the payment provider.