VibeFox Iugu for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. Sin WooCommerce, el plugin no se activa.
PHP: 8.0 o posterior.
Moneda de la tienda: real brasileño (BRL). Iugu cobra solo en BRL. El método de pago se oculta cuando la tienda, o el pedido de la página Pay for order, usa otra moneda, y para importes inferiores a R$ 1,00 (el mínimo de Iugu).
Cuenta de Iugu: necesitas dos tokens de API del panel de Iugu, uno de tipo "Test" y otro de tipo "Live" (véase Configuración). Iugu usa una única dirección de API para ambos: el token decide si las facturas son de prueba o reales. No hace falta configurar ningún webhook en Iugu.
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_iugu_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Establece la moneda de la tienda en real brasileño (BRL) en WooCommerce > Settings > General.
4. Abre la configuración: WooCommerce > Settings > Payments > Iugu > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
5. 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.
6. Introduce los tokens de API de prueba y de producción (véase Configuración), deja Test mode activado, activa Enable / Disable y guarda.
7. Haz un pedido de prueba y págalo con una tarjeta de prueba de Iugu. Cuando todo esté listo, desmarca Test mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Iugu. Debajo del título de la pasarela, la página muestra TEST MODE (las facturas se crean con el token de API de prueba, sin cargos reales) o LIVE. Avisa cuando falta el token del modo activo (en ese caso el método de pago se oculta en la finalización de compra) y cuando la moneda de la tienda no es BRL. En la lista de métodos de pago, Iugu aparece como pendiente de configuración hasta que se introduzca el token del modo activo, y muestra una insignia de modo de prueba mientras este modo esté activado.
General
Enable / Disable: Enable Iugu payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. Por defecto: Iugu.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Iugu. You will be redirected to complete your payment.
Credenciales de API
Crea los tokens de API en Iugu Alia (alia.iugu.com): Settings > API integration > New. Crea un token de tipo "Test" y otro de tipo "Live".
Test mode: Use the test API token (no real charges). Por defecto: on. Mientras el modo de prueba esté activado, la finalización de compra muestra SANDBOX — Test mode enabled. No real charges. encima de la descripción. Las consultas de estado y los reembolsos de un pedido siempre usan el token del modo en el que se creó su factura, así que cambiar de modo no rompe los pedidos anteriores.
Test API token: el token de API de Iugu de tipo "Test". Se usa mientras el modo de prueba está activado.
Live API token: el token de API de Iugu de tipo "Live" (producción). Se usa cuando el modo de prueba está desactivado. Manténlo en secreto.
Notificaciones de pago
Cada factura indica a Iugu que informe de los cambios de estado a la URL de notificaciones de tu tienda, que aparece en esta sección de la configuración. Tiene este aspecto: https://your-site/wc-api/webhook_wc_iugu/. No hay nada que configurar en Iugu. Un disparador adicional para toda la cuenta (gatilho) que apunte a la misma URL no causa problemas. Las notificaciones no contienen datos de pago en los que la tienda confíe: la factura siempre se vuelve a leer desde la API de Iugu (estado, importe, moneda) antes de que cambie el pedido.
El plugin reacciona a los eventos de Iugu que pueden cambiar el estado de una factura: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action e invoices. Para cada uno de ellos lee la factura y aplica su estado:
Otros eventos y facturas que no pertenecen a un pedido de esta tienda reciben la respuesta OK y se ignoran. Sin notificaciones, el pedido solo se comprueba cuando el cliente vuelve a la tienda desde la página de Iugu.
Avanzado
Debug log: Log API requests and notifications en WooCommerce > Status > Logs, origen wcp_iugu_gateway, sin tokens ni datos de clientes. Los errores siempre se registran. Por defecto: off.
Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Por defecto: off.
Finalizar compra
El cliente elige el método de pago (por defecto Iugu) y realiza el pedido. Se requiere un correo electrónico de facturación válido. El plugin crea una factura de Iugu por el total del pedido en BRL, con vencimiento a 3 días, y envía al cliente a la página de la factura de Iugu. Allí el cliente paga con tarjeta de crédito, boleto o PIX, con los métodos activados en tu cuenta de Iugu. El nombre y el correo electrónico del cliente se envían a Iugu, junto con el CPF/CNPJ, el número de calle y el barrio de los campos de "Brazilian Market on WooCommerce" de la finalización de compra, cuando están presentes. El teléfono y la dirección se envían solo en el formato que acepta Iugu (números de teléfono brasileños y direcciones de Brasil con un CEP de 8 dígitos).
Tras pagar, el cliente vuelve a la página Pedido recibido de tu tienda. El pedido se marca como pagado solo cuando Iugu lo confirma: la factura se lee desde la API de Iugu cuando el cliente regresa y cuando Iugu envía una notificación. Si el cliente generó un código de boleto o PIX y volvió antes de pagar, el pedido se pone En espera hasta que Iugu confirme el pago. El temporizador de pedidos no pagados de WooCommerce no cancela los pedidos cuya factura de Iugu sigue abierta.
Si la factura se canceló o venció y el pedido todavía puede pagarse, el cliente llega a la página Pay for order con el mensaje The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Cuando el cliente paga de nuevo, el plugin lo devuelve a la misma factura abierta si el importe no ha cambiado. En caso contrario, cancela la factura antigua en Iugu y crea una nueva, de modo que un pedido no se pueda pagar dos veces mediante dos facturas abiertas. Si una factura antigua se paga de todos modos, el pago sigue asociado al pedido.
Si Iugu no puede crear la factura, el cliente ve un mensaje breve, por ejemplo Iugu could not create the invoice: con el motivo y una petición para revisar los datos de facturación, o Could not connect to Iugu. Please try again in a moment. El motivo técnico se añade a las notas del pedido y al registro.
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 admite solo pagos únicos. No incluye formulario de tarjeta en la tienda, tarjetas guardadas, suscripciones ni cobros recurrentes, carnês (carnê), pagos divididos ni opciones de cuotas: para pagar en cuotas, usa los ajustes de la página de Iugu. Los métodos de pago que ofrece la página de Iugu no se pueden elegir en la configuración del plugin: se ofrecen todos los métodos activados en tu cuenta de Iugu.
Pedidos y reembolsos
Estados del pedido
Pending payment: la factura se creó y el cliente todavía no ha pagado.
Processing or Completed: Iugu confirmó el pago. WooCommerce asigna el estado habitual de un pedido pagado. La nota del pedido muestra el ID de la factura de Iugu y el método de pago (tarjeta de crédito, boleto o PIX). El ID de transacción es el ID de la factura de Iugu, y en la pantalla del pedido enlaza con la factura en Iugu.
On hold: el cliente generó un boleto o PIX y volvió a la tienda (pago pendiente), el pago con tarjeta está autorizado pero aún no capturado (captúralo en Iugu; el pedido se completa cuando Iugu informa de que la factura está pagada), el pago está en análisis, la factura se pagó solo parcialmente, se abrió un contracargo, o el importe o la moneda pagados no coinciden con el pedido. Un pago que llega después de que el pedido se haya cancelado también lo pone En espera en lugar de reabrirlo en silencio. Las notas del pedido indican cuál es el caso.
Failed: la factura venció sin pago. El cliente puede volver a pagar el pedido.
Cancelled: la factura se canceló en Iugu.
Refunded: la factura que pagó el pedido se reembolsó en Iugu.
Si otra factura del mismo pedido también se paga, el pedido no se vuelve a modificar. Una nota te pide que reembolses el pago duplicado en Iugu.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Iugu. El reembolso se envía con el token del modo en el que se creó la factura.
Solo se pueden reembolsar facturas pagadas, y no más del importe que aún sea reembolsable en Iugu. Un reembolso cuenta como realizado solo cuando Iugu lo confirma. Si Iugu lo rechaza o no lo confirma, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID de la factura y el motivo.
Un reembolso total hecho en el panel de Iugu marca el pedido como Reembolsado. Los reembolsos parciales hechos en el panel no se importan.
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 > Iugu. 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 eliminarla 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. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Iugu no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda con sesión iniciada 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 recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Iugu no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado y que el token del modo activo esté configurado: Test API token en modo de prueba, Live API token en modo real. La moneda de la tienda debe ser BRL y el total del pedido, de al menos R$ 1,00. La página de configuración muestra un aviso cuando el token o la moneda son incorrectos.
El pago se realizó, pero el pedido sigue en Pending payment: la notificación de Iugu no llegó a tu tienda o no se pudo comprobar. Activa el Debug log y revisa WooCommerce > Status > Logs, origen wcp_iugu_gateway. Comprueba que tu sitio sea accesible desde Internet en la URL de notificaciones que aparece en la configuración y que el token del modo en el que se creó la factura siga introducido. El pedido también se comprueba cuando el cliente vuelve a la tienda después de pagar.
Notification answers verification failed: la factura no se pudo leer desde la API de Iugu en ese momento, por ejemplo por un error de red o un token incorrecto. Iugu reintenta la notificación.
Notification answers invalid invoice id: la notificación no tenía un ID de factura válido. No se cambia nada.
El pedido está On hold: lee las notas del pedido. Un boleto o PIX sigue sin pagar, un pago con tarjeta espera captura, el pago está en análisis, se pagó parcialmente o está en disputa, el importe pagado no coincidió con el pedido, o el pago llegó después de que el pedido se cancelara.
The customer sees "Iugu payments are not available right now": falta el token de API o es incorrecto. Comprueba el token del modo activo.
Error al reembolsar: lee el mensaje. Los pagos con boleto no se pueden reembolsar a través de Iugu, los pagos con PIX solo se pueden reembolsar por el total y solo se pueden reembolsar facturas pagadas. Si Iugu no confirmó el reembolso, revisa la factura en Iugu antes de volver a intentarlo.
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 cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Los desarrolladores pueden modificar la solicitud de factura, por ejemplo para limitar los métodos de pago con payable_with, mediante el filtro wc_igu_invoice_data.
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. La configuración de la pasarela y los registros solo se eliminan si Delete Data on Uninstall estaba activado; si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.
Iugu es una marca registrada de su respectivo propietario. Este plugin no está afiliado a Iugu ni cuenta con su respaldo.