# Saleor

Acepta pagos a través de MONEI en tu tienda [Saleor](https://saleor.io/) usando la [app de pago oficial de MONEI](https://github.com/MONEI/saleor-monei). La app sigue la arquitectura de apps de pago de Saleor y admite tarjetas (Visa, Mastercard, Amex), Bizum, Apple Pay y Google Pay.

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

* **Métodos de pago admitidos** — Tarjetas vía iframe seguro de MONEI.js, Bizum por redirección, Apple Pay y Google Pay vía componentes MONEI.js
* **Ciclo de vida completo** — Autorizar, capturar (manual o automático), reembolsar y cancelar
* **Enrutamiento multiadquirente** — Enrutamiento inteligente para optimizar las tasas de autorización
* **Bizum nativo** — Adquirencia directa de Bizum, el método de pago móvil dominante en España
* **Conforme a PCI DSS** — Los datos de tarjeta se gestionan mediante iframes seguros de MONEI.js, manteniendo tu tienda fuera del alcance de PCI
* **Basado en webhooks** — Actualizaciones del estado del pago mediante webhooks firmados de MONEI

## Métodos de pago admitidos[​](#métodos-de-pago-admitidos "Enlace directo al Métodos de pago admitidos")

| Método                                | Integración               | Captura       | Reembolso | Cancelación |
| ------------------------------------- | ------------------------- | ------------- | --------- | ----------- |
| **Tarjetas** (Visa, Mastercard, Amex) | iframe seguro de MONEI.js | Manual / Auto | Sí        | Sí          |
| **Bizum**                             | Redirección               | Auto          | Sí        | Sí          |
| **Apple Pay**                         | Componente MONEI.js       | Auto          | Sí        | Sí          |
| **Google Pay**                        | Componente MONEI.js       | Auto          | Sí        | Sí          |

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

| Dependencia | Versión                     |
| ----------- | --------------------------- |
| Node.js     | 18.17+ (LTS recomendado)    |
| Saleor      | 3.13+ (Cloud o autoalojado) |

## 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 de prueba.

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

### Paso 1: Clonar y configurar[​](#paso-1-clonar-y-configurar "Enlace directo al Paso 1: Clonar y configurar")

```
git clone https://github.com/MONEI/saleor-monei.git

cd saleor-monei

cp .env.example .env
```

Edita `.env` con tus credenciales de MONEI:

```
MONEI_API_KEY=your_api_key

MONEI_ACCOUNT_ID=your_account_id

NEXT_PUBLIC_APP_URL=http://localhost:3000
```

### Paso 2: Instalar y ejecutar[​](#paso-2-instalar-y-ejecutar "Enlace directo al Paso 2: Instalar y ejecutar")

```
npm install

npm run dev
```

### Paso 3: Instalar en Saleor[​](#paso-3-instalar-en-saleor "Enlace directo al Paso 3: Instalar en Saleor")

1. Abre **Saleor Dashboard → Apps → Install External App**
2. Introduce la URL de tu manifest: `http://localhost:3000/api/manifest`
3. La app registra sus webhooks automáticamente

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

| Variable               | Descripción                                                                  | Obligatoria | Por defecto |
| ---------------------- | ---------------------------------------------------------------------------- | ----------- | ----------- |
| `MONEI_API_KEY`        | Clave de API del [MONEI Dashboard](https://dashboard.monei.com/settings/api) | Sí          | —           |
| `MONEI_ACCOUNT_ID`     | ID de la cuenta del comercio                                                 | Sí          | —           |
| `MONEI_WEBHOOK_SECRET` | Clave HMAC para verificar la firma del webhook                               | No          | —           |
| `MONEI_ENVIRONMENT`    | `test` o `live`                                                              | No          | `test`      |
| `APL`                  | Capa de persistencia de auth: `file` (dev) o `upstash` (prod)                | No          | `file`      |
| `NEXT_PUBLIC_APP_URL`  | URL pública donde se aloja esta app                                          | Sí          | —           |

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

La app gestiona tres webhooks síncronos de Saleor:

| Webhook                              | Propósito                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `PAYMENT_GATEWAY_INITIALIZE_SESSION` | Devuelve los métodos de pago disponibles y la configuración de MONEI.js    |
| `TRANSACTION_INITIALIZE_SESSION`     | Crea un pago en MONEI y devuelve el resultado o la URL de redirección      |
| `TRANSACTION_PROCESS_SESSION`        | Comprueba el estado del pago tras la acción del cliente (3D Secure, Bizum) |

### Flujo de pago[​](#flujo-de-pago "Enlace directo al Flujo de pago")

1. El cliente inicia el checkout → Saleor llama a `PAYMENT_GATEWAY_INITIALIZE_SESSION`
2. La app devuelve los métodos de pago de MONEI disponibles y la configuración de MONEI.js
3. El cliente selecciona un método de pago → Saleor llama a `TRANSACTION_INITIALIZE_SESSION`
4. La app crea un pago en MONEI y devuelve la URL de redirección o los datos de MONEI.js
5. El cliente completa el pago (3D Secure, redirección de Bizum, etc.)
6. Saleor llama a `TRANSACTION_PROCESS_SESSION` → La app comprueba el estado final del pago

<!-- -->

## Despliegue[​](#despliegue "Enlace directo al Despliegue")

Despliega en [Vercel](https://vercel.com), [Railway](https://railway.app) o cualquier plataforma compatible con Next.js:

```
npm run build

npm start
```

Para despliegues multiinquilino en producción, define `APL=upstash` y configura [Upstash Redis](https://upstash.com) para almacenar los tokens de auth.

## 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.
* Define `MONEI_ENVIRONMENT=live` en tus variables de entorno.

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

* [App de pago de Saleor de MONEI en GitHub](https://github.com/MONEI/saleor-monei)
* [Documentación de apps de pago de Saleor](https://docs.saleor.io/developer/payments/payment-apps)
* [Crear una app de pago de Saleor](https://docs.saleor.io/developer/extending/apps/building-payment-app)
* [Documentación del SDK de MONEI JS](https://docs.monei.com/es/es/monei-js/overview/.md)