VibeFox Eupago for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: euro (EUR). Eupago cobra solo en euros, por lo que el euro debe estar habilitado en tu tienda; cuando el cliente paga en otra moneda, 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 crees en el backoffice de Eupago (véase Configuración). El backoffice de producción es clientes.eupago.pt; el backoffice de sandbox es sandbox.eupago.pt. Sandbox y producción son cuentas separadas con claves separadas.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

La descarga es un archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_eupago_gateway-oc3-(versión).ocmod.zip y el paquete de OpenCart 4 wcp_eupago_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_eupago_gateway-oc3-(versión).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Eupago Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón con el lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, 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 (véase Configuración).

5. Elige el Payment Method, activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba en modo sandbox y después desactiva Sandbox Mode.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_eupago_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Eupago Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia, las claves de Eupago y el webhook como en los pasos 3 a 5 de OpenCart 3. La página de configuración y sus campos son iguales en ambas versiones. Solo la URL del webhook es diferente (véase URL del webhook).

Una instalación nueva empieza con el método de pago desactivado y el modo sandbox activado.

Configuración

Todas las configuraciones están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save bajo la lista guarda toda la página. Cuando el método de pago está activado, la página te avisa encima de los ajustes 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á activado. Sin el derecho de modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, el título no puede estar vacío ni tener más de 128 caracteres, hay que elegir un método de pago, Sort Order debe ser un número entero, Total un número no negativo, y la zona geográfica y los estados de pedido deben existir. Si no, un error indica el problema, por ejemplo Enter a title for the payment method (1 to 128 characters)., y no se guarda nada.

Eupago

Enable/Disable: Enable Eupago Gateway activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que el cliente ve en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Eupago. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. Predeterminado: Pay securely via Eupago.

Payment Method: el único método de Eupago que se ofrece en la finalización de compra.

Sort Order: la posición de Eupago entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece Eupago solo para direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar para que se ofrezca Eupago. Déjalo vacío para ofrecer Eupago con cualquier total. Independientemente de este campo, Eupago solo se ofrece cuando el cliente paga en EUR, y Multibanco solo para importes de 1 € a 999 999,99 €.

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 separadas con claves separadas.

Sandbox Mode: usa sandbox.eupago.pt y las claves de sandbox. No se cobran pagos reales. Predeterminado: activado. Desactívalo para cobrar pagos reales con las claves de producción. Mientras está activado, los clientes ven SANDBOX / TEST MODE en el paso Confirm Order.

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 de sandbox (sandbox.eupago.pt).

Sandbox Webhook Key: la clave de cifrado de tu Webhook 2.0 de sandbox.

Las claves guardadas nunca se muestran de nuevo. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

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 aparece en esta sección, método POST y cifrado activado. En OpenCart 3 la URL tiene la forma https://your-store/index.php?route=extension/payment/wcp_eupago_gateway/webhook, y en OpenCart 4, la de https://your-store/index.php?route=extension/wcp_eupago_gateway/payment/wcp_eupago_gateway.webhook. Se construye a partir de la dirección de la vitrina de tu instalación de OpenCart. 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 real. La extensión reacciona a estos estados de notificación:

Otros 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: la extensión no consulta a Eupago y el regreso del cliente no paga un pedido. El webhook también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart 3 deja pasar las peticiones de las extensiones de pago y la extensión añade en OpenCart 4 una acción de inicio para ello (también para el regreso del cliente desde la página de tarjeta).

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido faltante). Con Multibanco y MB WAY, el pedido recibe el estado de espera en cuanto Eupago ha emitido la referencia o la solicitud de MB WAY. Con tarjeta, el pedido solo recibe estado con la notificación de Eupago. El pedido se marca como pagado solo cuando llega una notificación verificada y su modo, referencia, importe y moneda coinciden con el pedido. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado del pedido que se asigna cuando se confirma el pago. Predeterminado: Procesando.

Awaiting payment status: se emitió la referencia de Multibanco o la solicitud de MB WAY y el cliente aún debe pagar. Los datos de Multibanco se envían con este estado (en el correo del pedido y en el historial de pedidos del cliente). Predeterminado: Pendiente.

Manual review status: Eupago informó de un pago que no coincide con el pedido (importe, moneda, referencia), de un pago posterior a la cancelación del pedido, o de un pago de un pedido cuyo carrito ya estaba pagado. Una nota explica el motivo. Predeterminado: Pendiente, porque OpenCart no tiene el estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled status: Eupago informó de que el pago actual de un pedido en espera fue cancelado o ha caducado. Predeterminado: Cancelado.

Failed status: Eupago informó de que el pago actual de un pedido en espera falló (ERROR). Predeterminado: Fallido.

Avanzado

Debug Log: escribe las llamadas a la API y las notificaciones en eupago_p_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no puede abrirse desde la web y, al llegar a 5 MB, se mueve a eupago_p_debug.old.log.php. Las claves, los correos electrónicos y los números de teléfono completos no se registran. Los errores siempre se registran. Predeterminado: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los pedidos y sus registros de pago de Eupago se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves API y de webhook no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Eupago). OpenCart crea el pedido en el paso Confirm Order, todavía sin estado. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. Lo que ocurre cuando el cliente hace clic en Confirm Order depende de Payment Method.

Multibanco: el cliente ve You will receive Multibanco payment details after placing the order. La extensión crea una referencia de Multibanco por el total del pedido en euros, y el pedido recibe Awaiting payment status. El correo del pedido y el historial de pedidos del cliente reciben el comentario Multibanco Payment Details con la entidad, la referencia y el importe. La página de pedido completado muestra los mismos datos. El cliente paga en un cajero automático o en banca online.

MB WAY: el cliente introduce MB WAY Phone Number, rellenado con el teléfono del pedido. Los números portugueses pueden introducirse sin +351. En OpenCart 4 no se pide un teléfono por defecto, así que el campo suele estar vacío y el cliente introduce el número. Un número incorrecto muestra Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). La extensión envía la solicitud de pago a la aplicación MB WAY, y el pedido recibe Awaiting payment status. La página de éxito 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. Si Eupago rechaza la solicitud, el cliente permanece en el paso Confirm Order con The MB WAY payment could not be started. Check that the phone number is associated with MB WAY and try again.

Credit Card: 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 de la tienda. El pedido permanece sin estado, y el carrito se conserva. Si la notificación ha llegado cuando el cliente vuelve, ve la página de pedido completado de OpenCart. En caso contrario, 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 los botones Check again y Back to checkout. 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. En OpenCart 4 estos mensajes aparecen encima de la página de finalización de compra.

En todos los métodos, el pedido se marca como pagado solo cuando Eupago lo confirma mediante una notificación verificada. Después, el pedido recibe su estado de la forma estándar de OpenCart, con la actualización del stock. Los datos del pago solo se muestran en la página de éxito mientras el pedido espera el pago. Si Eupago ya ha informado de que el pago fue cancelado, ha caducado o ha fallado, la página de éxito muestra Your Eupago payment was not completed. Please contact us about this order.

OpenCart 3 crea un nuevo pedido cada vez que se muestra el paso Confirm Order. OpenCart 4 actualiza el pedido de la finalización de compra, de modo que, tras un pago con tarjeta cancelado o fallido, el cliente paga el mismo pedido con un nuevo pago de Eupago. Si un pedido anterior del mismo carrito ya está pagado con Eupago, el cliente pasa a la página de éxito y no se crea un nuevo pago.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, caducó la referencia de Multibanco, Eupago rechazó la solicitud de MB WAY o cancelaste el pedido), el cliente vuelve a la finalización de compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., y el siguiente Confirm Order paga un pedido nuevo del carrito. Si ese pedido ya está pagado o espera su pago, pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el mensaje es Your previous order is already paid or awaiting its payment. Please confirm the order again: the cart will be paid with a new order. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

Si Eupago no puede iniciar el pago, el cliente permanece en el paso Confirm Order 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. El pedido queda sin estado, y los detalles se guardan en el registro.

La extensión ofrece un método de Eupago por instalación. No tiene reembolsos desde la tienda, tarjetas guardadas, suscripciones ni 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 de estados.

Pedidos

Estados de pedido

No status (missing order): se inició un pago con tarjeta y Eupago aún no lo ha confirmado, o ha fallado. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Awaiting payment status (default Pending): se creó una referencia de Multibanco o una solicitud de MB WAY. La nota muestra la entidad y la referencia o el teléfono enmascarado.

Order Status After Payment (default Processing): el pago fue confirmado. Una nota muestra el método, el ID de transacción de Eupago y la referencia.

Manual review status (default Pending): Eupago informó de un pago con un importe o una moneda distintos, con una referencia que no se creó para este pedido, para un pedido que mientras tanto se había cancelado o fallado (por ejemplo, una referencia de Multibanco pagada tarde), o para un pedido cuyo carrito ya había sido pagado por otro pedido. 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 a tus espaldas.

Cancelled status (default Canceled): Eupago informó de que el pago fue cancelado o ha caducado, para el intento de pago actual de un pedido en espera.

Failed status (default Failed): 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ó. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Eupago Gateway

En Sales > Orders abre un pedido pagado con Eupago. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Eupago Gateway muestra cada intento de pago del pedido: Date, Method (con una etiqueta Sandbox para los pagos de sandbox), Amount, Entity / reference / phone, Eupago transaction ID y Status. En un pedido en revisión manual, la pestaña muestra una advertencia. Debajo, Eupago notes enumera las notas de la extensión sobre el pedido. La pestaña es de solo lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos no están disponibles en esta extensión. Reembolsa al cliente en el backoffice de Eupago y actualiza el pedido en OpenCart manualmente. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Eupago.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Eupago Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Eupago Gateway > Edit, encima de los ajustes. Pega 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 aparecen la línea Product: opencart-payment-eupago y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el derecho Modify sobre la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen inglés y 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 seguido de una fecha. Después de cambiar 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 acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar 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. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit del panel de administración: 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 se necesita ninguna tarea cron. Al desinstalar la extensión, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Eupago does not appear at checkout: 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). El cliente debe pagar en EUR, y con Multibanco el importe del pedido debe estar entre 1 € y 999 999,99 €. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total definido en los ajustes.

The payment went through, but the order stays in the awaiting status or without a status: la notificación de Eupago no llega o es rechazada. En el backoffice de Eupago del modo que utilizas, comprueba que el Webhook 2.0 exista, que su URL sea exactamente la que aparece en Webhook URL, que el método sea 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 mira el campo Log de la página de la extensión. Si una notificación nunca llega, comprueba el pago en el backoffice de Eupago.

Webhook answers Invalid signature or Missing signature: la clave del webhook en la extensión 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.

Webhook answers Webhook key not configured: no hay ninguna clave de webhook configurada. Eupago reintenta la notificación después de que pegues la clave.

Webhook answers Decryption failed: la firma es válida, pero el cuerpo no pudo descifrarse. Revisa la configuración del Webhook 2.0 en el backoffice de Eupago.

Webhook answers Environment mismatch: la notificación está firmada con la clave del otro modo distinto al que se inició el pago. Una notificación de sandbox nunca paga un pago real y viceversa. Comprueba que las claves de sandbox y de producción no estén intercambiadas.

Webhook answers Order not found: la notificación corresponde a un pedido sin un pago de Eupago de esta tienda, por ejemplo un pago realizado en otra tienda con el mismo canal de Eupago.

Webhook answers Busy or Retry: otra petición estaba procesando el pedido en ese mismo momento, o el procesamiento falló. Eupago reintenta la notificación. El motivo está en el registro.

Legacy callback answers Invalid API key: la clave API enviada por 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.

The customer sees This payment method is temporarily unavailable: falta la clave API del modo actual. Introdúcela en los ajustes.

The customer sees 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.

Order is in the manual review status after payment: lee las Eupago notes de la pestaña VibeFox Eupago Gateway. El importe o la moneda eran distintos, la referencia era desconocida, el pago llegó después de que se cancelara el pedido o el carrito ya estaba pagado por otro pedido. Comprueba el pago en el backoffice de Eupago y después completa el pedido o reembolsa al cliente.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Eupago Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados en una reinstalación. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, además, sus eventos y su acción de inicio, que deja pasar el webhook y el regreso del cliente en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, método de pago, modo sandbox, claves, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pago de Eupago de los pedidos siempre se conservan, de modo que las notificaciones tardías de pedidos antiguos siguen funcionando tras una reinstalación. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox Eupago Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Eupago es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Eupago ni cuenta con su respaldo.