# Adobe Commerce (Magento 2)

MONEI Payments for Adobe Commerce (Magento 2) allows you to seamlessly integrate MONEI's payment processing capabilities into your Magento store. This official module provides a secure, reliable, and user-friendly payment experience for your customers.

[Live demo](https://magento2-demo.monei.com/)

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

| Component     | Minimum                                     |
| ------------- | ------------------------------------------- |
| Magento       | 2.4.4 (2.4.0–2.4.3 are EOL)                 |
| PHP           | 8.1                                         |
| MONEI PHP SDK | ^2.6 (installed automatically via Composer) |

You also need a [MONEI account](https://dashboard.monei.com/signup).

The module is published on the [Magento Marketplace](https://marketplace.magento.com/monei-module-monei-payment.html) and on [Packagist](https://packagist.org/packages/monei/module-monei-payment).

## 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).

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

<!-- -->

* Using composer (recommended)
* From the raw package

Go to your Adobe Commerce (Magento 2) root directory and run the following commands:

1. Add the package to your Magento installation:

```
composer require monei/module-monei-payment
```

2. Enable the module:

```
bin/magento module:enable Monei_MoneiPayment
```

3. Run the following commands to upgrade and compile the module:

```
bin/magento setup:upgrade

bin/magento setup:di:compile

bin/magento setup:static-content:deploy

bin/magento cache:clean
```

The MONEI PHP SDK is pulled in transitively by Composer.

Go to your Adobe Commerce (Magento 2) root directory.

1. Download the latest release from the [GitHub repository](https://github.com/MONEI/MONEI-AdobeCommerce-Magento2/releases)
2. Extract the contents to your `app/code/Monei/MoneiPayment` directory
3. Install the MONEI PHP SDK:

```
composer require monei/monei-php-sdk:^2.6
```

4. Go to your Adobe Commerce (Magento 2) root directory and run:

```
bin/magento module:enable Monei_MoneiPayment

bin/magento setup:upgrade

bin/magento setup:di:compile

bin/magento setup:static-content:deploy

bin/magento cache:clean
```

Bitnami stacks

On Bitnami Magento images, use `bin/magento-cli` (instead of `bin/magento`) and prefix each command with `sudo`, otherwise the commands fail with permission errors.

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

To configure the extension you have to go to **Stores → Configuration → Sales → Payment Methods → MONEI**.

![Configure MONEI Adobe Commerce](/assets/images/configure-magento-0-b412ddb6188c101361e865f26d8e0a75.png)

Enter your API Key. You can find your API Key in [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api). Set **Mode** to **Test** or **Production** to choose which API Key + Account ID pair is used.

From the configuration screen you can:

* Set **Payment Action** to **Sale** (auth + capture) or **Authorize** (capture later by creating an invoice). Pre-authorization is not supported for MB Way or Multibanco and is silently downgraded to capture for those methods.
* Enable or disable each payment method individually (Card, Card Vault, Bizum, Apple Pay / Google Pay, PayPal, Multibanco, MB Way, and the generic redirect method).
* Enable **card tokenization** to let returning customers pay with a stored card via Magento Vault.

For more information on how to configure the extension, please refer to the [MONEI Adobe Commerce Extension documentation](https://github.com/MONEI/MONEI-AdobeCommerce-Magento2/blob/main/README.md).

### Card field layout[​](#card-field-layout "Direct link to Card field layout")

Under **MONEI Card Insite**, **Card Field Layout** decides how the card form looks.

![Card Field Layout setting](/assets/images/configure-magento-card-layout-a4835e8b75c5d72480e1ee2e56fcf064.png)

**Separate fields** (default) — card number, expiry and CVC each get their own field, styled to match the theme's own inputs. Focus moves from number to expiry to CVC as the customer types.

![Separate card fields](/assets/images/configure-magento-card-fields-f6e5a6943834e55721df8fd8da462871.png)

**Single field** — all three share one field, which suits a compact checkout.

![Single card field](/assets/images/configure-magento-card-fields-single-7dc322d909cffa7e53634e460b9367c8.png)

**Json style** themes both layouts from the same JSON, so switching layout keeps your styling.

Separate fields became the default in v2.3.0

Up to v2.2.4 the card form was a single field. If you never chose a layout, your checkout moves to separate fields when you update — pick **Single field** under **MONEI Card Insite** to keep the old form. A layout you already selected is kept.

Whichever you pick, card details go straight to MONEI and your PCI DSS scope stays at SAQ A.

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

* Card (Visa, Mastercard, and more) — with Magento Vault tokenization for saved cards
* Apple Pay (domain registration is performed automatically when the method is enabled)
* Google Pay
* Bizum (Spain — automatically hidden for non-Spanish customers)
* PayPal
* Multibanco (Portugal — redirect only, no pre-auth)
* MB Way (Portugal — redirect only, no pre-auth)
* MONEI Flex card installments (Spain) — shown automatically on eligible card payments once [MONEI Flex](https://docs.monei.com/payment-methods/monei-flex.md) is activated for your account

## Express checkout[​](#express-checkout "Direct link to Express checkout")

Express checkout puts Apple Pay, Google Pay and PayPal buttons on the cart page, in the mini cart and on the product page. The customer pays from the wallet sheet, and the shipping and billing address comes from the wallet, so nobody fills in the checkout form. The shipping methods and the total in the sheet are the store's own: the module recalculates them for the address the customer picks.

![Express checkout buttons on the cart page](/assets/images/configure-magento-express-cart-7792d64a1a4b60a0e9d45c05af26dc58.png)

Requires module v2.4.0

Express checkout on all three surfaces is available from module version 2.4.0. Versions 2.3.x carried an earlier form of it on the cart, mini cart and checkout page.

To turn it on, go to **Stores → Configuration → Sales → Payment Methods → MONEI → Express Checkout** and set:

| Setting                     | What it does                                                                                              |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Enable Express Checkout** | Turns the buttons on. Off by default.                                                                     |
| **Show on Product Page**    | Button under **Add to Cart**.                                                                             |
| **Show on Cart Page**       | Buttons under **Proceed to Checkout** in the cart summary.                                                |
| **Show in Mini Cart**       | Buttons under **Proceed to Checkout** in the mini cart.                                                   |
| **PayPal Express Checkout** | Adds the PayPal button next to the wallet button. Needs the PayPal payment method enabled. On by default. |
| **Json style**              | Themes the buttons in JSON — for example `{"height":"45px"}`.                                             |

![Express checkout settings](/assets/images/configure-magento-express-20766abcbf3f3fd3ea1b1a2134d5387a.png)

The same conditions as the regular payment methods apply. Apple Pay needs your [domain registered](https://dashboard.monei.com/settings/payment-methods), and the Apple Pay or Google Pay button only appears for a customer whose device and browser can pay with that wallet. A wallet order shows in **Sales → Orders** under the express payment method; a PayPal express order under the PayPal method.

For the equivalent in a custom integration, see [Express checkout](https://docs.monei.com/integrations/express-checkout.md).

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

* Switch **Mode** to **Production** and confirm the production API Key + Account ID are filled.
* Make sure that you have at least one active [payment method](https://dashboard.monei.com/settings/payment-methods).
* Verify your webhook URL is reachable from MONEI (no IP allowlist, no Cloudflare bot block, no Varnish caching the callback path).
* Confirm cron is running (`bin/magento cron:status`) — the hourly job is the safety net for any missed webhooks.
* For Apple Pay, verify your domain shows in [MONEI Dashboard → Settings → Payment methods](https://dashboard.monei.com/settings/payment-methods).