VibeFox PayU LATAM 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: el carrito debe estar en ARS, BRL, CLP, COP, MXN, PEN o USD, las monedas que procesa PayU Latam en Argentina, Brasil, Chile, Colombia, México, Panamá y Perú. Con otras monedas, el método de pago no aparece en la finalización de compra.
Cuenta de PayU Latam: necesitas tres datos de tu comercio de PayU: el ID de comerciante, el ID de cuenta del país en el que vendes y la clave API. Están en el módulo de PayU (el panel de comerciante de PayU), en Settings > Technical configuration (merchant ID, API key) y Accounts (account ID). Para las pruebas, PayU publica credenciales públicas de sandbox y tarjetas de prueba en la página "Test your solution" de su documentación para desarrolladores. El API Login y otras credenciales de API no son necesarias, porque el pago se realiza en la página alojada de PayU y el módulo nunca llama a la API de PayU.
Acceso a internet a tu tienda: PayU envía el resultado del pago a tu tienda desde sus servidores, así que la tienda debe ser accesible desde internet (no un sitio local ni protegido con contraseña).
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 VibeFox PayU LATAM Payment más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en 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. Introduce las credenciales de sandbox y tus credenciales de producción (véase Configuración). No es necesario configurar ninguna URL de confirmación en PayU.
5. Activa Enable/Disable y haz clic en Save. Mantén Sandbox activado hasta que hayas hecho un pago de prueba; después desactívalo para aceptar pagos reales con las credenciales de producción.
Al instalarse, el módulo crea dos estados de pedido: Awaiting PayU LATAM payment y PayU LATAM payment on hold. PrestaShop ofrece un nuevo método de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences. Un país que habilites más tarde también debe marcarse allí para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Sandbox mode. Payments go to the PayU sandbox and no real money is charged. mientras el sandbox está activado; un error cuando falta el ID de comerciante, el ID de cuenta o la clave API del entorno actual; y una advertencia cuando PayU LATAM no procesa la moneda predeterminada de la tienda. Mientras falten credenciales, PayU LATAM no aparece en la finalización de compra. Los espacios al principio o al final de una credencial se ignoran. La página no guarda un Title vacío y muestra Enter a title for the payment method.
PayU LATAM
Enable/Disable: Enable PayU LATAM activa o desactiva el método de pago. Por defecto: desactivado.
Title: el título del método de pago que se muestra al cliente durante la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: PayU LATAM. Obligatorio.
Description: la descripción del método de pago que se muestra al cliente durante la finalización de compra. Por defecto: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.
Entorno
Sandbox: los pagos van al sandbox de PayU con las credenciales de sandbox indicadas abajo, y no se cobra dinero real. Cuando está desactivado, se usan las credenciales de producción y la página de pago de producción de PayU. Por defecto: activado. Mientras esté activado, los clientes ven Sandbox mode: no real money is charged. debajo del método de pago.
Credenciales de producción
Encuéntralas en el módulo de PayU: Settings > Technical configuration (merchant ID, API key) y Accounts (account ID del país en el que vendes). La sección enlaza con el panel de comerciante de PayU.
Merchant ID: el identificador numérico de tu comercio de PayU.
Account ID: el identificador de la cuenta de PayU. Hay una cuenta por país.
API Key: la clave secreta que se usa para firmar los pagos y verificar las notificaciones de PayU.
Credenciales de sandbox
PayU publica credenciales de prueba públicas y tarjetas de prueba para su sandbox. La sección enlaza con la página "Test your solution" de la documentación de PayU.
Sandbox merchant ID: el ID de comerciante para el sandbox de PayU.
Sandbox account ID: el ID de cuenta para el sandbox de PayU.
Sandbox API key: la clave API para el sandbox de PayU.
Las claves API guardadas 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 cambiarla.
Clear saved secrets: marca API Key o Sandbox API key y haz clic en Save para eliminar la clave guardada. Un campo vacío mantiene el valor guardado.
Cada intento de pago recuerda su entorno. La confirmación de un pago de sandbox se verifica con la clave API y el ID de comerciante del sandbox, y la de un pago real con los de producción, así que los pagos pendientes siguen funcionando tras el cambio. Un pago de sandbox confirmado después del cambio se marca como [sandbox] en las notas del pedido.
URL de confirmación
Esta sección muestra la URL a la que PayU informa de cada resultado de pago. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_payu_latam_payment/confirmation, posiblemente con un código de idioma como /en/. El módulo la envía a PayU con cada pago, así que no hay nada que configurar en PayU. La URL debe ser accesible desde internet. Funciona también mientras la tienda está en modo mantenimiento y no la bloquea la restricción de países de tu tienda. PayU firma la confirmación con tu clave API. Las confirmaciones sin firma válida, con otro ID de comerciante o con una referencia de pago que esta tienda no emitió se rechazan. El módulo gestiona estos estados de transacción de PayU:
Los demás estados solo se añaden como nota. Sin la confirmación, no se crea ningún pedido.
Avanzado
Debug log: registra las solicitudes de pago y las notificaciones de PayU en logs/payu_lp_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos personales no se registran. Los errores y las notificaciones rechazadas siempre se registran, incluso cuando este interruptor está desactivado. Por defecto: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete data: elimina los ajustes y los registros al desinstalar el módulo. Los datos de PayU de los pedidos (intentos de pago) y los estados de pedido se conservan. Por defecto: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto PayU LATAM) y confirma. Una página de tu tienda muestra You are being redirected to PayU LATAM to complete the payment... y envía automáticamente un formulario firmado a la página WebCheckout de PayU. Si eso no ocurre, el cliente hace clic en Pay with PayU LATAM, o en Back to checkout para volver. En este punto todavía no existe ningún pedido.
El formulario contiene el total y la moneda del carrito, el impuesto y la base imponible del carrito (ambos en 0 para los carritos sin impuestos, para que PayU no añada un IVA predeterminado), la descripción Cart # con el número de carrito y el nombre de tu tienda, y el correo electrónico, nombre, teléfono y dirección de facturación del cliente. La página de PayU se abre en español, portugués o inglés, según el idioma del carrito. En la página de PayU, el cliente paga con cualquier método habilitado en tu cuenta de PayU.
Cada visita a la página de pago inicia un nuevo intento de pago con su propia referencia (PS, el número de carrito y una marca de tiempo). Los intentos anteriores se recuerdan: si el cliente paga en una pestaña anterior de PayU, el pago se sigue aceptando.
El pedido se marca como pagado solo cuando PayU lo confirma mediante la confirmación firmada. El cliente que vuelve desde PayU nunca marca un pedido como pagado. Cuando el cliente vuelve:
Si faltan las credenciales del entorno actual, el cliente ve PayU LATAM is not available right now. Please choose another payment method. Para una moneda de carrito no compatible, el mensaje es PayU LATAM does not accept payments in seguido de la moneda. Un carrito que ya tiene pedido no se vuelve a cobrar: el cliente va a la página de confirmación de su pedido.
El módulo no tiene formulario de pago en tu tienda, no permite reembolsos desde PrestaShop, no guarda tarjetas, no gestiona suscripciones ni ajustes de cuotas (PayU muestra las cuotas en su página). No consulta la API de PayU para conocer el estado del pago: solo la confirmación firmada actualiza el pedido.
Pedidos
Estados de pedido
Sin pedido todavía: el cliente fue enviado a PayU y no ha pagado, el pago fue rechazado o PayU todavía no ha enviado la confirmación. Solo existe el carrito.
Payment accepted: PayU confirmó el pago y el importe y la moneda coinciden. El pago se registra con el ID de transacción de PayU, y una nota muestra la transacción, el importe, el método de pago y [sandbox] para los pagos de sandbox.
Awaiting PayU LATAM payment: PayU informa del pago como pendiente (pago en efectivo o bancario). El pedido pasa a Payment accepted cuando PayU confirma el pago.
PayU LATAM payment on hold: el importe o la moneda pagados no coinciden con el total del carrito, o se aprobó un pago para un pedido que había sido cancelado. El pago se registra si está en la moneda del pedido. La nota indica cuál es el caso: revisa el pago en el módulo de PayU y después procesa el pedido, restáuralo o reembolsa el pago.
Payment error: un pago pendiente del último intento fue rechazado, caducó o terminó con error después. La nota muestra el mensaje de PayU. Este carrito no se puede volver a pagar: el cliente realiza un nuevo pedido. Un rechazo de un intento anterior, o de un pedido que ya tiene un pago aprobado, solo se añade como nota.
Cada notificación se procesa una vez, con un bloqueo por carrito: las notificaciones repetidas de PayU no crean un segundo pedido ni añaden notas dos veces. Un pedido pagado nunca se reabre ni se degrada. Si llega otro pago aprobado para un pedido que ya está pagado, una nota lo indica: si el cliente pagó dos veces, reembolsa el duplicado en el módulo de PayU.
Bloque de pago de PayU LATAM
La página del pedido muestra un bloque PayU LATAM payment con la referencia, el ID de transacción, la referencia de PayU, el estado y el estado de PayU, el importe solicitado, el importe informado por PayU, el método de pago, el mensaje de PayU, una insignia SANDBOX para los pagos de sandbox, la lista de todos los intentos de pago del carrito y las PayU LATAM notes del pedido.
Reembolsos
Los reembolsos no se hacen desde PrestaShop. Reembolsa la transacción en el módulo de PayU y después registra el reembolso manualmente en PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayU LATAM Payment es el primer bloque de Modules > Module Manager > VibeFox PayU LATAM Payment > Configure, por 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: presta-payment-payu-latam y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, 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, PayU LATAM no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, 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 mediante la confirmación de PayU y el regreso del cliente.
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 tras introducir la clave y después una vez a la semana. No se necesita 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
PayU LATAM no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el ID de comerciante, el ID de cuenta y la clave API del entorno actual están rellenados: las credenciales de sandbox cuando Sandbox está activado, las de producción cuando está desactivado. Comprueba que la moneda del carrito es ARS, BRL, CLP, COP, MXN, PEN o USD. 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: la confirmación de PayU no llegó a tu tienda o fue rechazada. Comprueba que la URL de confirmación que aparece en los ajustes es accesible desde internet (sin sitio local, cortafuegos ni protección con contraseña). Revisa el campo Log de la página del módulo para ver las confirmaciones rechazadas. PayU vuelve a enviar la confirmación después de cualquier respuesta de error.
La confirmación responde Invalid signature: la confirmación no se firmó con la clave API del entorno del pago. Comprueba API Key para los pagos reales y Sandbox API key para los pagos de sandbox.
La confirmación responde Merchant mismatch: el ID de comerciante de la confirmación no coincide con Merchant ID o Sandbox merchant ID del entorno del pago. Introduce el ID de comerciante de la cuenta de PayU que procesa los pagos.
La confirmación responde Gateway not configured: falta la clave API o el ID de comerciante del entorno del pago, por ejemplo porque se borraron las credenciales de sandbox mientras había un pago de sandbox pendiente. Introdúcelas de nuevo; PayU reintentará la confirmación.
La confirmación responde Retry: otra solicitud estaba procesando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). No se cambió nada y PayU vuelve a enviar la confirmación. Revisa el Log para ver el motivo.
La confirmación responde Unknown reference: la referencia de pago no fue emitida por esta tienda.
La URL de confirmación muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de PayU.
El cliente ve This payment method is not available: el módulo no está permitido para el país, la moneda o el grupo del cliente en Payment > Preferences, o Enable/Disable está desactivado.
El pedido está en PayU LATAM payment on hold: lee las notas del bloque PayU LATAM payment. El importe o la moneda pagados eran distintos del carrito, o el pago llegó después de que el pedido se cancelara. Comprueba la transacción en el módulo de PayU.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayU LATAM Payment y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data está activado, se eliminan los ajustes y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago y los estados de pedido Awaiting PayU LATAM payment y PayU LATAM payment on hold se conservan siempre, para que una confirmación tardía de PayU de un intento antiguo siga reconociéndose tras una reinstalación. Los pedidos existentes conservan sus notas de pago, referencias de PayU e ID de transacción.
PayU es una marca registrada de su respectivo titular. Este módulo no está afiliado ni respaldado por PayU.