VibeFox Niubiz 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.
Moneda: soles peruanos (PEN) o dólares estadounidenses (USD). El método de pago solo se ofrece para carritos en una de estas monedas. Para las demás monedas se oculta en la finalización de compra.
Cuenta de Niubiz: Niubiz emite un merchant ID (código de comercio), un API user y una API password para cada entorno. Las credenciales de sandbox las proporciona el equipo de integraciones de Niubiz; las de producción, después de que Niubiz certifique tu integración. No hace falta configurar ningún webhook: Niubiz responde a la autorización de inmediato.
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, más tarde, busca VibeFox Niubiz Payment 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 (ver Clave de licencia).
4. Deja Sandbox mode activado e introduce el merchant ID, el API user y la API password de sandbox (ver Configuración).
5. Activa Enable/Disable, haz clic en Save y haz algunos pagos de prueba con las tarjetas de prueba de Niubiz.
6. Cuando Niubiz certifique tu integración, introduce las credenciales de producción y desactiva Sandbox mode.
Al instalar, el módulo crea el estado de pedido Niubiz payment on hold. PrestaShop vincula un módulo de pago nuevo a todas las monedas, a todos los grupos de clientes y a los países activos en ese momento. Puedes cambiarlo en Payment > Preferences. Comprueba allí que PEN o USD esté permitido para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página avisa si no hay ninguna moneda PEN o USD activa en la tienda, o si las credenciales del modo actual están incompletas (en ambos casos el método de pago se oculta en la finalización de compra). Si la moneda predeterminada de la tienda no es PEN ni USD, la página indica que Niubiz solo se ofrece para carritos en PEN o USD. Mientras el modo sandbox esté activado, la página muestra El modo sandbox está activado: los pagos van al sandbox de Niubiz y no se realiza ningún cargo real.
Niubiz
Enable/Disable: Enable Niubiz payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Credit or debit card (Niubiz). Obligatorio: un título vacío no se guarda y se mantiene el anterior.
Description: el texto que aparece debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.
Credenciales de Niubiz
Niubiz te proporciona un merchant ID, un API user y una API password para el sandbox y, tras la certificación, para producción. La documentación para desarrolladores está en desarrolladores.niubiz.com.pe.
Sandbox mode: usa el entorno sandbox (QA) de Niubiz, sin cargos reales. Cambia tanto los endpoints de la API como el conjunto de credenciales de abajo. Predeterminado: activado. Desactívalo para los pagos reales. Mientras está activado, los clientes ven MODO SANDBOX: usa tarjetas de prueba de Niubiz — no se realiza ningún cargo real. debajo del método de pago y en la página de pago.
Sandbox merchant ID: el código de comercio de tu cuenta de sandbox, solo dígitos. Los espacios se eliminan. Si el valor contiene otros caracteres, la página muestra un error y conserva el valor anterior. Los demás campos se guardan.
Sandbox API user: el API user del sandbox.
Sandbox API password: la API password del sandbox.
Production merchant ID: el código de comercio de tu cuenta de producción (afiliada), solo dígitos, con la misma comprobación.
Production API user: el API user de producción.
Production API password: la API password de producción.
Las contraseñas guardadas no se vuelven a mostrar. El campo queda vacío y muestra Guardada — deja el campo vacío para conservarla. Escribe un valor nuevo solo si quieres cambiarla.
Clear saved passwords: marca una contraseña y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.
Formulario de pago
Logo URL: dirección HTTPS opcional de tu logotipo, que se muestra en el formulario de pago de Niubiz, de unos 187 × 40 px. Sin ella se muestra el nombre de la tienda. Una dirección que no sea una dirección https:// válida se rechaza con un error y se mantiene la anterior.
Avanzado
Debug log: registra las llamadas a la API de Niubiz en logs/niubiz_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso cuando este interruptor está desactivado. Las credenciales, los tokens y los datos de la tarjeta y del cliente nunca se registran. Predeterminado: 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 el módulo se eliminan sus ajustes y el registro. Los datos de pago guardados para los pedidos (intentos de Niubiz, notas del pedido) y el estado del pedido se conservan siempre. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (de forma predeterminada Credit or debit card (Niubiz)) y confirma el pedido. El módulo solicita a Niubiz un token de acceso y una sesión de pago por el total del carrito en la moneda del carrito, y abre la página de pago Niubiz payment de tu tienda. Todavía no existe ningún pedido en este punto.
En la página de pago se abre automáticamente el formulario de pago de Niubiz. La página indica Completa el pago en el formulario seguro de pago de Niubiz: los datos de tu tarjeta se introducen en Niubiz, no en esta web. También tiene un botón Pay con el total del carrito para volver a abrir el formulario y un enlace Choose another payment method. Se necesita JavaScript. Si el formulario de Niubiz no se puede cargar, la página muestra No se pudo cargar el formulario de pago de Niubiz. Vuelve a cargar la página o inténtalo más tarde.
El cliente introduce la tarjeta en el formulario de Niubiz. Niubiz devuelve a tu tienda un token de un solo uso y el módulo lo autoriza en el servidor con el importe, la moneda y el número de compra de la sesión, en el entorno en el que se creó la sesión. El pago se cobra de inmediato. El pedido se marca como pagado solo cuando Niubiz aprueba el pago y la respuesta coincide con el carrito. Después se crea el pedido y el cliente ve la página estándar de confirmación del pedido.
Tarjeta rechazada: no se crea ningún pedido. El cliente vuelve a la página de pago con Tu pago ha sido rechazado: y el motivo de Niubiz, y puede intentarlo de nuevo con la misma tarjeta u otra. El formulario no se vuelve a abrir sobre el mensaje; el cliente hace clic en Pay.
Sin respuesta de Niubiz: si Niubiz no da una respuesta definitiva (tiempo de espera, error del servidor o respuesta ilegible), el pedido se crea en Niubiz payment on hold y la página de confirmación muestra No hemos podido confirmar tu pago con Niubiz. No vuelvas a pagar: la tienda comprobará el pago y se pondrá en contacto contigo. Si Niubiz aprobó un pago que no coincide con el carrito, la página muestra Tu pago se ha recibido y la tienda lo está revisando. Te contactaremos si hace falta algo más.
Solicitud rechazada: si Niubiz rechaza la propia solicitud (por ejemplo, credenciales no válidas o un número de compra duplicado), no se crea ningún pedido y el cliente ve Niubiz no ha podido procesar el pago y tu tarjeta no ha sido cargada. El motivo se escribe en el registro.
Carrito modificado: si el total del carrito cambia después de abrir el formulario (por ejemplo, en otra pestaña del navegador), el pago no se autoriza y el cliente ve Tu carrito ha cambiado desde que se abrió el formulario de pago, así que tu tarjeta no ha sido cargada. Comprueba el total y vuelve a pagar.
Sesión caducada: una sesión de pago de Niubiz dura hasta 20 minutos. Si ya se ha usado, le quedan menos de 5 minutos, pertenece a otro modo o a otro merchant ID, o el total del carrito ha cambiado, la página de pago crea una nueva sesión.
Cada intento de pago recibe un nuevo número de compra: el ID del carrito seguido de un número de intento de tres dígitos (hasta 12 caracteres), porque Niubiz exige un número de compra único para cada autorización.
El módulo acepta solo pagos únicos con tarjeta. No ofrece reembolsos ni cancelaciones desde PrestaShop, ni tarjetas guardadas, suscripciones o pagos recurrentes, ni selección de cuotas (cuotas), ni PagoEfectivo, Yape u otras billeteras y pagos con QR. Los pedidos puestos en espera porque se perdió la respuesta no se vuelven a comprobar automáticamente.
Pedidos
Estados del pedido
No order yet: el cliente está en la página de pago y no ha pagado, o la tarjeta fue rechazada o la solicitud fue denegada. Solo existe el carrito. Los rechazos y las denegaciones se escriben en el registro del módulo.
Payment accepted: Niubiz aprobó el pago y la respuesta coincidió con el carrito. El pago se registra con el ID de transacción de Niubiz, y una nota muestra el entorno, el ID de transacción, el código de autorización, el número de compra y la marca de la tarjeta con el número enmascarado.
Niubiz payment on hold, approved but not matching: Niubiz aprobó un pago cuyo número de compra, importe o moneda difiere del carrito, o cuya respuesta no contiene el importe o la moneda. El pedido no se marca como pagado. Si la aprobación está en la moneda del carrito, el importe aprobado se registra como un pago con su ID de transacción. La nota enumera las diferencias. Comprueba la transacción en la consola de Niubiz.
Niubiz payment on hold, no definitive answer: Niubiz no respondió con claridad, así que la tarjeta podría haberse cargado. No se registra ningún pago. La nota indica el número de compra. Búscalo en la consola de Niubiz: si la transacción está aprobada y es correcta, pon el pedido en Payment accepted; si no, cancélalo.
Si llega un segundo pago para un carrito que ya tiene pedido, no se crea un segundo pedido. Una nota en el pedido indica el número de compra, el ID de transacción y el importe, para que lo compruebes en la consola de Niubiz y lo reembolses o anules si hace falta.
Bloque de pago de Niubiz
La página del pedido muestra un bloque Niubiz payment con el número de compra, el entorno (sandbox o producción), el ID de transacción, el código de autorización, la tarjeta y las notas del pedido. En un pedido en Niubiz payment on hold, el bloque te recuerda que compruebes el número de compra en la consola de Niubiz. El bloque es de solo lectura.
Reembolsos
Los reembolsos y las cancelaciones no están disponibles desde PrestaShop. Reembolsa o anula la transacción en la consola de Niubiz y actualiza el pedido manualmente. Los botones estándar de reembolso de PrestaShop de la página del pedido no devuelven dinero a través de Niubiz.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Niubiz Payment es el primer bloque de Modules > Module Manager > VibeFox Niubiz Payment > 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-niubiz 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 Clave no encontrada, Esta clave pertenece a otro producto, Se ha alcanzado el límite de dominios o La licencia caducó el seguido de una fecha. Después de que cambie la dirección de la tienda, o 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, Niubiz no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve Este método de pago no está disponible. Elige otro. El storefront 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 la finalización de compra. 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.
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 después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Niubiz no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el merchant ID, el API user y la API password del modo actual estén rellenados (los campos de sandbox en modo sandbox, los de producción en el resto de casos) y que la moneda del carrito sea PEN o USD. La página de ajustes muestra un aviso si las credenciales o las monedas son incorrectas. 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: Niubiz no tiene webhook para este formulario de pago, así que el pedido se crea solo con la respuesta a la autorización. Si el cliente no terminó el formulario, no hay pedido. Si no, mira el campo Log de la página del módulo y busca el número de compra en la consola de Niubiz. Si Niubiz respondió pero el pedido no se pudo crear (por ejemplo, porque el módulo estaba desactivado), el cliente ve Tu pago se ha recibido, pero el pedido no se pudo completar automáticamente. Ponte en contacto con nosotros; no vuelvas a pagar., y el módulo vuelve a intentar crear el pedido cuando el cliente abre de nuevo la página de pago.
El cliente ve «No hemos podido conectar con Niubiz»: no se pudo obtener el token de acceso. Comprueba el API user y la API password del modo actual, y que tu servidor pueda acceder a la API de Niubiz. Activa Debug log para ver los detalles.
El cliente ve «No hemos podido iniciar el pago con Niubiz»: Niubiz no creó la sesión de pago. Comprueba el merchant ID del modo actual y el registro.
El cliente ve «Este intento de pago ya se ha procesado»: el mismo formulario se envió dos veces. El cliente vuelve a iniciar el pago en la página de pago; la tarjeta no se cobra dos veces.
El cliente ve «Este pedido ya se está pagando»: otra solicitud está autorizando el mismo carrito en este momento. El cliente espera un momento y revisa el correo electrónico antes de volver a intentarlo.
El registro muestra que Niubiz informó de una autorización duplicada: Niubiz ya conoce este número de compra. Compruébalo en la consola de Niubiz; el cliente puede reintentarlo con un nuevo número de compra.
El pedido está en Niubiz payment on hold: lee las notas del bloque Niubiz payment. Niubiz no dio una respuesta definitiva, o aprobó un pago que no coincide con el carrito. Busca el número de compra en la consola de Niubiz y pon el pedido en Payment accepted o cancélalo.
Error al guardar los ajustes: el merchant ID debe contener solo dígitos y la URL del logotipo debe ser una dirección https:// válida. Se mantiene el valor anterior.
Para desarrolladores: si Niubiz pide enviar campos antifraude específicos del comercio (MDD), otro módulo puede añadirlos con el hook actionNiubizPMerchantDefineData. Los datos del titular enviados con la sesión de pago se pueden modificar con el hook actionNiubizPCardholderData.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Niubiz Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Los intentos de pago de Niubiz (números de compra, entorno, ID de transacción) y el estado de pedido Niubiz payment on hold se conservan siempre como historial de pagos. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Niubiz es una marca comercial de su respectivo titular. Este módulo no está afiliado a Niubiz ni cuenta con su respaldo.