# Sylius

Acepta pagos a través de MONEI en tu tienda [Sylius](https://sylius.com/) usando el [plugin oficial de pago de MONEI](https://packagist.org/packages/monei/sylius-monei-plugin). El plugin admite tarjetas (Visa, Mastercard, Amex), Bizum, Apple Pay y Google Pay, con dos modos de integración: página de pago alojada o componente de pago integrado.

## Características[​](#características "Enlace directo al Características")

* **Dos modos de integración** — Página de pago alojada (redirección) o componente MONEI integrado (widget JS), configurable por pasarela en el admin de Sylius
* **Todos los métodos de pago de MONEI** — Tarjetas, Bizum, Apple Pay, Google Pay
* **Ciclo de vida completo** — Captura, reembolso (total y parcial), cancelación y sincronización de estado
* **Basado en webhooks** — Actualizaciones asíncronas del estado del pago mediante webhooks firmados de MONEI
* **Listo para PSD2 / SCA** — 3D Secure gestionado automáticamente por MONEI

## Requisitos[​](#requisitos "Enlace directo al Requisitos")

| Dependencia | Versión   |
| ----------- | --------- |
| PHP         | 8.2+      |
| Sylius      | 2.1+      |
| Symfony     | 6.4 o 7.x |

## Antes de empezar[​](#antes-de-empezar "Enlace directo al Antes de empezar")

Para probar tu integración:

* Usa tu clave de API en [modo de prueba](https://docs.monei.com/es/es/testing/.md). La encuentras en [MONEI Dashboard → Configuración → Acceso a la API](https://dashboard.monei.com/settings/api).
* Puedes consultar el estado de un pago de prueba en [MONEI Dashboard → Pagos](https://dashboard.monei.com/payments) (en modo de prueba).
* Consulta las [tarjetas de prueba de MONEI](https://docs.monei.com/es/es/testing/.md) para ver números de tarjeta y teléfonos de Bizum de prueba.

## Instalación[​](#instalación "Enlace directo al Instalación")

### Paso 1: Instalar vía Composer[​](#paso-1-instalar-vía-composer "Enlace directo al Paso 1: Instalar vía Composer")

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

### Paso 2: Registrar el bundle[​](#paso-2-registrar-el-bundle "Enlace directo al Paso 2: Registrar el bundle")

Si tu proyecto Sylius no usa Symfony Flex, añade el bundle manualmente:

```
// config/bundles.php

return [

    // ...

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

];
```

### Paso 3: Importar las rutas del plugin[​](#paso-3-importar-las-rutas-del-plugin "Enlace directo al Paso 3: Importar las rutas del plugin")

```
# config/routes/monei.yaml

monei_sylius:

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

  prefix: /monei
```

nota

Payum gestiona la ruta de notificación del webhook automáticamente — no se necesita configuración de rutas adicional para el funcionamiento básico.

## Configuración[​](#configuración "Enlace directo al Configuración")

1. En tu admin de Sylius, ve a **Configuration → Payment methods**

2. Haz clic en **Create** y elige **MONEI** como pasarela

3. Introduce tu **API Key** y tu **Account ID** — los encuentras en [MONEI Dashboard → Configuración → Acceso a la API](https://dashboard.monei.com/settings/api)

4. Selecciona tu **tipo de integración** preferido:

   <!-- -->

   * **Redirect** — El cliente es redirigido a la página de pago alojada de MONEI, conforme a PCI
   * **Component** — Se renderiza un formulario de pago en la página con MONEI.js (campo de tarjeta, botones de Bizum, Apple Pay y Google Pay)

5. Activa el **modo Sandbox** para pruebas

6. Asigna el método de pago a los canales que quieras

### Referencia de configuración[​](#referencia-de-configuración "Enlace directo al Referencia de configuración")

| Campo              | Descripción                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `api_key`          | Tu clave de API de MONEI (`pk_test_...` para sandbox, `pk_live_...` para producción) |
| `account_id`       | Tu identificador de cuenta de MONEI                                                  |
| `integration_type` | `redirect` (página alojada) o `component` (widget MONEI.js integrado)                |
| `sandbox`          | Activa el modo de prueba — no se procesan cargos reales                              |

## Cómo funciona[​](#cómo-funciona "Enlace directo al Cómo funciona")

### Flujo de redirección (página de pago alojada)[​](#flujo-de-redirección-página-de-pago-alojada "Enlace directo al Flujo de redirección (página de pago alojada)")

1. El cliente hace clic en "Pagar" → Sylius crea un pago en MONEI vía la API
2. El cliente es redirigido a la página alojada de MONEI
3. El cliente completa el pago (tarjeta, Bizum, Apple Pay, Google Pay)
4. MONEI redirige de vuelta a la URL de finalización de tu tienda
5. MONEI envía un webhook para confirmar el estado final de forma asíncrona

<!-- -->

### Flujo de componente (MONEI.js integrado)[​](#flujo-de-componente-moneijs-integrado "Enlace directo al Flujo de componente (MONEI.js integrado)")

1. El cliente hace clic en "Pagar" → Sylius crea un pago en MONEI vía la API
2. Se renderiza un formulario de pago en la página con campo de tarjeta, Bizum, Apple Pay y Google Pay
3. El cliente completa el pago sin salir de la página
4. El cliente es redirigido a la página de confirmación del pedido
5. MONEI envía un webhook para confirmar el estado final de forma asíncrona

## Webhooks[​](#webhooks "Enlace directo al Webhooks")

MONEI usa webhooks para notificar a tu tienda los cambios de estado del pago. El plugin verifica automáticamente la cabecera `MONEI-Signature` (HMAC-SHA256) y vuelve a consultar el pago en la API de MONEI para evitar suplantaciones.

Asegúrate de que tu servidor sea accesible desde internet para que MONEI pueda alcanzar la URL de callback.

## Antes de pasar a producción[​](#antes-de-pasar-a-producción "Enlace directo al Antes de pasar a producción")

* Asegúrate de usar tu clave de API en [modo producción (live)](https://docs.monei.com/es/es/testing/.md).
* Asegúrate de tener al menos un [método de pago](https://dashboard.monei.com/settings/payment-methods) activo.

## Enlaces[​](#enlaces "Enlace directo al Enlaces")

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