Skip to main content

Medusa

Accept payments through MONEI in your Medusa v2 store using the official medusa-payment-monei plugin. All MONEI payment methods are available automatically — Cards, Bizum, PayPal, Google Pay, Apple Pay, , MB Way, and Multibanco.

Features​

  • Full payment lifecycle — Initiate, , , refund (full and partial), and cancel
  • Auth + Capture flow — when ready (default), or auto-capture on authorization
  • Webhook support — Real-time payment status updates with signature verification
  • Multi-payment methods — All MONEI payment methods available automatically
  • MONEI Flex — card installments in Spain, shown automatically on eligible card payments once MONEI Flex is activated for your account
  • Two integration modes — Hosted Payment Page (redirect) or embedded MONEI.js components

Requirements​

DependencyVersion
Node.js20+
Medusav2

Before you begin​

To test your integration:

Install​

npm install medusa-payment-monei
# or
yarn add medusa-payment-monei

Configure​

Step 1: Add to medusa-config.ts​

import {defineConfig} from '@medusajs/framework/utils';

export default defineConfig({
  // ...
  modules: [
    {
      resolve: '@medusajs/medusa/payment',
      options: {
        providers: [
          {
            resolve: 'medusa-payment-monei',
            id: 'monei',
            options: {
              apiKey: process.env.MONEI_API_KEY,
              // Optional: auto-capture payments (default: false)
              // When false, payments use AUTH + manual capture flow
              // When true, payments use SALE flow (captured immediately)
              capture: false
            }
          }
        ]
      }
    }
  ]
});

Step 2: Set environment variables​

# .env
MONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx

Step 3: Enable in Medusa Admin​

Go to Settings → Regions and enable MONEI for your region(s).

MONEI registers as pp_monei_monei.

Configuration options​

OptionTypeDefaultDescription
apiKeystringrequiredYour MONEI API key
capturebooleanfalseAuto-capture payments on authorization
webhookSecretstring—Optional webhook signing secret

Payment flows​

Default: Auth + Capture (recommended)​

  1. Customer selects MONEI → payment is created with transactionType: AUTH
  2. Customer completes payment on the MONEI Hosted Payment Page or via MONEI.js component
  3. MONEI sends a webhook with AUTHORIZED status → order is created
  4. Admin captures the payment from the Medusa dashboard
note

Card payments must be captured within 7 days, Bizum within 30 days.

Auto-capture (set capture: true)​

  1. Customer selects MONEI → payment is created with transactionType: SALE
  2. Customer completes payment → funds are captured immediately
  3. Webhook receives SUCCEEDED status → order is created

Webhooks​

MONEI sends asynchronous webhook notifications to your Medusa server at:

{your_server_url}/hooks/payment/monei_monei

The plugin verifies the MONEI-Signature header using HMAC-SHA256 signature verification.

Configure the in MONEI Dashboard → Settings, or it will be set dynamically during payment creation.

Storefront integration​

Option A: Hosted Payment Page (simplest)​

After initiating the payment session, the session data contains a redirect_url. Redirect the customer:

const paymentSession = cart.payment_collection?.payment_sessions?.[0];

if (paymentSession?.data?.redirect_url) {
  window.location.href = paymentSession.data.redirect_url;
}

Option B: Embedded MONEI.js Components​

Use the MONEI JS SDK to embed payment components directly in your checkout:

import monei from '@monei-js/components';

const paymentId = paymentSession.data.id;

// Render card input
const cardInput = monei.CardInput({
  paymentId,
  onChange: (event) => {
    // Handle validation
  }
});
cardInput.render('#card-input');

// Tokenize the card, then confirm the payment
const {token, error} = await cardInput.submit();
if (error) {
  // Show the error to the customer
  return;
}

const result = await monei.confirmPayment({
  paymentId,
  paymentToken: token
});

Payment methods​

All payment methods enabled in your MONEI Dashboard are automatically available:

MethodDescription
CardsVisa, Mastercard via 3D Secure
BizumSpain's #1 mobile payment (direct acquiring)
PayPalGlobal digital wallet
Google PayAndroid/Chrome payments
Apple PayiOS/Safari payments
Visa/Mastercard secure remote commerce
BNPLBuy now, pay later
MB WayPortuguese mobile payments
MultibancoPortuguese bank transfers

Before you go live​