VibeFox Nexi XPay 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.
Divisa: la divisa del carrito debe ser EUR. Para otras divisas, el método de pago se oculta en el proceso de compra.
Cuenta de Nexi XPay: necesitas una cuenta de comerciante de Nexi XPay («Pagamento Semplice», integración por redirección) con el alias (ID de terminal) y la clave MAC de tu terminal. Las credenciales de prueba y las reales son independientes: las de prueba se obtienen en el área de pruebas de Nexi XPay o en el portal para desarrolladores (developer.nexi.it), y las reales, en tu back office de Nexi XPay una vez activada la cuenta de comerciante. No hay que configurar nada en el back office de Nexi: la dirección de notificación se envía con cada pago.
Sitio público: la URL de notificación debe ser accesible desde internet, sin autenticación básica ni reglas de cortafuegos que bloqueen a Nexi. El modo de mantenimiento de la tienda no la bloquea. 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
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 Nexi XPay Gateway en la lista de módulos y haz clic en Configure.
3. Introduce 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 (ver Clave de licencia).
4. Deja Test Mode activado e introduce el alias y la clave MAC de prueba (ver Configuración).
5. Activa Enable/Disable, haz clic en Save y realiza un pedido de prueba. Cuando todo funcione, introduce el alias y la clave MAC reales y desactiva Test Mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Nexi XPay payment y Nexi XPay payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las divisas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences. Un país activado en la tienda después de instalar el módulo también debe marcarse allí.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, 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á habilitada pero el alias o la clave MAC del modo actual están vacíos, o cuando la divisa predeterminada de la tienda no es EUR. En esos casos, el método de pago se oculta en el proceso de compra. Los espacios y saltos de línea alrededor de los valores pegados se eliminan al guardar.
Nexi XPay
Enable/Disable: Enable Nexi XPay Gateway activa o desactiva el método de pago. Predeterminado: off.
Title: el título del método de pago que se muestra al cliente en el proceso de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Credit Card (Nexi). En modo de prueba, el proceso de compra y el pedido añaden (TEST MODE) al título.
Description: la descripción del método de pago que se muestra al cliente en el proceso de compra. Predeterminado: Pay securely with your credit card via Nexi XPay.
Entorno de prueba
Los pagos de prueba van a int-ecommerce.nexi.it y nunca cargan tarjetas reales. Obtén el alias y la clave MAC de prueba en el área de pruebas de Nexi XPay o en el portal para desarrolladores (developer.nexi.it).
Test Mode: usa el entorno de prueba de Nexi XPay y las credenciales de prueba. Desactívalo para cobrar pagos reales con las credenciales reales. Predeterminado: on.
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 real
El alias y la clave MAC reales se muestran 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 real de Nexi XPay.
Live MAC Key: la clave de cálculo MAC de tu terminal real de Nexi XPay.
Las claves MAC 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 cambiarla.
Eliminar claves guardadas: marca Test MAC Key o Live MAC Key y haz clic en Save para eliminar una clave guardada. Un campo vacío mantiene el valor guardado.
Pago
Notification URL: se muestra como referencia. Se envía a Nexi con cada pago, así que no hay que configurar nada en el back office de Nexi. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, posiblemente con un código de idioma como /it/, y con el número del carrito al final. 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 se firman igual 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 carrito. Los resultados que no superan la comprobación se rechazan y no cambian nada.
Captura: cuándo se cobra el dinero.
Order Status After Payment: el estado del pedido tras un pago correcto.
Avanzado
Debug Log: registra los eventos de pago en logs/nexi_ip_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves MAC, los MAC, los datos de la tarjeta y las direcciones de correo no se registran. Los errores y advertencias, por ejemplo una comprobación MAC fallida, siempre se registran, incluso con la opción desactivada. Predeterminado: off.
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 todos sus ajustes y el registro. Los datos de pago de Nexi XPay de los pedidos y los estados de pedido se conservan. Predeterminado: off.
Proceso de compra
En el paso de pago, el cliente elige el método de pago (por defecto Credit Card (Nexi)) y confirma. La página siguiente muestra Redirecting to Nexi XPay for payment... y envía al cliente automáticamente a la página de Nexi XPay, con un botón Pay Now como alternativa. El pago se envía en EUR por el total del carrito, con un nuevo código de transacción, el correo electrónico del cliente, la descripción Cart, el número del carrito y el nombre de tu tienda. La página de Nexi se abre en el idioma del carrito 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. Todavía no existe ningún pedido en este punto.
El cliente paga y regresa a tu tienda. El pedido se marca como pagado solo después de un resultado verificado de Nexi con el importe y la divisa exactos del carrito: procedente de la notificación de servidor a servidor o del retorno firmado del cliente, lo que llegue primero. Entonces se crea el pedido y el cliente ve la página estándar de confirmación de pedido con Your Nexi XPay payment has been received. Si Nexi informa de 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. En un pedido en espera (captura diferida o revisión manual) muestra We have received your Nexi XPay payment authorization. Your order will be processed shortly. Si un pago pendiente falla después, la página muestra The payment was not completed. Please contact us.
Si el resultado todavía no se ha procesado cuando el cliente regresa, aparece una página con We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. y un botón Check again. La notificación crea el pedido en cuanto llega.
Si el pago es rechazado o el cliente cancela en la página de Nexi, vuelve al proceso de 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. No se crea ningún pedido y el carrito se conserva, así que el cliente puede volver a pagar. Si el carrito ya tiene un pedido (por ejemplo, se pagó en otra pestaña), el cliente va a la confirmación del pedido en lugar de a un nuevo pago.
Si el módulo no está configurado para el modo actual, el cliente ve This payment method is not available right now. Please choose another payment method.
La notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
El módulo solo acepta pagos en la página de Nexi XPay. No admite reembolsos desde PrestaShop, ni tarjetas guardadas u OneClick, ni suscripciones o pagos recurrentes, ni Pay-By-Link, ni campos integrados de XPay Build, ni métodos de pago seleccionados en PrestaShop: la página de Nexi muestra los métodos activados en tu terminal.
Pedidos y reembolsos
Estados del pedido
Sin pedido todavía: el cliente fue enviado a Nexi y no ha pagado, cancelado ni ha sido rechazado, o Nexi aún no ha confirmado el pago. Solo existe el carrito.
Payment accepted, Delivered or Nexi XPay payment on hold: Nexi confirmó el pago. El estado sigue a Order Status After Payment. El pago se registra con el código de transacción de Nexi como ID de transacción, y 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.
Nexi XPay payment on hold (authorized): está seleccionada la captura diferida y el pago solo está autorizado. Captúralo con Capture Nexi XPay payment en la página del pedido.
Awaiting Nexi XPay payment: Nexi informó de que el pago está pendiente de confirmación. El pedido se actualiza con el resultado final.
Nexi XPay payment on hold after payment: el importe o la divisa recibidos de Nexi no coincidieron con el carrito (el pedido no se marca como pagado), o llegó un pago correcto para un pedido que ya había sido cancelado. La nota lo explica. Comprueba el pago en el back office de Nexi XPay y procesa o reembolsa el pedido.
Error de pago: un pago pendiente falló. El mismo carrito no se puede pagar de nuevo, así que el cliente tiene que hacer un nuevo pedido.
Un pedido pagado nunca se degrada por un fallo posterior. Si llega otro pago correcto para un pedido que ya está pagado, una nota te pide reembolsarlo en el back office de Nexi XPay si es un duplicado.
Bloque de pago de Nexi XPay
La página del pedido muestra un bloque Nexi XPay payment con el código de transacción (codTrans), el estado y el resultado de Nexi, el modo de captura, el importe enviado a Nexi y el importe recibido, el código de autorización, la marca de la tarjeta, el mensaje de Nexi y la fecha, una insignia Test environment para los pagos de prueba y las Nexi XPay notes del pedido.
Captura diferida
Para un pedido autorizado en espera, haz clic en Capture Nexi XPay payment en el bloque (el botón muestra el importe) y confirma la pregunta Capture the authorized amount through Nexi XPay? Necesitas permiso para editar pedidos. El módulo captura el importe autorizado en el entorno del pago, con las claves de ese entorno, registra el pago y pone el estado según Order Status After Payment. Si la captura falla, el bloque 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 PrestaShop, 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 PrestaShop. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Nexi.
Clave de licencia
El módulo 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 Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure, 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 aparecen la línea Product: presta-payment-nexi 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 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 el servidor de licencias no está disponible, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo 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, Nexi XPay no se muestra a los clientes en el proceso de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. El front office 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 el proceso de compra. Aparece un aviso en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando, y los pagos autorizados todavía se pueden capturar.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren 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 tras introducir la clave, y después una vez por semana. No hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Nexi XPay no aparece en el proceso de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene ambas credenciales (Test Alias y Test MAC Key en modo de prueba, Live Alias y Live MAC Key en modo real) y que la divisa del carrito es EUR. La página de ajustes muestra una advertencia en estos casos. En Payment > Preferences, comprueba que el módulo está permitido para EUR, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: 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 real) del pago, y activa Debug Log para ver lo que envió Nexi en el campo Log de la página del módulo.
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: el código de transacción no lo emitió esta tienda para ese carrito. 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 el pedido lo estaba actualizando otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). Nexi reintenta la notificación.
La URL de notificación muestra method_not_allowed en el navegador: es normal. La URL solo acepta solicitudes de Nexi.
El pedido está en Nexi XPay payment on hold after payment: lee las Nexi XPay notes del bloque del pedido. Está seleccionada la captura diferida (captura el pago con el botón), el importe o la divisa no coincidían, llegó un pago para un pedido cancelado, o Nexi XPay payment on hold está seleccionado como estado tras el pago.
Falta o falla Capture Nexi XPay payment: el botón solo aparece en pedidos de Nexi XPay que están en espera como autorizados con captura diferida, y solo para empleados que pueden editar pedidos. Si el alias o la clave MAC del entorno del pago están vacíos, el bloque lo indica. Si la captura falla, lee el error en el bloque 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 real: 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 Modules > Module Manager, abre el menú junto a VibeFox Nexi XPay Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo se eliminan siempre. Si Delete Data on Uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de pago de Nexi XPay de los pedidos y los estados de pedido Awaiting Nexi XPay payment y Nexi XPay payment on hold siempre se conservan, así que los pagos autorizados se pueden seguir capturando tras reinstalar. Los pedidos existentes conservan sus notas de pago e ID de transacción.
Nexi y XPay son marcas comerciales de sus respectivos titulares. Este módulo no está afiliado a Nexi ni cuenta con su respaldo.