asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore: reorganize docs apps (#7228)

Browse Source 
* reorganize docs apps

* add README

* fix directory

* add condition for old docs
This commit is contained in:
Shahed Nasser
2024-05-03 17:36:38 +03:00
committed by GitHub
parent 224ebb2154
commit 4fe28f5a95
6187 changed files with 601447 additions and 598226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/payment/examples/page.mdx
+377
View File
@@ -0,0 +1,377 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `Examples of the Payment Module`,
}
# {metadata.title}
In this guide, you’ll find common examples of how you can use the Payment Module in your application.
## Create a Payment Collection
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const paymentCollection =
await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 4000,
})
res.json({
payment_collection: paymentCollection,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function POST(request: Request) {
const paymentModuleService = await initializePaymentModule()
const paymentCollection =
await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 4000,
})
return NextResponse.json({
payment_collection: paymentCollection,
})
}
```
</CodeTab>
</CodeTabs>
---
## Create Payment Session
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const paymentSession =
await paymentModuleService.createPaymentSession(
"pay_col_123",
{
currency_code: "usd",
provider_id: "system",
amount: 4000,
data: {},
}
)
res.json({
payment_session: paymentSession,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function POST(request: Request) {
const paymentModuleService = await initializePaymentModule()
const paymentSession =
await paymentModuleService.createPaymentSession(
"pay_col_123",
{
currency_code: "usd",
provider_id: "system",
amount: 4000,
data: {},
}
)
return NextResponse.json({
payment_session: paymentSession,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Payment Sessions of Payment Collection
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const paymentSessions =
await paymentModuleService.listPaymentSessions({
payment_collection_id: ["pay_col_123"],
})
res.json({
payment_sessions: paymentSessions,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function POST(
request: Request
) {
const paymentModuleService = await initializePaymentModule()
const paymentSessions =
await paymentModuleService.listPaymentSessions({
payment_collection_id: ["pay_col_123"],
})
return NextResponse.json({
payment_sessions: paymentSessions,
})
}
```
</CodeTab>
</CodeTabs>
---
## Authorize Payment Session
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const payment =
await paymentModuleService.authorizePaymentSession(
"payses_123",
{}
)
res.json({
payment,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function POST(
request: Request
) {
const paymentModuleService = await initializePaymentModule()
const payment =
await paymentModuleService.authorizePaymentSession(
"payses_123",
{}
)
return NextResponse.json({
payment,
})
}
```
</CodeTab>
</CodeTabs>
---
## List Payments of Payment Session
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const payments = await paymentModuleService.listPayments({
session_id: "payses_123",
})
res.json({
payments,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function GET(
request: Request
) {
const paymentModuleService = await initializePaymentModule()
const payments = await paymentModuleService.listPayments({
session_id: "payses_123",
})
return NextResponse.json({
payments,
})
}
```
</CodeTab>
</CodeTabs>
---
## Capture Payment
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
const payment = await paymentModuleService.capturePayment({
payment_id: "pay_123",
})
res.json({
payment,
})
}
```
</CodeTab>
<CodeTab label="Next.js App Router" value="nextjs">
```ts
import { NextResponse } from "next/server"
import {
initialize as initializePaymentModule,
} from "@medusajs/payment"
export async function POST(
request: Request
) {
const paymentModuleService = await initializePaymentModule()
const payment = await paymentModuleService.capturePayment({
payment_id: "pay_123",
})
return NextResponse.json({
payment,
})
}
```
</CodeTab>
</CodeTabs>
---
## More Examples
The [module interface reference](/references/payment) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/payment/module-options/page.mdx
+134
View File
@@ -0,0 +1,134 @@
---
sidebar_label: "Module Options"
---
import { Table } from "docs-ui"
export const metadata = {
title: `Payment Module Options`,
}
# {metadata.title}
In this document, you'll learn about the options of the Payment Module.
## All Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`webhook_delay`
</Table.Cell>
<Table.Cell>
A number indicating the delay in milliseconds before processing a webhook event.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`5000`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`webhook_retries`
</Table.Cell>
<Table.Cell>
The number of times to retry the webhook event processing in case of an error.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`3`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`providers`
</Table.Cell>
<Table.Cell>
An array of payment providers to install and register. Learn more [in this section](#providers).
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## providers
The `providers` option is an array of either payment provider modules, payment plugins, or path to a file that holds a payment provider.
When the Medusa application starts, these providers are registered and can be used to process payments.
For example:
```js title="medusa-config.js"
const modules = {
// ...
payment: {
resolve: "@medusajs/payment",
options: {
providers: [
{
resolve: "@medusajs/payment-stripe",
options: {
// ...
},
},
{
resolve: "medusa-payment-paypal",
options: {
// ...
},
},
],
},
},
}
```
The `providers` option is an array of objects that accept the following properties:
- `resolve`: A string indicating the package name of the payment provider module or the payment plugin, or the path to the file defining the payment provider.
- `options`: An optional object of options to pass to the payment provider.
www/apps/resources/app/commerce-modules/payment/page.mdx
+164
View File
@@ -0,0 +1,164 @@
import { CodeTabs, CodeTab } from "docs-ui"
import { Table } from "docs-ui"
export const metadata = {
title: `Payment Module`,
}
# {metadata.title}
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
The Payment Module provides payment functionalities that allow you to process payment of any resource, such as a cart.
All payment processing starts with creating a payment collection.
```ts
const paymentCollection =
await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 5000,
})
```
### Authorize, Capture, and Refund Payment
The Payment Module provides essential features to receive and handle payments, including authorizing, capturing, and refunding payment.
```ts
await paymentModuleService.capturePayment({
payment_id: "pay_1",
})
```
### Integrate Third-Party Payment Providers
Use payment providers like Stripe and PayPal to handle and process payments.
```ts
const payment =
await paymentModuleService.createPaymentSession(
"pay_col_1",
{
provider_id: "stripe",
amount: 1000,
currency_code: "usd",
data: {
// necessary data for the payment provider
},
}
)
```
### Handle Webhook Events
The Payment Module allows you to handle webhook events from third-party providers and process the associated payment.
```ts
await paymentModuleService.processEvent({
provider: "stripe",
payload: {
// webhook payload
},
})
```
---
## Configure Payment Module
After installing the `@medusajs/payment` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
```js title="medusa-config.js"
const modules = {
// ...
apiKey: {
resolve: "@medusajs/payment",
options: {
// ...
},
},
}
```
### Module Options
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
---
## How to Use Payment Module's Service
You can use the Payment Module's main service by resolving from the Medusa container the resource `ModuleRegistrationName.PAYMENT` imported from `@medusajs/modules-sdk`.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService =
req.scope.resolve(ModuleRegistrationName.PAYMENT)
res.json({
payment_collections:
await paymentModuleService.listPaymentCollections(),
})
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/medusa"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
export default async function subscriberHandler({
container,
}: SubscriberArgs) {
const paymentModuleService: IPaymentModuleService =
container.resolve(ModuleRegistrationName.API_KEY)
const payment_collections =
await paymentModuleService.listPaymentCollections()
}
```
</CodeTab>
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/workflows-sdk"
import { IPaymentModuleService } from "@medusajs/types"
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
const step1 = createStep("step-1", async (_, context) => {
const paymentModuleService: IPaymentModuleService =
context.container.resolve(
ModuleRegistrationName.API_KEY
)
const payment_collections =
await paymentModuleService.listPaymentCollections()
})
```
</CodeTab>
</CodeTabs>
www/apps/resources/app/commerce-modules/payment/payment-collection/page.mdx
+37
View File
@@ -0,0 +1,37 @@
export const metadata = {
title: `Payment Collection`,
}
# {metadata.title}
In this document, you’ll learn what a payment collection is and how to use it with the Cart Module.
## 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.
Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
- The payment sessions that represents the payment amount to authorize.
- The payments that are created when a payment session is authorized. They can be captured and refunded.
- The payment providers that handle the processing of each payment session, including the authorization, capture, and refund.
---
## 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).
![Diagram showcasing the relation between the Payment and Cart modules](https://res.cloudinary.com/dza7lstvk/image/upload/v1711537849/Medusa%20Resources/cart-payment_ixziqm.jpg)
---
## 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.
![Diagram showcasing how a payment collection can have multiple payment sessions and payments](https://res.cloudinary.com/dza7lstvk/image/upload/v1711554695/Medusa%20Resources/payment-collection-multiple-payments_oi3z3n.jpg)
www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx
+144
View File
@@ -0,0 +1,144 @@
export const metadata = {
title: `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>
## Flow Overview
![A diagram showcasing the payment flow's steps](https://res.cloudinary.com/dza7lstvk/image/upload/v1711566781/Medusa%20Resources/payment-flow_jblrvw.jpg)
---
## 1. Create a Payment Collection
The payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
For example:
```ts
const paymentCollection =
await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 5000,
})
```
You can then link the payment collection to another resource, such as a cart in the Cart Module.
<Note>
Learn more about the `createPaymentCollections` method in [this reference](/references/payment/createPaymentCollections).
</Note>
---
## 2. Create Payment Sessions
The payment collection has one or more payment sessions, each being a payment amount to be authorized by a payment provider.
So, after creating the payment collection, create at least one payment session for a provider.
For example:
```ts
const paymentSession =
await paymentModuleService.createPaymentSession(
paymentCollection.id,
{
provider_id: "stripe",
currency_code: "usd",
amount: 5000,
data: {
// any necessary data for the
// payment provider
},
}
)
```
You can also create payment sessions for every supported payment provider to allow customers to choose from them.
<Note>
Learn more about the `createPaymentSession` method in [this reference](/references/payment/createPaymentSession).
</Note>
---
## 3. Authorize Payment Session
Once the customer chooses a payment session, start the authorization process. This may involve some action performed by the third-party payment provider, such as entering a 3DS code.
For example:
```ts
const payment =
await paymentModuleService.authorizePaymentSession(
paymentSession.id,
{}
)
```
When the payment authorization is successful, a payment is created and returned.
<Note>
Learn more about the `authorizePaymentSession` method in [this reference](/references/payment/authorizePaymentSession).
</Note>
### Handling Additional Action
If the payment authorization isn’t successful, either because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
In that case, you can catch that error and, if there are required actions, handle them accordingly, then retry the authorization.
For example:
```ts
try {
const payment =
await paymentModuleService.authorizePaymentSession(
paymentSession.id,
{}
)
} catch (e) {
// retrieve the payment session again
const updatedPaymentSession = (
await paymentModuleService.listPaymentSessions({
id: [paymentSession.id],
})
)[0]
if (updatedPaymentSession.status === "requires_more") {
// TODO perform required action
// TODO authorize payment again.
}
}
```
---
## 4. Payment Flow Complete
The payment flow is complete once the payment session is authorized and the payment is created.
You can then use the payment to capture the amount using the [capturePayment method](/references/payment/capturePayment). You can also refund captured amounts using the [refundPayment method](/references/payment/refundPayment).
<Note>
Some payment providers allow capturing the payment automatically once it’s authorized. In that case, you don’t need to do it manually.
</Note>
www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
+47
View File
@@ -0,0 +1,47 @@
export const metadata = {
title: `Payment Provider`,
}
# {metadata.title}
In this document, you’ll learn what a payment provider is.
## What's a Payment Provider?
A payment provider handles payment processing. It can integrate third-party payment providers, such as Stripe or PayPal.
To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.
---
## System Payment Provider
The Payment Module provides a `system` payment provider that acts as a placeholder payment provider. It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
---
## How are Payment Providers Created?
A payment provider is a TypeScript or JavaScript class that extends the `AbstractPaymentProvider` imported from `@medusajs/utils`. It can then be used in a payment plugin or exported in a provider module.
<Note title="Tip">
Refer to [this guide](/references/payment/provider) on how to create a payment provider for the Payment Module.
</Note>
---
## Configure Payment Providers
The Payment Module accepts a `providers` option that allows you to register providers in your application.
Learn more about this option in [this documentation](../module-options/page.mdx#providers).
---
## PaymentProvider Data Model
When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists. This data model is used to reference a payment provider and determine whether it’s installed in the application.
www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/page.mdx
+200
View File
@@ -0,0 +1,200 @@
---
sidebar_label: "Stripe"
---
import { Table } from "docs-ui"
export const metadata = {
title: `Stripe Provider Module`,
}
# {metadata.title}
In this document, you’ll learn about the Stripe provider module and how to install and use it in the Payment Module.
## Features
[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales.
These features are also available in a safe test environment, allowing for a concern-free development process.
---
## Install the Stripe Provider Module
<Note type="check">
- [Stripe account](https://stripe.com/).
- [Stripe API Key](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard)
- For deployed Medusa applications, a [Stripe webhook secret](https://docs.stripe.com/webhooks#add-a-webhook-endpoint). When creating the Webhook, set the endpoint URL to `{medusa_url}/hooks/payment/stripe`, where `{medusa_url}` with the URL to your deployed Medusa application.
</Note>
To install the Stripe provider module, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/payment-stripe
```
Next, add the module to the array of providers passed to the Payment Module:
```js title="medusa-config.js"
const modules = {
// ...
payment: {
resolve: "@medusajs/payment",
options: {
providers: [
{
resolve: "@medusajs/payment-stripe",
options: {
credentials: {
usd: {
apiKey: process.env.STRIPE_USD_API_KEY,
},
},
},
},
],
},
},
}
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`credentials`
</Table.Cell>
<Table.Cell>
An object where each entry is a stripe provider installation. The object’s keys are the name suffix of the provider, where the provider name will be formatted as `stripe-{key}`. For example, `stripe-usd`.
Each value is an object that accepts the following properties:
- `apiKey`: A string indicating the Stripe API key.
- `webhookSecret`: (optional in development) A string indicating the Stripe webhook secret. This is only useful for deployed Medusa applications.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`capture`
</Table.Cell>
<Table.Cell>
Whether to automatically capture payment after authorization.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`false`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`automatic_payment_methods`
</Table.Cell>
<Table.Cell>
A boolean value indicating whether to enable Stripe's automatic payment methods. This is useful if you integrate services like Apple pay or Google pay.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`false`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`payment_description`
</Table.Cell>
<Table.Cell>
A string used as the default description of a payment if none is available in cart.context.payment_description.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
STRIPE_USD_API_KEY=<YOUR_STRIPE_API_KEY>
```
---
## Use Provider
To use the Stripe provider, create a payment session for the provider:
```ts
const paymentSession =
await paymentModuleService.createPaymentSession(
"pay_col_123",
{
provider_id: "stripe-usd",
amount: 5000,
currency_code: "usd",
data: {
// any necessary data
// to pass to stripe
},
}
)
```
www/apps/resources/app/commerce-modules/payment/payment-session/page.mdx
+35
View File
@@ -0,0 +1,35 @@
export const metadata = {
title: `Payment Session`,
}
# {metadata.title}
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 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).
![Diagram showcasing how every payment session has a different payment provider](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565056/Medusa%20Resources/payment-session-provider_guxzqt.jpg)
---
## 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.
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.
---
## Payment Session Status
The `status` field of a payment session indicates its current status. Its value can be:
- `pending`: The payment session is awaiting authorization.
- `requires_more`: The payment session requires an action before it’s authorized. For example, to enter a 3DS code.
- `authorized`: The payment session is authorized.
- `error`: An error occurred while authorizing the payment.
- `canceled`: The authorization of the payment session has been canceled.
www/apps/resources/app/commerce-modules/payment/payment/page.mdx
+37
View File
@@ -0,0 +1,37 @@
export const metadata = {
title: `Payment`,
}
# {metadata.title}
In this document, you’ll learn what a payment is and how it's created, captured, and refunded.
## 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.
A payment carries along many of the data and relations of a payment session:
- It belongs to the same payment collection.
- It’s associated with the same payment provider, which handles further payment processing.
- It stores the payment session’s `data` field in its `data` field, as it’s still useful for the payment provider’s processing.
---
## 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.
The payment can also be captured incrementally, each time a capture record is created for that amount.
![A diagram showcasing how a payment's multiple captures are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565445/Medusa%20Resources/payment-capture_f5fve1.jpg)
---
## 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.
A payment can be refunded multiple times, and each time a refund record is created for that refund.
![A diagram showcasing how a payment's multiple refunds are stored](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565555/Medusa%20Resources/payment-refund_lgfvyy.jpg)
www/apps/resources/app/commerce-modules/payment/relations-to-other-modules/page.mdx
+27
View File
@@ -0,0 +1,27 @@
export const metadata = {
title: `Relations between Payment Module and Other Modules`,
}
# {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.
## Cart Module
The Payment Module can be used with the Cart Module to accept payment for the cart during checkout.
Learn more about this relation in [this documentation](../payment-collection/page.mdx#usage-with-the-cart-module).
---
## 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.
![A diagram showcasing an example of how resources from the Payment and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711569520/Medusa%20Resources/payment-region_jyo2dz.jpg)
This increases the flexibility of your store.
For example, paired with other modules, such as the Cart Module, you only show during checkout the payment providers associated with the cart's region.
www/apps/resources/app/commerce-modules/payment/webhook-events/page.mdx
+44
View File
@@ -0,0 +1,44 @@
export const metadata = {
title: `Webhook Events`,
}
# {metadata.title}
In this document, you’ll learn how the Payment Module supports listening to webhook events.
## What's a Webhook Event?
A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status. This is useful in different cases such as when a payment is being processed asynchronously or when a request is interrupted.
---
## 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.
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.
![A diagram showcasing the steps of how the processEvent method words](https://res.cloudinary.com/dza7lstvk/image/upload/v1711567415/Medusa%20Resources/payment-webhook_seaocg.jpg)
You can use this method in your webhook listener API routes or endpoints.
<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).