MONEI payment provider for Medusa v2. Accept Cards, Bizum, PayPal, Google Pay, Apple Pay, BNPL, MB Way, SEPA Direct Debit and more through MONEI — a licensed European Payment Institution (Banco de España #6911).

Features

Full payment lifecycle: initiate → authorize → capture → refund → cancel
Auth + Capture flow: pre-authorize and capture when ready (default), or auto-capture on authorization
Webhook support: real-time payment status updates with HMAC signature verification
Multi-payment methods: all MONEI payment methods available automatically (Cards, Bizum, PayPal, Google Pay, Apple Pay, etc.)
Hosted Payment Page: redirect customers to MONEI's secure PCI-compliant payment page
monei.js integration: storefront can use MONEI JS SDK for embedded payment components
Partial capture & refund: supported via MONEI API

Prerequisites

Medusa v2 application
MONEI account (sign up)
API Key from MONEI Dashboard → Settings → API Access

Installation

1npm install medusa-payment-monei
2# or
3yarn add medusa-payment-monei

Configuration

1. Add to

1import { defineConfig } from "@medusajs/framework/utils"
2
3export 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,
          },
        },
      ],
    },
  },
],
25})

2. Set environment variables

1# .env
2MONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx

3. Enable in Medusa Admin

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

The provider registers as (format: ).

Payment Flows

Default: Auth + Capture (recommended)

Customer selects MONEI → creates a MONEI payment with
Customer completes payment → redirected to MONEI hosted page or uses monei.js component, completes 3DS if needed
MONEI webhook → receives status, completes the cart
Admin captures → calls MONEI capture API

⏰ Capture window: Card payments must be captured within 7 days, Bizum within 30 days.

Auto-capture (set )

Customer selects MONEI → payment created with
Customer completes payment → funds are captured immediately
Webhook receives status → order is created

Webhooks

MONEI sends asynchronous webhook notifications to your Medusa server. Medusa provides a built-in webhook endpoint:

{your_server_url}/hooks/payment/monei_monei

Setting up webhooks

Configure the callback URL in MONEI Dashboard → Settings → Webhooks, or pass it dynamically via in the payment creation.

The plugin verifies the header using the MONEI Node SDK's built-in signature verification.

Storefront Integration

Option A: Hosted Payment Page (simplest)

After , the session data contains . Redirect the customer:

1// In your checkout component
2const paymentSession = cart.payment_collection?.payment_sessions?.[0]
3
4if (paymentSession?.data?.redirect_url) {
5  window.location.href = paymentSession.data.redirect_url
6}

Option B: monei.js Embedded Components

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

1import monei from "@monei-js/components"
2
3// The payment ID from the session data serves as the client reference
4const paymentId = paymentSession.data.id
5
6// Render card input
7const cardInput = monei.CardInput({
8  paymentId,
9  onChange: (event) => {
10    // Handle validation
11  },
12})
13cardInput.render("#card-input")
14
15// Confirm payment
16const result = await monei.confirmPayment({
17  paymentId,
18  paymentToken: token, // from cardInput.getToken()
19})

Payment Methods

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

Method	Description
Cards	Visa, Mastercard, Amex via 3D Secure
Bizum	Spain's #1 mobile payment (direct acquiring)
PayPal	Global digital wallet
Google Pay	Android/Chrome payments
Apple Pay	iOS/Safari payments
Click to Pay	Visa/Mastercard secure remote commerce
BNPL	Buy now, pay later (Cofidis, Klarna)
MB Way	Portuguese mobile payments
Multibanco	Portuguese bank transfers
SEPA DD	Euro direct debit

API Reference

Provider Options

Option	Type	Default	Description
		required	MONEI API Key
			Auto-capture payments on authorization
		-	Optional webhook signing secret

Session Data

The object stored in the payment session contains:

Field	Description
	MONEI payment ID
	Current MONEI payment status
	URL for hosted payment page
	Reference for monei.js (same as payment ID)
	Medusa session tracking ID

Testing

Use test mode credentials from MONEI Dashboard. Test card numbers and Bizum phone numbers are available in the MONEI Testing documentation.

Common test cards:

Success:
3DS Required:
Declined:

Development

1# Clone and install
2git clone https://github.com/MONEI/medusa-payment-monei.git
3cd medusa-payment-monei
4npm install
5
6# Build
7npm run build
8
9# Watch mode
10npm run watch

Using as a local module in Medusa

During development, you can place the plugin source directly in your Medusa app:

1your-medusa-app/
src/
  modules/
    monei-payment/
      service.ts   ← copy from src/service.ts
      index.ts     ← copy from src/index.ts

Then in :

1{
resolve: "@medusajs/medusa/payment",
options: {
  providers: [
    {
      resolve: "./src/modules/monei-payment",
      id: "monei",
      options: {
        apiKey: process.env.MONEI_API_KEY,
      },
    },
  ],
},
14}

About MONEI

MONEI is a licensed Payment Institution regulated by Banco de España (#6911) and a SWIFT member (BIC: MDIPES22). MONEI provides a unified payments platform for European merchants with direct acquiring for Bizum and multi-acquirer card processing.