HyperSwitch Payment Processor Plugin for Medusa

Medusa v2 payment plugin for HyperSwitch — unified checkout, webhooks, refunds, proxy support, and an admin configuration UI.

Features

• Process payments through HyperSwitch's unified API
• Multiple payment methods with a unified checkout experience
• Webhook handling and payment status synchronization
• Manual and automatic capture modes
• Refund processing
• Admin UI for API keys, proxy, customization, and logging

Prerequisites

• Medusa v2.15+
• Node.js v20+
• A HyperSwitch account and API keys

Installation

Follow these steps in your Medusa store project (the app where you run medusa develop), not in this plugin repository.

Step 1: Create a Medusa application (if you don't have one)

npx create-medusa-app@latest my-medusa-store
cd my-medusa-store

Step 2: Install the plugin package

From your Medusa application root directory, install the plugin:

npm install medusa-payment-hyperswitch

Or with another package manager:

yarn add medusa-payment-hyperswitch
# or
pnpm add medusa-payment-hyperswitch

This installs the plugin and its runtime dependencies (axios, axios-retry, https-proxy-agent, and admin UI packages). Your Medusa app must already satisfy the peer dependencies (@medusajs/framework, @medusajs/medusa, etc. at v2.15+).

Local development: To test unpublished changes from this repo, use npx medusa plugin:add medusa-payment-hyperswitch after running npx medusa plugin:publish in the plugin repo. See Local plugin development.

Step 3: Set the encryption key

Generate a 32-byte key for encrypting secrets stored by the plugin:

openssl rand -base64 32

Add it to your .env:

HYPERSWITCH_HASH_KEY=your-generated-base64-key-here

Step 4: Configure Medusa

Update medusa-config.ts:

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

loadEnv(process.env.NODE_ENV || "development", process.cwd())

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS!,
      adminCors: process.env.ADMIN_CORS!,
      authCors: process.env.AUTH_CORS!,
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    },
  },
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            id: "hyperswitch",
            resolve: "medusa-payment-hyperswitch/providers/hyperswitch",
          },
        ],
      },
    },
  ],
  plugins: [
    {
      resolve: "medusa-payment-hyperswitch",
      options: {
        key: process.env.HYPERSWITCH_HASH_KEY,
      },
    },
  ],
})

Step 5: Run migrations and start

npx medusa db:migrate
npm run dev

Step 6: Configure in Admin

1. Open the Medusa Admin panel (e.g. http://localhost:9000/app)
2. Go to Extensions → Hyperswitch
3. Enter your HyperSwitch API keys, profile ID, and environment
4. Enable the payment provider for your region in Settings → Regions

Local plugin development

To work on the plugin itself and test it in a Medusa store:

git clone https://github.com/Ayyanaruto/hyperswitch-medusajs-plugin.git
cd hyperswitch-medusajs-plugin
pnpm install
pnpm build
npx medusa plugin:publish

In your Medusa store:

npx medusa plugin:add medusa-payment-hyperswitch

Keep pnpm dev running in the plugin repo during development so changes are republished automatically.

Publishing to npm

From the plugin repository:

pnpm build
npm publish

The prepublishOnly script runs the build automatically before publish.

Troubleshooting

• Payment errors — Check Medusa server logs and the plugin's logging dashboard in Admin
• Webhooks — Verify webhook URLs and signing in your HyperSwitch dashboard
• API keys — Confirm sandbox vs production keys match your configured environment
• Proxy — Configure proxy settings in the Admin UI if your server requires one

Resources

• HyperSwitch Documentation
• Plugin Repository
• Medusa Plugin Guide
• Report an Issue

License

MIT