docs: document payment changes + account holder (#11242)

* docs: document payment changes + account holder * added version
2025-02-11 13:27:10 +02:00
parent 320d84d191
commit 615b6f107e
8 changed files with 259 additions and 3 deletions
@@ -0,0 +1,47 @@
+export const metadata = {
+  title: `Account Holders and Saved Payment Methods`,
+}
+
+# {metadata.title}
+
+In this documentation, you'll learn about account holders, and how they're used to save payment methods in third-party payment providers.
+
+<Note>
+
+Account holders are available starting from Medusa `v2.5.0`.
+
+</Note>
+
+## What's an Account Holder?
+
+An account holder represents a customer that can have saved payment methods in a third-party service. It's represented by the `AccountHolder` data model.
+
+It holds fields retrieved from the third-party provider, such as:
+
+- `external_id`: The ID of the equivalent customer or account holder in the third-party provider.
+- `data`: Data returned by the payment provider when the account holder is created.
+
+A payment provider that supports saving payment methods for customers would create the equivalent of an account holder in the third-party provider. Then, whenever a payment method is saved, it would be saved under the account holder in the third-party provider.
+
+---
+
+## Save Payment Methods
+
+If a payment provider supports saving payment methods for a customer, they must implement the following methods:
+
+- `createAccountHolder`: Creates an account holder in the payment provider. The Payment Module uses this method before creating the account holder in Medusa, and uses the returned data to set fields like `external_id` and `data` in the created `AccountHolder` record.
+- `deleteAccountHolder`: Deletes an account holder in the payment provider. The Payment Module uses this method when an account holder is deleted in Medusa.
+- `savePaymentMethod`: Saves a payment method for an account holder in the payment provider.
+- `listPaymentMethods`: Lists saved payment methods in the third-party service for an account holder. This is useful when displaying the customer's saved payment methods in the storefront.
+
+Learn more about implementing these methods in the [Create Payment Provider guide](/references/payment/provider).
+
+---
+
+## Account Holder in Medusa Payment Flows
+
+In the Medusa application, when a payment session is created for a registered customer, the Medusa application uses the Payment Module to create an account holder for the customer.
+
+Consequently, the Payment Module uses the payment provider to create an account holder in the third-party service, then creates the account holder in Medusa.
+
+This flow is only supported if the chosen payment provider has implemented the necessary [save payment methods](#save-payment-methods).
@@ -13,6 +13,7 @@ This document showcases the module links defined between the Payment Module and
 The Payment Module has the following links to other modules:

 - [`Cart` data model of Cart Module \<\> `PaymentCollection` data model](#cart-module).
+- [`Customer` data model of Customer Module \<\> `AccountHolder` data model](#customer-module).
 - [`Order` data model of Order Module \<\> `PaymentCollection` data model](#order-module).
 - [`OrderClaim` data model of Order Module \<\> `PaymentCollection` data model](#order-module).
 - [`OrderExchange` data model of Order Module \<\> `PaymentCollection` data model](#order-module).
@@ -112,6 +113,100 @@ createRemoteLinkStep({

 ---

+## Customer Module
+
+Medusa defines a link between the `Customer` and `AccountHolder` data models, allowing payment providers to save payment methods for a customer, if the payment provider supports it.
+
+<Note>
+
+This link is available starting from Medusa `v2.5.0`.
+
+</Note>
+
+### Retrieve with Query
+
+To retrieve the customer associated with an account holder with [Query](!docs!/learn/fundamentals/module-links/query), pass `customer.*` in `fields`:
+
+<CodeTabs group="relation-query">
+  <CodeTab label="query.graph" value="method">
+
+```ts
+const { data: accountHolders } = await query.graph({
+  entity: "account_holder",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// accountHolders.customer
+```
+
+  </CodeTab>
+  <CodeTab label="useQueryGraphStep" value="step">
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: accountHolders } = useQueryGraphStep({
+  entity: "account_holder",
+  fields: [
+    "customer.*",
+  ],
+})
+
+// accountHolders.customer
+```
+
+  </CodeTab>
+</CodeTabs>
+
+### Manage with Link
+
+To manage the account holders of a customer, use [Link](!docs!/learn/fundamentals/module-links/link):
+
+<CodeTabs group="relation-link">
+  <CodeTab label="link.create" value="method">
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await link.create({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
+})
+```
+
+  </CodeTab>
+  <CodeTab label="createRemoteLinkStep" value="step">
+
+```ts
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.CUSTOMER]: {
+    customer_id: "cus_123",
+  },
+  [Modules.PAYMENT]: {
+    account_holder_id: "acchld_123",
+  },
+})
+```
+
+  </CodeTab>
+</CodeTabs>
+
+---
+
 ## Order Module

 An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
@@ -21,6 +21,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
 - [Authorize, Capture, and Refund Payments](./payment/page.mdx): Authorize, capture, and refund payments for a single resource.
 - [Payment Collection Management](./payment-collection/page.mdx): Store and manage all payments of a single resources, such as a cart, in payment collections.
 - [Integrate Third-Party Payment Providers](./payment-provider/page.mdx): Use payment providers like [Stripe](./payment-provider/stripe/page.mdx) to handle and process payments, or integrate custom payment providers.
+- [Saved Payment Methods](./account-holder/page.mdx): Save payment methods for customers in third-party payment providers.
 - [Handle Webhook Events](./webhook-events/page.mdx): Handle webhook events from third-party providers and process the associated payment.

 ---