README

MONEI Payment Plugin for Sylius

Accept payments with MONEI in your Sylius store — Cards, Bizum, Apple Pay, Google Pay.
MONEI is a licensed Payment Institution (Banco de España #6911).

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 (Visa, Mastercard, Amex), Bizum, Apple Pay, Google Pay
Full lifecycle support — Capture, Refund (full & partial), Cancel, and Status sync
Webhook-driven — Asynchronous payment status updates via signed MONEI webhooks
PSD2 / SCA ready — 3D Secure handled automatically by MONEI
Official SDK — Built on the monei/monei-php-sdk for reliable API communication and signature verification
Multi-language — Admin translations in English, Spanish, Catalan, and French

Requirements

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

Installation

1. Install via Composer

composer require monei/sylius-monei-plugin

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],
];

3. Import the plugin routes (optional)

# config/routes/monei.yaml
monei_sylius:
    resource: "@MoneiSyliusPlugin/config/routes.xml"
    prefix: /monei

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

4. Configure MONEI in the Sylius Admin

Go to Configuration → Payment methods
Click Create and choose MONEI as the gateway
Fill in your API Key and Account ID (find these at dashboard.monei.com)
Select your preferred Integration Type: Redirect or Embedded Component
Toggle Sandbox mode for testing
Assign the payment method to your desired channels

That's it — your store is now accepting payments via MONEI.

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

Redirect Flow (Hosted Payment Page)

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

Component Flow (Embedded MONEI.js)

Customer clicks "Pay" → Sylius creates a MONEI payment via the API
An in-page payment form is rendered using MONEI.js with card input, Bizum, Apple Pay, and Google Pay buttons
Customer completes payment without leaving the page
On success, the customer is redirected to the order confirmation page
MONEI sends a webhook to confirm the final status asynchronously

Webhooks

MONEI uses webhooks to notify your store of payment status changes. The plugin automatically:

Verifies the MONEI-Signature header using the official SDK's signature verification (timestamp-based HMAC-SHA256)
Re-fetches the payment from MONEI's API to prevent spoofing
Updates the Sylius payment status accordingly

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

Testing

# Run all tests
make test

# Run only unit tests
make test-unit

# Static analysis
make analyse

# Code style check
make check

# Auto-fix code style
make fix

Use MONEI sandbox credentials (pk_test_...) and MONEI test cards to test the full flow without real charges.

Architecture

SyliusMoneiPlugin/
├── config/
│   ├── routes.xml                     # Plugin routes
│   └── services.xml                   # Service definitions
├── src/
│   ├── Action/
│   │   ├── CaptureAction.php          # Creates payment, redirect or component
│   │   ├── ConvertPaymentAction.php   # Maps Sylius Payment → MONEI params
│   │   ├── NotifyAction.php           # Processes MONEI webhooks
│   │   ├── RefundAction.php           # Triggers refunds via MONEI API
│   │   └── StatusAction.php           # Maps MONEI status → Sylius status
│   ├── Client/
│   │   └── MoneiApiClient.php         # Thin wrapper around monei-php-sdk
│   ├── DependencyInjection/           # Symfony DI wiring
│   ├── Factory/
│   │   └── MoneiGatewayFactory.php    # Payum gateway factory registration
│   ├── Form/Type/
│   │   └── MoneiGatewayConfigurationType.php  # Admin config form
│   ├── Resolver/
│   │   └── PaymentStatusResolver.php  # Clean MONEI → Sylius status mapping
│   └── Resources/
│       └── translations/              # en, es, ca, fr
└── tests/
    ├── Unit/                          # PHPUnit unit tests
    └── Integration/                   # PHPUnit integration tests

Contributing

Please see CONTRIBUTING.md for details.

License

This plugin is open-sourced software licensed under the MIT license.

monei / sylius-monei-plugin

Maintainers

Package info

Statistics

Security