VibeFox Nexi XPay for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo.
PHP: 8.0 o posterior.
Moneda: la moneda de la tienda o del pedido debe ser EUR. Para otras monedas, el método de pago se oculta en la finalización de 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 las reales son independientes: las de prueba se obtienen en el área de pruebas de Nexi XPay o en el portal de 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 modo de mantenimiento, autenticación básica ni reglas de cortafuegos que bloqueen a Nexi. De lo contrario, 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 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_nexi_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Nexi XPay > Manage, o haz clic en Settings debajo del 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. Mantén Test Mode activado e introduce el alias y la clave MAC de prueba (véase Configuración).
6. Activa Enable/Disable y haz un pedido de prueba. Cuando todo funcione, introduce el alias y la clave MAC reales y desmarca Test Mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Nexi XPay. Encima de los campos, la página muestra El modo de prueba está activado: los pagos van al entorno de pruebas de Nexi XPay y no se cobra dinero real. mientras el modo de prueba esté activado, y avisa cuando la pasarela está habilitada pero el alias o la clave MAC del modo actual están vacíos, o cuando la moneda de la tienda no es EUR. En ambos casos, el método de pago se oculta en la finalización de compra. Los espacios y saltos de línea alrededor de las claves pegadas se eliminan al guardar.
General
Enable/Disable: Enable Nexi XPay Gateway activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el título del método de pago que ve el cliente en la finalización de compra. Predeterminado: Credit Card (Nexi). En modo de prueba, la finalización de compra añade (TEST MODE) al título.
Description: la descripción del método de pago que ve el cliente en la finalización 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 de desarrolladores (developer.nexi.it).
Test Mode: Enable test mode usa el entorno de pruebas de Nexi XPay y las credenciales de prueba. Desmárcalo para aceptar pagos reales con las credenciales reales. Predeterminado: activado.
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 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 real de Nexi XPay.
Live MAC Key: la clave de cálculo MAC de tu terminal real de Nexi XPay.
Pago
La URL de notificación se envía a Nexi con cada pago, así que no hay que configurar nada en el back office. La sección la muestra; tiene este aspecto: https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, con el ID del pedido al final. Nexi envía el resultado del pago de servidor a servidor a esta URL 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 realizó el pago, el alias de ese entorno y el código de transacción emitido para ese pedido. Los resultados que no superen la comprobación se rechazan y no cambian nada.
Capture: cuándo se cobra el dinero.
Order Status After Payment: el estado del pedido tras un pago correcto. El estado se establece de una vez, con un solo cambio de estado y un solo correo electrónico.
Avanzado
Debug Log: Enable logging registra los eventos de pago en WooCommerce > Status > Logs, origen wcp_nexi_gateway. Las claves MAC, los datos de tarjeta 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 con la opción desactivada. Predeterminado: desactivado.
Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Credit Card (Nexi)) y realiza el pedido. La página siguiente muestra Redirigiendo a Nexi XPay para el pago... 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 con un nuevo código de transacción, el correo electrónico del cliente y la descripción Order, el número de pedido y el nombre de tu sitio. La página de Nexi se abre en el idioma de la tienda 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 la página de pedido recibido de tu tienda. El pedido se marca como pagado solo después de un resultado verificado de Nexi con el importe y la moneda exactos del pedido: desde la notificación de servidor a servidor o desde el retorno firmado del cliente, el que llegue primero.
Si el pago es rechazado o el cliente cancela en la página de Nexi, vuelve a la finalización de compra (o a la página Pay for order si el carrito está vacío) y ve uno de estos mensajes: No se completó el pago. Inténtalo de nuevo o elige otro método de pago., Se ha cancelado el pago. Inténtalo de nuevo. o No hemos podido confirmar el pago. Si tu tarjeta fue cargada, ponte en contacto con nosotros antes de volver a pagar. Cancelar en la página de Nexi deja el pedido sin cambios, así que el cliente puede volver a pagar.
Si el plugin no está configurado para el modo actual, el cliente ve Este método de pago no está disponible en este momento. Elige otro método de pago.
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).
El plugin solo acepta pagos en la página de Nexi XPay. No tiene reembolsos desde WooCommerce, 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 WooCommerce: la página de Nexi muestra los métodos activados en tu terminal.
Pedidos y reembolsos
Estados del pedido
Pendiente de pago: el cliente fue enviado a Nexi y aún no ha pagado, o canceló en la página de Nexi.
Procesando, Completado o En espera: Nexi confirmó el pago. El estado sigue a Order Status After Payment. La nota del pedido muestra el código de autorización, el código de transacción, la marca de la tarjeta y el mensaje de Nexi. El ID de transacción es el código de transacción de Nexi.
En espera (autorizado): se ha seleccionado captura diferida y el pago solo está autorizado. Captúralo con la acción de pedido Capture Nexi XPay payment.
En espera (pendiente): Nexi informó de que el pago está pendiente de confirmación. El pedido se actualiza con el resultado final.
En espera tras el pago: el importe o la moneda recibidos de Nexi no coincidieron con el pedido (el pedido no se marca como pagado), o llegó un pago correcto para un pedido que ya había sido cancelado. La nota del pedido lo explica. Comprueba el pago en el back office de Nexi XPay y procesa o reembolsa el pedido.
Fallido: el último intento de pago fue rechazado, cancelado o terminó con un error. El cliente puede volver a pagar.
Un pedido pagado nunca pasa a un estado inferior 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.
Captura diferida
Para un pedido autorizado En espera, abre el pedido, elige Capture Nexi XPay payment en las acciones del pedido y haz clic en la flecha. El plugin captura el importe autorizado en el entorno del pago y marca el pedido como pagado con el estado de Order Status After Payment. Si la captura falla, el error se muestra en la pantalla del pedido y se añade a las notas, y el pedido se queda En espera.
Reembolsos
Los reembolsos no se realizan desde WooCommerce, así que no hay botón Refund via. Haz el reembolso en el back office de Nexi XPay y después regístralo manualmente en WooCommerce.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Nexi XPay. 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 quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Quitar la clave de un sitio 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 la finalización de compra. Si un pago se inicia de todos modos, el cliente ve Este método de pago no está disponible. Elige otro. Los gestores de la tienda que han iniciado sesión 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 aviso en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los pagos diferidos se pueden seguir capturando.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Nexi XPay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el modo actual tenga ambas credenciales (Test Alias y Test MAC Key en modo de prueba, Live Alias y Live MAC Key en modo real) y que la moneda de la tienda o del pedido sea EUR. La página de ajustes muestra un aviso en estos casos.
El pago se realizó, pero el pedido sigue en Pendiente de pago: no se aceptó ni la notificación ni el retorno del cliente. Comprueba que la tienda sea accesible desde internet, que la clave MAC y el alias coincidan con el entorno (prueba o real) del pago, y activa Debug Log para ver qué envió Nexi en WooCommerce > Status > Logs, origen wcp_nexi_gateway.
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 pedido. 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 reintenta la notificación.
El pedido está En espera tras el pago: lee la nota del pedido. Se ha seleccionado captura diferida (captura el pago con la acción del pedido), el importe o la moneda no coincidieron, llegó un pago para un pedido cancelado, el pago está pendiente en Nexi o se ha seleccionado En espera como estado tras el pago.
Capture Nexi XPay payment no aparece o falla: la acción solo se muestra para pedidos de Nexi En espera como autorizados con captura diferida. Si falla, lee el error en las notas del pedido; la captura usa las claves del entorno en el que se realizó el pago.
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.
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 solo se eliminan si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Nexi y XPay son marcas comerciales de sus respectivos propietarios. Este plugin no está afiliado a Nexi ni cuenta con su respaldo.