medusa-payment-provider-adapter

A universal adapter to make Medusa 2.8.x payment provider plugins compatible with Medusa 2.10.3+

🚀 Why This Plugin?

Medusa v2.5.0 introduced a major refactoring of the payment interface. Payment provider plugins designed for Medusa 2.8.x are not compatible with Medusa 2.10.3+, causing:

• ❌ "moduleProviderServices is not iterable" errors
• ❌ Payment providers not auto-registering in the database
• ❌ Providers not appearing in the Medusa Admin

This adapter fixes all these issues using an AOP (Aspect-Oriented Programming) approach.

📦 Installation

npm install medusa-payment-provider-adapter
# or
yarn add medusa-payment-provider-adapter
# or
pnpm add medusa-payment-provider-adapter

🎯 Quick Start

1. Create an Adapter Module

Create a file src/modules/your-provider-adapter/index.ts:

import { createPaymentProviderAdapter } from "medusa-payment-provider-adapter"

// Replace with your legacy payment provider package path
export default createPaymentProviderAdapter("@vendor/medusa-payment-plugin/providers/provider-name")

2. Configure in medusa-config.ts

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

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "./src/modules/your-provider-adapter",  // ← Use your adapter
            id: "your-provider-id",
            options: {
              apiKey: process.env.YOUR_API_KEY,
              // ... other provider options
            },
          },
        ],
      },
    },
  ],
})

3. Start Your Medusa App

npm run dev

✅ Your payment provider is now auto-registered!

📚 Real-World Examples

Example 1: PayPal (@alphabite/medusa-paypal)

// src/modules/paypal-adapter/index.ts
import { createPaymentProviderAdapter } from "medusa-payment-provider-adapter"

export default createPaymentProviderAdapter("@alphabite/medusa-paypal/providers/paypal")

// medusa-config.ts
export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "./src/modules/paypal-adapter",
            id: "paypal",
            options: {
              clientId: process.env.PAYPAL_CLIENT_ID,
              clientSecret: process.env.PAYPAL_CLIENT_SECRET,
              isSandbox: process.env.PAYPAL_IS_SANDBOX === "true",
            },
          },
        ],
      },
    },
  ],
})

Example 2: Custom Payment Provider

// src/modules/custom-pay-adapter/index.ts
import { createPaymentProviderAdapter } from "medusa-payment-provider-adapter"

export default createPaymentProviderAdapter("@your-company/medusa-custom-pay/providers/custom")

🔍 How It Works

The adapter uses an AOP (Aspect-Oriented Programming) approach:

┌─────────────────────────────────────────────────────────────┐
│ Legacy Plugin (Medusa 2.8.x)                                │
│                                                              │
│ export default ModuleProvider(Modules.PAYMENT, {            │
│   services: [YourPaymentService]                            │
│ })                                                           │
└─────────────────────────────────────────────────────────────┘
                            ↓
                   [Adapter Intercepts]
                            ↓
                  Unwraps __definition
                            ↓
              Extracts services[0] = YourPaymentService
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Adapted Export (Medusa 2.10.3+ Compatible)                  │
│                                                              │
│ export default YourPaymentService  ← Direct class export    │
└─────────────────────────────────────────────────────────────┘
                            ↓
              ✅ Auto-registers in database
              ✅ Works in Medusa Admin
              ✅ Full payment functionality

🛠️ API Reference

createPaymentProviderAdapter(packagePath: string): PaymentProviderService

Creates an adapter for a legacy payment provider plugin.

Parameters:

• packagePath (string): The provider export path from the legacy plugin package

Returns:

• The unwrapped payment provider service class

Throws:

• Error if the package cannot be loaded or doesn't have a valid provider export

Example:

const PayPalService = createPaymentProviderAdapter("@alphabite/medusa-paypal/providers/paypal")

❓ When Do You Need This Adapter?

Use this adapter if you encounter any of these issues:

1. Error Message: "moduleProviderServices is not iterable"
2. Auto-Registration Failure: Provider doesn't appear in the payment_provider database table
3. Version Mismatch: Plugin requires Medusa 2.8.x, but you're using 2.10.x
4. Admin Panel: Payment provider not showing up in region configuration

✅ Compatibility

• Medusa Version: 2.10.0+
• Node.js: 20+
• Legacy Plugins: Any payment provider plugin designed for Medusa 2.8.x

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © [Your Name]

🙏 Acknowledgments

• Inspired by the need to maintain compatibility during Medusa's payment interface refactoring
• Thanks to the Medusa.js team for building an amazing e-commerce platform
• Special thanks to the community for identifying and reporting compatibility issues

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Join the discussion

🔗 Related Links

• Medusa Documentation
• Medusa Payment Module
• Medusa v2.5.0 Release Notes

Made with ❤️ for the Medusa community