Medusa

Acepta pagos a través de MONEI en tu tienda Medusa v2 usando el plugin oficial medusa-payment-monei. Todos los métodos de pago de MONEI están disponibles automáticamente — tarjetas, Bizum, PayPal, Google Pay, Apple Pay, , MB Way, Multibanco y SEPA Direct Debit.

Características

• Ciclo de pago completo — Iniciar, , , reembolsar (total y parcial) y cancelar
• Flujo Auth + Capture — Preautoriza y captura cuando quieras (por defecto), o captura automáticamente en la autorización
• Compatible con webhooks — Actualizaciones del estado del pago en tiempo real con verificación de firma
• Múltiples métodos de pago — Todos los métodos de pago de MONEI disponibles automáticamente
• Dos modos de integración — Página de pago alojada (redirección) o componentes MONEI.js integrados

Requisitos

Dependencia	Versión
Node.js	18+
Medusa	v2

Antes de empezar

Para probar tu integración:

• Usa tu clave de API en modo de prueba. La encuentras en MONEI Dashboard → Configuración → Acceso a la API.
• Puedes consultar el estado de un pago de prueba en MONEI Dashboard → Pagos (en modo de prueba).
• Consulta las tarjetas de prueba de MONEI para ver números de tarjeta y teléfonos de Bizum de prueba.

Instalación

npm install medusa-payment-monei
# o
yarn add medusa-payment-monei

Configuración

Paso 1: Añadir a medusa-config.ts

import {defineConfig} from '@medusajs/framework/utils';

export default defineConfig({
  // ...
  modules: [
    {
      resolve: '@medusajs/medusa/payment',
      options: {
        providers: [
          {
            resolve: 'medusa-payment-monei',
            id: 'monei',
            options: {
              apiKey: process.env.MONEI_API_KEY,
              // Opcional: captura automática de pagos (por defecto: false)
              // Si es false, los pagos usan el flujo AUTH + captura manual
              // Si es true, los pagos usan el flujo SALE (capturados de inmediato)
              capture: false
            }
          }
        ]
      }
    }
  ]
});

Paso 2: Definir las variables de entorno

# .env
MONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx

Paso 3: Activar en Medusa Admin

Ve a Settings → Regions y activa MONEI para tu(s) región(es).

MONEI se registra como pp_monei_monei.

Opciones de configuración

Opción	Tipo	Por defecto	Descripción
apiKey	string	obligatorio	Tu clave de API de MONEI
capture	boolean	false	Captura automática de pagos al autorizar
webhookSecret	string	—	Clave de firma de webhook (opcional)

Flujos de pago

Por defecto: Auth + Capture (recomendado)

1. El cliente selecciona MONEI → se crea el pago con transactionType: AUTH
2. El cliente completa el pago en la página alojada de MONEI o vía el componente MONEI.js
3. MONEI envía un webhook con estado AUTHORIZED → se crea el pedido
4. El administrador captura el pago desde el panel de Medusa

nota

Los pagos con tarjeta deben capturarse en un plazo de 7 días, y los de Bizum en 30 días.

Captura automática (define capture: true)

1. El cliente selecciona MONEI → se crea el pago con transactionType: SALE
2. El cliente completa el pago → los fondos se capturan de inmediato
3. El webhook recibe el estado SUCCEEDED → se crea el pedido

Webhooks

MONEI envía notificaciones webhook asíncronas a tu servidor de Medusa en:

{your_server_url}/hooks/payment/monei_monei

El plugin verifica la cabecera MONEI-Signature mediante verificación de firma HMAC-SHA256.

Configura la en MONEI Dashboard → Configuración, o se establecerá dinámicamente al crear el pago.

Integración en el storefront

Opción A: Página de pago alojada (la más sencilla)

Tras iniciar la sesión de pago, los datos de la sesión contienen una redirect_url. Redirige al cliente:

const paymentSession = cart.payment_collection?.payment_sessions?.[0];

if (paymentSession?.data?.redirect_url) {
  window.location.href = paymentSession.data.redirect_url;
}

Opción B: Componentes MONEI.js integrados

Usa el SDK de MONEI JS para integrar componentes de pago directamente en tu checkout:

import monei from '@monei-js/components';

const paymentId = paymentSession.data.id;

// Renderiza el campo de tarjeta
const cardInput = monei.CardInput({
  paymentId,
  onChange: (event) => {
    // Gestiona la validación
  }
});
cardInput.render('#card-input');

// Tokeniza la tarjeta y luego confirma el pago
const {token, error} = await cardInput.submit();
if (error) {
  // Muestra el error al cliente
  return;
}

const result = await monei.confirmPayment({
  paymentId,
  paymentToken: token
});

Métodos de pago

Todos los métodos de pago activados en tu MONEI Dashboard están disponibles automáticamente:

Método	Descripción
Tarjetas	Visa, Mastercard, Amex con 3D Secure
Bizum	El pago móvil n.º 1 de España (adquirencia directa)
PayPal	Monedero digital global
Google Pay	Pagos en Android/Chrome
Apple Pay	Pagos en iOS/Safari
	Comercio remoto seguro de Visa/Mastercard
BNPL	Compra ahora, paga después
MB Way	Pagos móviles portugueses
Multibanco	Transferencias bancarias portuguesas
SEPA DD	Domiciliación en euros

Antes de pasar a producción

• Asegúrate de usar tu clave de API en modo producción (live).
• Asegúrate de tener al menos un método de pago activo.

Enlaces

• medusa-payment-monei en npm
• medusa-payment-monei en GitHub
• Documentación del SDK de MONEI JS
• Documentación del módulo de pago de Medusa