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

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

Configuration

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,
            },
          },
        ],
      },
    },
  ],
})

2. Set environment variables

# .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 pp_monei_monei (format: pp_{identifier}_{id}).

Payment Flows

Default: Auth + Capture (recommended)

1. Customer selects MONEI → initiatePayment creates a MONEI payment with transactionType: AUTH
2. Customer completes payment → redirected to MONEI hosted page or uses monei.js component, completes 3DS if needed
3. MONEI webhook → getWebhookActionAndData receives AUTHORIZED status, completes the cart
4. Admin captures → capturePayment calls MONEI capture API

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

Auto-capture (set capture: true)

1. Customer selects MONEI → payment 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. 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 callbackUrl in the payment creation.

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

Storefront Integration

Option A: Hosted Payment Page (simplest)

After initiatePayment, the session data contains redirect_url. Redirect the customer:

// 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:

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 | |--------|------|---------|-------------| | apiKey | string | required | MONEI API Key | | capture | boolean | false | Auto-capture payments on authorization | | webhookSecret | string | - | Optional webhook signing secret |

Session Data

The data object stored in the payment session contains:

| Field | Description | |-------|-------------| | id | MONEI payment ID | | status | Current MONEI payment status | | redirect_url | URL for hosted payment page | | client_secret | Reference for monei.js (same as payment ID) | | session_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: 4111 1111 1111 1111
• 3DS Required: 4000 0000 0000 3220
• Declined: 4000 0000 0000 0002

Development

# 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:

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

Then in medusa-config.ts:

{
  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