Providers Overview

Learn about the provider pattern in Medusa and explore available providers for payments, fulfillment, file storage, notifications, and authentication.

Providers Overview

Providers in Medusa are modular, pluggable services that handle specific functionalities like payment processing, file storage, notifications, and authentication. They follow a consistent pattern that makes it easy to swap implementations or add new providers.

What are Providers?

Providers are specialized services that:

• Implement standardized interfaces for specific domains (payment, file storage, etc.)
• Can be easily swapped or configured based on your needs
• Are registered using the ModuleProvider pattern
• Support multiple providers of the same type running simultaneously

Provider Categories

Medusa includes providers across several categories:

Payment Providers

Handle payment processing and transaction management.

• payment-stripe - Stripe payment integration with support for multiple payment methods
  • Stripe (default card payments)
  • Bancontact
  • Blik
  • Giropay
  • iDEAL
  • Przelewy24
  • PromptPay
  • OXXO

Learn more about Payment Providers

Fulfillment Providers

Manage order fulfillment and shipping.

• fulfillment-manual - Manual fulfillment provider for self-managed shipping

Learn more about Fulfillment Providers

File Storage Providers

Handle file uploads, downloads, and storage.

• file-local - Local filesystem storage for development
• file-s3 - Amazon S3 cloud storage for production

Learn more about File Storage Providers

Notification Providers

Send notifications via email, SMS, and other channels.

• notification-local - Local logging provider for development
• notification-sendgrid - SendGrid email integration

Learn more about Notification Providers

Auth Providers

Handle user authentication and identity management.

• auth-emailpass - Email and password authentication
• auth-google - Google OAuth authentication
• auth-github - GitHub OAuth authentication

Learn more about Auth Providers

Other Providers

Additional provider types available:

• Analytics Providers - analytics-local, analytics-posthog
• Caching Providers - caching-redis
• Locking Providers - locking-postgres, locking-redis

Provider Pattern

All providers follow a consistent registration pattern:

import { ModuleProvider, Modules } from "@medusajs/framework/utils"
import { MyProviderService } from "./services/my-provider"

const services = [MyProviderService]

export default ModuleProvider(Modules.PAYMENT, {
  services,
})

Provider Services

Each provider service:

1. Extends an abstract base class (e.g., AbstractPaymentProvider, AbstractFileProviderService)
2. Defines a static identifier property
3. Implements required methods defined by the interface
4. Accepts configuration options via constructor

Example:

export class MyPaymentProvider extends AbstractPaymentProvider {
  static identifier = "my-payment"

  constructor(container, options) {
    super(...arguments)
    this.options_ = options
  }

  async initiatePayment(input) {
    // Implementation
  }

  // ... other required methods
}

Configuration

Providers are configured in your medusa-config.ts file:

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/payment-stripe",
            id: "stripe",
            options: {
              apiKey: process.env.STRIPE_API_KEY,
              webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
            },
          },
        ],
      },
    },
  ],
})

Using Providers

Providers are accessed through their respective modules:

import { Modules } from "@medusajs/framework/utils"

// In a workflow or service
const paymentModule = container.resolve(Modules.PAYMENT)

// Use the provider through the module
await paymentModule.initiatePayment({
  provider_id: "stripe",
  amount: 1000,
  currency_code: "usd",
  // ...
})

Creating Custom Providers

You can create custom providers by:

1. Extending the appropriate abstract provider class
2. Implementing all required methods
3. Defining a unique identifier
4. Registering with ModuleProvider

Each provider type has specific methods and interfaces to implement. See the individual provider documentation for details.

Next Steps

Payment Providers

Integrate payment processing

File Storage Providers

Configure file uploads and storage

Notification Providers

Set up email and notifications

Auth Providers

Add authentication methods