VibeFox PayPlug 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 e importes: euro (EUR), de 0,99 a 20.000,00 por pago, los valores predeterminados de PayPlug. El euro debe estar activado en System > Localisation > Currencies y debe seleccionarlo el cliente. Con otra moneda de compra o fuera de estos límites, el método de pago no se muestra.

Cuenta de PayPlug: necesitas las claves secretas de tu cuenta de PayPlug: la clave de prueba (sk_test_...) y/o la clave real (sk_live_...). No se necesitan otras claves y no hay que configurar ninguna notificación en PayPlug. Tu tienda debe ser accesible desde internet para recibir notificaciones; si no lo es, los pedidos se confirman cuando el cliente vuelve desde PayPlug.

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_payplug_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_payplug_gateway.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_payplug_gateway-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 PayPlug Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón con el lápiz) para abrir la página de configuración. Introduce 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. Pega tus claves secretas del portal de PayPlug (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test Mode activado y, después, desactívalo para aceptar pagos reales.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_payplug_gateway.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 PayPlug Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón con el lápiz).

4. Introduce la clave de licencia y las claves secretas de PayPlug como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de notificación es diferente (ver Notifications).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save debajo de la lista guarda la página completa. Sobre los ajustes, la página avisa cuando el método de pago está activado pero la clave secreta del modo actual está vacía, y cuando la moneda predeterminada de la tienda no es EUR. En ambos casos el método de pago no se muestra en la compra (con otra moneda predeterminada, mientras esa moneda esté seleccionada). Sin permiso para modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title debe tener de 1 a 128 caracteres, Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0 y los estados de pedido deben existir; si no, no se guarda nada y la página muestra los errores. Una clave secreta con formato incorrecto no se guarda, pero los demás ajustes sí: la página muestra Settings saved, except the secret key shown in red. y, por ejemplo, Test Secret Key must start with "sk_test_". The previous value was kept.

Checkout

Enable/Disable: Enable PayPlug Gateway activa o desactiva el método de pago. Por defecto: desactivado.

Title: el nombre del método de pago que ven los clientes en la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: PayPlug. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay securely by card via PayPlug.

Sort Order: la posición de PayPlug entre los métodos de pago de la compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece PayPlug solo para 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 debe alcanzar un pedido para que se ofrezca PayPlug. Déjalo vacío para ofrecer PayPlug con cualquier total. PayPlug acepta por sí mismo de 0,99 a 20.000,00 EUR por pago.

API keys

Encuentra tus claves secretas en el portal de PayPlug, en Developers > API keys. La sección tiene un enlace al portal.

Test Mode: usa la clave secreta de prueba para los pagos nuevos. No se procesa ningún pago real. Los pagos hechos en el otro modo siguen usando la clave de su propio modo para comprobar el estado y para los reembolsos. Por defecto: activado. Mientras está activado, el cliente ve Test mode: no real payment will be made. en el paso Confirm Order.

Test Secret Key: tu clave secreta de prueba de PayPlug. Empieza por sk_test_.

Live Secret Key: tu clave secreta real de PayPlug. Empieza por sk_live_.

Las claves 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. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

Notifications

Notification URL: la dirección que la extensión envía a PayPlug con cada pago. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. No hay que introducir nada en el portal de PayPlug. Cada notificación se comprueba leyendo el pago de nuevo desde la API de PayPlug, así que los pagos se confirman aunque el cliente no vuelva a la tienda. La URL debe ser accesible desde internet; si no, los pedidos solo se confirman cuando el cliente vuelve desde PayPlug.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido perdido). El pedido recibe un estado solo cuando PayPlug ha informado del pago, mediante la notificación o el regreso del cliente; el pago siempre se vuelve a leer desde PayPlug. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado asignado tras un pago correcto, por ejemplo Processing o Complete. Por defecto: Processing.

PayPlug Payment On Hold Status: el pago necesita tu revisión (ver Order statuses). Por defecto: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Payment Error Status: el pago autorizado de un pedido en espera ha fallado o se ha cancelado. Por defecto: Failed.

Refunded Status: se asigna cuando el pago se reembolsa por completo desde la página del pedido. Por defecto: Refunded.

Advanced

Logging: registra las llamadas a la API y las notificaciones en ppg_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran. Las claves secretas, los datos de tarjeta y los datos del cliente nunca se registran. 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: si está activado, al desinstalar la extensión se eliminan sus ajustes y su registro. Los registros de pagos y reembolsos de PayPlug de los pedidos siempre se conservan. Por defecto: desactivado.

Import / Export

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves secretas no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves secretas guardadas se conservan.

Compra

En el paso Payment Method el cliente elige el método de pago (por defecto, PayPlug). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to the secure PayPlug payment page to pay by card.; en modo de prueba, también Test mode: no real payment will be made. 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 del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de compra. Cuando el cliente hace clic en Confirm Order, la extensión crea un pago de PayPlug por el total del pedido en céntimos y envía al cliente a la página de pago de PayPlug. Las direcciones de facturación y de envío, el correo electrónico y el idioma del pedido se envían a PayPlug. Allí el cliente paga con tarjeta.

Tras pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando PayPlug lo confirma: la extensión vuelve a leer el pago desde la API de PayPlug cuando llega la notificación y cuando el cliente regresa. 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, y el cliente ve la página de éxito del pedido de OpenCart con Your payment with PayPlug has been received. Si el pedido está en espera, la página dice We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Si el pedido está en el estado de error de pago, la página dice Your PayPlug payment was not completed. Please contact us about this order. Si no se pudo consultar a PayPlug cuando el cliente regresó, una página Payment confirmation muestra el mismo texto de «estamos confirmando» y un botón Check again; la notificación asigna el estado del pedido en cuanto llega.

Si el cliente cancela en la página de PayPlug, la página de pago se cierra en PayPlug, por lo que no se puede pagar más tarde por error. El cliente vuelve a la compra con un mensaje: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. o, si el pago quedó abierto, Your PayPlug payment was not completed. You can try again or choose another payment method. El carrito se conserva. En OpenCart 4 estos mensajes se muestran encima de la página de compra.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, y OpenCart 4 actualiza el pedido del proceso de compra (un intento nuevo es un pago nuevo de PayPlug para el mismo pedido), así que la extensión revisa primero los intentos anteriores del mismo carrito. Si uno se ha pagado entretanto, se usa ese pago sin crear otro y el cliente va a la página de éxito. Si el intento de este pedido sigue abierto por el mismo importe, se vuelve a usar la misma página de pago. En caso contrario, la página anterior se cierra en PayPlug y se crea un pago nuevo. Un pago tardío de una página cerrada se registra igualmente. Un cambio del carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

OpenCart 4 mantiene el pedido en el proceso de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, lo cancelaste o su pago autorizado falló), el cliente vuelve al proceso de compra con el mensaje Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. El siguiente Confirm Order paga un pedido nuevo. Si ese pedido ya se había pagado para un carrito anterior y el carrito ha cambiado desde entonces, el cliente vuelve al proceso de compra, y el siguiente Confirm Order paga un pedido nuevo del carrito actual. Un pedido cerrado nunca se muestra como pagado.

Si PayPlug no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje breve, por ejemplo PayPlug could not accept your billing details (postcode). Please check them and try again. o The payment provider could not be reached. Please try again in a moment. El motivo técnico se escribe en el registro.

La notificación también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart deja pasar las peticiones de las extensiones de pago (en OpenCart 4 la extensión añade para ello su propia acción de inicio, que también deja pasar el regreso del cliente desde PayPlug).

Los pagos se cobran de inmediato. La extensión no incluye cuotas de Oney, tarjetas guardadas con un clic, formulario de pago integrado, suscripciones ni cobro diferido.

Pedidos y reembolsos

Order statuses

Sin estado (pedido perdido): el cliente fue enviado a PayPlug y no ha pagado, o PayPlug todavía no ha confirmado el pago. En Sales > Orders estos pedidos solo aparecen con el filtro Order Status en Missing Orders. Si el pago falla, el intento se cierra y el cliente puede volver a pagar.

Order Status After Payment (por defecto Processing): el pago está confirmado. Una nota muestra el pago de PayPlug y su modo.

PayPlug Payment On Hold Status (por defecto Pending): el importe o la moneda pagados no coinciden con el pedido (nota amount/currency mismatch); o se hizo un pago de prueba mientras la tienda estaba en modo real, así que no se recibió dinero; o el pago llegó después de que el pedido hubiera recibido otro estado, por ejemplo se canceló; o hay un pago autorizado pero no capturado (captúralo en el portal de PayPlug; el pedido se marca como pagado cuando PayPlug lo informe como pagado). La nota explica qué revisar.

Payment Error Status (por defecto Failed): un pago autorizado de un pedido en espera ha fallado o se ha cancelado. OpenCart notifica este cambio al cliente.

Refunded Status (por defecto Refunded): el pago se reembolsó por completo mediante la extensión.

Si otro pedido de un carrito que ya está pagado también se paga, ese pedido se queda sin estado y el pedido pagado no cambia. Una nota en el pedido pagado pide que reembolses el pago duplicado en el portal de PayPlug. Una notificación posterior nunca vuelve a abrir un pedido pagado o reembolsado.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox PayPlug Gateway

En Sales > Orders, abre un pedido pagado con PayPlug. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox PayPlug Gateway muestra el PayPlug payment ID con la etiqueta Test mode para los pagos de prueba, el Status del pago, los importes Paid / refunded, el formulario de reembolso, el historial de reembolsos (con el modo de cada reembolso) y las PayPlug notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox PayPlug Gateway introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via PayPlug. Confirma la pregunta Refund this amount through PayPlug? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se hacen hasta el importe que PayPlug cobró realmente, así que tras una diferencia de importe puedes reembolsar lo que pagó el cliente, no el total del pedido. El reembolso va al pago que realmente pagó el pedido, con la clave secreta del modo (prueba o real) en el que se hizo, así que esa clave debe estar configurada. Si PayPlug no acepta el reembolso, la pestaña 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 del reembolso de PayPlug y el motivo. Un reembolso total asigna al pedido el Refunded Status sin notificar al cliente y sin devolver productos al stock, igual que un cambio manual de estado. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que PayPlug ha informado de que el pago está pagado.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de PayPlug.

Los reembolsos hechos en el portal de PayPlug llegan mediante notificación y se añaden a las notas una sola vez. Aparecen en el historial de reembolsos, pero no cuentan como reembolsos de la extensión y no cambian el estado del pedido. Regístralos manualmente si hace falta.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayPlug Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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-payplug y el enlace Manage licenses and domains in your account, 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 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 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 contactar con el 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. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, PayPlug no se muestra a los clientes en la compra. Si un pago se inicia 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 pueda 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 queda oculto 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 se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard del panel de administración o la página Edit: 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 hace falta ninguna tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

PayPlug no aparece en la compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene una clave secreta (Test Secret Key en modo de prueba, Live Secret Key en modo real), que la moneda de compra es EUR y que el total del pedido está entre 0,99 y 20.000,00 EUR. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total de los ajustes. Los desarrolladores pueden cambiar las monedas y los límites con los eventos de OpenCart ppg_supported_currencies y ppg_amount_limits (valores en céntimos), y la petición de pago con ppg_payment_data.

El pago se realizó, pero el pedido se queda sin estado: la notificación no llegó a tu tienda y el cliente no volvió. Comprueba que tu tienda es accesible desde internet en la Notification URL que aparece en los ajustes, por ejemplo que ningún cortafuegos o protección con contraseña la bloquea. Activa Logging y revisa el campo Log por si hay notificaciones rechazadas.

La notificación responde Verification failed.: no se pudo leer el pago desde la API de PayPlug, por ejemplo porque PayPlug no respondió o porque la clave secreta del modo del pago no está configurada. El pedido no se modifica y PayPlug vuelve a enviar la notificación.

La notificación responde Temporarily unavailable.: el carrito estaba siendo actualizado por otra petición en el mismo momento, por ejemplo el regreso del cliente, o no se pudo asignar el estado del pedido. PayPlug vuelve a enviar la notificación. El registro muestra el motivo.

La notificación responde Unknown payment. o Payment does not belong to the order.: el pago no lo creó esta tienda o no corresponde a este pedido, por ejemplo un pago de otra tienda de la misma cuenta de PayPlug. Se ignora.

La URL de notificación muestra Method not allowed. en el navegador: es normal. La URL solo acepta peticiones de PayPlug.

El cliente ve un error después de Confirm Order: activa Logging y revisa el campo Log. Una clave incorrecta da This payment method is temporarily unavailable. Please choose another payment method.; otros mensajes indican el campo de facturación que PayPlug rechazó.

El cliente regresa y ve Payment verification failed.: el enlace de regreso no corresponde a un intento de pago del pedido, por ejemplo porque se abrió en otro navegador. Comprueba el pago en el portal de PayPlug; la notificación sigue asignando el estado del pedido.

El pedido está en espera tras el pago: lee las notas de la pestaña VibeFox PayPlug Gateway (ver Order statuses) y después procesa el pedido o reembolsa el pago.

No hay formulario de reembolso en la pestaña: la pestaña indica el motivo: el pago todavía no está pagado, está reembolsado por completo, tu grupo de usuarios no tiene permiso para modificar la extensión, o la clave secreta del modo del pago no está configurada.

El reembolso falla con Unexpected response from PayPlug.: PayPlug respondió sin un reembolso válido. No se registró nada. Comprueba el reembolso en el portal de PayPlug antes de volver a intentarlo.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox PayPlug Gateway. La clave de licencia y el estado de 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 deja pasar las notificaciones y el regreso del cliente en modo de mantenimiento). Si Delete Data on Uninstall está activado, se eliminan los demás ajustes (título, descripción, modo de prueba, claves secretas, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de PayPlug siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de 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 PayPlug Gateway en la lista de extensiones instaladas; después, haz clic en Delete (el botón rojo de papelera) para eliminar el paquete subido.

PayPlug es una marca comercial de su respectivo titular. Esta extensión no está afiliada a PayPlug ni cuenta con su aprobación.