docs: improve payment related guides (#12502)

* improve guide * update guides * small change
2025-05-15 18:40:21 +03:00
parent b312a7e077
commit 22cdcedddc
26 changed files with 15844 additions and 15704 deletions
@@ -76,6 +76,8 @@ export default MyPaymentProviderService
 The constructor allows you to access resources from the [module's container](https://docs.medusajs.com/learn/fundamentals/modules/container)
 using the first parameter, and the module's options using the second parameter.

+If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
+
 :::note

 A module's options are passed when you register it in the Medusa application.
@@ -125,7 +127,7 @@ export default MyPaymentProviderService

 #### Parameters

-<TypeList types={[{"name":"cradle","type":"`Record<string, unknown>`","description":"The module's container cradle used to resolve resources.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AbstractPaymentProvider"/>
+<TypeList types={[{"name":"cradle","type":"`Record<string, unknown>`","description":"The module's container used to resolve resources.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="AbstractPaymentProvider"/>

 ### identifier

@@ -146,13 +148,30 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### authorizePayment

-This method authorizes a payment session. When authorized successfully, a payment is created by the Payment
-Module which can be later captured using the [capturePayment](page.mdx#capturepayment) method.
+This method authorizes a payment session using the third-party payment provider.

-Refer to [this guide](https://docs.medusajs.com/resources/commerce-modules/payment/payment-flow#3-authorize-payment-session)
-to learn more about how this fits into the payment flow and how to handle required actions.
+During checkout, the customer may need to perform actions required by the payment provider,
+such as entering their card details or confirming the payment. Once that is done,
+the customer can place their order.

-To automatically capture the payment after authorization, return the status `captured`.
+During cart-completion before placing the order, this method is used to authorize the cart's payment session with the 
+third-party payment provider. The payment can later be captured
+using the [capturePayment](page.mdx#capturepayment) method.
+
+![Diagram showcasing authorize payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747307795/Medusa%20Resources/authorize-payment\_qzpy6e.jpg)
+
+When authorized successfully, a `Payment` is created by the Payment
+Module, and it's associated with the order.
+
+#### Understanding `data` property
+
+The `data` property of the method's parameter contains the `PaymentSession` record's `data` property, which was
+returned by the [initiatePayment](page.mdx#initiatepayment) method.
+
+The `data` property returned by this method is then stored in the created `Payment` record. You can store data relevant to later capture or process the payment.
+For example, you can store the ID of the payment in the third-party provider to reference it later.
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747309278/Medusa%20Resources/authorize-data\_erjg7r.jpg)

 #### Example

@@ -195,7 +214,18 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### cancelPayment

-This method cancels a payment.
+This method cancels a payment in the third-party payment provider. It's used when
+the admin user cancels an order. The order can only be canceled if the payment
+is not captured yet.
+
+#### Understanding `data` property
+
+The `data` property of the method's parameter contains the `Payment` record's `data` property, which was
+returned by the [authorizePayment](page.mdx#authorizepayment) method.
+
+The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant for any further processing of the payment.
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310189/Medusa%20Resources/cancel-data\_gzcgbc.jpg)

 #### Example

@@ -233,13 +263,24 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### capturePayment

-This method is used to capture a payment. The payment is captured in one of the following scenarios:
+This method captures a payment using the third-party provider. In this method, use the third-party provider to capture the payment.

- The [authorizePayment](page.mdx#authorizepayment) method returns the status `captured`, which automatically executed this method after authorization.
- The merchant requests to capture the payment after its associated payment session was authorized.
- A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in [this guide](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events).
+When an order is placed, the payment is authorized using the [authorizePayment](page.mdx#authorizepayment) method. Then, the admin
+user can capture the payment, which triggers this method.

-In this method, use the third-party provider to capture the payment.
+![Diagram showcasing capture payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747307414/Medusa%20Resources/Klarna\_Payment\_Graphic\_2025\_1\_lii7bw.jpg)
+
+This method can also be triggered by a webhook event if the [getWebhookActionAndData](page.mdx#getwebhookactionanddata) method returns the action `captured`.
+
+#### Understanding `data` property
+
+The `data` property of the input parameter contains data that was previously stored in the Payment record's `data` property, which was
+returned by the [authorizePayment](page.mdx#authorizepayment) method.
+
+The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant to later refund or process the payment.
+For example, you can store the ID of the payment in the third-party provider to reference it later.
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747309870/Medusa%20Resources/capture-data\_acgdhf.jpg)

 #### Example

@@ -260,7 +301,12 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

      // assuming you have a client that captures the payment
    const newData = await this.client.capturePayment(externalId)
-    return {data: newData}
+    return {
+      data: {
+        ...newData,
+        id: externalId,
+      }
+    }
  }
  // ...
 }
@@ -398,9 +444,22 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### deletePayment

-This method is used when a payment session is deleted, which can only happen if it isn't authorized, yet.
+This method deletes a payment session in the third-party payment provider.

-Use this to delete or cancel the payment in the third-party service.
+When a customer chooses a payment method during checkout, then chooses a different one,
+this method is triggered to delete the previous payment session.
+
+If your provider doesn't support deleting a payment session, you can just return an empty object or
+an object that contains the same received `data` property.
+
+![Diagram showcasing delete payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311084/Medusa%20Resources/delete-payment\_smxsiq.jpg)
+
+#### Understanding `data` property
+
+The `data` property of the method's parameter contains the `PaymentSession` record's `data` property, which was
+returned by the [initiatePayment](page.mdx#initiatepayment) method.
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311084/Medusa%20Resources/delete-data\_xg65ck.jpg)

 #### Example

@@ -421,7 +480,9 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

    // assuming you have a client that cancels the payment
    await this.client.cancelPayment(externalId)
-    return {}
+    return {
+      data: input.data
+    }
  }

  // ...
@@ -487,10 +548,11 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### getWebhookActionAndData

-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.
+This method is executed when a webhook event is received from the third-party payment provider. Medusa uses
+the data returned by this method to perform actions in the Medusa application, such as completing the associated cart
+if the payment was authorized successfully.

-Learn more in [this documentation](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events)
+Learn more in the [Webhook Events](https://docs.medusajs.com/resources/commerce-modules/payment/webhook-events) documentation.

 #### Example

@@ -522,6 +584,8 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
          return {
            action: "authorized",
            data: {
+              // assuming the session_id is stored in the metadata of the payment
+              // in the third-party provider
              session_id: (data.metadata as Record<string, any>).session_id,
              amount: new BigNumber(data.amount as number)
            }
@@ -530,19 +594,27 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
          return {
            action: "captured",
            data: {
+              // assuming the session_id is stored in the metadata of the payment
+              // in the third-party provider
              session_id: (data.metadata as Record<string, any>).session_id,
              amount: new BigNumber(data.amount as number)
            }
          }
        default:
          return {
-            action: "not_supported"
+            action: "not_supported",
+            data: {
+              session_id: "",
+              amount: new BigNumber(0)
+            }
          }
      }
    } catch (e) {
      return {
        action: "failed",
        data: {
+          // assuming the session_id is stored in the metadata of the payment
+          // in the third-party provider
          session_id: (data.metadata as Record<string, any>).session_id,
          amount: new BigNumber(data.amount as number)
        }
@@ -560,12 +632,32 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 #### Returns

-<TypeList types={[{"name":"Promise","type":"Promise&#60;[WebhookActionResult](../../../types/interfaces/types.WebhookActionResult/page.mdx)&#62;","optional":false,"defaultValue":"","description":"The webhook result. If the `action`'s value is `captured`, the payment is captured within Medusa as well.\nIf the `action`'s value is `authorized`, the associated payment session is authorized within Medusa.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getWebhookActionAndData"/>
+<TypeList types={[{"name":"Promise","type":"Promise&#60;[WebhookActionResult](../../../types/interfaces/types.WebhookActionResult/page.mdx)&#62;","optional":false,"defaultValue":"","description":"The webhook result. If the `action`'s value is `captured`, the payment is captured within Medusa as well.\nIf the `action`'s value is `authorized`, the associated payment session is authorized within Medusa and the associated cart\nwill be completed to create an order.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="getWebhookActionAndData"/>

 ### initiatePayment

-This method is used when a payment session is created. It can be used to initiate the payment
-in the third-party session, before authorizing or capturing the payment later.
+This method initializes a payment session with the third-party payment provider.
+
+When a customer chooses a payment method during checkout, this method is triggered to
+perform any initialization action with the third-party provider, such as creating a payment session.
+
+![Diagram showcasing initiate payment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310624/Medusa%20Resources/initiate-payment\_dpoa2g.jpg)
+
+#### Understanding `data` property
+
+The `data` property returned by this method will be stored in the created `PaymentSession` record. You can store data relevant to later authorize or process the payment.
+For example, you can store the ID of the payment session in the third-party provider to reference it later.
+
+The `data` property is also available to storefronts, allowing you to store data necessary for the storefront to integrate
+the payment provider in the checkout flow. For example, you can store the client token to use with the payment provider's SDK.
+
+:::note
+
+This also means you shouldn't store sensitive data and tokens in the `data` property, as it's publicly accessible.
+
+:::
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747310699/Medusa%20Resources/initiate-data\_ikc05t.jpg)

 #### Example

@@ -672,7 +764,25 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### refundPayment

-This method refunds an amount of a payment previously captured.
+This method refunds an amount using the third-party payment provider. This method
+is triggered when the admin user refunds a payment of an order.
+
+#### Understanding `data` property
+
+The `data` property of the method's parameter contains the `Payment` record's `data` property, which was
+returned by the [capturePayment](page.mdx#capturepayment) or [refundPayment](page.mdx#refundpayment) method.
+
+The `data` property returned by this method is then stored in the `Payment` record. You can store data relevant to later refund or process the payment.
+For example, you can store the ID of the payment in the third-party provider to reference it later.
+
+:::note
+
+A payment may be refunded multiple times with different amounts. In this case, the `data` property
+of the input parameter contains the data from the last refund.
+
+:::
+
+![Diagram showcasing data flow between methods](https://res.cloudinary.com/dza7lstvk/image/upload/v1747311296/Medusa%20Resources/refund-data\_plcjl0.jpg)

 #### Example

@@ -697,7 +807,9 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
        input.amount
      )

-    return {data: newData}
+    return {
+      data: input.data,
+    }
  }
  // ...
 }
@@ -713,7 +825,7 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### retrievePayment

-Retrieves the payment's data from the third-party service.
+This method retrieves the payment's data from the third-party payment provider.

 #### Example

@@ -870,7 +982,7 @@ class MyPaymentProviderService extends AbstractPaymentProvider<

 ### updatePayment

-Update a payment in the third-party service that was previously initiated with the [initiatePayment](page.mdx#initiatepayment) method.
+This method updates a payment in the third-party service that was previously initiated with the [initiatePayment](page.mdx#initiatepayment) method.

 #### Example

@@ -923,7 +1035,8 @@ class MyPaymentProviderService extends AbstractPaymentProvider<
 ### validateOptions

 This method validates the options of the provider set in `medusa-config.ts`.
-Implementing this method is optional. It's useful if your provider requires custom validation.
+Implementing this method is optional, but it's useful to ensure that the required
+options are passed to the provider, or if you have any custom validation logic.

 If the options aren't valid, throw an error.

@@ -944,7 +1057,7 @@ class MyPaymentProviderService extends AbstractPaymentProvider<Options> {

 #### Parameters

-<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>
+<TypeList types={[{"name":"options","type":"`Record<any, any>`","description":"The provider's options passed in `medusa-config.ts`.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="validateOptions"/>

 ---