VibeFox Niubiz for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 6.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Moneda de la tienda: soles peruanos (PEN) o dólares estadounidenses (USD). Para otras monedas, el método de pago 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, 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
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_niubiz_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Niubiz > 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 Sandbox mode activado e introduce el merchant ID, el API user y la API password del sandbox (véase Configuración).
6. Activa Enable/Disable y haz algunos pagos de prueba con las tarjetas de prueba de Niubiz.
7. Cuando Niubiz certifique tu integración, introduce las credenciales de producción y desmarca Sandbox mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Niubiz. Encima de los campos, la página te avisa cuando la moneda de la tienda no es PEN ni USD, o cuando las credenciales del modo actual están incompletas (en ambos casos el método de pago se oculta en la finalización de compra), y muestra El modo sandbox está activado: los pagos van al sandbox de Niubiz y no se realiza ningún cargo real. mientras el modo sandbox esté activado. En la lista de métodos de pago, Niubiz aparece como pendiente de configuración hasta que el modo actual tenga las credenciales completas.
General
Enable/Disable: Enable Niubiz payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. Predeterminado: Credit or debit card (Niubiz).
Description: el texto que se muestra bajo el 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: Use the Niubiz sandbox (QA) environment — no real charges. Cambia tanto los endpoints de la API como el conjunto de credenciales de abajo. Predeterminado: activado. Desmárcalo para los pagos reales.
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 de ajustes muestra un error y conserva el valor anterior.
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.
Production API user: el API user de producción.
Production API password: la API password de producción.
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 empiece por https:// se rechaza y se conserva el valor anterior.
Avanzado
Debug log: Log API calls escribe las peticiones de Niubiz en WooCommerce > Status > Logs, origen wcp_niubiz_payment. Los errores siempre se registran. Las credenciales, los tokens y los datos de tarjeta y de cliente nunca se registran. Predeterminado: desactivado.
Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. Desactivar el plugin nunca borra nada. Los datos de pago guardados en los pedidos se conservan. Predeterminado: desactivado.
Los ajustes de la versión 1.0, que tenía un solo conjunto de credenciales, se trasladan automáticamente: a los campos de sandbox si el modo de prueba estaba activado, y si no, a los campos de producción.
Finalización de compra
El cliente elige el método de pago (por defecto Credit or debit card (Niubiz)) y realiza el pedido. El plugin solicita a Niubiz un token de acceso y una sesión de pago por el total del pedido, y envía al cliente a la página de pago del pedido de tu tienda. En modo sandbox, la finalización de compra y la página de pago muestran MODO SANDBOX: usa las tarjetas de prueba de Niubiz; no se realiza ningún cargo real.
En la página de pago se abre automáticamente el formulario de pago de Niubiz. La página también tiene un botón Pay con el total del pedido para volver a abrir el formulario, un botón Cancel order 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 plugin lo autoriza en el servidor con el importe, la moneda y el número de compra propios del pedido. El pago se cobra de inmediato. El pedido se marca como pagado solo cuando Niubiz aprueba el pago y la respuesta coincide con el pedido. Después, el cliente ve la página de pedido recibido.
Tarjeta rechazada: el cliente vuelve a la página de pago con Tu pago ha sido rechazado: y el motivo de 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, error del servidor o respuesta ilegible), el cliente ve la página de pedido recibido con No hemos podido confirmar tu pago con Niubiz. No vuelvas a pagar: la tienda verificará el pago y se pondrá en contacto contigo.
Sesión caducada: la sesión de pago dura hasta 20 minutos. Cuando se usa o está a punto de caducar, o cuando cambian el total del pedido o el modo, la página de pago crea una sesión nueva.
Cada intento de pago recibe un número de compra nuevo: el ID del pedido 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 cliente puede volver a pagar un pedido sin pagar o fallido desde la página Pay for order.
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 únicos con tarjeta. No tiene reembolsos ni anulaciones desde WooCommerce, 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
Pendiente de pago: el cliente fue enviado a la página de pago y aún no ha pagado.
Procesando: Niubiz aprobó el pago y la respuesta coincidió con el pedido. Los pedidos con solo productos virtuales descargables pasan a Completado, como es habitual en WooCommerce. La nota del pedido 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. El ID de transacción del pedido es el ID de transacción de Niubiz.
Fallido: la tarjeta fue rechazada. La nota del pedido muestra el motivo de Niubiz, el código de acción y el número de compra. El cliente puede volver a pagar.
En espera, aprobado pero no coincide: Niubiz aprobó un pago cuyo número de compra, importe o moneda difiere del pedido, o cuya respuesta no contiene el importe o la moneda. El pedido no se marca como pagado; la nota enumera las diferencias. Comprueba la transacción en la consola de Niubiz. El cliente ve Tu pago se ha recibido y la tienda lo está revisando.
En espera, sin respuesta definitiva: Niubiz no respondió con claridad, así que la tarjeta podría haberse cargado. 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 a Procesando; si no, cancélalo.
Cancelado: el cliente hizo clic en Cancel order en la página de pago, o tú o el tiempo de reserva de stock de WooCommerce cancelasteis el pedido.
Cuando Niubiz rechaza la petición en sí (por ejemplo un número de compra duplicado, HTTP 406 o credenciales no válidas), el estado del pedido no cambia. Una nota indica que la tarjeta no se cargó, y el cliente puede reintentarlo con un número de compra nuevo.
Reembolsos
Los reembolsos y las anulaciones no están disponibles desde WooCommerce. Reembolsa o anula la transacción en la consola de Niubiz y actualiza el pedido manualmente, por ejemplo con un reembolso manual de WooCommerce.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Niubiz. 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, Niubiz 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 en el formulario de Niubiz siguen autorizándose.
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
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 (campos de sandbox en modo sandbox, campos de producción en caso contrario) y que la moneda sea PEN o USD. En la página Pay for order cuenta la moneda del pedido. La página de ajustes muestra una advertencia cuando las credenciales o la moneda son incorrectas.
El pago se realizó, pero el pedido sigue en Pendiente de pago: Niubiz no tiene webhook para este formulario de pago, así que el pedido solo se actualiza con la respuesta a la autorización. Si el pedido está En espera con una nota, busca el número de compra en la consola de Niubiz. Si sigue en Pendiente de pago, el cliente no terminó el formulario; revisa WooCommerce > Status > Logs, origen wcp_niubiz_payment.
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 el 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 Tu sesión de pago ha caducado y no se ha cargado nada en tu tarjeta: la página de pago estuvo abierta demasiado tiempo. El cliente vuelve a intentarlo en la misma página.
Nota del pedido: 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 reintentar con un número de compra nuevo.
El pedido está En espera con una nota de Niubiz: lee la nota. 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 a Procesando o cancélalo.
Error al guardar los ajustes: un merchant ID solo puede contener dígitos, y la URL del logotipo debe ser una dirección https:// válida. Se conserva el valor anterior.
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 la dirección del sitio ha cambiado, 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.
Para desarrolladores: si Niubiz te pide enviar campos antifraude específicos del comercio (MDD), añádelos con el filtro niubiz_p_merchant_define_data. Las claves son MDD más un número, y los valores tienen hasta 100 caracteres. Otros filtros: niubiz_p_cardholder_data (datos del titular enviados con la sesión de pago), niubiz_p_purchase_number (número de compra de un intento, de 1 a 12 letras o dígitos, único por intento) y niubiz_p_icon (icono del método de pago).
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. Los datos de Niubiz guardados en los pedidos (ID de transacción, número de compra, tarjeta enmascarada) forman parte del historial de pagos y siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Niubiz es una marca comercial de su propietario. Este plugin no está afiliado a Niubiz ni cuenta con su respaldo.