VibeFox PayU India 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: rupia india (INR). PayU India cobra solo en rupias. Para los carritos en otras monedas, el método de pago se oculta en la finalización de compra.
Número de teléfono: PayU requiere un número de teléfono en cada pago. Haz que el campo de teléfono de la dirección sea obligatorio o, como mínimo, visible en tu finalización de compra.
Cuenta de PayU India: necesitas el Merchant Key y el Merchant Salt (v1) de PayU Dashboard > Payment Gateway > Key Salt Details. Cambia el panel a Test Mode para ver el par de prueba. Usa Salt v1, no Salt v2.
Acceso a Internet a tu tienda: necesario para el webhook opcional. Sin él, los pedidos se confirman cuando el cliente regresa de PayU.
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 India Payment Gateway más tarde 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 situado en la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).
4. Introduce el Test Merchant Key y Salt y el Live Merchant Key y Salt (consulta Configuración).
5. Recomendado: en PayU Dashboard > Webhooks, añade la URL del webhook que se muestra en la página Configure para los pagos correctos y fallidos.
6. Elige el Mode, activa Enable/Disable y haz clic en Save. Prueba un pago en modo de prueba y luego cambia a modo en vivo.
Al instalar, el módulo crea dos estados de pedido: Awaiting PayU India payment y PayU India payment on hold. PrestaShop ofrece el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; la moneda INR debe seguir permitida para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayU India Payment Gateway > 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 si falta la clave o el salt del modo actual, muestra Test mode is active: payments go to test.payu.in and no real money is charged. en modo de prueba y muestra un error si la moneda predeterminada de tu tienda no es INR (en ese caso, la pasarela se oculta en la finalización de compra).
Al guardar, se eliminan los espacios y saltos de línea de las claves y los salts, porque un salt con un espacio pegado haría que todas las respuestas de PayU fallaran la comprobación.
PayU India
Enable/Disable: Enable PayU India Payment Gateway activa o desactiva el método de pago. Por defecto: desactivado. Si lo activas sin la clave y el salt del modo actual, la página te avisará después de guardar.
Title: el título del método de pago que ve el cliente durante la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: PayU India. Obligatorio.
Description: la descripción del método de pago que ve el cliente durante la finalización de compra. Por defecto: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.
Credenciales de API
Copia el Merchant Key y el Merchant Salt (v1) de PayU Dashboard > Payment Gateway > Key Salt Details. Cambia el panel a Test Mode para obtener el par de prueba. La sección tiene un enlace Open the PayU Dashboard.
Mode: el entorno de PayU que usan los nuevos pagos.
Los pagos ya iniciados conservan el modo en el que se iniciaron: sus resultados se comprueban y sus reembolsos se envían con la clave y el salt de ese modo, incluso después de cambiar el modo.
Live Merchant Key: tu Merchant Key de PayU en vivo.
Live Merchant Salt (v1): tu Merchant Salt (v1) de PayU en vivo. Firma las solicitudes y verifica las respuestas de PayU. Mantenlo en secreto.
Test Merchant Key: tu Merchant Key de prueba de PayU, usada solo en modo de prueba.
Test Merchant Salt (v1): tu Merchant Salt (v1) de prueba de PayU, usada solo en modo de prueba.
Los salts 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 salts: marca un salt y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
URL de retorno y de webhook
Return URL: tiene el aspecto de https://your-shop/module/wcp_payu_india_payment/return, posiblemente con un código de idioma como /en/. Se envía a PayU automáticamente con cada pago; no hay que configurar nada.
Webhook URL: tiene el aspecto de https://your-shop/module/wcp_payu_india_payment/webhook, posiblemente con un código de idioma. Es opcional, pero recomendable: confirma los pagos aunque el cliente cierre el navegador antes de regresar. Añádela en PayU Dashboard > Webhooks para los pagos correctos y fallidos. Copia la URL exactamente como la muestra la página Configure. Debe ser accesible desde Internet (sin autenticación básica ni bloqueo por cortafuegos). El modo de mantenimiento de la tienda y sus restricciones por país no la bloquean.
El webhook contiene el mismo resultado firmado que el retorno del cliente. Los webhooks sin un hash válido de PayU se rechazan.
Avanzado
Verify Payment: comprueba de nuevo cada pago correcto con la API verify_payment de PayU. Recomendado. Si la comprobación no se puede completar, el pedido se pone en espera en lugar de marcarse como pagado. Por defecto: activado.
Enable Logging: registra los eventos de la pasarela para la resolución de problemas en logs/payu_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran; esta opción añade los demás eventos, como cada formulario de pago y cada resultado de PayU. Las claves, los salts y los datos personales de los clientes nunca se registran. 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 on uninstall: elimina los ajustes y los registros del módulo al desinstalarlo. Los pedidos y los registros de transacciones de PayU nunca se eliminan. Por defecto: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto PayU India) y confirma. Si ni la dirección de facturación ni la de envío tienen un número de teléfono fijo o móvil, el cliente permanece en la finalización de compra con PayU India requires a phone number. Please enter your phone number and try again. En caso contrario, ve una página breve con Thank you for your order. You will be redirected to PayU to complete your payment., que envía una solicitud de pago firmada por el total del carrito a la finalización de compra alojada de PayU. Si el navegador no continúa solo, la página tiene un botón Pay with PayU y un botón Back to checkout. En la página de PayU, el cliente paga con tarjeta, NetBanking, UPI o billetera. En este punto todavía no existe ningún pedido.
Cada intento de pago recibe su propio ID de transacción de PayU, que empieza con el número del carrito, y se guarda con su importe y modo. Un pago realizado en una página de pago abierta anteriormente del mismo carrito todavía se acepta. Un carrito que ya tiene un pedido nunca recibe un nuevo formulario de pago, así que el botón Atrás del navegador no puede iniciar un segundo pago.
PayU envía el resultado de vuelta con el cliente y, si está configurado, mediante webhook. Un resultado solo se acepta con un hash válido de PayU generado con la clave y el salt del modo en el que se inició el pago, y solo para un ID de transacción emitido para ese carrito. Con Verify Payment activado, un resultado correcto también se comprueba con la API verify_payment de PayU. El importe pagado debe coincidir con el importe del intento y con el total del carrito hasta el paisa, en INR. El pedido solo se marca como pagado después de que PayU lo confirme de esta forma. El módulo gestiona estos resultados de PayU:
Tras un pago correcto o pendiente, el cliente ve la página estándar de confirmación del pedido. Un pago pendiente añade Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.; un pedido en espera añade Your payment is being reviewed. We will contact you if anything else is needed.; y un pedido en Payment error o Canceled muestra Your PayU payment was not completed. Please contact us about this order.
Tras un pago sin éxito, el cliente regresa a la finalización de compra con un mensaje: Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again. o, si no se pudo comprobar el resultado, We could not confirm the payment result. If your account was charged, please contact us before paying again. Si el resultado todavía se está procesando cuando el cliente regresa, aparece una página con We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. y un botón Check again.
El módulo cobra solo en INR y no tiene procesamiento multimoneda (MCP). No tiene tarjetas guardadas ni tokenización, ni suscripciones, ni formulario de tarjeta en el sitio (seamless), ni gestión de EMI u ofertas, ni compra con un clic de PayU.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a PayU y no ha pagado, o el pago falló o fue cancelado. Solo existe el carrito.
Payment accepted: el pago fue confirmado. El pago se registra con el ID de transacción de PayU (mihpayid) como ID de transacción, y una nota muestra PayU payment successful. Transaction ID: …, Mode: …, Bank: …
Awaiting PayU India payment: un pago con UPI o NetBanking todavía está pendiente en PayU. El pedido pasa a Payment accepted cuando PayU lo confirma.
PayU India payment on hold: el importe o la moneda pagados no coinciden con el carrito, la API verify_payment no se pudo contactar o no ha confirmado aún el pago, o llegó un pago para un pedido que había sido cancelado. La nota indica el motivo. Revisa la transacción en el PayU Dashboard y después pon el pedido en Payment accepted o cancélalo y reembolsa el pago. Cuando solo falló la verificación, el pedido se paga automáticamente en la siguiente entrega del resultado.
Payment error: un pago pendiente fue rechazado o cancelado más tarde. Un resultado correcto posterior todavía paga el pedido.
Refunded: todo lo pagado fue reembolsado a través del módulo.
Si PayU informa de otro pago correcto para un pedido que ya está pagado, el pedido no cambia y una nota te pide que reembolses el duplicado en el PayU Dashboard. Un pago de PayU para un carrito que se pidió con otro método de pago recibe una nota y no paga ese pedido.
Bloque de pago de PayU India
La página del pedido muestra un bloque PayU India payment con el ID de transacción de PayU (mihpayid), el ID de transacción de la tienda (txnid), el entorno, el estado de PayU, el modo y el banco del pago, el importe pagado y el importe de reembolsos solicitado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las notas del módulo. En un pedido en espera muestra un recordatorio para revisar el pago.
Reembolsos
En el bloque PayU India payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via PayU. Confirma la pregunta Refund this amount through PayU? This cannot be undone. Se admiten reembolsos totales y parciales; el importe debe ser mayor que cero y no superior al resto de lo que cobró PayU. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. El reembolso se envía a través de la API de reembolsos de PayU con la clave y el salt del modo en el que se hizo el pago, así que esas credenciales deben estar configuradas. Si PayU rechaza el reembolso, el bloque muestra PayU refund failed: con el mensaje de PayU y no se registra ningún reembolso.
PayU pone los reembolsos en cola y los completa de forma asíncrona; el cliente normalmente recibe el dinero en 5–7 días laborables. El historial de reembolsos y las notas muestran el importe, el ID de solicitud de PayU y el motivo. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando PayU ya ha informado del ID de transacción del pago. El módulo no comprueba después el estado del reembolso y no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en 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 India Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox PayU India Payment 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-payu-india 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 India 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, 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.
Resolución de problemas
PayU India no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que la clave y el salt del Mode seleccionado estén rellenados. Comprueba que la moneda del carrito sea INR y que el módulo esté permitido para esa moneda, el país del cliente y el grupo en Payment > Preferences. La página Configure muestra una advertencia por las credenciales que faltan y por una moneda de tienda distinta de INR.
El pago se realizó, pero no se creó ningún pedido: el cliente no regresó a la tienda y no llegó ningún webhook. Añade la URL del webhook de la página Configure en PayU Dashboard > Webhooks para los pagos correctos y fallidos, y asegúrate de que sea accesible desde Internet.
El webhook responde invalid_signature: el hash de PayU no coincide. Comprueba que la clave y el salt del modo del pago sean correctos y que se use Salt v1, no Salt v2. También se rechaza un resultado de un pago en vivo firmado con el salt de prueba, o al revés. No se cambia nada.
El webhook responde not_configured: falta la clave o el salt del modo en el que se inició el pago. Introdúcelos; PayU reintenta el webhook.
El webhook responde verify_unavailable: la API verify_payment todavía no pudo confirmar el pago. El pedido queda en espera y la siguiente entrega vuelve a verificarlo.
El webhook responde busy o retry: el retorno del cliente del mismo carrito se estaba procesando en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). PayU reintenta el webhook. El motivo se escribe en el registro.
El webhook responde ignored_unknown_txnid: la transacción no fue iniciada por esta tienda, por ejemplo otra tienda que usa la misma cuenta de PayU. No se cambia nada.
El cliente ve PayU India requires a phone number: haz que el campo de teléfono de la dirección sea obligatorio o visible en la finalización de compra. Se usa primero la dirección de facturación y después la de envío.
El pedido está en PayU India payment on hold: lee las notas del bloque PayU India payment. El motivo es una discrepancia de importe o de moneda, una verificación fallida o pendiente, o un pago para un pedido cancelado.
El reembolso falla: PayU transaction ID not found for this order. significa que el pedido todavía no tiene ningún pago de PayU. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (o Live mode) significa que primero debes introducir las credenciales de ese modo. Invalid refund amount: at most … INR can be refunded. significa que el importe es mayor que el resto del pago.
Muy poca información en el registro: los errores y las advertencias siempre se escriben; activa Enable Logging para ver también cada formulario de pago y cada resultado de PayU.
Hook para desarrolladores: actionPayuPRequestFields cambia los campos de la solicitud de pago antes de firmarlos. Con él no se pueden cambiar la clave, el ID de transacción, el importe ni las URL de retorno.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayU India Payment 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 del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de transacciones de PayU, las solicitudes de reembolso y los estados de pedido Awaiting PayU India payment y PayU India payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago y los ID de transacción de PayU.
PayU es una marca comercial de su respectivo propietario. Este módulo no está afiliado a PayU ni cuenta con su respaldo.