VibeFox PayU LATAM for OpenCart — Ayuda
Requisitos
OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).
PHP: 8.0 o posterior.
Moneda: la moneda de compra del cliente debe ser ARS, BRL, CLP, COP, MXN, PEN o USD, las monedas que PayU Latam procesa en Argentina, Brasil, Chile, Colombia, México, Panamá y Perú. En otras monedas, el método de pago no aparece en la finalización de compra.
Cuenta de PayU Latam: necesitas tres valores de tu comercio de PayU: el ID de comerciante, el ID de cuenta del país en el que vendes y la clave de API. Están en el panel de comerciante de PayU, en Settings > Technical configuration (merchant ID, API key) y Accounts (account ID). Para hacer 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. No se necesitan la API Login ni otras credenciales de API, porque el pago se realiza en la página alojada de PayU y la extensión nunca llama a la API de PayU.
Acceso a Internet para 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 uno protegido con contraseña).
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_payu_latam_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_payu_latam_payment.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.
OpenCart 3
1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_payu_latam_payment-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.
2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayU LATAM Payment y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.
3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (ver Clave de licencia).
4. Introduce las credenciales de sandbox y tus credenciales de producción (ver 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 hagas un pago de prueba; después, desactívalo para aceptar pagos reales con las credenciales de producción.
OpenCart 4
1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_payu_latam_payment.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.
2. El paquete aparece en la lista de extensiones instaladas de la misma página. Haz clic en Install (el botón verde +) junto a él.
3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayU LATAM Payment, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).
4. Introduce la clave de licencia y las credenciales de PayU como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la URL de confirmación es diferente (consulta URL de confirmación).
Una instalación nueva empieza con el método de pago desactivado y el sandbox activado.
Configuración
Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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 de API del entorno actual (en ese caso, PayU LATAM no se ofrece en la finalización de compra); y una advertencia cuando PayU LATAM no procesa la moneda predeterminada de la tienda. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.
Al guardar, Title no puede estar vacío ni tener más de 128 caracteres (la página muestra Enter a title for the payment method (at most 128 characters).), Sort Order debe ser un número entero (se admiten números negativos), Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido deben existir. Si no, no se guarda nada. Los espacios al principio o al final de una credencial se ignoran.
PayU LATAM
Enable/Disable: Enable PayU LATAM activa o desactiva el método de pago. Por defecto: desactivado.
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. Por defecto: PayU LATAM. Obligatorio, máximo 128 caracteres.
Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. 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.
Sort Order: la posición de PayU LATAM entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.
Geo Zone: ofrece PayU LATAM solo para las direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.
Total: el total de la compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar para que se ofrezca PayU LATAM. Déjalo vacío para ofrecer PayU LATAM con cualquier importe.
Entorno
Sandbox: los pagos se envían al sandbox de PayU con las credenciales de sandbox, y no se cobra dinero real. Cuando está desactivado, se usan las credenciales de producción y la finalización de compra de PayU en producción. Por defecto: activado. Mientras esté activado, el cliente ve Sandbox mode: no real money is charged. en el paso Confirm Order.
Credenciales de producción
Encuéntralas en el panel de comerciante 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 de API para el sandbox de PayU.
Las claves de 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 cambiarlo. Para eliminar una clave guardada, marca Clear saved secret on save debajo del campo y haz clic en Save.
Cada intento de pago recuerda su entorno. La confirmación de un pago de sandbox se verifica con la clave de API y el ID de comerciante del sandbox, y la de un pago real, con los de producción; así, los pagos pendientes siguen funcionando después de cambiar de entorno. Los pagos de sandbox se marcan 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. En OpenCart 3 tiene este formato: https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation; en OpenCart 4, https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. La extensión la envía a PayU con cada pago, así que no hay nada que configurar en PayU. La URL debe ser accesible desde Internet. También funciona mientras la tienda está en modo de mantenimiento (en OpenCart 4, a través de la acción de inicio de la extensión, que además permite al cliente volver desde PayU). PayU firma la confirmación con tu clave de 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. La extensión gestiona estos estados de transacción de PayU:
Los demás estados solo se añaden como nota. Sin la confirmación, el pedido no recibe ningún estado.
Pedidos
OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido perdido). El pedido recibe un estado solo después de la confirmación firmada de PayU. Cada campo de abajo muestra tus estados de pedido de OpenCart.
Order Status After Payment: un pago aprobado (estado 4 de PayU) con el importe y la moneda esperados. Por defecto: Procesando.
Awaiting Payment Status: un pago pendiente (estados 7, 10, 12, 14, 15 y 18; por ejemplo, un pago en efectivo o bancario aún no completado). El pedido recibe Order Status After Payment cuando PayU lo confirma. Por defecto: Pendiente.
On Hold (Review) Status: PayU aprobó un pago, pero con un importe o una moneda distintos a los del pedido, o para un pedido que había sido cancelado. Una nota muestra los detalles; el pedido no se marca como pagado. Por defecto: Pendiente, porque OpenCart no tiene un estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.
Failed Payment Status: un pago pendiente del último intento que PayU informó después como rechazado, vencido o fallido. Por defecto: Fallido.
Cancelled Order Status: el estado que tu tienda usa para los pedidos cancelados. Un pago aprobado para un pedido así lo pone en On Hold (Review) Status en lugar de marcarlo como pagado. La extensión nunca asigna este estado. Por defecto: Cancelado.
Avanzado
Debug log: registra las solicitudes de pago y las notificaciones de PayU en payu_lp_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se mueve a payu_lp_debug.old.log.php. Las claves y los datos personales no se registran. Los errores y las notificaciones rechazadas siempre se registran, incluso con este interruptor 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: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los pedidos y los registros de pago de PayU (intentos de pago) nunca se eliminan. Por defecto: desactivado.
Importar / Exportar
Export: Download JSON guarda los ajustes como archivo JSON. Las claves de API no se exportan.
Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Las claves de API guardadas se conservan.
Finalización de compra
En el paso Payment Method, el cliente elige el método de pago (por defecto, PayU LATAM). En el paso Confirm Order, el cliente ve tu descripción; OpenCart crea el pedido en este paso, todavía sin estado. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque de métodos de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra. Cuando el cliente hace clic en Confirm Order, la extensión prepara un formulario de pago firmado, la página muestra You are being redirected to PayU LATAM to complete the payment... y envía el formulario automáticamente a la página WebCheckout de PayU. Si eso no ocurre, el cliente hace clic en Pay with PayU LATAM.
El formulario contiene el total del pedido en la moneda del pedido, el impuesto y la base imponible del pedido (ambos en 0 para los pedidos sin impuestos, para que PayU no añada un IVA predeterminado), la descripción Order # con el número de pedido y el nombre de tu tienda, y el correo electrónico, el nombre, el teléfono y la 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 cliente. En la página de PayU, el cliente paga con cualquier método habilitado en tu cuenta de PayU.
Cada clic en Confirm Order inicia un nuevo intento de pago con su propia referencia (OC, el número de pedido y una marca de tiempo). En OpenCart 4 un nuevo intento paga el mismo pedido de la finalización de compra. Los intentos anteriores se recuerdan: si el cliente paga en una pestaña anterior de PayU, el pago sigue reconociéndose.
El pedido se marca como pagado solo después de que PayU lo confirme con la confirmación firmada. Después, el pedido recibe su estado de la forma habitual de OpenCart, con los correos electrónicos de pedido habituales y la actualización del stock. El cliente que vuelve desde PayU nunca marca un pedido como pagado. Cuando el cliente vuelve:
En OpenCart 4, los mensajes de la finalización de compra se muestran encima de la página de finalización de compra.
OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, y OpenCart 4 actualiza el pedido de la finalización de compra, pero un carrito solo se paga una vez: si otro pedido del mismo carrito ya está pagado, pendiente de pago o en revisión, Confirm Order lleva directamente a la página de éxito. Si faltan las credenciales del entorno actual, el cliente ve PayU LATAM is not available right now. Please choose another payment method.
OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si mientras tanto ese pedido se cerró sin pago (por ejemplo, su pago en efectivo falló o lo cancelaste), el cliente vuelve a la finalización de compra con Your PayU LATAM payment was not approved y el motivo de PayU si lo hay. Si se había pagado y después lo cerró la tienda, o se había pagado para un carrito anterior y el carrito ha cambiado desde entonces, el mensaje es Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. El siguiente Confirm Order paga un pedido nuevo. Un pedido cerrado nunca se muestra como pagado.
La extensión no tiene formulario de pago en tu sitio, ni reembolsos desde OpenCart, ni tarjetas guardadas, ni suscripciones, ni opciones de pagos a plazos (PayU muestra los pagos a plazos 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 del pedido
Sin estado (pedido perdido): el cliente fue enviado a PayU y no ha pagado, el pago fue rechazado o PayU todavía no ha enviado la confirmación. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.
Order Status After Payment (default Processing): PayU confirmó el pago y el importe y la moneda coinciden. Una nota muestra la transacción, el importe, el método de pago y si fue un pago de sandbox.
Awaiting Payment Status (default Pending): PayU informa del pago como pendiente (pago en efectivo o bancario). El pedido pasa a Order Status After Payment cuando PayU confirma el pago, o a Failed Payment Status si el pago falla. OpenCart notifica al cliente estos cambios.
On Hold (Review) Status (default Pending): el importe o la moneda pagados no coinciden con el total del pedido, o se aprobó un pago para un pedido que había sido cancelado. La nota indica cuál es el caso: revisa el pago en el panel de PayU y, después, procesa el pedido, restáuralo o reembolsa el pago.
Failed Payment Status (default Failed): un pago pendiente del último intento fue rechazado, venció o terminó con un error después. La nota muestra el mensaje de PayU. El 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 sola vez, con un bloqueo por carrito; así, las notificaciones repetidas de PayU no cambian el pedido dos veces ni añaden notas dos veces. Un pedido pagado nunca se degrada. Si llega otro pago aprobado para un pedido que ya está pagado, o para otro pedido del mismo carrito, una nota en el pedido pagado lo indica: si el cliente pagó dos veces, reembolsa el duplicado en el panel de PayU.
Las notas son entradas del History del pedido que el cliente no ve.
Pestaña VibeFox PayU LATAM Payment
En Sales > Orders, abre un pedido pagado con PayU LATAM. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox PayU LATAM Payment muestra la Reference, el Transaction ID, la PayU reference, el Status y el estado de PayU, el importe Requested, el Amount reported by PayU, el Payment method, el PayU message, una insignia SANDBOX para los pagos de sandbox, la lista de todos los Payment attempts del carrito y las PayU LATAM notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.
Reembolsos
Los reembolsos no se realizan desde OpenCart. Reembolsa la transacción en el panel de PayU y, después, registra el reembolso manualmente en OpenCart.
Clave de licencia
La extensión 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 Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit, 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: opencart-payment-payu-latam y el enlace Gestionar licencias y dominios en tu cuenta, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su plaza de dominio. Libérala 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 se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método de pago se oculta para todos. Después de abrir una vez la página Edit, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose con la confirmación de PayU y con el regreso del cliente.
Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit del panel de administración: una vez al día durante los primeros 14 días después de introducir la clave y, después, una vez por semana. No se necesita ninguna tarea cron. Al desinstalar la extensión, siempre se eliminan 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 de API del entorno actual estén rellenados: las credenciales de sandbox cuando Sandbox está activado, y las de producción cuando está desactivado. Comprueba también que la moneda del cliente sea ARS, BRL, CLP, COP, MXN, PEN o USD, que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.
El pago se realizó, pero el pedido se queda sin estado: 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 sea accesible desde Internet (sin sitio local, cortafuegos ni protección con contraseña). Revisa el campo Log de la página de la extensión 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 de API del entorno del pago. Revisa 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 es distinto de Merchant ID o de Sandbox merchant ID, según el 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 de API o el ID de comerciante del entorno del pago, por ejemplo porque se eliminaron las credenciales de sandbox mientras un pago de sandbox estaba 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 establecer el estado del pedido. PayU enviará de nuevo la confirmación. Revisa el Log para ver el motivo.
La confirmación responde Unknown reference: la referencia de pago no la emitió 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. Please reload the checkout page.: la sesión de finalización de compra ya no coincide con el pedido, o Enable/Disable se desactivó mientras tanto. El cliente debe recargar la finalización de compra.
El pedido está en el estado de revisión: lee las notas de la pestaña VibeFox PayU LATAM Payment. El importe o la moneda pagados fueron distintos de los del pedido, o el pago llegó después de que el pedido se cancelara. Revisa la transacción en el panel de PayU.
Desinstalación
Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox PayU LATAM Payment. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. También se elimina el evento de OpenCart de la extensión (en OpenCart 4 también sus eventos y su acción de inicio, que permiten pasar la confirmación y el retorno del cliente en modo de mantenimiento). Si Delete data está activado, se eliminan los demás ajustes de la pasarela (título, descripción, sandbox, credenciales e interruptor del registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los intentos de pago siempre se conservan, de modo que una confirmación tardía de PayU de un intento antiguo sigue reconociéndose tras una reinstalación. Los pedidos existentes conservan sus notas de pago.
En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox PayU LATAM Payment en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.
PayU es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por PayU.