VibeFox Netopia for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior con las extensiones OpenSSL, DOM y SimpleXML. El módulo no se instala sin ellas.
Moneda: la moneda del carrito debe ser RON, EUR, USD o GBP. EUR, USD y GBP deben estar habilitadas en tu cuenta de Netopia. Para otras monedas, el método de pago se oculta en el checkout.
Cuenta de Netopia: necesitas una cuenta de vendedor de Netopia Payments con un punto de venta. En sus ajustes técnicos necesitas la firma de la cuenta y, para cada entorno que uses (sandbox y en vivo), el certificado público (.cer) y la clave privada (.key). No hay que configurar nada en el lado de Netopia: la dirección IPN se envía con cada solicitud de pago.
Tienda pública: la URL de IPN (confirmación) debe ser accesible desde internet, no detrás de un inicio de sesión ni de autenticación básica. Los pedidos solo se crean mediante la IPN de Netopia.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 VibeFox Netopia Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).
4. En el panel de Netopia abre tu punto de venta, copia la firma de la cuenta y descarga el certificado y la clave privada del entorno sandbox y del entorno en vivo. Pega la firma y el contenido completo de los archivos en los ajustes (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo sandbox y, después, desactiva Test mode para aceptar pagos reales.
Al instalarse, el módulo crea dos estados de pedido, Awaiting Netopia payment y Netopia payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Netopia Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si falta la firma de la cuenta, el certificado o la clave privada del entorno activo (en ese caso el método de pago se oculta en el checkout), y muestra Test mode is on: payments go to the Netopia sandbox and no real money is charged. mientras el modo de prueba está activo. Al guardar, un certificado o una clave privada no válidos se rechazan con un error y se conserva el valor anterior; los demás campos se guardan.
IPN (confirm) URL
Se muestra en modo de solo lectura en la parte superior de la página. Con URL amigables tiene este formato: https://your-shop/module/wcp_netopia_gateway/notify, posiblemente con un código de idioma como /en/. Se envía con cada solicitud de pago como URL de confirmación, así que no hace falta introducirla en el panel de Netopia. Netopia envía la IPN a esta URL. El módulo la descifra con la clave privada del entorno en el que se inició el pago, y comprueba la firma de tu cuenta y la solicitud de pago. Netopia informa de estas acciones:
Una notificación con un código de error de Netopia (por ejemplo, una tarjeta rechazada) pone un pedido pendiente en Payment error; sin pedido, el cliente puede volver a pagar. Las notificaciones que no se pueden descifrar, llevan otra firma de cuenta o no responden a una solicitud de pago de ese carrito se rechazan y no cambian nada.
Finalizar compra
Enable/Disable: Enable Netopia Payments activa o desactiva el método de pago. Por defecto: off.
Title: el título del método de pago que se muestra en el checkout. También es el nombre del método de pago guardado en el pedido. Por defecto: Card Payment (Netopia).
Description: la descripción del método de pago que se muestra en el checkout. Por defecto: Pay securely with your credit or debit card via Netopia.
Cuenta de Netopia
En el panel de Netopia ve a Seller accounts > your point of sale > Technical settings: copia la firma de la cuenta y descarga el certificado público (.cer) y la clave privada (.key) de cada entorno. Abre los archivos en un editor de texto y pega todo su contenido, incluidas las líneas BEGIN/END.
Account signature: la firma de la cuenta de vendedor (formato XXXX-XXXX-XXXX-XXXX-XXXX), la misma para sandbox y en vivo.
Test mode: usa el sandbox de Netopia (sandboxsecure.mobilpay.ro) y las claves de sandbox. Por defecto: on. Desactívalo para aceptar pagos reales con las claves en vivo.
Sandbox public certificate (.cer): el contenido del archivo del certificado público de sandbox. Se usa para cifrar la solicitud de pago.
Sandbox private key (.key): el contenido del archivo de la clave privada de sandbox. Se usa para descifrar la IPN.
Live public certificate (.cer): el contenido del archivo del certificado público en vivo.
Live private key (.key): el contenido del archivo de la clave privada en vivo.
Las claves privadas guardadas nunca se vuelven a mostrar. El campo queda vacío, y su texto de ayuda empieza con A private key is saved. Déjalo vacío para conservar la clave guardada, o pega una clave nueva para reemplazarla. Un campo de certificado vacío elimina el certificado.
Clear saved private keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío conserva la clave guardada.
Pedidos
Order status after payment: el estado de un pedido pagado.
Avanzado
Debug log: registra las solicitudes y el procesamiento de las IPN en logs/netopia_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. No se registran datos de tarjeta, claves ni datos de clientes. Los errores, por ejemplo las IPN rechazadas, siempre se registran, incluso con la opción desactivada. Por defecto: off.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: al desinstalar el módulo, elimina los ajustes de la pasarela, los registros de pagos de Netopia del módulo y el registro. Los pedidos se conservan. Por defecto: off.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto Card Payment (Netopia)) y confirma. La página siguiente muestra Redirecting you to Netopia for secure payment… y envía al cliente automáticamente a la página de pago de Netopia, con los botones Proceed to payment y Cancel (volver al checkout) como alternativa. La solicitud de pago se cifra con tu certificado de Netopia y contiene el total del carrito en la moneda del carrito, Cart # con el número de carrito, y los datos de contacto de facturación y envío. En modo sandbox, la solicitud va al sandbox de Netopia. Todavía no existe ningún pedido en este punto.
El cliente paga con tarjeta en la página de Netopia y vuelve a tu tienda. La vuelta por sí misma nunca crea ni paga un pedido. El pedido se marca como pagado solo cuando Netopia lo confirma mediante la IPN. Si el pedido existe, el cliente ve la página estándar de confirmación del pedido. Para un pedido pendiente muestra Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Para un pedido en espera muestra Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Para un pedido cancelado muestra The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Para un pedido con error de pago muestra The payment was declined by Netopia.
Si la IPN aún no ha llegado cuando el cliente vuelve, una página Payment confirmation muestra el mismo texto de «aún no confirmado» con los botones Check again y Back to checkout. El pedido se crea en cuanto llega la IPN.
Si Netopia informó de una cancelación o de un rechazo antes de crear ningún pedido, el cliente vuelve al checkout con The payment was cancelled at Netopia. You can try again or choose another payment method. o The payment was declined by Netopia. You can try again or choose another payment method. El carrito se conserva. Cada nuevo intento es una nueva solicitud de pago; las solicitudes anteriores del carrito siguen siendo válidas, así que una IPN tardía de un intento anterior se sigue registrando.
Si el módulo no está bien configurado, el cliente permanece en el checkout con Netopia gateway is not configured properly. Please contact the store administrator. Otros mensajes son Netopia cannot process payments in, seguido de la moneda, This order has nothing to pay. y Payment encryption failed. Please try again or contact support. El motivo técnico se escribe en el registro.
La IPN 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 acepta pagos con tarjeta solo mediante el protocolo de tarjeta Netopia v1. No ofrece reembolsos ni capturas desde PrestaShop, ni tarjetas guardadas o pagos con un clic, ni suscripciones, pagos a plazos u otros métodos de pago, ni Netopia API v2.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Netopia y no ha pagado, o Netopia todavía no ha enviado la IPN. Solo existe el carrito.
Payment accepted or Delivered: Netopia confirmó el pago. El estado sigue a Order status after payment. El pago se registra con la transacción de Netopia como ID de transacción, y una nota privada muestra el importe, el número de tarjeta enmascarado y la transacción de Netopia; los pagos sandbox se marcan como [sandbox].
Awaiting Netopia payment: el pago es una preautorización que espera captura en el panel de Netopia, o está en revisión en Netopia. Todavía no se registra ningún pago. El pedido pasa al estado pagado cuando Netopia lo confirma.
Netopia payment on hold: el importe o la moneda de la factura difieren del carrito o del pedido, solo se capturó una parte del pago, Netopia confirmó el pago de un pedido cancelado o de un pedido realizado con otro método de pago, o se confirmó un pago sandbox (de prueba) mientras la tienda está en modo en vivo (no se recibió dinero real, por eso no se registra ningún pago). La nota lo explica. Revisa la transacción en el panel de Netopia y, después, procesa el pedido o reembolsa el pago allí.
Payment error: Netopia informó de un error, por ejemplo una tarjeta rechazada, para un pedido pendiente.
Canceled: Netopia canceló el pago de un pedido pendiente.
Refunded: el pago se reembolsó por completo en el panel de Netopia.
Las notificaciones tardías nunca degradan un pedido pagado o cerrado. Si Netopia confirma otro pago para un pedido que ya está pagado, una nota te pide reembolsar el duplicado en el panel de Netopia.
Bloque de Netopia
La página del pedido muestra un bloque Netopia Payments con la transacción de Netopia, el entorno (sandbox o en vivo), la solicitud de pago, la última acción de IPN, la tarjeta enmascarada, los importes pagado, reembolsado y restante, y el historial de reembolsos. El bloque es de solo lectura.
Reembolsos
Los reembolsos no se hacen desde PrestaShop: el protocolo de tarjeta Netopia v1 no tiene llamada de reembolso. Reembolsa la transacción en el panel de Netopia. Después, Netopia envía una IPN de crédito, y el módulo registra el reembolso en el pedido automáticamente, con la nota Netopia refund processed: y el importe. Un reembolso parcial mantiene el estado del pedido; cuando no queda nada por reembolsar, el pedido pasa a Refunded. Para los pedidos en EUR, USD y GBP, el importe reembolsado, que Netopia informa en RON, se convierte de nuevo a la moneda del pedido. Un reembolso nunca se registra dos veces ni por más del importe restante. Si Netopia informa de un error en el reembolso, solo se añade una nota.
El módulo no crea facturas de abono ni repone productos en el stock. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Netopia.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Netopia Gateway es el primer bloque de la página Modules > Module Manager > VibeFox Netopia Gateway > Configure, por encima de los ajustes. Introduce la clave en el campo 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-netopia y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 contactar con el servidor de licencias, 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. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Netopia no se muestra a los clientes en el checkout. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda 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 checkout. Aparece un recordatorio 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 reembolsos hechos en el panel de Netopia se siguen registrando.
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 después de introducir la clave, y luego una vez a la semana. No es necesario ningún cron job. Al desinstalar o restablecer el módulo, siempre se elimina la clave de licencia y el estado de la licencia.
Solución de problemas
Netopia no aparece en el checkout: comprueba que la licencia está activa, que Enable/Disable está activado, que el entorno activo está completo (Account signature más el certificado y la clave privada de sandbox en modo de prueba, o los de en vivo en modo en vivo) y que la moneda del carrito es RON, EUR, USD o GBP. La página de ajustes muestra un aviso cuando falta algo. En Payment > Preferences, comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: la IPN no llegó a tu tienda o fue rechazada. Comprueba que la URL de IPN (confirmación) de los ajustes es accesible desde internet (sin autenticación básica ni cortafuegos). Mira el campo Log en la página del módulo: las IPN rechazadas siempre se registran. Activa Debug log para ver todas las IPN. La vuelta del cliente por sí sola nunca crea un pedido.
El registro muestra failed decrypting data: la clave privada no coincide con el certificado que usó Netopia. La IPN se descifra con la clave privada guardada de cada entorno, así que mantén guardada la clave del otro entorno mientras sus pagos sigan abiertos. Netopia reintenta la IPN.
El registro muestra signature mismatch: la Account signature no coincide con el punto de venta que envió la IPN. Cópiala de nuevo desde el panel de Netopia.
El registro muestra unknown payment request: la IPN no responde a una solicitud de pago que tu tienda hizo para ese carrito en ese entorno (sandbox o en vivo). No se cambia nada.
El registro muestra gateway not configured: no hay clave privada ni firma de cuenta guardadas. Netopia reintenta la IPN, y el pago se registra una vez completados los ajustes.
El registro muestra busy, retry later or processing failed: el carrito estaba siendo procesado por otra solicitud en el mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Netopia reintenta la IPN automáticamente.
Error al guardar sobre el certificado o la clave privada: el texto pegado no es un certificado ni una clave válidos. Pega el contenido completo del archivo, incluidas las líneas BEGIN/END. Se conservó el valor anterior.
El pedido está en Netopia payment on hold tras el pago: lee la nota privada del pedido (ver Estados del pedido). El importe o la moneda eran distintos, solo se capturó una parte, el pedido se había cancelado o se confirmó un pago sandbox mientras la tienda estaba en modo en vivo. Revisa la transacción en el panel de Netopia.
Un reembolso hecho en Netopia no aparece en el pedido: la IPN de crédito no llegó a la tienda o fue rechazada. Revisa el registro.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Netopia Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo se eliminan siempre. Si Delete data on uninstall está activado, se eliminan los ajustes de la pasarela (incluidas las claves guardadas), los registros de pagos de Netopia del módulo (que se muestran en el bloque de Netopia de los pedidos) y el registro. Si está desactivado, todo se conserva para una reinstalación posterior. Los pedidos y los estados de pedido Awaiting Netopia payment y Netopia payment on hold nunca se eliminan. Los pedidos existentes conservan sus notas de pago e ID de transacción.
Netopia Payments y mobilPay son marcas comerciales de sus respectivos titulares. Este módulo no está afiliado ni respaldado por Netopia Payments.