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

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

Configuration

1. Add to medusa-config.ts

1import { defineConfig } from "@medusajs/framework/utils"
2
3export default defineConfig({
4  // ...
5  modules: [
6    {
7      resolve: "@medusajs/medusa/payment",
8      options: {
9        providers: [
10          {
11            resolve: "medusa-payment-monei",
12            id: "monei",
13            options: {
14              apiKey: process.env.MONEI_API_KEY,
15              // Optional: auto-capture payments (default: false)
16              // When false, payments use AUTH + manual capture flow
17              // When true, payments use SALE flow (captured immediately)
18              capture: false,
19            },
20          },
21        ],
22      },
23    },
24  ],
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 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:

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:

API Reference

Provider Options

Session Data

The data object stored in the payment session contains:

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

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/
2  src/
3    modules/
4      monei-payment/
5        service.ts   ← copy from src/service.ts
6        index.ts     ← copy from src/index.ts

Then in medusa-config.ts:

1{
2  resolve: "@medusajs/medusa/payment",
3  options: {
4    providers: [
5      {
6        resolve: "./src/modules/monei-payment",
7        id: "monei",
8        options: {
9          apiKey: process.env.MONEI_API_KEY,
10        },
11      },
12    ],
13  },
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.

License

MIT