VibeFox Iugu 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: real brasileño (BRL). Iugu cobra solo en BRL. El método de pago se oculta para carritos en otra moneda y para totales 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 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 más adelante VibeFox Iugu Gateway 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 de configuración y haz clic en Activate (véase Clave de licencia).
4. Introduce los tokens de API de prueba y de producción (véase Configuración), deja Test mode activado, activa Enable / Disable y haz clic en Save.
5. Haz un pedido de prueba y págalo en la página de Iugu con un pago de prueba de Iugu. Cuando esté listo, desactiva Test mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Iugu payment e Iugu payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences. En cualquier caso, Iugu solo se ofrece para carritos en BRL.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Iugu Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, 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 predeterminada de la tienda no es BRL (entonces Iugu no se ofrece para carritos en otras monedas).
Iugu
Enable / Disable: Enable Iugu payments activa o desactiva el método de pago. Predeterminado: 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 guardado en el pedido. Predeterminado: Iugu. Obligatorio.
Description: el texto que se muestra bajo el método de pago en la finalización de compra. Predeterminado: 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: usa el token de API de prueba, así que no se realizan cargos reales. Predeterminado: 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 afecta a 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. Mantenlo en secreto.
Los tokens guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved tokens: marca un token y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Notificaciones de pago
Notification URL: cada factura indica a Iugu que informe de los cambios de estado a esta URL de tu tienda. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_iugu_gateway/webhook. No hay nada que configurar en Iugu. Un disparador (gatilho) adicional de toda la cuenta que apunte a la misma URL es inofensivo. 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 crear o modificar un pedido.
El módulo responde 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 creó tu tienda reciben una respuesta HTTP 200 y se ignoran, sin ninguna consulta a Iugu. Sin notificaciones, una factura solo se comprueba cuando el cliente vuelve a la tienda desde la página de Iugu.
Avanzado
Debug log: escribe las solicitudes y notificaciones de Iugu en logs/wc_igu_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los tokens y los datos del cliente no se registran. Los errores y las advertencias siempre se escriben, aunque el interruptor esté desactivado. Predeterminado: off.
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 los ajustes de la pasarela y el registro. Los pedidos, las referencias de facturas de Iugu, los reembolsos y los estados de pedido del módulo siempre se conservan, así que los pedidos antiguos siguen funcionando tras una reinstalación. Predeterminado: off.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto Iugu) y confirma. Es necesario un correo electrónico válido del cliente. El módulo crea una factura de Iugu por el total del carrito en BRL, con vencimiento a los 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. La factura muestra Order # y el número del carrito. El nombre y el correo electrónico del cliente se envían a Iugu, junto con la empresa y el CPF/CNPJ del campo Identification number o VAT number de la dirección, cuando existan. El teléfono y la dirección se envían solo en el formato que acepta Iugu (números de teléfono brasileños, direcciones brasileñas con CEP de 8 dígitos; el número de la casa se envía como s/n). En este punto todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a 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. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with Iugu has been received.
Si el cliente generó un código de boleto o PIX y volvió antes de pagar, el pedido se crea en Awaiting Iugu payment y la página de confirmación muestra Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. El pedido pasa a Payment accepted cuando Iugu informa del pago, por notificación o cuando el cliente vuelve a abrir el enlace de retorno. Si Iugu todavía no respondió cuando el cliente regresa, una página de Payment confirmation muestra We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. con un botón Check again y otro Back to checkout. Un pedido cuya factura se canceló o caducó sin pago muestra Your Iugu payment was not completed. Please contact us about this order. en la página de confirmación.
Si la factura se canceló o caducó antes de que existiera un pedido, el cliente vuelve a la finalización de compra con The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. El carrito se conserva. Cuando el cliente paga de nuevo, el módulo lo envía a la misma factura abierta si el importe y el modo no han cambiado. En caso contrario, cancela la factura anterior en Iugu y crea una nueva, de modo que un mismo carrito no pueda pagarse con dos facturas abiertas. Si una factura anterior se paga de todos modos, el pago se asocia igualmente al carrito.
Si Iugu no puede crear la factura, el cliente se queda en la finalización de compra con 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 escribe en el registro.
La URL de notificaciones funciona mientras la tienda está en modo de mantenimiento y no está bloqueada por la restricción de países de tu tienda.
El módulo 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 las cuotas usa los ajustes de la página de Iugu. Los métodos de pago que se ofrecen en la página de Iugu no se pueden elegir en la configuración del módulo: se ofrecen todos los métodos activados en tu cuenta de Iugu. Un pedido en Payment error o Canceled no se puede volver a pagar desde la tienda; el cliente debe realizar un nuevo pedido.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Iugu y no ha pagado, o Iugu aún no ha confirmado el pago. Solo existe el carrito.
Payment accepted: Iugu confirmó el pago. El pago se registra con el ID de la factura de Iugu como ID de transacción, y una nota muestra el ID de la factura y el método de pago (tarjeta de crédito, boleto o PIX).
Awaiting Iugu payment: el cliente volvió con un boleto o PIX emitido. El pedido pasa a Payment accepted cuando Iugu informa del pago.
Iugu payment on hold: el pago con tarjeta está autorizado pero aún no capturado (captúralo en Iugu, y 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, Iugu informó de un importe o una moneda distintos a los del carrito (por ejemplo, si el carrito se cambió después de crear la factura), o el pago llegó después de que el pedido se cancelara. Las notas lo explican. Revisa el pedido y complétalo o reembólsalo.
Payment error: la factura de un pedido en espera caducó sin pago. Si Iugu informa más tarde de que la factura está pagada, el pedido pasa a Payment accepted.
Canceled: la factura de un pedido en espera se canceló en Iugu.
Refunded: el pago se reembolsó por completo a través del módulo o en el panel de Iugu.
Si otra factura del mismo carrito también se paga, el pedido no cambia. Una nota pide que reembolses el pago duplicado en Iugu.
Bloque de pago de Iugu
La página del pedido muestra un bloque Iugu payment con el ID de la factura de Iugu (con enlace a la factura en Iugu), el método de pago, el estado, el importe cobrado por Iugu y el importe reembolsado, una insignia Test mode para las facturas de prueba, el historial de reembolsos y las Iugu notes del pedido.
Reembolsos
En el bloque Iugu payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Iugu. Confirma la pregunta Refund this amount through Iugu? This cannot be undone. Necesitas el permiso para editar pedidos. El reembolso se envía con el token del modo en el que se creó la factura, así que ese token debe estar configurado.
Los reembolsos se calculan a partir del importe que Iugu cobró realmente por la factura, así que tras una diferencia de importe puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. Solo se pueden reembolsar facturas pagadas, y no más de lo que aún sea reembolsable en Iugu. Un reembolso cuenta como hecho solo cuando Iugu lo confirma. Si Iugu rechaza el reembolso o no lo confirma, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ID de la factura y el motivo. Un reembolso total cambia el pedido a Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Iugu ya ha informado de que la factura está pagada.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Iugu.
Un reembolso total hecho en el panel de Iugu cambia el pedido a Refunded con una nota. Los reembolsos parciales hechos en el panel no se importan.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Iugu Gateway es el primer bloque de Modules > Module Manager > VibeFox Iugu Gateway > Configure, por 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-iugu 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 el inglés y el 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda 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. 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 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 y los reembolsos funcionan.
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. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.
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 de producción. La moneda del carrito debe ser BRL y el total, de al menos R$ 1,00. En Payment > Preferences comprueba que el módulo está permitido para la moneda BRL, el país del cliente y el grupo del cliente. La página de configuración muestra una advertencia si el token o la moneda son incorrectos.
El pago se realizó, pero no se creó ningún pedido: la notificación de Iugu no llegó a tu tienda o no se pudo comprobar. Activa Debug log y revisa el campo Log de la página del módulo. Comprueba que tu tienda es accesible desde internet en la Notification URL y que el token del modo en el que se creó la factura sigue introducido. La factura también se comprueba cuando el cliente vuelve a la tienda tras 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, un token incorrecto o la falta del token del modo de la factura. Iugu reintenta la notificación.
Notification answers busy: el carrito estaba siendo procesado por otra petición en el mismo momento, o el pedido no se pudo crear (por ejemplo, porque el módulo está desactivado). Iugu reintenta la notificación. El registro muestra el motivo.
Notification answers invalid invoice id: la notificación no tenía un ID de factura válido. No se cambia nada.
Pedido en Iugu payment on hold: lee las Iugu notes en el bloque del pedido. Un pago con tarjeta espera captura, el pago está en análisis, parcialmente pagado o en disputa, el importe pagado no coincide con el carrito, o el pago llegó después de cancelar el pedido.
El cliente ve «Iugu payments are not available right now»: falta el token de API o es incorrecto. Comprueba el token del modo activo.
El cliente ve «This order already has an Iugu payment that the store has to review»: una factura anterior del carrito está autorizada, en análisis o parcialmente pagada, pero no se pudo crear ningún pedido. Revisa la factura en Iugu y el registro.
Refund fails: lee el mensaje del bloque. Los pagos con boleto no se pueden reembolsar a través de Iugu, los pagos con PIX solo se pueden reembolsar por completo, y solo se pueden reembolsar facturas pagadas. Si el mensaje indica que el pago se hizo en modo de prueba o de producción y no hay ningún token configurado, introduce el token de ese modo. Si Iugu no confirmó el reembolso, comprueba la factura en Iugu antes de volver a intentarlo.
Los desarrolladores pueden cambiar la solicitud de factura, por ejemplo para limitar los métodos de pago con payable_with, en el hook actionWcpIuguInvoiceData.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Iugu Gateway 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 de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las referencias de facturas de Iugu y los reembolsos, así como los estados de pedido Awaiting Iugu payment e Iugu payment on hold, siempre se conservan, de modo que los pedidos pagados antes se pueden reembolsar todavía y las notificaciones tardías siguen asociándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Iugu es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Iugu ni cuenta con su respaldo.