docs: edits and fixes to commerce module docs (#7468)
Apply edits and fixes to the commerce modules docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
130de74d6d
commit
2c5ba408d4
160 files changed
+6400
-3790
No files matched your search
@@ -8,4 +8,10 @@ export const metadata = {
|
||||
|
||||
Find in this reference the list of events emitted by the Payment Module.
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Events are still in development, so this reference will change in the future.
|
||||
|
||||
</Note>
|
||||
|
||||
<EventsTable />
|
||||
@@ -374,4 +374,4 @@ In this guide, you’ll find common examples of how you can use the Payment Modu
|
||||
|
||||
## More Examples
|
||||
|
||||
The [module interface reference](/references/payment) provides a reference to all the methods available for use with examples for each.
|
||||
The [Payment Module's main service reference](/references/payment) provides a reference to all the methods available for use with examples for each.
|
||||
@@ -9,8 +9,6 @@ export const metadata = {
|
||||
|
||||
The Payment Module is the `@medusajs/payment` NPM package that provides payment-related features in your Medusa and Node.js applications.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Add Payment Functionalities to Any Resource
|
||||
@@ -40,7 +38,7 @@ await paymentModuleService.capturePayment({
|
||||
|
||||
### Integrate Third-Party Payment Providers
|
||||
|
||||
Use payment providers like Stripe and PayPal to handle and process payments.
|
||||
Use payment providers like Stripe to handle and process payments.
|
||||
|
||||
```ts
|
||||
const payment =
|
||||
@@ -74,12 +72,16 @@ await paymentModuleService.processEvent({
|
||||
|
||||
## Configure Payment Module
|
||||
|
||||
After installing the `@medusajs/payment` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
|
||||
To use the Payment Module, enable it in the `modules` object in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const { Modules } = require("@medusajs/modules-sdk")
|
||||
|
||||
// ...
|
||||
|
||||
const modules = {
|
||||
// ...
|
||||
apiKey: {
|
||||
[Modules.PAYMENT]: {
|
||||
resolve: "@medusajs/payment",
|
||||
options: {
|
||||
// ...
|
||||
@@ -134,7 +136,7 @@ For example:
|
||||
container,
|
||||
}: SubscriberArgs) {
|
||||
const paymentModuleService: IPaymentModuleService =
|
||||
container.resolve(ModuleRegistrationName.API_KEY)
|
||||
container.resolve(ModuleRegistrationName.PAYMENT)
|
||||
|
||||
const payment_collections =
|
||||
await paymentModuleService.listPaymentCollections()
|
||||
@@ -149,10 +151,12 @@ For example:
|
||||
import { IPaymentModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
const step1 = createStep("step-1", async (_, context) => {
|
||||
const step1 = createStep(
|
||||
"step-1",
|
||||
async (_, { container }) => {
|
||||
const paymentModuleService: IPaymentModuleService =
|
||||
context.container.resolve(
|
||||
ModuleRegistrationName.API_KEY
|
||||
container.resolve(
|
||||
ModuleRegistrationName.PAYMENT
|
||||
)
|
||||
|
||||
const payment_collections =
|
||||
|
||||
@@ -8,7 +8,7 @@ In this document, you’ll learn what a payment collection is and how to use it
|
||||
|
||||
## What's a Payment Collection?
|
||||
|
||||
A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the `PaymentCollection` data model.
|
||||
A payment collection stores payment details related to a resource, such as a cart or an order. It’s represented by the [PaymentCollection data model](/references/payment/models/PaymentCollection).
|
||||
|
||||
Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
|
||||
|
||||
@@ -18,20 +18,20 @@ Every purchase or request for payment starts with a payment collection. The coll
|
||||
|
||||
---
|
||||
|
||||
## Usage with the Cart Module
|
||||
|
||||
The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
|
||||
|
||||
With the Payment Module, you can create a payment collection for the cart and handle the payment functionalities.
|
||||
|
||||
The Medusa application creates a link between the `PaymentCollection` and `Cart` data models. It also implements the payment flow during checkout as explained in [this documentation](../payment-flow/page.mdx).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Multiple Payments
|
||||
|
||||
The payment collection supports multiple payment sessions and payments. You can use this to accept payments in increments or split payments across payment providers.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Usage with the Cart Module
|
||||
|
||||
The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
|
||||
|
||||
With the Payment Module, you can create a payment collection for the cart and process the payment.
|
||||
|
||||
The Medusa application creates a link between the `PaymentCollection` and `Cart` data models. It also implements the payment flow during checkout as explained in [this documentation](../payment-flow/page.mdx).
|
||||
|
||||
|
||||
@@ -1,16 +1,10 @@
|
||||
export const metadata = {
|
||||
title: `Payment Flow`,
|
||||
title: `Accept Payment Flow`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about the payment flow implemented by the Medusa application. This is the recommended flow to follow when accepting a payment for a resource using the Payment Module.
|
||||
|
||||
<Note>
|
||||
|
||||
The flow described is in the checkout context. However, you can apply it in any use case.
|
||||
|
||||
</Note>
|
||||
In this document, you’ll learn how to implement an accept-payment flow.
|
||||
|
||||
## Flow Overview
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ In this document, you’ll learn what a payment session is.
|
||||
|
||||
## What's a Payment Session?
|
||||
|
||||
A payment session, represented by the `PaymentSession` data model, is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
|
||||
A payment session, represented by the [PaymentSession data model](/references/payment/modules/PaymentSession), is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
|
||||
|
||||
A payment collection can have multiple payment sessions. For example, during checkout, when a customer chooses between paying with Stripe or PayPal, each of these payment options is a payment session associated with a payment provider (Stripe or PayPal).
|
||||
|
||||
@@ -18,9 +18,9 @@ A payment collection can have multiple payment sessions. For example, during che
|
||||
|
||||
## data field
|
||||
|
||||
Payment providers may need some additional data to process the payment later. The `PaymentSession` data model has a `data` field used to store that data.
|
||||
Payment providers may need additional data to process the payment later. The `PaymentSession` data model has a `data` field used to store that data.
|
||||
|
||||
For example, for Stripe, you must pass Stripe’s customer ID when processing the payment. So, when you create a payment session, the Stripe payment provider creates the customer in Stripe and stores the ID in the `data` field.
|
||||
For example, the customer's ID in Stripe is stored in the `data` field.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ In this document, you’ll learn what a payment is and how it's created, capture
|
||||
|
||||
## What's a Payment?
|
||||
|
||||
When a payment session is authorized, a payment, represented by the `Payment` data model, is created. This payment is an authorized amount that’s later captured or refunded.
|
||||
When a payment session is authorized, a payment, represented by the [Payment data model](/references/payment/models/Payment), is created. This payment can later be captured or refunded.
|
||||
|
||||
A payment carries along many of the data and relations of a payment session:
|
||||
|
||||
@@ -20,7 +20,7 @@ A payment carries along many of the data and relations of a payment session:
|
||||
|
||||
## Capture Payments
|
||||
|
||||
When a payment is captured, a capture, represented by the `Capture` data model, is created. It holds details related to the capture, such as the amount, the capture date, and more.
|
||||
When a payment is captured, a capture, represented by the [Capture data model](/references/payment/models/Capture), is created. It holds details related to the capture, such as the amount, the capture date, and more.
|
||||
|
||||
The payment can also be captured incrementally, each time a capture record is created for that amount.
|
||||
|
||||
@@ -30,8 +30,8 @@ The payment can also be captured incrementally, each time a capture record is cr
|
||||
|
||||
## Refund Payments
|
||||
|
||||
An amount of a payment can be refunded if it’s already captured. Once it’s refunded, a refund, represented by the `Refund` data model, is created. It holds details related to the refund, such as the amount, refund date, and more.
|
||||
When a payment is refunded, a refund, represented by the [Refund data model](/references/payment/models/Refund), is created. It holds details related to the refund, such as the amount, refund date, and more.
|
||||
|
||||
A payment can be refunded multiple times, and each time a refund record is created for that refund.
|
||||
A payment can be refunded multiple times, and each time a refund record is created.
|
||||
|
||||
|
||||
@@ -4,9 +4,7 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
When Commerce Modules are used together in a Medusa application, the Medusa application handles building the relations between these modules.
|
||||
|
||||
This document showcases the relation between the Payment Module and other Commerce Modules.
|
||||
This document showcases the link modules defined between the Payment Module and other commerce modules.
|
||||
|
||||
## Cart Module
|
||||
|
||||
@@ -16,6 +14,14 @@ Learn more about this relation in [this documentation](../payment-collection/pag
|
||||
|
||||
---
|
||||
|
||||
## Order Module
|
||||
|
||||
An order's payment is stored in a payment collection. Medusa defines a link module that builds a relationship between the `Order` and `PaymentCollection` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Region Module
|
||||
|
||||
You can specify for each region which payment providers are available. The Medusa application forms a relation between the `PaymentProvider` and the `Region` data models.
|
||||
|
||||
@@ -14,31 +14,12 @@ A webhook event is sent from a third-party payment provider to your application.
|
||||
|
||||
## processEvent Method
|
||||
|
||||
The Payment Module’s main service (`IPaymentModuleService`) provides a `processEvent` method used to handle incoming webhook events from third-party providers. The method delegates the handling to the associated payment provider, which returns the event's details.
|
||||
The Payment Module’s main service (`IPaymentModuleService`) provides a [processEvent method](/references/payment/processEvent) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
|
||||
|
||||
If the event's details indicate that the payment should be authorized, then the `authorizePaymentSession` of the main service is executed on the specified payment session.
|
||||
|
||||
If the event's details indicate that the payment should be captured, then the `capturePayment` of the main service is executed on the payment of the specified payment session.
|
||||
Medusa implements a webhook listener at the `/hooks/payment/[provider]` API route, where `[provider]` is the ID of the provider (for example, `stripe`). You can use that webhook listener in your third-party payment provider's configurations.
|
||||
|
||||
|
||||
|
||||
You can use this method in your webhook listener API routes or endpoints.
|
||||
If the event's details indicate that the payment should be authorized, then the [authorizePaymentSession method of the main service](/references/payment/authorizePaymentSession) is executed on the specified payment session.
|
||||
|
||||
<Note>
|
||||
|
||||
Medusa V2 implements a webhook listener at the `/hooks/payment/[provider]` API route, where `[provider]` is the ID of the provider (for example, `stripe`). You can use that webhook listener in your third-party payment provider's configurations.
|
||||
|
||||
</Note>
|
||||
|
||||
For example:
|
||||
|
||||
```ts
|
||||
await paymentModuleService.processEvent({
|
||||
provider: "stripe",
|
||||
payload: {
|
||||
// webhook event data
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Learn more about the method’s parameters and return types in [this reference](/references/payment/processEvent).
|
||||
If the event's details indicate that the payment should be captured, then the [capturePayment method of the main service](/references/payment/capturePayment) is executed on the payment of the specified payment session.
|
||||
Reference in new issue
Block a user