VibeFox Niubiz 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.

Moneda: los soles peruanos (PEN) o los dólares estadounidenses (USD) deben estar activados en System > Localisation > Currencies. El método de pago solo se ofrece cuando el cliente paga en una de estas monedas. Para las demás monedas se oculta en la finalización de compra.

Cuenta de Niubiz: Niubiz emite un ID de comerciante (código de comercio), un usuario de API y una contraseña de API para cada entorno. Las credenciales de sandbox las proporciona el equipo de integraciones de Niubiz, y las de producción, una vez que Niubiz certifica tu integración. No hay que 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

El archivo de descarga es un único zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_niubiz_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_niubiz_payment.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 panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_niubiz_payment-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también 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 Niubiz Payment y haz clic en Install (el botón verde +). Tu usuario de administración necesita permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. 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 (consulta License key).

4. Deja activado Sandbox mode e introduce el ID de comerciante, el usuario de API y la contraseña de API de sandbox (consulta Configuration).

5. Activa Enable/Disable, haz clic en Save y realiza 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.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_niubiz_payment.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 Niubiz Payment, haz clic en Install (el botón verde +) y, después, en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las credenciales de Niubiz y prueba los pagos como en los pasos 3 a 6 para OpenCart 3. La página de ajustes y sus campos son iguales en las dos versiones.

Una instalación nueva empieza con el método de pago desactivado y el modo sandbox activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit. Las secciones aparecen en la lista de la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, la página te avisa si no hay ninguna moneda PEN o USD activada 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 te indica que Niubiz solo se ofrece cuando el cliente paga en PEN o USD. Mientras el modo sandbox está activado, la página muestra Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. Sin el permiso para modificar la extensión, la página muestra los ajustes, pero no permite guardarlos.

Al guardar, un valor incorrecto no se guarda: la página muestra un error encima de los ajustes, el campo vuelve a su valor anterior y los demás campos sí se guardan. Esto se aplica a un Title vacío o de más de 128 caracteres, a un ID de comerciante que no contenga solo dígitos, a una URL del logotipo que no empiece por https://, a un Sort Order que no sea un número entero y a un Total que no sea un número igual o mayor que 0.

Niubiz

Enable/Disable: activa o desactiva los pagos con Niubiz. Por defecto: off.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Credit or debit card (Niubiz). Obligatorio, hasta 128 caracteres.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

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

Geo Zone: ofrece Niubiz solo para las direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones. En OpenCart 4, cuando la tienda no pide dirección de pago, se usa la dirección de envío.

Total: el importe total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Niubiz. Déjalo vacío para ofrecer Niubiz con cualquier importe.

Credenciales de Niubiz

Niubiz te proporciona un ID de comerciante, un usuario de API y una contraseña de API para el sandbox (QA) y, tras la certificación, para producción. Un pago que ya se ha iniciado siempre se autoriza con las credenciales de su propio modo.

Sandbox mode: usa el sandbox de Niubiz, sin cargos reales. Cambia tanto los endpoints de la API como el conjunto de credenciales que aparecen a continuación. Por defecto: on. Desactívalo para aceptar pagos reales con las credenciales de producción. Mientras está activado, los clientes ven SANDBOX MODE: use Niubiz test cards — no real charges are made. en el paso Confirm Order 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.

Sandbox API user: el usuario de API del sandbox, normalmente una dirección de correo electrónico.

Sandbox API password: la contraseña de API del sandbox.

Production merchant ID: el código de comercio de tu cuenta de producción (afiliada), solo dígitos.

Production API user: el usuario de API de producción.

Production API password: la contraseña de API de producción.

Las contraseñas guardadas nunca se vuelven a mostrar ni se envían al navegador. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para eliminar una contraseña guardada, marca Clear the saved password on save debajo del campo y haz clic en Save.

Formulario de pago

Logo URL: dirección opcional de tu logotipo, que se muestra en el formulario de pago de Niubiz. Debe ser una dirección https://. Déjalo vacío para mostrar el nombre de la tienda.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido sin terminar). El pedido recibe un estado solo después de que Niubiz haya respondido a la autorización. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: Niubiz aprobó el pago y el número de compra, el importe y la moneda coinciden con el pedido. Por defecto: Processing.

On Hold Status: Niubiz aprobó un pago que no coincide con el pedido, o no dio una respuesta definitiva, así que es posible que se haya cobrado la tarjeta. Por defecto: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Debug log: escribe las solicitudes a la API de Niubiz y los pasos del pago en niubiz_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web, y al llegar a 5 MB se traslada a niubiz_p_debug.old.log.php. Los errores y las advertencias siempre se registran, incluso cuando este interruptor está desactivado. Las contraseñas, los tokens y los datos de tarjeta o de clientes nunca se registran. Por defecto: off.

Log: muestra el tamaño y las entradas más recientes 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 datos de pago de Niubiz de los pedidos (números de compra, ID de transacción) siempre se conservan. Por defecto: off.

Importar / Exportar

Export: Download JSON guarda los ajustes como un archivo JSON. Las contraseñas de API no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las contraseñas de API guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Credit or debit card (Niubiz)). En el paso Confirm Order, el cliente ve tu descripción y la nota You will complete the payment in the secure Niubiz payment form. OpenCart crea el pedido en este paso, todavía sin estado. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque de métodos de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. Cuando el cliente hace clic en Confirm Order, la extensión solicita a Niubiz un token de acceso y una sesión de pago por el total del pedido, en la moneda del pedido, y abre la página Niubiz payment de tu tienda. Si no se puede crear la sesión, el cliente permanece en el paso Confirm Order con un breve mensaje, por ejemplo We could not connect to Niubiz. Please try again in a few minutes.

En la página de pago, el formulario de pago de Niubiz se abre automáticamente. La página indica Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. También tiene un botón Pay con el total del pedido para volver a abrir el formulario y un enlace Choose another payment method para volver a la finalización de compra. Se necesita JavaScript. Si el formulario de Niubiz no se puede cargar, la página muestra The Niubiz payment form could not be loaded. Please reload the page or try again later.

El cliente introduce la tarjeta en el formulario de Niubiz. Niubiz devuelve a tu tienda un token de un solo uso, y la extensión 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 solo se marca como pagado cuando Niubiz lo confirma y la respuesta coincide con el pedido. Después, el pedido recibe su estado de la forma habitual de OpenCart, con los correos electrónicos de pedido habituales y la actualización del stock, y el cliente ve la página de confirmación de pedido de OpenCart.

Tarjeta rechazada: el pedido permanece sin estado y se le añade una nota. El cliente vuelve a la página de pago con Your payment was declined: y el motivo que indica Niubiz, y puede volver a intentarlo 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 agotado, error del servidor, respuesta ilegible), el pedido recibe el On Hold Status y la página de confirmación muestra We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. Si Niubiz aprobó un pago que no coincide con el pedido, la página de confirmación muestra Your payment was received and is being reviewed by the store. We will contact you if anything else is needed.

Solicitud rechazada: si Niubiz rechaza la propia solicitud (por ejemplo, credenciales no válidas o un número de compra duplicado), el pedido permanece sin estado, se añade una nota y el cliente ve Niubiz could not process the payment and your card was not charged. Si en ese momento no se puede acceder a la API de Niubiz, el cliente ve We could not connect to Niubiz and your card was not charged. Please try again in a few minutes.

Pedido modificado: si el total del pedido ya no coincide con la sesión cuando se envía el formulario, el pago no se autoriza y el cliente ve Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again.

Sesión caducada: una sesión de pago de Niubiz dura hasta 20 minutos. Cuando ya se ha usado, le quedan menos de 5 minutos, pertenece a otro modo o ID de comerciante, o el total del pedido ha cambiado, la página de pago crea una nueva sesión.

Cada intento de pago recibe un nuevo número de compra: el número de pedido seguido de un número de intento de tres dígitos, porque Niubiz exige un número de compra único para cada autorización. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order. OpenCart 4 mantiene un solo pedido para la finalización de compra y lo actualiza, así que tras una tarjeta rechazada el cliente paga el mismo pedido con un número de compra nuevo. Un carrito que ya está pagado no se vuelve a cobrar: en su lugar, el cliente pasa a la página de confirmación del pedido pagado.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de confirmación. Si ese pedido se cerró sin pago entretanto (por ejemplo, lo cancelaste), el cliente vuelve a la finalización de compra con Your previous order was cancelled or its payment failed. Please confirm the order again., y el siguiente Confirm Order paga un pedido nuevo. Si ese pedido ya tiene un estado y el carrito tiene ahora otros productos o cantidades, el mensaje es Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. En OpenCart 4, los mensajes que devuelven al cliente a la finalización de compra, como The Niubiz payment could not be found. Please confirm your order again., se muestran encima de la página de finalización de compra.

La página de pago, la respuesta del formulario de Niubiz y el regreso a la tienda también funcionan mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para ellas.

La extensión solo admite pagos únicos con tarjeta. No ofrece reembolsos ni cancelaciones desde OpenCart, ni tarjetas guardadas, suscripciones ni pagos recurrentes, ni selección de cuotas (cuotas), ni PagoEfectivo, Yape ni otras billeteras y pagos con QR. Los pedidos retenidos porque se perdió la respuesta no se vuelven a comprobar automáticamente.

Pedidos

Estados de pedido

Sin estado (pedido sin terminar): el cliente está en la página de pago y no ha pagado, o la tarjeta fue rechazada o la solicitud fue denegada. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status configurado en Missing Orders. Los rechazos y las denegaciones se añaden a las notas del pedido.

En OpenCart 4, un pedido sin pagar de la finalización de compra puede recibir el estado Voided, que OpenCart 4 asigna cuando el cliente vuelve al paso Confirm Order. La extensión trata ese pedido como un pedido sin estado, y un pago posterior sigue confirmándolo.

Order Status After Payment (por defecto Processing): Niubiz aprobó el pago y la respuesta coincidió con el pedido. 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 de tarjeta enmascarado.

On Hold Status (por defecto Pending), aprobado pero no coincidente: Niubiz aprobó un pago cuyo número de compra, importe o moneda difiere del pedido, o cuya respuesta no contiene el importe ni la moneda. El pedido no se marca como pagado. La nota enumera las diferencias. Revisa la transacción en la consola de Niubiz.

On Hold Status (por defecto Pending), sin respuesta definitiva: Niubiz no respondió con claridad, así que es posible que se haya cobrado la tarjeta. La nota indica el número de compra. Búscalo en la consola de Niubiz: si la transacción está aprobada y es correcta, cambia el pedido al estado de pagado; si no, cancélalo.

Si se responde a un segundo pago para un carrito que ya está pagado, no se establece ningún segundo estado. Una nota en el pedido pagado indica el número de compra, el ID de transacción y el importe, para que puedas revisarlo en la consola de Niubiz y reembolsarlo o anularlo si es necesario.

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

Pestaña VibeFox Niubiz Payment

En Sales > Orders, abre un pedido pagado con Niubiz. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Niubiz Payment muestra el número de compra, el entorno (sandbox o producción), la Niubiz answer, el ID de transacción, el código de autorización, la tarjeta, el importe (y el importe aprobado por Niubiz), los problemas detectados, el número de intentos y las Niubiz notes del pedido. En un pedido con el estado de retención, la pestaña te recuerda que compruebes el número de compra en la consola de Niubiz. La pestaña es de solo lectura y la ven los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos y las cancelaciones no están disponibles desde OpenCart. Reembolsa o anula la transacción en la consola de Niubiz y actualiza el estado del pedido manualmente. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Niubiz.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Niubiz Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox Niubiz Payment > 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-niubiz y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios de administración con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Niubiz no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario de administración que haya iniciado sesión en el panel 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 panel de administración, así que sin una clave activa el método de pago se oculta a todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

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 cuando abres el Dashboard o la página Edit del panel de administración: 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 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

Niubiz no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el ID de comerciante, el usuario de API y la contraseña de API del modo actual estén rellenados (los campos de sandbox en modo sandbox, los de producción en los demás casos) y que el cliente pague en PEN o USD. La página de ajustes muestra una advertencia cuando las credenciales o las monedas son incorrectas. 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 sigue sin estado: Niubiz no tiene webhook para este formulario de pago, así que el pedido solo recibe su estado a partir de la respuesta a la autorización. Si el cliente no terminó el formulario, no se cobró nada. En caso contrario, revisa el campo Log de la página de la extensión y busca el número de compra en la consola de Niubiz. Si Niubiz respondió pero no se pudo establecer el estado, el cliente ve Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., y la extensión vuelve a intentar establecer el estado cuando el cliente abre la página de pago o confirma el carrito de nuevo.

El cliente ve We could not connect to Niubiz: no se pudo obtener el token de acceso. Comprueba el usuario de API y la contraseña de API del modo actual, y que tu servidor pueda acceder a la API de Niubiz. Activa Debug log para ver los detalles.

El cliente ve We could not start the Niubiz payment: Niubiz no creó la sesión de pago. Comprueba el ID de comerciante del modo actual y el registro.

El cliente ve This payment attempt was already processed: el mismo formulario se envió dos veces. El cliente inicia de nuevo el pago en la página de pago; la tarjeta no se cobra dos veces.

El cliente ve This order is already being paid: 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.

Una nota indica 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 volver a intentarlo con un nuevo número de compra.

El pedido está en el estado de retención: lee las notas de la pestaña VibeFox Niubiz Payment. Niubiz no dio una respuesta definitiva, o aprobó un pago que no coincide con el pedido. Busca el número de compra en la consola de Niubiz y cambia el pedido al estado de pagado o cancélalo.

Error al guardar los ajustes: el ID de comerciante debe contener solo dígitos, la URL del logotipo debe ser una dirección https:// válida y el título no puede estar vacío ni tener más de 128 caracteres. Se mantiene el valor anterior.

Para desarrolladores: si Niubiz te pide que envíes campos antifraude específicos del comerciante (MDD), otra extensión puede añadirlos con el evento de OpenCart niubiz_p_merchant_define_data. Los datos del titular de la tarjeta enviados con la sesión de pago pueden modificarse con el evento niubiz_p_cardholder_data.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Niubiz Payment. La clave de licencia y el estado de la 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 Orders, que vuelven a sus valores predeterminados al reinstalar. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar la página de pago, la respuesta del formulario de Niubiz y el regreso 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 sandbox, credenciales, logotipo, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los intentos de pago de Niubiz (números de compra, entorno, ID de transacción) siempre se conservan como historial de pagos. 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 la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Niubiz Payment en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Niubiz es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Niubiz ni cuenta con su respaldo.