MONEI

medusa-payment-monei

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

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

Configuration

1. Add to Copy to clipboardmedusa-config.ts

1234567891011121314151617181920
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,
            },
          },

2. Set environment variables

12
# .env
MONEI_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 Copy to clipboardpp_monei_monei (format: Copy to clipboardpp_{identifier}_{id}).

Payment Flows

Default: Auth + Capture (recommended)

1. Customer selects MONEI → Copy to clipboardinitiatePayment creates a MONEI payment with Copy to clipboardtransactionType: AUTH
2. Customer completes payment → redirected to MONEI hosted page or uses monei.js component, completes 3DS if needed
3. MONEI webhook → Copy to clipboardgetWebhookActionAndData receives Copy to clipboardAUTHORIZED status, completes the cart
4. Admin captures → Copy to clipboardcapturePayment calls MONEI capture API

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

Auto-capture (set Copy to clipboardcapture: true)

1. Customer selects MONEI → payment created with Copy to clipboardtransactionType: SALE
2. Customer completes payment → funds are captured immediately
3. Webhook receives Copy to clipboardSUCCEEDED status → order is created

Webhooks

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

1
{your_server_url}/hooks/payment/monei_monei

Setting up webhooks

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

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

Storefront Integration

Option A: Hosted Payment Page (simplest)

After Copy to clipboardinitiatePayment, the session data contains Copy to clipboardredirect_url. Redirect the customer:

123456
// In your checkout component
const paymentSession = cart.payment_collection?.payment_sessions?.[0]

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

Option B: monei.js Embedded Components

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

12345678910111213141516171819
import monei from "@monei-js/components"

// The payment ID from the session data serves as the client reference
const paymentId = paymentSession.data.id

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

// Confirm payment
const result = await monei.confirmPayment({
  paymentId,
  paymentToken: token, // from cardInput.getToken()
})

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 Copy to clipboardapiKey Copy to clipboardstring required MONEI API Key Copy to clipboardcapture Copy to clipboardboolean Copy to clipboardfalse Auto-capture payments on authorization Copy to clipboardwebhookSecret Copy to clipboardstring - Optional webhook signing secret

Session Data

The Copy to clipboarddata object stored in the payment session contains:

Field Description Copy to clipboardid MONEI payment ID Copy to clipboardstatus Current MONEI payment status Copy to clipboardredirect_url URL for hosted payment page Copy to clipboardclient_secret Reference for monei.js (same as payment ID) Copy to clipboardsession_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: Copy to clipboard4111 1111 1111 1111
• 3DS Required: Copy to clipboard4000 0000 0000 3220
• Declined: Copy to clipboard4000 0000 0000 0002

Development

12345678910
# Clone and install
git clone https://github.com/MONEI/medusa-payment-monei.git
cd medusa-payment-monei
npm install

# Build
npm run build

# Watch mode
npm run watch

Using as a local module in Medusa

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

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

Then in Copy to clipboardmedusa-config.ts:

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

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.

License

MIT