VibeFox Nets Nexi 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.

Cuenta de Nets: necesitas las claves secretas de tu cuenta de Nets Easy (de prueba y de producción). Solo se usan las claves secretas. Las claves de checkout no son necesarias, porque los clientes pagan en la página de pago alojada por Nets.

Monedas y métodos de pago: la extensión no limita las monedas por sí misma. Usa las monedas activadas en tu cuenta de Nets; si una moneda no es compatible, Nets lo indica al crear el pago. Qué métodos de pago ve el cliente depende de tu contrato con Nets, del país y de la moneda.

HTTPS para webhooks: Nets solo llama a direcciones HTTPS públicas de como máximo 256 caracteres y sin "&", así que tu tienda necesita HTTPS para recibir webhooks. Sin HTTPS, el pago se confirma igualmente cuando el cliente vuelve a la tienda o con la comprobación de estado en la página del pedido.

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_nets_nexi_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_nets_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_nets_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 Nets Nexi 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. Copia la clave secreta de prueba desde el portal de pruebas de Nets Easy y pégala en Test Secret Key (ver Configuración). No hay que configurar nada en el portal de Nets.

5. Activa Enable/Disable, deja Test Mode activado, haz clic en Save y realiza un pedido de prueba. Después introduce la clave secreta 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_nets_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 Nets Nexi Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón con el lápiz).

4. Introduce la clave de licencia y las claves secretas como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la dirección del webhook es diferente (ver Webhooks).

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 Nets Nexi 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 te avisa cuando falta la clave secreta del modo seleccionado, por ejemplo Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., y muestra Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. mientras el modo de prueba esté activado. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (hasta 128 caracteres), Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y la geo zone y los estados de pedido deben existir; si algún campo es incorrecto, no se guarda nada.

Nets Nexi (países nórdicos)

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

Title: el título del método de pago que se muestra a los clientes durante la compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Nets Easy. Obligatorio.

Description: el texto que el cliente ve en el paso Confirm Order. Por defecto: Pay securely with Nets Easy.

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

Geo Zone: ofrece Nets 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 importe total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Nets. Déjalo vacío para ofrecer Nets con cualquier importe.

Claves de API

Copia las claves secretas del portal de Nets Easy en Company > Integration: el portal de pruebas (test.portal.dibspayment.eu) para la clave de prueba y el portal de producción (portal.dibspayment.eu) para la clave de producción. La sección enlaza a ambos portales. Las claves de checkout no son necesarias.

Test Mode: el modo de prueba usa test.api.dibspayment.eu con la clave secreta de prueba; el modo de producción usa api.dibspayment.eu con la clave secreta de producción. Los reembolsos y las capturas de un pedido siempre usan el entorno en el que se pagó. Por defecto: activado. Mientras está activado, los clientes ven Test mode: no real money will be charged. en el paso Confirm Order.

Test Secret Key: tu clave secreta de API del entorno de prueba de Nets.

Live Secret Key: tu clave secreta de API del entorno de producción de Nets.

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

Pago

Webhooks: las notificaciones de Nets (webhooks) se registran automáticamente con cada pago. No hay nada que configurar en el portal de Nets. El campo muestra la dirección a la que se envían. En OpenCart 3 tiene un aspecto como https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook, y en OpenCart 4 como https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Si no es una dirección HTTPS pública, el campo te avisa de que la tienda no recibe webhooks; en ese caso, los pagos se confirman cuando el cliente vuelve a la tienda o con Nets: check payment status and capture en la página del pedido. Se registran estos eventos:

Cada webhook debe incluir el secreto aleatorio que la extensión creó para ese pago. Los webhooks sin el secreto correcto se rechazan. El webhook solo indica a la extensión qué pago cambió: el pago en sí siempre se lee de la API de Nets con la clave secreta del entorno en el que se realizó.

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido «missing order»). Recibe un estado solo después de que el pago se haya leído de la API de Nets (webhook, el regreso del cliente a la tienda o Nets: check payment status and capture en la página del pedido) y de que se haya cobrado una reserva que coincida. Cada campo de estado de abajo muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado del pedido una vez que Nets haya confirmado y cobrado el pago. Por defecto: Processing. Elige Complete para marcar los pedidos pagados como completados.

Nets Payment On Hold Status: el importe o la moneda difieren del pedido, el cobro falló o el cliente pagó después de que el pedido se cancelara. No se cobra nada automáticamente y una nota explica el motivo. Por defecto: Pending, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled Status: se establece cuando la reserva del pedido se cancela en el portal de Nets. Por defecto: Canceled.

Refunded Status: se establece después de reembolsar completamente el pago desde la página del pedido. Por defecto: Refunded.

Avanzado

Debug log: registra las llamadas a la API y los cambios de estado de los pagos en nng_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Las claves y los datos de los clientes no se registran. Los errores y las advertencias siempre se registran, también cuando está desactivado. 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 y reembolsos de Nets de los pedidos siempre se conservan. Por defecto: desactivado.

Importar / Exportar

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

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

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto Nets Easy). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the Nets payment page to pay securely. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea un pago de Nets por el total del pedido en la moneda del pedido, con los productos, el envío y los demás totales del pedido (cupones, vales, comisiones) como líneas del pedido, y envía al cliente a la página de pago alojada por Nets. 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 compra. La referencia del pago en Nets es el número de pedido de OpenCart. El correo electrónico, el nombre, la dirección de envío y el teléfono del cliente se envían a Nets cuando Nets acepta su formato. La página de términos y condiciones de compra de tu tienda aparece enlazada en la página de Nets (si no hay ninguna, la página principal de la tienda).

Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Nets lo confirma: la extensión lee el pago de la API de Nets, compara el importe y la moneda reservados con el pedido, cobra la reserva y solo entonces establece el estado del pedido. Esto ocurre con el webhook o cuando el cliente regresa, lo que suceda primero. Después, el pedido recibe su estado de la forma habitual de OpenCart, con el correo electrónico estándar del pedido y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart. Si el pago todavía no se puede confirmar (no se pudo contactar con Nets, o otra petición lo estaba confirmando en ese momento), una página Payment confirmation muestra Your Nets payment is being confirmed. Your order will be updated as soon as it is confirmed — please do not pay again. con los botones Check again y Back to checkout.

Si el cliente cancela en la página de Nets, vuelve a la compra con The Nets payment was cancelled. You can try again or choose another payment method. Si no se pagó nada, el mensaje es The payment was not completed. You can try again or choose another payment method. En OpenCart 4 estos mensajes se muestran encima de la página de compra. El carrito se conserva. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un mismo pedido para la compra y paga ese pedido de nuevo con un nuevo pago de Nets. En un nuevo intento, la extensión comprueba primero los pagos anteriores del carrito; si uno ya está pagado, se confirma ese pedido en lugar de crear un pago nuevo. Si no, las sesiones anteriores de Nets se cierran antes de iniciar una nueva. Cuando otro pedido del mismo carrito ya está pagado o en espera, el cliente pasa a la página de éxito.

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 mientras tanto (por ejemplo, lo cancelaste, también después de cancelar la reserva en el portal de Nets), 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 Nets, y el siguiente Confirm Order paga un pedido nuevo. Un pedido del carrito que se pagó y después se canceló o reembolsó ya no retiene el carrito.

Si Nets no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje breve, por ejemplo Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. o The payment service could not be reached. Please try again in a moment. Un importe de pedido de cero da The order total must be greater than zero to pay with Nets. Los detalles se escriben en el registro.

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 en OpenCart 4 la extensión añade una acción de inicio para ello, que también permite al cliente volver desde Nets.

La extensión solo usa la página de pago alojada. No tiene pago de Nets integrado en la propia página, ni suscripciones o pagos recurrentes, ni tarjetas guardadas, ni tasas de factura, ni modo de solo autorización, ni capturas parciales por envío.

Pedidos y reembolsos

Estados de pedido

No status (missing order): el cliente fue enviado a Nets y no ha pagado, o el pago todavía no está confirmado. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Order Status After Payment (default Processing): Nets confirmó y cobró el pago. Una nota muestra el ID del pago, el ID del cobro y el método de pago.

Nets Payment On Hold Status (default Pending): el importe o la moneda en Nets difieren del pedido (no capturado), el cobro fue rechazado o el cliente pagó después de que el pedido se hubiera cancelado (reservado, no capturado). La nota lo explica. No se cobra nada automáticamente. Tras revisar el pedido, captura con Nets: check payment status and capture o cancela la reserva en el portal de Nets.

Cancelled Status (default Canceled): la reserva del pedido se canceló, por ejemplo en el portal de Nets.

Refunded Status (default Refunded): el pago se reembolsó por completo a través de la extensión.

Cuando un webhook o el regreso del cliente pasa un pedido del estado en espera al estado pagado o lo cancela, OpenCart notifica al cliente. Los webhooks repetidos y las recargas nunca cobran dos veces ni añaden notas duplicadas, y un pedido pagado nunca vuelve a cambiar por eventos de Nets. Si un enlace de pago antiguo se completa para un pedido que ya está pagado, o para otro pedido del mismo carrito, la segunda reserva se libera automáticamente; si ya se había cobrado, una nota te pide reembolsarla en el portal de Nets. Si el pedido se marcó como pagado de otra forma, un pago de Nets reservado no se captura y una nota lo indica.

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

Pestaña VibeFox Nets Nexi Gateway

En Sales > Orders abre un pedido pagado con Nets. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Nets Nexi Gateway muestra el bloque Nets Easy payment: el ID del pago, el ID del cobro, el entorno (con la etiqueta Test environment en los pagos de prueba), el estado y el método de pago, los importes reservados y cobrados en Nets, el total del pedido y el importe reembolsado, el formulario de reembolso, el historial de reembolsos y las Nets notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión; sus botones requieren el permiso para modificar la extensión (se configura en System > Users > User Groups).

Nets: check payment status and capture: aparece en los pedidos que todavía no están pagados. Lee el pago de Nets y captura una reserva que coincida con el pedido, también después de una captura fallida o tras haber revisado un pedido en espera. Si nada cambia, una nota explica el motivo, por ejemplo que el cliente aún no ha completado el pago. Un estado establecido con este botón, como un estado establecido por un reembolso, se cambia directamente, como cambio manual de estado, sin correos electrónicos ni movimientos de stock.

Reembolsos

En la pestaña, introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via Nets. Confirma la pregunta Refund this amount through Nets? This cannot be undone. Los reembolsos totales y parciales son posibles una vez cobrado el pago, hasta el total del pedido; un pago que solo está reservado puede cancelarse en el portal de Nets. El reembolso va al cobro del pedido en el entorno en el que se pagó, así que debe estar configurada la clave secreta de ese entorno. Si Nets no acepta el reembolso, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ID de reembolso de Nets. Un reembolso total establece el pedido en Refunded Status; un reembolso parcial no cambia el estado.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Nets. Los reembolsos hechos en el portal de Nets no se sincronizan; actualiza el pedido manualmente si es necesario.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Nets Nexi Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Nets Nexi 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-nets-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, Nets 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 queda oculto 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 se siguen confirmando y los reembolsos funcionan.

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

Nets Nexi no aparece en la compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el modo seleccionado tiene una clave secreta: Test Secret Key en modo de prueba, Live Secret Key en modo de producción. La página de ajustes muestra una advertencia cuando falta la clave. 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: el webhook no llegó a tu tienda. Comprueba que la tienda usa HTTPS, de modo que la dirección de Webhooks sea una dirección HTTPS pública, y que la clave secreta del entorno del pago esté configurada. El pedido también recibe su estado cuando el cliente vuelve a la tienda después de pagar, o con Nets: check payment status and capture en la pestaña del pedido.

El webhook responde Unauthorized: el webhook no llevaba el secreto de ese pago. Los webhooks solo se aceptan con el secreto registrado con el pago.

El webhook responde Unknown payment: el pago no lo creó esta tienda.

El webhook responde Busy, retry later, Payment lookup failed o Payment not reserved yet: otra petición estaba confirmando el mismo carrito, no se pudo contactar con la API de Nets, o la reserva todavía no era visible. Nets vuelve a intentar el webhook automáticamente.

El webhook responde Order could not be updated, retry later: no se pudo establecer el estado del pedido. Nets vuelve a intentar el webhook. Activa Debug log para ver el motivo.

La URL del webhook muestra Method not allowed en el navegador: es normal. La dirección solo acepta peticiones de Nets.

El cliente ve un error después de Confirm Order: activa Debug log y revisa el campo Log de la página de la extensión. This payment method is temporarily unavailable. Please choose another payment method. normalmente indica una clave secreta incorrecta o que falta. Una moneda rechazada aparece en el registro, informada por Nets. This payment method is not available. significa que la sesión de compra ya no coincide con el pedido, o que el método de pago se desactivó entretanto: el cliente recarga la compra.

El cliente ve We could not match this payment to an order: el enlace de regreso está incompleto o pertenece a otro pedido. Si el cliente fue cobrado, busca el pago en el portal de Nets y revisa el pedido.

El pedido está en el estado en espera tras el pago: lee las Nets notes de la pestaña. Si el cobro fue rechazado, vuelve a intentarlo con Nets: check payment status and capture o cóbralo en el portal de Nets. Si el importe o la moneda no coinciden, revisa el pago en el portal de Nets. Si el cliente pagó después de la cancelación, revisa el pedido y captura o cancela la reserva.

Refund via Nets no aparece o falla: los reembolsos solo son posibles después de que el pago se haya cobrado; la pestaña muestra entonces un ID de cobro. Un reembolso usa la clave secreta del entorno en el que se pagó el pedido, así que esa clave debe estar configurada; si no, la pestaña indica qué clave de entorno falta.

Para desarrolladores: antes de crear el pago, la extensión dispara el evento de OpenCart nng_create_payment_payload con el cuerpo de la petición y el pedido; nng_currency_decimals cambia los decimales de una moneda.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Nets Nexi 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 pedido de la sección Payment, que vuelven a sus valores predeterminados al reinstalar. En OpenCart 4 también se eliminan los eventos de la extensión y su acción de inicio, que deja pasar el webhook 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, claves secretas, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los datos de pagos de Nets de los pedidos (pagos, cobros y reembolsos) siempre se conservan, así que los pedidos pagados antes se pueden reembolsar después de reinstalar. 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 desinstalarla y haz clic en Uninstall (el botón naranja −) junto a VibeFox Nets Nexi Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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