Payment Module

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.

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.

await paymentModuleService.capturePayment({
  payment_id: "pay_1",
})

Integrate Third-Party Payment Providers

Use payment providers like Stripe and PayPal to handle and process payments.

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.

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:

medusa-config.js

const modules = {
  // ...
  apiKey: {
    resolve: "@medusajs/payment",
    options: {
      // ...
    },
  },
}

Module Options

Option	Description	Required	Default
webhook_delay	A number indicating the delay in milliseconds before processing a webhook event.	No	5000
webhook_retries	The number of times to retry the webhook event processing in case of an error.	No	3
providers	An array of payment providers to install and register. Learn more here.	No	-

---

How to Use Payment Module's Service

You can use the Payment Module's main service by resolving from the dependency container the resource ModuleRegistrationName.PAYMENT imported from @medusajs/modules-sdk.

For example:

• API Route
• Subscriber
• Workflow Step

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(),
  })
}

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()
}

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()
})