medusa-hyperswitch-prism

Hyperswitch Prism payment provider plugin for Medusa v2. Enables payment processing through multiple connectors — Stripe, Adyen, PayPal, GlobalPay, Braintree, Cybersource, and Mollie — via a unified Prism-powered provider.

Compatibility

| Requirement | Version | |-------------|---------| | Medusa | >= 2.15.0 | | Node.js | >= 20 | | Framework | Medusa v2 |

Installation

npm install medusa-hyperswitch-prism

Setup

1. Environment variables

# Stripe
STRIPE_API_KEY=sk_test_...

# Adyen
ADYEN_API_KEY=AQE...
ADYEN_MERCHANT_ACCOUNT=YourMerchantAccount

# PayPal
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

# GlobalPay
GLOBALPAY_APP_ID=...
GLOBALPAY_APP_KEY=...

2. Register providers in medusa-config.ts

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

export default defineConfig({
  modules: [
    {
      key: Modules.PAYMENT,
      resolve: "@medusajs/payment",
      options: {
        providers: [
          {
            resolve: "medusa-hyperswitch-prism",
            id: "stripe",
            options: {
              connector: "stripe",
              connectorConfig: {
                apiKey: { value: process.env.STRIPE_API_KEY ?? "" },
              },
              environment: "SANDBOX",
            },
          },
          {
            resolve: "medusa-hyperswitch-prism",
            id: "adyen",
            options: {
              connector: "adyen",
              connectorConfig: {
                apiKey: { value: process.env.ADYEN_API_KEY ?? "" },
                merchantAccount: { value: process.env.ADYEN_MERCHANT_ACCOUNT ?? "" },
              },
              environment: "SANDBOX",
            },
          },
          {
            resolve: "medusa-hyperswitch-prism",
            id: "paypal",
            options: {
              connector: "paypal",
              connectorConfig: {
                clientId: { value: process.env.PAYPAL_CLIENT_ID ?? "" },
                clientSecret: { value: process.env.PAYPAL_CLIENT_SECRET ?? "" },
                // "NO_SHIPPING" (default) — hides address collection in the PayPal popup
                // "GET_FROM_FILE" — uses the shipping address already collected by the storefront
                shippingPreference: "NO_SHIPPING",
              },
              environment: "SANDBOX",
            },
          },
          {
            resolve: "medusa-hyperswitch-prism",
            id: "globalpay",
            options: {
              connector: "globalpay",
              connectorConfig: {
                appId: { value: process.env.GLOBALPAY_APP_ID ?? "" },
                appKey: { value: process.env.GLOBALPAY_APP_KEY ?? "" },
              },
              environment: "SANDBOX",
            },
          },
        ],
      },
    },
  ],
})

3. Assign providers to regions

In the Medusa Admin, assign each provider to the regions where it should be available.

4. Switch to production

Change environment per provider when going live:

environment: process.env.NODE_ENV === "production" ? "PRODUCTION" : "SANDBOX",

5. Start the backend

npx medusa develop

Plugin Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | connector | string | Yes | — | "stripe", "adyen", "paypal", "globalpay", "braintree", "cybersource", "mollie" | | connectorConfig | object | Yes | — | Connector-specific credentials (see examples above) | | environment | string | No | "SANDBOX" | "SANDBOX" or "PRODUCTION" | | capture | boolean | No | false | Auto-capture on authorization |

Connector Credentials Reference

| Connector | Required fields in connectorConfig | |-----------|--------------------------------------| | stripe | apiKey | | adyen | apiKey, merchantAccount | | paypal | clientId, clientSecret, shippingPreference (optional) | | globalpay | appId, appKey | | braintree | publicKey, privateKey | | cybersource | apiKey, merchantAccount, apiSecret | | mollie | apiKey |

Each credential value is provided as { value: string } to support secret manager integrations.

Test Cards

Stripe

| Card Number | Expiry | CVV | |-------------|--------|-----| | 4242 4242 4242 4242 | 03/2030 | 737 |

Adyen

| Card Number | Expiry | CVV | |-------------|--------|-----| | 4111 1111 4555 1142 | 03/2030 | 737 |

GlobalPay

| Card Number | Expiry | CVV | |-------------|--------|-----| | 4263 9700 0000 5262 | 03/2030 | 737 |

PayPal

| Card Number | Expiry | CVV | |-------------|--------|-----| | 4032 0366 9170 5063 | 10/2028 | 901 |

Storefront Integration

For React/Next.js storefront integration, see the companion package medusa-hyperswitch-prism-react.

License

MIT