VibeFox Eupago for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo.
PHP: 8.0 o posterior.
Moneda de la tienda: euro (EUR). Eupago cobra solo en euros, así que para 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 WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_eupago_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Eupago > Manage, o haz clic en Settings bajo el nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. 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).
6. Elige el Payment Method, activa Enable/Disable, haz un pedido de prueba en modo sandbox y después desmarca Sandbox Mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Eupago. Cuando la pasarela está activada, la página te avisa si la clave API del modo actual está vacía (en ese caso la pasarela se oculta en la finalización de compra), o muestra Sandbox mode: no real payments are taken. mientras el modo sandbox está activo. En la lista de métodos de pago, Eupago aparece marcado como que requiere acción hasta que se define la clave API del modo actual, y muestra una etiqueta de modo de prueba en el modo sandbox.
General
Enable/Disable: Enable Eupago Gateway activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: Eupago.
Description: el texto que se muestra bajo el 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: Processing (por defecto) o Completed. El estado se asigna de una vez, con un solo cambio de estado y un solo correo electrónico.
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 Mode: Enable sandbox/test mode usa sandbox.eupago.pt y las claves de sandbox. No se cobra ningún pago real. Por defecto: on. Desmárcalo para cobrar pagos reales con las claves de producción.
Live API Key: la clave API de tu canal de Eupago de 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 sandbox (sandbox.eupago.pt).
Sandbox Webhook Key: la clave de cifrado de tu Webhook 2.0 de sandbox.
URL del webhook
El webhook avisa a tu tienda de que se ha realizado un pago. En el backoffice de Eupago crea un Webhook 2.0 con la URL que aparece en esta sección de los ajustes, método POST y cifrado activado. La URL tiene este aspecto: https://your-site/wc-api/eupago_payment_callback/. Crea un webhook en el backoffice de sandbox y otro en el de producción.
Copia la clave de cada webhook en Sandbox Webhook Key o 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. El plugin reacciona a estos estados de notificación:
Los demás estados no requieren 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 plugin no consulta a Eupago y la vuelta del cliente a la tienda no paga un pedido.
Avanzado
Debug Log: Enable logging escribe las llamadas a la API y las notificaciones en WooCommerce > Status > Logs, origen wcp_eupago_gateway. No se registran claves, correos electrónicos ni números de teléfono completos. Los errores siempre se registran. Por defecto: off.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Si está marcado, los ajustes de la pasarela y los registros se eliminan al borrar el plugin. Los pedidos y sus datos de pago se conservan. Por defecto: off.
Finalización de compra
El cliente elige el método de pago (por defecto Eupago) y realiza el pedido. En el modo sandbox la finalización de compra muestra SANDBOX / TEST MODE. 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 plugin crea una referencia de Multibanco por el total del pedido. El pedido pasa a En espera, se reducen las existencias y se vacía el carrito. La página de pedido recibido muestra Multibanco Payment Details con la entidad, la referencia y el importe. Los mismos datos se añaden al correo electrónico del pedido mientras el pedido espera el pago. 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 se rellena con el teléfono 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 plugin envía la solicitud de pago a la aplicación MB WAY. El pedido pasa a En espera, se reducen las existencias y se vacía el carrito. La página de pedido recibido pide al cliente que abra la aplicación MB WAY 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 tarjeta de Eupago, en portugués, español o inglés según el idioma del sitio. El pedido sigue en Pago pendiente y se conserva el carrito. Tras pagar, el cliente vuelve a la página de pedido recibido, que muestra Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. hasta que llega la notificación. Si el pago con tarjeta falla o se abandona, el cliente llega a la página Pay for order 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.
En todos los métodos, el pedido se marca como pagado solo después de que Eupago lo confirme con una notificación verificada. Un cliente puede volver a pagar un pedido no pagado desde la página Pay for order; toda referencia de pago creada para el pedido sigue siendo válida para la comprobación.
Si Eupago no puede iniciar el pago, el cliente ve 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. El pedido no cambia y los detalles están en el registro.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS). Los textos que ve el cliente están traducidos al portugués.
El plugin ofrece un único método de Eupago por instalación. No tiene reembolsos desde WooCommerce, 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
Pending payment: se inició un pago con tarjeta y Eupago aún no lo ha confirmado.
On hold, awaiting payment: se creó una referencia de Multibanco o una solicitud de MB WAY. La nota del pedido muestra la entidad y la referencia o el número de teléfono enmascarado.
Processing or Completed: el pago fue confirmado. El estado sigue a Order Status After Payment. La nota del pedido muestra el método, el ID de transacción de Eupago y la referencia. El ID de transacción del pedido es el ID de transacción de Eupago.
On hold, manual review: Eupago informó de un pago con un importe o una moneda distintos, con una referencia que no se creó para este pedido, o para un pedido que mientras tanto se había cancelado o fallado (por ejemplo, una referencia de Multibanco pagada tarde). La nota lo explica. Comprueba el pago y las existencias, y después completa el pedido manualmente o reembolsa al cliente. Las notificaciones posteriores de este pago no completan el pedido sin que tú lo sepas.
Cancelled: Eupago informó de que el pago se canceló o caducó, para el intento de pago actual de un pedido no pagado.
Failed: Eupago informó de un error en el intento de pago actual de un pedido no pagado.
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ó.
Reembolsos: los reembolsos desde WooCommerce no son compatibles. Reembolsa al cliente en el backoffice de Eupago y registra el reembolso en WooCommerce con Refund manually.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Eupago. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio 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. Los gestores de la tienda con sesión iniciada siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Eupago no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que la clave API del modo actual está definida (Sandbox API Key en modo sandbox, Live API Key en modo de producción) y que la moneda de la tienda es EUR. Con Multibanco, el total del pedido debe estar entre 1 € y 999 999,99 €.
El pago se realizó, pero el pedido sigue en Pending payment o On hold: 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 aparece en los ajustes, 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 WooCommerce > Status > Logs, origen wcp_eupago_gateway. Si una notificación nunca llega, comprueba el pago en el backoffice de Eupago.
El webhook responde Invalid signature o Missing signature: la clave del webhook en el plugin no coincide con la clave 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 está definida ninguna de las claves de webhook. Eupago reintenta la notificación después de que pegues la clave.
El webhook responde Decryption failed: la firma es válida, pero no se pudo descifrar el cuerpo. Comprueba los ajustes del Webhook 2.0 en el backoffice de Eupago.
El webhook responde Environment mismatch: la notificación está firmada con la clave del otro modo distinto al del pedido. Una notificación de sandbox nunca paga un pedido de producción y viceversa.
El callback heredado responde Invalid API key: la clave API que envía Eupago no coincide con Live API Key ni con Sandbox API Key.
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á On hold tras el pago: lee la nota del pedido. El importe o la moneda eran distintos, la referencia era desconocida o el pago llegó después de que se cancelara el pedido. Verifica el pago en el backoffice de Eupago y después completa el pedido o reembolsa al cliente.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Para desarrolladores, la documentación del plugin enumera los filtros eupago_p_icon (icono de la finalización de compra) y eupago_p_card_language (idioma de la página de tarjeta de Eupago: PT, EN o ES).
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros se eliminan solo si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos y sus referencias de Eupago siempre se conservan. Los pedidos existentes mantienen sus notas de pago y sus IDs de transacción.
Eupago es una marca comercial de su respectivo titular. Este plugin no está afiliado a Eupago ni cuenta con su respaldo.