# Medusa

Accept payments through MONEI in your [Medusa](https://medusajs.com/) v2 store using the official [medusa-payment-monei](https://www.npmjs.com/package/medusa-payment-monei) plugin. All MONEI payment methods are available automatically — Cards, Bizum, PayPal, Google Pay, Apple Pay, BNPL, MB Way, Multibanco, and SEPA Direct Debit.

## Features[​](#features "Direct link to Features")

* **Full payment lifecycle** — Initiate, authorize, capture, refund (full and partial), and 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
* **Two integration modes** — Hosted Payment Page (redirect) or embedded MONEI.js components

## Requirements[​](#requirements "Direct link to Requirements")

| Dependency | Version |
| ---------- | ------- |
| Node.js    | 18+     |
| Medusa     | v2      |

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

To test your integration:

* Use your [test mode](https://docs.monei.com/testing/.md) API Key. You can find it in [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api).
* You can check the status of a test payment in your [MONEI Dashboard → Payments](https://dashboard.monei.com/payments) (in test mode).
* See [MONEI test cards](https://docs.monei.com/testing/.md) for test card numbers and Bizum phone numbers.

## Install[​](#install "Direct link to Install")

```
npm install medusa-payment-monei

# or

yarn add medusa-payment-monei
```

## Configure[​](#configure "Direct link to Configure")

### Step 1: Add to `medusa-config.ts`[​](#step-1-add-to-medusa-configts "Direct link to step-1-add-to-medusa-configts")

```
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

            }

          }

        ]

      }

    }

  ]

});
```

### Step 2: Set environment variables[​](#step-2-set-environment-variables "Direct link to Step 2: Set environment variables")

```
# .env

MONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx
```

### Step 3: Enable in Medusa Admin[​](#step-3-enable-in-medusa-admin "Direct link to Step 3: Enable in Medusa Admin")

Go to **Settings → Regions** and enable MONEI for your region(s).

MONEI registers as `pp_monei_monei`.

### Configuration options[​](#configuration-options "Direct link to Configuration options")

| Option          | Type    | Default    | Description                            |
| --------------- | ------- | ---------- | -------------------------------------- |
| `apiKey`        | string  | *required* | Your MONEI API key                     |
| `capture`       | boolean | `false`    | Auto-capture payments on authorization |
| `webhookSecret` | string  | —          | Optional webhook signing secret        |

## Payment flows[​](#payment-flows "Direct link to Payment flows")

### Default: Auth + Capture (recommended)[​](#default-auth--capture-recommended "Direct link to Default: Auth + Capture (recommended)")

1. Customer selects MONEI → payment is created with `transactionType: AUTH`
2. Customer completes payment on MONEI hosted page or via MONEI.js component
3. MONEI sends a webhook with `AUTHORIZED` status → order is created
4. Admin captures the payment from the Medusa dashboard

<!-- -->

note

Card payments must be captured within **7 days**, Bizum within **30 days**.

### Auto-capture (set `capture: true`)[​](#auto-capture-set-capture-true "Direct link to auto-capture-set-capture-true")

1. Customer selects MONEI → payment is created with `transactionType: SALE`
2. Customer completes payment → funds are captured immediately
3. Webhook receives `SUCCEEDED` status → order is created

## Webhooks[​](#webhooks "Direct link to Webhooks")

MONEI sends asynchronous webhook notifications to your Medusa server at:

```
{your_server_url}/hooks/payment/monei_monei
```

The plugin verifies the `MONEI-Signature` header using HMAC-SHA256 signature verification.

Configure the callback URL in [MONEI Dashboard → Settings](https://dashboard.monei.com/settings), or it will be set dynamically during payment creation.

## Storefront integration[​](#storefront-integration "Direct link to Storefront integration")

### Option A: Hosted Payment Page (simplest)[​](#option-a-hosted-payment-page-simplest "Direct link to Option A: Hosted Payment Page (simplest)")

After initiating the payment session, the session data contains a `redirect_url`. Redirect the customer:

```
const paymentSession = cart.payment_collection?.payment_sessions?.[0];



if (paymentSession?.data?.redirect_url) {

  window.location.href = paymentSession.data.redirect_url;

}
```

### Option B: Embedded MONEI.js Components[​](#option-b-embedded-moneijs-components "Direct link to Option B: Embedded MONEI.js Components")

Use the [MONEI JS SDK](https://docs.monei.com/monei-js/overview/.md) to embed payment components directly in your checkout:

```
import monei from '@monei-js/components';



const paymentId = paymentSession.data.id;



// Render card input

const cardInput = monei.CardInput({

  paymentId,

  onChange: (event) => {

    // Handle validation

  }

});

cardInput.render('#card-input');



// Tokenize the card, then confirm the payment

const {token, error} = await cardInput.submit();

if (error) {

  // Show the error to the customer

  return;

}



const result = await monei.confirmPayment({

  paymentId,

  paymentToken: token

});
```

## Payment methods[​](#payment-methods "Direct link to Payment methods")

All payment methods enabled in your [MONEI Dashboard](https://dashboard.monei.com/settings/payment-methods) 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                           |
| **MB Way**       | Portuguese mobile payments                   |
| **Multibanco**   | Portuguese bank transfers                    |
| **SEPA DD**      | Euro direct debit                            |

## Before you go live[​](#before-you-go-live "Direct link to Before you go live")

* Make sure that you are using [live (production) mode](https://docs.monei.com/testing/.md) API Key.
* Make sure that you have at least one active [payment method](https://dashboard.monei.com/settings/payment-methods).

## Links[​](#links "Direct link to Links")

* [medusa-payment-monei on npm](https://www.npmjs.com/package/medusa-payment-monei)
* [medusa-payment-monei on GitHub](https://github.com/MONEI/medusa-payment-monei)
* [MONEI JS SDK documentation](https://docs.monei.com/monei-js/overview/.md)
* [Medusa Payment Module documentation](https://docs.medusajs.com/resources/commerce-modules/payment)