VibeFox PayU for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Moneda: una de PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. La moneda también debe estar habilitada para tu punto de venta en PayU. Para otras monedas, la opción de pago no aparece en la finalización de compra.
Acceso a Internet a tu tienda: PayU envía las notificaciones de pago a tu tienda, por lo que debe ser accesible desde Internet (no detrás de autenticación HTTP ni de un cortafuegos). Sin notificaciones, los pagos se siguen comprobando cuando el cliente regresa de PayU.
Cuenta de PayU: necesitas cuatro claves de tu punto de venta (POS): POS ID, Second key (MD5), OAuth client_id y OAuth client_secret. Están en el panel de comerciante de PayU, en Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Las claves de sandbox proceden de una cuenta de sandbox de PayU independiente.
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 carga, haz clic en Configure, o busca VibeFox PayU Payment en la lista de módulos más tarde y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia situado en la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).
4. Introduce las cuatro claves de Sandbox y las cuatro claves de Live (véase Configuración). No hace falta configurar ninguna URL de notificación en PayU.
5. Activa Enable/Disable y haz clic en Save. Deja Test Mode activado hasta que hayas hecho un pago de prueba; después desactívalo para aceptar pagos reales con las claves de Live.
Al instalarse, el módulo crea dos estados de pedido: Awaiting PayU payment confirmation y PayU payment on hold. PrestaShop habilita el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayU Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa mientras el modo sandbox está activado (El modo sandbox (prueba) está activado: los pagos van al sandbox de PayU y no se cobra dinero real. No envíes pedidos pagados en modo de prueba.), cuando falta una de las cuatro claves del modo actual y cuando PayU no acepta la moneda predeterminada de la tienda. En los dos últimos casos, PayU no se muestra en la finalización de compra.
Al guardar, se eliminan los espacios y saltos de línea de todas las claves, porque al copiarlas desde el panel de PayU suelen añadirse. Un Title vacío no se guarda: la página muestra Introduce un título para el método de pago.
PayU
Enable/Disable: Enable PayU payment gateway activa o desactiva la opción de pago. Por defecto: desactivado.
Title: el título del método de pago que ve el cliente. También es el nombre del método de pago que se guarda en el pedido. Por defecto: PayU. Obligatorio.
Description: la descripción del método de pago que ve el cliente en la finalización de compra. Por defecto: Pay securely via PayU.
Credenciales de API
Encontrarás las claves en el panel de comerciante de PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Las claves de sandbox proceden de una cuenta de sandbox de PayU independiente. Hay que rellenar las cuatro claves de un modo.
Test Mode: usa el sandbox de PayU y las claves de Sandbox indicadas abajo. No se cobra dinero real. Mientras esté activado, los clientes ven El modo sandbox está activado: no se realiza ningún pago real. debajo de la opción de pago. Desactívalo para aceptar pagos reales con las claves de Live. Por defecto: activado.
Live POS ID: el POS ID (merchantPosId) de tu punto de venta de producción.
Live Second Key (MD5): se usa para verificar la firma de las notificaciones de PayU.
Live OAuth Client ID: el client_id de OAuth del punto de venta.
Live OAuth Client Secret: el client_secret de OAuth del punto de venta.
Sandbox POS ID: el POS ID de tu punto de venta del sandbox de PayU.
Sandbox Second Key (MD5): se usa para verificar la firma de las notificaciones del sandbox de PayU.
Sandbox OAuth Client ID: el client_id de OAuth del punto de venta del sandbox.
Sandbox OAuth Client Secret: el client_secret de OAuth del punto de venta del sandbox.
Las Second Keys y los client secrets guardados no se vuelven a mostrar. El campo queda vacío y muestra Guardado: déjalo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo. Los POS ID y los client ID se muestran tal como están guardados.
Clear saved secrets: marca un secreto y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
Cada pago recuerda su entorno. Las notificaciones, las comprobaciones de estado y los reembolsos de un pago siempre usan las claves de ese entorno, así que los pagos anteriores siguen funcionando tras cambiar de modo. Una notificación firmada con la clave de sandbox nunca se acepta para un pago real, y viceversa.
Notificaciones de pago
Notification URL: muestra la dirección a la que PayU envía las notificaciones. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_payu_payment/webhook, posiblemente con un código de idioma. El módulo la envía a PayU con cada pago, así que no hay que configurar nada en el panel de PayU. Asegúrate de que sea accesible desde Internet (que no esté bloqueada por un cortafuegos ni por autenticación HTTP). Las notificaciones también funcionan mientras la tienda está en modo mantenimiento y no las bloquea la restricción por país de tu tienda.
Avanzado
Receive payments automatically: recibe automáticamente los pagos pendientes de confirmación. Solo importa si la recepción automática está desactivada para tu punto de venta en el panel de PayU: en ese caso, los pagos esperan confirmación (WAITING_FOR_CONFIRMATION). Con esta opción activada, el módulo recibe esos pagos al momento y el pedido se crea cuando PayU informa de que el pago está completado. Si está desactivada, o si la recepción falla, el pedido se crea en Awaiting PayU payment confirmation y tú recibes o cancelas el pago con los botones del bloque de PayU del pedido. Por defecto: activado.
Logging: escribe los eventos técnicos (números de carrito y de pedido, ID de pedidos de PayU, estados, errores; sin claves ni datos personales) en logs/wc_pu_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran; los demás eventos solo mientras esta opción esté activada. Por defecto: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: elimina los ajustes y los registros del módulo al desinstalarlo. Los pedidos y sus datos de pago (transacciones de PayU, reembolsos, estados de pedido) nunca se eliminan. Por defecto: desactivado.
Finalización de compra
En el paso de pago, el cliente elige la opción de pago (por defecto PayU) y ve la descripción y la nota Serás redirigido a PayU para completar el pago (BLIK, transferencia bancaria, tarjeta y otros métodos). Tras confirmar, el módulo crea un pedido de PayU por el total del carrito en la moneda del carrito, con la descripción Cart #, el número de carrito y el nombre de tu tienda, y con los productos, el envío y el envoltorio de regalo para mostrarlos en la página de PayU. El correo electrónico, el nombre y el teléfono del cliente se envían a PayU. El idioma de la página de PayU sigue el idioma de la tienda cuando PayU lo admite; si no, es inglés. El cliente es enviado a la página de PayU, elige allí un método y paga. En este momento aún no existe ningún pedido.
Cada intento de pago recibe su propio pedido de PayU. Cuando el cliente vuelve a intentarlo, el pago de PayU anterior sin terminar del carrito se cancela en PayU, así que un enlace de pago antiguo no se puede pagar dos veces. Si resulta que el pago anterior ya estaba pagado, se crea el pedido en lugar de un nuevo pago.
Volver a tu tienda por sí solo nunca paga un pedido. El pedido se marca como pagado solo después de que PayU lo confirme: mediante una notificación firmada con la Second Key del entorno del pago, o mediante una comprobación del estado del pedido de PayU en el servidor cuando el cliente regresa (como máximo una vez cada 10 segundos por carrito). El pedido de PayU debe haberse creado para este carrito, y el importe y la moneda deben coincidir. El módulo gestiona estos estados de PayU:
Tras un pago confirmado, el cliente ve la página estándar de confirmación del pedido. En un pedido pendiente de confirmación o en espera, la página añade Estamos verificando tu pago. Te enviaremos un correo electrónico en cuanto se confirme. Si el pago de ese pedido se cancela después, la página muestra Tu pago de PayU no se completó. Ponte en contacto con nosotros sobre este pedido.
Si PayU aún no ha confirmado el pago cuando el cliente regresa, aparece una página Payment confirmation con Todavía no hemos recibido la confirmación del pago de PayU. Si el pago se interrumpió, puedes intentarlo de nuevo: (o, cuando PayU informó de un error, El pago no se completó. Puedes intentarlo de nuevo:) con los botones Pay again y Check again. La notificación crea el pedido en cuanto llega. Si el pago se canceló, el cliente vuelve a la finalización de compra con El pago no se completó. Puedes intentarlo de nuevo o elegir otro método de pago. El carrito se conserva.
Si PayU no puede iniciar el pago, el cliente se queda en la finalización de compra con Error de pago. Inténtalo de nuevo o elige otro método de pago. El motivo técnico se escribe en el registro. Si faltan las claves del modo actual, el mensaje es La pasarela de pago no está configurada correctamente. Ponte en contacto con el administrador.
Si un vale de descuento del carrito deja de ser válido entre el pago y su confirmación, se elimina del pedido. El pedido pasa entonces a PayU payment on hold con una nota que indica el vale, porque el cliente pagó el precio con el descuento.
El cliente elige el método de pago en la página de PayU, no en tu finalización de compra. El módulo no tiene formulario de tarjeta en tu tienda, ni tarjetas guardadas ni pagos con un clic, ni suscripciones, ni widgets de pago a plazos o de crédito de PayU. Utiliza un punto de venta por entorno.
Pedidos y reembolsos
Estados del pedido
Todavía no hay pedido: el cliente fue enviado a PayU y no ha pagado, o PayU aún no ha confirmado el pago. Solo existe el carrito.
Payment accepted: el pago se ha confirmado. El pago se registra con el ID del pedido de PayU como ID de transacción, y una nota muestra el ID del pedido de PayU, el importe y el entorno (sandbox o live).
Awaiting PayU payment confirmation: el pago está autorizado y espera tu acción (recepción automática desactivada o fallida). Todavía no se registra ningún pago.
PayU payment on hold: el importe o la moneda pagados no coinciden con el carrito (el pedido no se marca como pagado), se eliminó un vale de descuento, un pago pendiente de confirmación tenía otro importe, o se completó un pago de un pedido que había sido cancelado (el pago se registra). La nota indica cuál es el caso. Revisa el pedido y procésalo o reembolsa el pago.
Payment error: el pago de un pedido pendiente de confirmación se canceló o rechazó.
Refunded: el pago se reembolsó por completo a través del módulo.
Cada notificación se procesa una sola vez: las notificaciones repetidas no añaden notas ni vuelven a cambiar el pedido. Si se completa otro pago para un pedido que ya está pagado o reembolsado, una nota te pide que lo reembolses en el panel de PayU. Un pago pendiente de confirmación en un pedido que ya está pagado o cerrado se cancela automáticamente, para que el dinero no se cobre dos veces.
Bloque de pago de PayU
La página del pedido muestra un bloque PayU payment con el ID del pedido de PayU, el extOrderId, el estado de PayU, el importe cobrado y reembolsado, una etiqueta Sandbox para los pagos de sandbox, el historial de reembolsos y las PayU notes del pedido. Las acciones del bloque requieren el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos.
Pagos pendientes de confirmación
En un pedido con un pago pendiente de confirmación, el bloque muestra Receive PayU payment (waiting for confirmation) y Cancel PayU payment (release the funds). Tras confirmar la pregunta, la acción se envía a PayU con las claves del entorno del pago, se añade a las notas con tu nombre y el nuevo estado de PayU se aplica al momento: un pago recibido pone el pedido en Payment accepted, y uno cancelado, en Payment error.
Reembolsos
En el bloque PayU payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via PayU. Confirma la pregunta ¿Reembolsar este importe a través de PayU? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales. El reembolso se envía para el pedido de PayU que realmente se pagó, con las claves del entorno del pago, así que esas claves deben estar configuradas. Los reembolsos se hacen por el importe y en la moneda que cobró PayU; por tanto, tras una discrepancia de importe o moneda, puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El motivo se envía como descripción del reembolso. Si PayU rechaza el reembolso, el bloque muestra el error de PayU y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
Los reembolsos son asíncronos en PayU. El módulo añade de inmediato una nota con el ID y el estado del reembolso de PayU; el estado final llega después como notificación de PayU y se añade a las notas y al historial de reembolsos. Si PayU cancela un reembolso, la nota indica que el dinero no se devolvió al cliente, y el importe puede reembolsarse de nuevo.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de PayU.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayU Payment es el primer bloque de Modules > Module Manager > VibeFox PayU Payment > 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-payu 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 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. Tras cambiar la dirección de la tienda, o tras liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, 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. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, PayU 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 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 siguen confirmándose mediante las notificaciones, 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 tras introducir la clave, y después una vez por semana. No hace falta 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 no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que se hayan rellenado las cuatro claves del modo actual: las claves de Sandbox en modo sandbox, las de Live en modo live. Comprueba que la moneda del carrito sea una de las monedas admitidas. 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. La página de configuración muestra un aviso cuando faltan claves o la moneda de la tienda no es compatible.
El pago se realizó, pero no se creó ningún pedido: PayU aún no ha entregado la notificación y la comprobación de estado en la página de regreso no vio un pago completado. Comprueba que la Notification URL que aparece en la configuración sea accesible desde Internet. Activa Logging para ver qué llega. El cliente también puede hacer clic en Check again en la página Payment confirmation.
La notificación responde Invalid signature: la notificación no se firmó con la Second Key de ninguno de los dos entornos. Comprueba Live Second Key (MD5) y Sandbox Second Key (MD5). La respuesta Invalid signature for this payment significa que la notificación se firmó con la clave del entorno distinto al del pago.
La notificación responde Ignored: unknown PayU order: el pedido de PayU no lo creó esta tienda, por ejemplo otra tienda en el mismo POS. PayU deja de reintentar.
La notificación responde Busy, retry later: el carrito se estaba confirmando en ese momento con otra solicitud, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). PayU repite la notificación. Activa Logging para ver el motivo.
La URL de notificación muestra POST expected en el navegador: es normal. La URL solo acepta notificaciones de PayU.
El cliente ve Payment error al elegir PayU: activa Logging y revisa el campo Log de la página del módulo. El registro muestra el código HTTP y el estado de PayU. No se pudo autenticar con PayU (comprueba el OAuth client ID / secret). significa que las claves OAuth del modo actual son incorrectas.
El pedido está en PayU payment on hold: lee las notas del bloque PayU payment (consulta Estados del pedido) y, después, procesa el pedido o reembolsa el pago.
El pedido está en Awaiting PayU payment confirmation: la recepción automática está desactivada para tu punto de venta y el pago espera tu decisión. Usa Receive PayU payment o Cancel PayU payment en el bloque de PayU.
El reembolso falla: Este pedido no tiene un pago de PayU completado. No se puede procesar el reembolso. significa que PayU aún no ha completado ningún pago del pedido. Un mensaje que indique que faltan las claves de Sandbox o de Live significa que el pago se hizo en ese entorno y que sus claves no están configuradas. Introdúcelas y vuelve a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayU Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Los tokens de acceso de PayU en caché siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de PayU y los estados de pedido Awaiting PayU payment confirmation y PayU payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar también después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
PayU es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por PayU.