VibeFox Eupago for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Moneda: euro (EUR). Eupago cobra solo en euros, así que en los carritos con otras monedas el método de pago se oculta en la finalización de compra.
Cuenta de Eupago: necesitas la clave API de tu canal de Eupago y la clave de un Webhook 2.0 que creas en el backoffice de Eupago (ver Configuración). El backoffice de producción es clientes.eupago.pt y el de sandbox es sandbox.eupago.pt. Sandbox y producción son cuentas independientes con claves independientes.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure o busca más tarde VibeFox Eupago Gateway en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).
4. Introduce la clave API de tu canal de Eupago, crea un Webhook 2.0 en el backoffice de Eupago y pega su clave (ver Configuración).
5. Elige el Payment Method, activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en modo sandbox y después desactiva Sandbox Mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Eupago payment y Eupago payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; el euro debe seguir permitido para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Eupago Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cuando el método de pago está activado, la página muestra un aviso encima de los campos si la clave API del modo actual está vacía (en ese caso el método de pago se oculta en la finalización de compra), o muestra Sandbox mode: no real payments are taken. mientras el modo sandbox está activo.
Eupago
Enable/Disable: Enable Eupago Gateway activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Eupago. Obligatorio: si el título está vacío, aparece Enter a title for the payment method.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Eupago.
Payment Method: el único método de Eupago que se ofrece en la finalización de compra.
Order Status After Payment: el estado del pedido que se asigna cuando se confirma el pago.
Cuenta de Eupago
Obtén la clave API de tu canal y la clave del Webhook 2.0 en el backoffice de Eupago: clientes.eupago.pt (producción) o sandbox.eupago.pt (sandbox). Sandbox y producción son cuentas independientes con claves independientes.
Sandbox Mode: usa sandbox.eupago.pt y las claves de sandbox. No se cobra ningún pago real. Por defecto: activado. Desactívalo para cobrar pagos reales con las claves de producción. Mientras esté activado, los clientes ven SANDBOX / TEST MODE debajo del método de pago.
Live API Key: la clave API de tu canal de Eupago en producción (clientes.eupago.pt).
Live Webhook Key: la clave de cifrado de tu Webhook 2.0 de producción. Obligatoria: las notificaciones sin firma válida se rechazan.
Sandbox API Key: la clave API de tu canal de sandbox (sandbox.eupago.pt).
Sandbox Webhook Key: la clave de cifrado de tu Webhook 2.0 de sandbox.
Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved keys: marca la casilla de una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
URL del webhook
El webhook informa a tu tienda de que se ha realizado un pago. En el backoffice de Eupago, crea un Webhook 2.0 con la URL que se muestra en esta sección, método POST y cifrado activado. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_eupago_gateway/webhook, posiblemente con un código de idioma como /pt/. Copia la URL exactamente como la muestran los ajustes. Crea un webhook en el backoffice de sandbox y otro en el backoffice de producción.
Copia la clave de cada webhook en Sandbox Webhook Key o en Live Webhook Key. Los webhooks sin firma válida se rechazan. Un webhook sin cifrar solo se acepta si Eupago lo firma, así que mantén el cifrado activado. Una notificación debe estar firmada con la clave del modo en que se inició el pago, de modo que una notificación de sandbox nunca paga un pago de producción. El módulo reacciona a estos estados de notificación:
Los demás estados no requieren ninguna acción. El callback GET heredado de Eupago a la misma URL también se acepta; se autentica con la clave API y siempre informa de un pago. Sin notificaciones, los pedidos nunca se marcan como pagados: el módulo no consulta a Eupago y el regreso del cliente no paga un pedido. El webhook funciona con la tienda en modo mantenimiento y no se ve bloqueado por la restricción de países de tu tienda.
Avanzado
Debug Log: escribe las llamadas a la API y las notificaciones en logs/eupago_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves, los correos electrónicos y los números de teléfono completos no se registran. Los errores siempre se registran. Por defecto: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete Data on Uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela, los registros de pagos de Eupago de este módulo y el registro. Los pedidos y sus datos de pago se conservan. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto, Eupago) en el paso de pago y realiza el pedido. Lo que ocurre después depende de Payment Method.
Multibanco: en la finalización de compra, el cliente ve You will receive Multibanco payment details after placing the order. El módulo crea una referencia de Multibanco por el total del carrito. El pedido se crea de inmediato en Awaiting Eupago payment, como cualquier pedido de PrestaShop, y el carrito se vacía. La página de confirmación del pedido muestra Multibanco Payment Details con la entidad, la referencia y el importe. Los mismos datos se añaden a la línea de pago del correo electrónico de confirmación del pedido. El cliente paga en un cajero automático o en la banca online.
MB WAY: en la finalización de compra, el cliente introduce MB WAY Phone Number, que aparece rellenado con el teléfono de la dirección de facturación. Los números portugueses se pueden introducir sin +351. Un número incorrecto muestra Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). El módulo envía la solicitud de pago a la aplicación MB WAY y crea el pedido en Awaiting Eupago payment. La página de confirmación del pedido pide al cliente que abra la aplicación MB WAY en el número de teléfono enmascarado y apruebe la solicitud en un plazo de 5 minutos.
Credit Card: en la finalización de compra, el cliente ve You will be redirected to a secure payment page to enter your card details. El cliente es enviado a la página de tarjetas de Eupago, en portugués, español o inglés según el idioma del carrito. Todavía no existe ningún pedido y el carrito se conserva. El pedido se crea solo cuando Eupago confirma el pago. Si la notificación ha llegado cuando el cliente regresa, ve la página estándar de confirmación del pedido. Si no, una página Payment confirmation muestra Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. con un botón Check again. Si el pago con tarjeta falla o se abandona, el cliente vuelve a la finalización de compra con The card payment was not completed. You can try again or choose another payment method. o The card payment was cancelled. You can try again or choose another payment method.
Para todos los métodos, el pedido se marca como pagado solo después de que Eupago lo confirme con una notificación verificada. Los datos de pago solo se muestran mientras el pedido está en Awaiting Eupago payment. Si Eupago informa después de que el pago se ha cancelado, ha caducado o ha fallado, y el pedido no estaba pagado, la página de confirmación del pedido muestra Your Eupago payment was not completed. Please contact us about this order.
Si Eupago no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. No se crea ningún pedido y los detalles están en el registro. Un carrito en otra moneda muestra Eupago only supports payments in EUR.
El módulo ofrece un único método de Eupago por instalación. No tiene reembolsos desde PrestaShop, ni tarjetas guardadas, suscripciones o preautorización, ni PayShop, Cofidis Pay, Bizum u otros métodos de Eupago, ni recordatorios por SMS, ni fecha de caducidad de Multibanco, ni consulta periódica del estado.
Pedidos
Estados del pedido
No order yet: se inició un pago con tarjeta y Eupago aún no lo ha confirmado. Solo existe el carrito.
Awaiting Eupago payment: se creó una referencia de Multibanco o una solicitud de MB WAY. La nota muestra la entidad y la referencia, o el número de teléfono enmascarado.
Payment accepted or Delivered: el pago se confirmó. El estado sigue a Order Status After Payment. El pago se registra con el ID de transacción de Eupago como ID de transacción, y una nota muestra el método, el ID de transacción y la referencia.
Eupago payment on hold: Eupago informó de un pago con un importe o una moneda distintos, con una referencia que no se creó para este carrito, o para un pedido que entretanto se había cancelado o había fallado (por ejemplo, una referencia de Multibanco pagada con retraso). La nota lo explica. Comprueba el pago y el stock y después completa el pedido manualmente o reembolsa al cliente. Las notificaciones posteriores de este pago no completan el pedido sin que lo sepas.
Canceled: Eupago informó de que el pago se ha cancelado o ha caducado, para el intento de pago actual de un pedido en espera.
Payment error: Eupago informó de un error en el intento de pago actual de un pedido en espera.
Si Eupago informa de otro pago para un pedido que ya está pagado (por ejemplo, también se pagó una referencia de Multibanco anterior), el pedido no cambia. Una nota te pide que compruebes si hay un pago duplicado y lo reembolses en el backoffice de Eupago. Una notificación de pago nunca reabre un pedido que se pagó y después se canceló o reembolsó.
Bloque de pago de Eupago
La página del pedido muestra un bloque Eupago payment con cada intento de pago del carrito: fecha, método, una insignia Sandbox para los pagos de sandbox, importe, la entidad y la referencia de Multibanco o el teléfono enmascarado de MB WAY, el ID de transacción de Eupago y el estado. Mientras el pedido está en Eupago payment on hold, el bloque muestra una advertencia Manual review. Debajo, Eupago notes enumera las notas del módulo sobre el pedido, de la más reciente a la más antigua.
Reembolsos
Los reembolsos desde PrestaShop no son compatibles. Reembolsa al cliente en el backoffice de Eupago y actualiza el pedido en PrestaShop manualmente. Los botones estándar de reembolso de PrestaShop de la página del pedido no devuelven dinero a través de Eupago.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Eupago Gateway es el primer bloque de Modules > Module Manager > VibeFox Eupago Gateway > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo de ellos están la línea Product: presta-payment-eupago y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el ruso).
Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on y una fecha. Después de que cambie la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Eupago no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Eupago no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que la clave API del modo actual está configurada (Sandbox API Key en modo sandbox, Live API Key en modo producción). La moneda del carrito debe ser EUR, y en Payment > Preferences el módulo debe estar permitido para el euro, para el país del cliente y para el grupo del cliente. Con Multibanco, el total del pedido debe estar entre 1 € y 999 999,99 €.
El pago se realizó, pero el pedido sigue en Awaiting Eupago payment o no se creó ningún pedido: la notificación de Eupago no llega o se rechaza. En el backoffice de Eupago del modo que usas, comprueba que el Webhook 2.0 existe, que su URL es exactamente la que se muestra en Webhook URL, que el método es POST y que el cifrado está activado. Comprueba que su clave está en el campo correspondiente (Sandbox Webhook Key o Live Webhook Key). Activa Debug Log y revisa el campo Log de la página del módulo. Si una notificación nunca llega, comprueba el pago en el backoffice de Eupago.
El webhook responde Invalid signature o Missing signature: la clave de webhook del módulo no coincide con la del webhook, o el webhook no está cifrado ni firmado. Copia la clave de nuevo y mantén el cifrado activado.
El webhook responde Webhook key not configured: no hay ninguna clave de webhook configurada. Eupago reintenta la notificación después de que pegues la clave.
El webhook responde Decryption failed: la firma es válida, pero el cuerpo no se pudo descifrar. Revisa los ajustes del Webhook 2.0 en el backoffice de Eupago.
El webhook responde Environment mismatch: la notificación está firmada con la clave de un modo distinto del que se usó para iniciar el pago. Una notificación de sandbox nunca paga un pago de producción, y viceversa. Comprueba que las claves de sandbox y de producción no están intercambiadas.
El webhook responde Order not found: la notificación corresponde a un carrito sin un pago de Eupago de esta tienda, por ejemplo un pago realizado desde otra tienda con el mismo canal de Eupago.
El webhook responde Busy or Retry: otra petición estaba procesando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Eupago reintenta la notificación. El motivo está en el registro.
El callback heredado responde Invalid API key: la clave API que envió Eupago no coincide con Live API Key ni con Sandbox API Key. La misma respuesta aparece si abres la URL del webhook en un navegador; es normal.
El cliente ve The MB WAY payment could not be started: comprueba que el número de teléfono está asociado a MB WAY e inténtalo de nuevo.
El pedido está en Eupago payment on hold tras el pago: lee las Eupago notes en el bloque Eupago payment. El importe o la moneda eran distintos, la referencia era desconocida o el pago llegó después de cancelar el pedido. Verifica el pago en el backoffice de Eupago y después completa el pedido o reembolsa al cliente.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Eupago Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes de la pasarela, los registros de pagos de Eupago de este módulo y el registro. Si está desactivado, todos los ajustes y registros se conservan para una reinstalación posterior. Los estados de pedido Awaiting Eupago payment y Eupago payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Eupago es una marca comercial de su respectivo titular. Este módulo no está afiliado a Eupago ni cuenta con su respaldo.