# Sylius

Accept payments through MONEI in your [Sylius](https://sylius.com/) store using the official [MONEI Payment Plugin](https://packagist.org/packages/monei/sylius-monei-plugin). The plugin supports Cards (Visa, Mastercard, Amex), Bizum, Apple Pay, and Google Pay with two integration modes — hosted payment page or embedded payment component.

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

* **Two integration modes** — Hosted Payment Page (redirect) or Embedded MONEI Component (JS widget), configurable per gateway in the Sylius admin
* **All MONEI payment methods** — Cards, Bizum, Apple Pay, Google Pay
* **Full lifecycle support** — Capture, Refund (full and partial), Cancel, and Status sync
* **Webhook-driven** — Asynchronous payment status updates via signed MONEI webhooks
* **PSD2 / SCA ready** — 3D Secure handled automatically by MONEI

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

| Dependency | Version    |
| ---------- | ---------- |
| PHP        | 8.2+       |
| Sylius     | 2.1+       |
| Symfony    | 6.4 or 7.x |

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

### Step 1: Install via Composer[​](#step-1-install-via-composer "Direct link to Step 1: Install via Composer")

```
composer require monei/sylius-monei-plugin
```

### Step 2: Register the bundle[​](#step-2-register-the-bundle "Direct link to Step 2: Register the bundle")

If your Sylius project doesn't use Symfony Flex, add the bundle manually:

```
// config/bundles.php

return [

    // ...

    Monei\SyliusPlugin\MoneiSyliusPlugin::class => ['all' => true],

];
```

### Step 3: Import plugin routes[​](#step-3-import-plugin-routes "Direct link to Step 3: Import plugin routes")

```
# config/routes/monei.yaml

monei_sylius:

  resource: '@MoneiSyliusPlugin/config/routes.xml'

  prefix: /monei
```

note

Payum handles the webhook notify route automatically — no additional route config is needed for basic operation.

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

1. In your Sylius admin, go to **Configuration → Payment methods**

2. Click **Create** and choose **MONEI** as the gateway

3. Fill in your **API Key** and **Account ID** — find these at [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api)

4. Select your preferred **Integration Type**:

   <!-- -->

   * **Redirect** — Customer is redirected to MONEI's PCI-compliant hosted payment page
   * **Component** — An in-page payment form is rendered using MONEI.js (card input, Bizum, Apple Pay, Google Pay buttons)

5. Toggle **Sandbox mode** for testing

6. Assign the payment method to your desired channels

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

| Field              | Description                                                                  |
| ------------------ | ---------------------------------------------------------------------------- |
| `api_key`          | Your MONEI API key (`pk_test_...` for sandbox, `pk_live_...` for production) |
| `account_id`       | Your MONEI account identifier                                                |
| `integration_type` | `redirect` (hosted page) or `component` (embedded MONEI.js widget)           |
| `sandbox`          | Enable test mode — no real charges are processed                             |

## How it works[​](#how-it-works "Direct link to How it works")

### Redirect flow (Hosted Payment Page)[​](#redirect-flow-hosted-payment-page "Direct link to Redirect flow (Hosted Payment Page)")

1. Customer clicks "Pay" → Sylius creates a MONEI payment via the API
2. Customer is redirected to MONEI's hosted page
3. Customer completes payment (card, Bizum, Apple Pay, Google Pay)
4. MONEI redirects back to your store's completion URL
5. MONEI sends a webhook to confirm the final status asynchronously

<!-- -->

### Component flow (Embedded MONEI.js)[​](#component-flow-embedded-moneijs "Direct link to Component flow (Embedded MONEI.js)")

1. Customer clicks "Pay" → Sylius creates a MONEI payment via the API
2. An in-page payment form is rendered with card input, Bizum, Apple Pay, and Google Pay
3. Customer completes payment without leaving the page
4. Customer is redirected to the order confirmation page
5. MONEI sends a webhook to confirm the final status asynchronously

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

MONEI uses webhooks to notify your store of payment status changes. The plugin automatically verifies the `MONEI-Signature` header (HMAC-SHA256) and re-fetches the payment from MONEI's API to prevent spoofing.

Ensure your server is accessible from the internet so MONEI can reach the callback URL.

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

* [MONEI Sylius Plugin on Packagist](https://packagist.org/packages/monei/sylius-monei-plugin)
* [MONEI Sylius Plugin on GitHub](https://github.com/MONEI/SyliusMoneiPlugin)
* [Sylius Store listing](https://addons.sylius.com/en_US/products/monei-payment-plugin)
* [MONEI PHP SDK](https://github.com/MONEI/monei-php-sdk)