Hyperswitch

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)

1npx create-medusa-app@latest my-medusa-store
2cd 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:

1yarn add medusa-payment-hyperswitch
2# or
3pnpm 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:

1import { loadEnv, defineConfig } from "@medusajs/framework/utils"
2
3loadEnv(process.env.NODE_ENV || "development", process.cwd())
4
5module.exports = defineConfig({
6  projectConfig: {
7    databaseUrl: process.env.DATABASE_URL,
8    http: {
9      storeCors: process.env.STORE_CORS!,
10      adminCors: process.env.ADMIN_CORS!,
11      authCors: process.env.AUTH_CORS!,
12      jwtSecret: process.env.JWT_SECRET || "supersecret",
13      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
14    },
15  },
16  modules: [
17    {
18      resolve: "@medusajs/medusa/payment",
19      options: {
20        providers: [
21          {
22            id: "hyperswitch",
23            resolve: "medusa-payment-hyperswitch/providers/hyperswitch",
24          },
25        ],
26      },
27    },
28  ],
29  plugins: [
30    {
31      resolve: "medusa-payment-hyperswitch",
32      options: {
33        key: process.env.HYPERSWITCH_HASH_KEY,
34      },
35    },
36  ],
37})

Step 5: Run migrations and start

1npx medusa db:migrate
2npm 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:

1git clone https://github.com/Ayyanaruto/hyperswitch-medusajs-plugin.git
2cd hyperswitch-medusajs-plugin
3pnpm install
4pnpm build
5npx 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:

1pnpm build
2npm 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