# Medusa Acepta pagos a través de MONEI en tu tienda [Medusa](https://medusajs.com/) v2 usando el plugin oficial [medusa-payment-monei](https://www.npmjs.com/package/medusa-payment-monei). Todos los métodos de pago de MONEI están disponibles automáticamente — tarjetas, Bizum, PayPal, Google Pay, Apple Pay, BNPL, MB Way, Multibanco y SEPA Direct Debit. ## Características[​](#características "Enlace directo al Características") * **Ciclo de pago completo** — Iniciar, autorizar, capturar, 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 HMAC * **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[​](#requisitos "Enlace directo al Requisitos") | Dependencia | Versión | | ----------- | ------- | | Node.js | 18+ | | Medusa | v2 | ## 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") ``` npm install medusa-payment-monei # o yarn add medusa-payment-monei ``` ## Configuración[​](#configuración "Enlace directo al Configuración") ### Paso 1: Añadir a `medusa-config.ts`[​](#paso-1-añadir-a-medusa-configts "Enlace directo al paso-1-añadir-a-medusa-configts") ``` 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[​](#paso-2-definir-las-variables-de-entorno "Enlace directo al Paso 2: Definir las variables de entorno") ``` # .env MONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx ``` ### Paso 3: Activar en Medusa Admin[​](#paso-3-activar-en-medusa-admin "Enlace directo al 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[​](#opciones-de-configuración "Enlace directo al 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[​](#flujos-de-pago "Enlace directo al Flujos de pago") ### Por defecto: Auth + Capture (recomendado)[​](#por-defecto-auth--capture-recomendado "Enlace directo al 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`)[​](#captura-automática-define-capture-true "Enlace directo al 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[​](#webhooks "Enlace directo al 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 URL de callback en [MONEI Dashboard → Configuración](https://dashboard.monei.com/settings), o se establecerá dinámicamente al crear el pago. ## Integración en el storefront[​](#integración-en-el-storefront "Enlace directo al Integración en el storefront") ### Opción A: Página de pago alojada (la más sencilla)[​](#opción-a-página-de-pago-alojada-la-más-sencilla "Enlace directo al 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[​](#opción-b-componentes-moneijs-integrados "Enlace directo al Opción B: Componentes MONEI.js integrados") Usa el [SDK de MONEI JS](https://docs.monei.com/es/es/monei-js/overview/.md) 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[​](#métodos-de-pago "Enlace directo al Métodos de pago") Todos los métodos de pago activados en tu [MONEI Dashboard](https://dashboard.monei.com/settings/payment-methods) 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 | | **Click to Pay** | 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[​](#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") * [medusa-payment-monei en npm](https://www.npmjs.com/package/medusa-payment-monei) * [medusa-payment-monei en GitHub](https://github.com/MONEI/medusa-payment-monei) * [Documentación del SDK de MONEI JS](https://docs.monei.com/es/es/monei-js/overview/.md) * [Documentación del módulo de pago de Medusa](https://docs.medusajs.com/resources/commerce-modules/payment)