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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser
2024-12-26 10:32:16 +02:00
committed by GitHub
parent c8f9938865
commit ebca8fed28
112 changed files with 9465 additions and 7731 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/payment/examples/page.mdx
-359
View File
@@ -1,359 +0,0 @@
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.
<Note>
You should only use the Payment Module's main service when implementing complex customizations. For common cases, check out [available workflows instead](../../../medusa-workflows-reference/page.mdx).
</Note>
## Create a Payment Collection
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.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/medusa/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 [Payment Module's main service reference](/references/payment) provides a reference to all the methods available for use with examples for each.
www/apps/resources/app/commerce-modules/payment/links-to-other-modules/page.mdx
+12 -12
View File
@@ -39,8 +39,8 @@ To retrieve the cart associated with the payment collection with [Query](!docs!/
const { data: paymentCollections } = await query.graph({
entity: "payment_collection",
fields: [
"cart.*"
]
"cart.*",
],
})
// paymentCollections.cart
@@ -57,8 +57,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: paymentCollections } = useQueryGraphStep({
entity: "payment_collection",
fields: [
"cart.*"
]
"cart.*",
],
})
// paymentCollections.cart
@@ -131,8 +131,8 @@ To retrieve the order of a payment collection with [Query](!docs!/learn/fundamen
const { data: paymentCollections } = await query.graph({
entity: "payment_collection",
fields: [
"order.*"
]
"order.*",
],
})
// paymentCollections.order
@@ -149,8 +149,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: paymentCollections } = useQueryGraphStep({
entity: "payment_collection",
fields: [
"order.*"
]
"order.*",
],
})
// paymentCollections.order
@@ -224,8 +224,8 @@ To retrieve the regions of a payment provider with [Query](!docs!/learn/fundamen
const { data: paymentProviders } = await query.graph({
entity: "payment_provider",
fields: [
"regions.*"
]
"regions.*",
],
})
// paymentProviders.regions
@@ -242,8 +242,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: paymentProviders } = useQueryGraphStep({
entity: "payment_provider",
fields: [
"regions.*"
]
"regions.*",
],
})
// paymentProviders.regions
www/apps/resources/app/commerce-modules/payment/page.mdx
+133 -94
View File
@@ -1,5 +1,4 @@
import { CodeTabs, CodeTab } from "docs-ui"
import { Table } from "docs-ui"
import { CodeTabs, CodeTab, ChildDocs } from "docs-ui"
export const metadata = {
title: `Payment Module`,
@@ -7,130 +6,170 @@ export const metadata = {
# {metadata.title}
The Payment Module provides payment-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the Payment Module and how to use it in your application.
## How to Use Payment Module's Service
Medusa has payment related features available out-of-the-box through the Payment Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Payment Module.
You can use the Payment Module's main service by resolving from the Medusa container the resource `Modules.PAYMENT`.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
## Payment Features
- [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.
- [Handle Webhook Events](./webhook-events/page.mdx): Handle webhook events from third-party providers and process the associated payment.
---
## How to Use the Payment Module
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
export const highlights = [
["12", "Modules.PAYMENT", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/create-payment-collection.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const paymentModuleService = container.resolve(
Modules.PAYMENT
)
const createPaymentCollectionStep = createStep(
"create-payment-collection",
async ({}, { container }) => {
const paymentModuleService = container.resolve(Modules.PAYMENT)
const payment_collections =
await paymentModuleService.listPaymentCollections()
})
const paymentCollection = await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 5000,
})
return new StepResponse({ paymentCollection }, paymentCollection.id)
},
async (paymentCollectionId, { container }) => {
if (!paymentCollectionId) {
return
}
const paymentModuleService = container.resolve(Modules.PAYMENT)
await paymentModuleService.deletePaymentCollections([paymentCollectionId])
}
)
export const createPaymentCollectionWorkflow = createWorkflow(
"create-payment-collection",
() => {
const { paymentCollection } = createPaymentCollectionStep()
return new WorkflowResponse({
paymentCollection,
})
}
)
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createPaymentCollectionWorkflow } from "../../workflows/create-payment-collection"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
) {
const { result } = await createPaymentCollectionWorkflow(req.scope)
.run()
res.json({
payment_collections: await paymentModuleService.listPaymentCollections(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createPaymentCollectionWorkflow(container)
.run()
export default async function subscriberHandler({ container }: SubscriberArgs) {
const paymentModuleService = container.resolve(
Modules.PAYMENT
)
console.log(result)
}
const payment_collections =
await paymentModuleService.listPaymentCollections()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createPaymentCollectionWorkflow } from "../workflows/create-payment-collection"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createPaymentCollectionWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
---
## 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, which carries information for authorized, captured, and refunded payments for a single resource.
```ts
const paymentCollection = await paymentModuleService.createPaymentCollections({
region_id: "reg_123",
currency_code: "usd",
amount: 5000,
})
```
### Authorize, Capture, and Refund Payment
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 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
},
})
```
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Configure Payment Module
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
The Payment Module accepts options for further configurations. Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
---
## Providers
Medusa provides the following payment providers out-of-the-box. You can use them to process payments for orders, returns, and other resources.
<ChildDocs showItems={["Providers"]} hideTitle />
---
<CommerceModuleSections name="Payment" />