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 plugin's peer dependencies.

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

Storefront Integration (Next.js Starter)

Use this plugin with the storefront repo:
https://github.com/Ayyanaruto/hyperswitch-medusa-storefront

Storefront environment variables

In your storefront project's .env.local, set:

1NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_
2MEDUSA_BACKEND_URL=http://localhost:9000
3NEXT_PUBLIC_BASE_URL=http://localhost:8000
4NEXT_PUBLIC_HYPERSWITCH_KEY=pk_snd_

Enable HyperSwitch in the target region

In Medusa Admin:

1. Open Settings → Regions
2. Select your region
3. Add/enable hyperswitch payment provider
4. Save changes

4) Test checkout from the storefront

1. Start backend (npm run dev in your Medusa app)
2. Start storefront (yarn dev in your Next.js app)
3. Add a product to cart and proceed to checkout
4. Select HyperSwitch payment method and place an order

5) Validate webhooks (recommended)

For reliable payment state updates, configure HyperSwitch webhooks to point to your Medusa backend webhook endpoint and verify events are received in backend logs.

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