VibeFox Nexi XPay 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: el cliente debe pagar en EUR, así que la moneda EUR debe estar activada en System > Localisation > Currencies. Para otras monedas, el método de pago se oculta en la compra.

Cuenta de Nexi XPay: necesitas una cuenta de comerciante de Nexi XPay (integración por redirección «Pagamento Semplice») con el alias (ID de terminal) y la clave MAC de tu terminal. Las credenciales de prueba y de producción son independientes: las de prueba proceden del área de pruebas de Nexi XPay o del portal de desarrolladores (developer.nexi.it), y las de producción, del back office de Nexi XPay una vez activada la cuenta de comerciante. No hay que configurar nada en el back office de Nexi: las direcciones de retorno y de notificación se envían con cada pago.

Tienda pública: la URL de notificación debe ser accesible desde internet, sin autenticación básica ni reglas de cortafuegos que bloqueen a Nexi. Si la notificación no puede llegar a la tienda, el pago se confirma igualmente con el retorno firmado del cliente.

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

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_nexi_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_nexi_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 administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_nexi_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, 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 Nexi XPay Gateway y haz clic en Install (el botón verde +). Tu usuario de 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 ajustes. 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 (ver la sección Clave de licencia).

4. Deja Test Mode activado e introduce el alias de prueba y la clave MAC de prueba (ver Configuración).

5. Activa Enable/Disable, haz clic en Save y realiza un pedido de prueba en EUR. Cuando todo funcione, introduce el alias y la clave MAC de producción y desactiva Test Mode.

OpenCart 4

1. En el administrador ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_nexi_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 Nexi XPay Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón con el lápiz).

4. Introduce la clave de licencia, los alias y las claves MAC como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de notificación es diferente (ver Notification URL).

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

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Nexi XPay Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save debajo de la lista guarda la página completa. Encima de los ajustes, la página muestra Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. mientras el modo de prueba esté activado. Avisa cuando la pasarela está activada pero el alias o la clave MAC del modo actual están vacíos (el método de pago queda entonces oculto en la compra), y cuando la moneda predeterminada de la tienda no es EUR (el método de pago entonces solo se muestra a los clientes que paguen en EUR). Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede tener más de 128 caracteres, Sort Order debe ser un número entero, Total un número igual o mayor que 0, y la geo zone y los estados de pedido deben existir; si alguno de estos datos es incorrecto, no se guarda nada. Los espacios alrededor de los alias y las claves pegados se eliminan.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway activa o desactiva el método de pago. Por defecto: desactivado.

Title: el título del método de pago que se muestra al cliente en la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Credit Card (Nexi); un título vacío usa el predeterminado. Hasta 128 caracteres. En modo de prueba, la compra y el pedido añaden (TEST MODE) al título; un título muy largo se acorta para que el nombre con (TEST MODE) quepa en los 128 caracteres del pedido.

Description: el texto que se muestra al cliente en el paso Confirm Order. Por defecto: Pay securely with your credit card via Nexi XPay.

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

Geo Zone: ofrece Nexi XPay solo para direcciones de pago de la geo zone seleccionada. Por defecto: All zones. Las geo zones 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 antes de ofrecer Nexi XPay. Déjalo vacío para ofrecerlo con cualquier total.

Entorno de prueba

Los pagos de prueba van a int-ecommerce.nexi.it y nunca cobran tarjetas reales. Obtén el alias y la clave MAC de prueba en el área de pruebas de Nexi XPay o en el portal de desarrolladores (developer.nexi.it, enlazado en la sección).

Test Mode: usa el entorno de prueba de Nexi XPay y las credenciales de prueba. Desactívalo para cobrar pagos reales con las credenciales de producción. Por defecto: activado. Mientras esté activado, los clientes ven TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged. en el paso Confirm Order.

Test Alias: el alias (ID de terminal) de tu terminal de prueba de Nexi XPay.

Test MAC Key: la clave de cálculo MAC de tu terminal de prueba de Nexi XPay.

Entorno de producción

El alias y la clave MAC de producción aparecen en tu back office de Nexi XPay (ecommerce.nexi.it) una vez activada tu cuenta de comerciante.

Live Alias: el alias (ID de terminal) de tu terminal de producción de Nexi XPay.

Live MAC Key: la clave de cálculo MAC de tu terminal de producción de Nexi XPay.

Las claves MAC 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 cambiarla. Para eliminar una clave guardada, marca Clear the saved MAC key on save debajo del campo y haz clic en Save.

Pago

Notification URL: se muestra como referencia. En OpenCart 3 tiene un aspecto como https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}, y en OpenCart 4 como https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}, con el número del pedido al final, y se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Se envía a Nexi con cada pago, así que no hay que configurar nada en el back office de Nexi. Nexi envía el resultado del pago a esta URL de servidor a servidor y también lo pasa con el retorno del cliente. Ambos llegan firmados de la misma forma y se comprueban con la clave MAC del entorno en el que se hizo el pago, el alias de ese entorno y el código de transacción emitido para ese pedido. Los resultados que no superan la comprobación se rechazan y no cambian nada.

Capture: cuándo se cobra el importe.

Order Status After Payment: el estado del pedido tras un pago correcto. Los estados de OpenCart usados para cada opción se configuran en la sección Orders.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido «missing order»). Solo recibe un estado a partir de un resultado verificado de Nexi. Cada campo de abajo muestra tus estados de pedido de OpenCart. OpenCart no tiene el estado On hold: por defecto se usa Pending y una nota del pedido explica el motivo. Puedes crear tus propios estados en System > Localisation > Order Statuses y seleccionarlos aquí.

Status: Processing: se usa cuando Order Status After Payment es Processing. Por defecto: Processing.

Status: Completed: se usa cuando Order Status After Payment es Completed. Por defecto: Complete.

Status: awaiting payment: Nexi indica el pago como pendiente (esito PEN). Por defecto: Pending.

Status: on hold: discrepancia de importe o moneda, pago recibido para un pedido cancelado, captura diferida (autorizado, aún sin capturar) o Order Status After Payment establecido en On hold. Por defecto: Pending.

Status: payment failed: un pago pendiente que después ha fallado. Por defecto: Failed.

Status of cancelled orders: el estado que tu tienda usa para los pedidos cancelados. Un pago recibido para un pedido así se pone en espera, nunca se marca como pagado. La extensión solo lee este estado y nunca lo establece. Por defecto: Canceled.

Avanzado

Debug Log: registra los eventos de pago en nexi_ip_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Las claves MAC, los MAC, los datos de tarjetas y las direcciones de correo electrónico no se registran. Los errores y las advertencias, por ejemplo una comprobación MAC fallida, siempre se registran, incluso cuando la opción está desactivada. 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 la extensión se eliminan los ajustes de la pasarela y el registro. Los registros de pagos de Nexi XPay de los pedidos siempre se conservan. Por defecto: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves MAC no se exportan.

Import: pega el JSON exportado y haz clic en Import para restaurar los ajustes. Las claves MAC guardadas no cambian.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto Credit Card (Nexi)). En OpenCart 4, el cliente lo elige 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 compra. En el paso Confirm Order, el cliente ve tu descripción. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la página muestra Redirecting to the Nexi XPay payment page... y Please do not close this window. y envía al cliente a la página de Nexi XPay automáticamente tras un segundo, con un botón Pay with Nexi XPay como alternativa. El pago se envía en EUR por el total del pedido, con un nuevo código de transacción, el correo electrónico del cliente y la descripción Order, el número del pedido y el nombre de tu tienda. La página de Nexi se abre en el idioma de la tienda del cliente si es italiano, inglés, español, francés, alemán, japonés, chino, árabe, ruso o portugués; en caso contrario, en inglés.

El cliente paga y vuelve a tu tienda. El pedido solo se marca como pagado tras un resultado verificado de Nexi con el importe y la moneda exactos del pedido: lo que llegue primero, la notificación de servidor a servidor o el retorno firmado del cliente. Después el pedido recibe su estado de la forma estándar de OpenCart, con el correo habitual del pedido y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart con Your Nexi XPay payment has been received. Si Nexi indica que el pago está pendiente, la página muestra Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Para un pedido en espera (captura diferida o revisión manual) muestra Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

Si el resultado todavía no se ha procesado cuando el cliente vuelve, una página Payment confirmation muestra We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. con un botón Check again. La notificación establece el estado del pedido en cuanto llega.

Si el pago es rechazado, un pago pendiente falla o el cliente cancela en la página de Nexi, vuelve a la compra y ve uno de estos mensajes: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. o We could not confirm the payment. If your card was charged, please contact us before paying again. En OpenCart 4 estos mensajes se muestran encima de la página de compra. Un pedido sin estado sigue sin estado y el carrito se conserva, así que el cliente puede volver a pagar. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un solo pedido para la compra y vuelve a pagar el mismo pedido con un nuevo código de transacción. cuando otro pedido del mismo carrito ya está pagado, pendiente de pago o en espera, el cliente pasa a la página de éxito en lugar de a un nuevo pago.

En OpenCart 4, el pedido se mantiene en la compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, un pago pendiente falló o lo cancelaste), el cliente vuelve a la compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., también cuando vuelve desde Nexi, y la siguiente Confirm Order paga un pedido nuevo. Si el pedido estaba pagado y luego lo cerró la tienda (por ejemplo, reembolsado), el mensaje es Your previous order #(número) was closed by the store. Please confirm the order again to pay with a new order. Si el pedido de la compra ya está realizado y el carrito ha cambiado desde entonces, el mensaje es Your previous order #(número) has already been placed. Your cart has changed: please confirm the new order to pay for it. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

Si la extensión no está configurada para el modo actual, el cliente ve This payment method is not available right now. Please choose another payment method.

La notificación también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart 3 deja pasar las peticiones de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para ello, que también deja volver al cliente desde Nexi.

La extensión acepta pagos solo en la página de Nexi XPay. No tiene reembolsos desde OpenCart, ni tarjetas guardadas ni OneClick, ni suscripciones o pagos recurrentes, ni Pay-By-Link, ni campos integrados de XPay Build, ni elección de métodos de pago en OpenCart: la página de Nexi muestra los métodos activados en tu terminal.

Pedidos y reembolsos

Estados de pedido

No status (missing order): el cliente fue enviado a Nexi y no ha pagado, ha cancelado o el pago fue rechazado, o Nexi aún no ha confirmado el pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Status: Processing, Completed or on hold: Nexi confirmó el pago. El estado sigue a Order Status After Payment. Una nota muestra el código de autorización, el código de transacción, la marca de la tarjeta y el mensaje de Nexi.

Status: on hold (authorized): está seleccionada la captura diferida y el pago solo está autorizado. Captúralo con Capture Nexi XPay payment en la pestaña del pedido.

Status: awaiting payment: Nexi indicó el pago como pendiente de confirmación. El pedido se actualiza con el resultado final.

Status: on hold after payment: el importe o la moneda recibidos de Nexi no coinciden con el pedido (el pedido no se marca como pagado), o llegó un pago correcto para un pedido que ya estaba cancelado. La nota lo explica. Revisa el pago en el back office de Nexi XPay y procesa o reembolsa el pedido.

Status: payment failed: un pago pendiente ha fallado.

Un pedido pagado nunca se degrada por un fallo posterior. Si llega otro pago correcto para un pedido que ya está pagado, o para otro pedido del mismo carrito, una nota en el pedido pagado te pide reembolsarlo en el back office de Nexi XPay si es un duplicado; el segundo pedido no se marca como pagado. Cuando un pago pendiente tiene éxito o falla más tarde, OpenCart notifica al cliente el nuevo estado.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Nexi XPay Gateway

En Sales > Orders abre un pedido pagado con Nexi XPay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Nexi XPay Gateway muestra el código de transacción (codTrans) con la etiqueta Test environment en los pagos de prueba, el estado y el resultado de Nexi, el modo y el estado de la captura, el importe enviado a Nexi y el recibido, el código de autorización, la marca de la tarjeta, el mensaje de Nexi, la fecha y las Nexi XPay notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Captura diferida

Para un pedido autorizado en espera, haz clic en Capture Nexi XPay payment en la pestaña (el botón muestra el importe) y confirma la pregunta Capture the authorized amount through Nexi XPay? Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). La extensión captura el importe autorizado en el entorno del pago, con las claves de ese entorno, y establece el estado según Order Status After Payment con una nota. El estado se cambia directamente, como un cambio manual de estado, sin correos electrónicos ni movimientos de stock. Si la captura falla, la pestaña muestra el error, se añade una nota y el pedido sigue en espera. Una segunda captura del mismo pago se rechaza.

Reembolsos

Los reembolsos no se hacen desde OpenCart, así que no hay botón de reembolso para Nexi XPay. Haz el reembolso en el back office de Nexi XPay y después regístralo manualmente en OpenCart. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Nexi.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Nexi XPay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Nexi XPay 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-nexi y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del administrador (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 un hueco de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no está disponible, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio. Eliminar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, Nexi XPay no se muestra a los clientes en la compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en el administrador 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 se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los pagos autorizados todavía se pueden capturar.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del administrador: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez por 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

Nexi XPay no aparece en la compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene las dos credenciales (Test Alias y Test MAC Key en modo de prueba, Live Alias y Live MAC Key en modo de producción) y que el cliente paga en EUR. La página de ajustes muestra un aviso en estos casos. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado en los ajustes.

El pago se realizó, pero el pedido se queda sin estado: ni la notificación ni el retorno del cliente fueron aceptados. Comprueba que la tienda es accesible desde internet, que la clave MAC y el alias coinciden con el entorno (prueba o producción) del pago, y activa el Debug Log para ver lo que envió Nexi en el campo Log de la página de la extensión.

La notificación responde invalid_mac o invalid_alias: la clave MAC o el alias de los ajustes no coinciden con el terminal que envió el resultado. Cópialos de nuevo desde el área de pruebas o el back office de Nexi.

La notificación responde unknown_transaction u order_not_found: el código de transacción no lo emitió esta tienda para ese pedido, o el pedido no existe. El resultado se ignora.

La notificación responde not_configured o busy: el alias o la clave MAC del entorno del pago están vacíos, o otra petición estaba actualizando el pedido en ese mismo momento. Nexi vuelve a enviar la notificación.

La URL de notificación muestra method_not_allowed en el navegador: es normal. La URL solo acepta peticiones de Nexi.

El cliente ve This payment method is not available. Please reload the checkout page.: la sesión de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente recarga la compra.

El pedido está en el estado en espera tras el pago: lee las Nexi XPay notes en la pestaña del pedido. Está seleccionada la captura diferida (captura el pago con el botón), no coincidían el importe o la moneda, llegó un pago para un pedido cancelado, o Order Status After Payment está establecido en On hold.

Capture Nexi XPay payment no aparece o falla: el botón solo se muestra en pedidos de Nexi XPay en espera como autorizados con captura diferida, y solo a los usuarios que pueden modificar la extensión. Si el alias o la clave MAC del entorno del pago están vacíos, la pestaña lo indica. Si la captura falla, lee el error en la pestaña y en las notas, por ejemplo Nexi XPay refused the capture con el código y el mensaje de Nexi.

Los pagos de prueba no confirman un pago de producción: cada pago se comprueba con las claves del entorno en el que se inició. Cambia Test Mode al modo que quieras usar y utiliza el alias y la clave MAC de ese modo.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Nexi XPay Gateway. La clave de licencia y el estado de 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 la sección Orders, que vuelven a sus valores predeterminados al reinstalar. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar la notificación en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, alias, claves MAC, captura, estado del pedido tras el pago, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos de Nexi XPay de los pedidos siempre se conservan, así que los pagos autorizados todavía se pueden capturar 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 después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Nexi XPay Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Nexi y XPay son marcas comerciales de sus respectivos propietarios. Esta extensión no está afiliada ni respaldada por Nexi.