A DeroPay gateway pointed at a DERO wallet RPC. See the gateway setup guide for a step-by-step walkthrough. By default the gateway listens on port 3080.
Medusa.js v2 — this plugin requires Medusa v2 and will not work on v1.

Installation

Medusa v2 projects are monorepos with an apps/backend/ directory. Install the plugin inside the backend workspace:

# From your project root
cd apps/backend
npm install medusa-payment-deropay
# or
bun add medusa-payment-deropay

Configuration

Edit apps/backend/medusa-config.ts to register the provider:

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

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

module.exports = defineConfig({
  projectConfig: {
    // ... your existing config
  },
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-payment-deropay",
            id: "deropay",
            options: {
              gatewayUrl: process.env.DEROPAY_GATEWAY_URL!,
              apiKey: process.env.DEROPAY_API_KEY!,
              webhookSecret: process.env.DEROPAY_WEBHOOK_SECRET,
            },
          },
        ],
      },
    },
  ],
});

Add the corresponding variables to apps/backend/.env:

DEROPAY_GATEWAY_URL=http://localhost:3080
DEROPAY_API_KEY=your-api-key
DEROPAY_WEBHOOK_SECRET=your-webhook-secret

Options

Option	Required	Description
`gatewayUrl`	Yes	Base URL of your DeroPay gateway (e.g. `http://localhost:3080`)
`apiKey`	Yes	API key for the gateway. Set `DEROPAY_API_KEYS` in the gateway's env to enable key auth.
`webhookSecret`	Yes	HMAC-SHA256 secret for webhook signature verification. Required — without it, a forged webhook could mark an order paid with no real payment.

Activating the payment provider in admin

After starting Medusa, you must activate DeroPay as a payment provider for a region before it appears at checkout:

Open the admin at http://localhost:9000/app
Go to Settings → Regions
Select or create a region
Under Payment Providers, enable DeroPay

You will also need a Publishable API Key for any storefront that calls the Store API:

Go to Settings → API Key Management
Create a new Publishable key
Pass it as the x-publishable-api-key header on all storefront requests

Webhook Setup

Configure your DeroPay gateway to send webhooks to your Medusa backend:

Webhook URL: https://your-medusa-store.com/hooks/payment/deropay_deropay

The gateway sends { invoiceId, status, metadata } payloads. The plugin maps invoiceId to the Medusa payment session for automatic order completion.

How It Works

initiatePayment — Creates a DeroPay invoice when the customer reaches checkout. Returns the invoice ID and integrated DERO address.
authorizePayment — Polls invoice status. Maps completed → captured, confirming → authorized, expired → error.
capturePayment — No-op. DERO settles on-chain so capture is implicit at authorization.
getPaymentStatus — Used by Medusa to poll status during the checkout flow.
getWebhookActionAndData — Verifies the gateway webhook signature (required) and returns the captured/authorized action so Medusa can auto-complete orders without polling.

Important Notes

Refunds: On-chain DERO payments cannot be automatically refunded. The plugin logs a warning and returns success — process refunds manually from the admin or by contacting the customer directly.
Fiat conversion: Non-DERO currencies (e.g. USD, EUR) are automatically converted to DERO atomic amounts by the gateway using live price feeds. Set your region currency to DERO to use atomic amounts directly.
Self-hosted: Both the Medusa store and the DeroPay gateway are self-hosted. No third-party payment processor handles your funds.