medusa-store/www/apps/resources/app/commerce-modules/payment/page.mdx

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>