feat: Add support to update account holder (#11499)

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

@@ -1,6 +1,10 @@
 import { BigNumberInput } from "../totals"
 import { PaymentCollectionStatus } from "./common"
-import { PaymentCustomerDTO, PaymentProviderContext } from "./provider"
+import {
+  PaymentAccountHolderDTO,
+  PaymentCustomerDTO,
+  PaymentProviderContext,
+} from "./provider"
 
 /**
  * The payment collection to be created.
@@ -275,6 +279,33 @@ export interface CreateAccountHolderDTO {
   }
 }
 
+export interface UpdateAccountHolderDTO {
+  /**
+   * The ID of the account holder.
+   */
+  id: string
+
+  /**
+   * The provider's ID.
+   */
+  provider_id: string
+
+  /**
+   * Necessary context data for the associated payment provider.
+   */
+  context: PaymentProviderContext & {
+    /**
+     * The account holder information from Medusa.
+     */
+    account_holder: PaymentAccountHolderDTO
+  }
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
+  metadata?: Record<string, unknown>
+}
+
 /**
  * The details of the webhook event payload.
  */

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

@@ -193,6 +193,18 @@ export type CreateAccountHolderInput = PaymentProviderInput & {
   }
 }
 
+export type UpdateAccountHolderInput = PaymentProviderInput & {
+  /**
+   * The context of creating the account holder.
+   */
+  context: PaymentProviderContext & {
+    /**
+     * The account holder's details.
+     */
+    account_holder: PaymentAccountHolderDTO
+  }
+}
+
 /**
  * @interface
  *
@@ -323,6 +335,8 @@ export type CreateAccountHolderOutput = PaymentProviderOutput & {
   id: string
 }
 
+export type UpdateAccountHolderOutput = PaymentProviderOutput
+
 export type DeleteAccountHolderOutput = PaymentProviderOutput
 
 export type ListPaymentMethodsOutput = (PaymentProviderOutput & {
@@ -466,6 +480,50 @@ export interface IPaymentProvider {
     data: CreateAccountHolderInput
   ): Promise<CreateAccountHolderOutput>
 
+  /**
+   * This method is used when updating an account holder in Medusa, allowing you to update
+   * the equivalent account in the third-party service.
+   *
+   * The returned data will be stored in the account holder created in Medusa. For example,
+   * the returned `id` property will be stored in the account holder's `external_id` property.
+   *
+   * @param data - Input data including the details of the account holder to update.
+   * @returns The result of updating the account holder. If an error occurs, throw it.
+   *
+   * @version 2.6.0
+   *
+   * @example
+   * import { MedusaError } from "@medusajs/framework/utils"
+   *
+   * class MyPaymentProviderService extends AbstractPaymentProvider<
+   *  Options
+   * > {
+   *  async updateAccountHolder({ context, data }: UpdateAccountHolderInput) {
+   *   const { account_holder, customer } = context
+   *
+   *   if (!account_holder?.data?.id) {
+   *     throw new MedusaError(
+   *       MedusaError.Types.INVALID_DATA,
+   *       "Missing account holder ID."
+   *     )
+   *   }
+   *
+   *   // assuming you have a client that updates the account holder
+   *   const providerAccountHolder = await this.client.updateAccountHolder({
+   *     id: account_holder.data.id,
+   *    ...data
+   *   })
+   *
+   *   return {
+   *     id: providerAccountHolder.id,
+   *     data: providerAccountHolder as unknown as Record<string, unknown>
+   *   }
+   * }
+   */
+  updateAccountHolder?(
+    data: UpdateAccountHolderInput
+  ): Promise<UpdateAccountHolderOutput>
+
   /**
    * This method is used when an account holder is deleted in Medusa, allowing you
    * to also delete the equivalent account holder in the third-party service.

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

@@ -35,6 +35,7 @@ import {
   CreateAccountHolderDTO,
   UpsertPaymentCollectionDTO,
   CreatePaymentMethodDTO,
+  UpdateAccountHolderDTO,
 } from "./mutations"
 import { WebhookActionResult } from "./provider"
 
@@ -788,6 +789,37 @@ export interface IPaymentModuleService extends IModuleService {
     sharedContext?: Context
   ): Promise<AccountHolderDTO>
 
+  /**
+   * This method updates(if supported by provider) the account holder in the payment provider.
+   *
+   * @param {UpdateAccountHolderDTO} data - The details of the account holder.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<Record<string, unknown>>} The account holder's details in the payment provider, typically just the ID.
+   *
+   * @example
+   * const accountHolder =
+   *   await paymentModuleService.updateAccountHolder(
+   *     {
+   *       provider_id: "stripe",
+   *       context: {
+   *         account_holder: {
+   *           data: {
+   *             id: "acc_holder_123",
+   *           },
+   *         },
+   *         customer: {
+   *           id: "cus_123",
+   *           company_name: "new_name",
+   *         },
+   *       },
+   *     }
+   *   )
+   */
+  updateAccountHolder(
+    input: UpdateAccountHolderDTO,
+    sharedContext?: Context
+  ): Promise<AccountHolderDTO>
+
   /**
    * This method deletes the account holder in the payment provider.
    *