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

Configuration

1. Add to medusa-config.ts

2. Set environment variables

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:

Option B: monei.js Embedded Components

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

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

Using as a local module in Medusa

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

Then in medusa-config.ts:

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