VibeFox MultiSafepay for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 o posterior (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: la moneda de la finalización de compra debe ser una de las que acepta MultiSafepay, por ejemplo EUR, USD, GBP, PLN, CHF, SEK, DKK o NOK. Con otras monedas, el método de pago no se muestra en la finalización de compra.

Cuenta de MultiSafepay: necesitas la clave API de tu sitio web en MultiSafepay Control. Las cuentas de prueba y reales tienen claves distintas. No hay que configurar nada más en MultiSafepay: la dirección de notificación se envía con cada pago.

Sitio público: MultiSafepay debe poder acceder a tu tienda para enviar las notificaciones. Si no puede, los pedidos reciben igualmente su estado cuando el cliente vuelve desde MultiSafepay.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

El archivo de descarga es un único zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_multisafepay_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_multisafepay_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_multisafepay_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions, elige el tipo Payments, busca VibeFox MultiSafepay Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de métodos de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. 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 License key).

4. Pega la clave API de prueba y/o real de MultiSafepay Control (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_multisafepay_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, en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions, elige el tipo Payments, busca VibeFox MultiSafepay Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Pega la clave de licencia y las claves API como en los pasos 3 a 5 para OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de notificación es distinta (ver Notification URL).

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 MultiSafepay Gateway > 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 Test mode: new payments use the MultiSafepay test environment (no real payments). mientras el modo de prueba está activado. También avisa cuando el método de pago está activado pero el modo actual no tiene clave API (en ese caso el método de pago no se muestra en la finalización de compra) y cuando MultiSafepay no acepta la moneda predeterminada de tu tienda. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title debe tener entre 1 y 128 caracteres, Sort Order debe ser un número entero (se permiten los 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 y la página indica el problema. Si el método de pago está activado sin la clave API del modo actual, los ajustes se guardan con una advertencia.

Checkout

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

Title: el nombre del método de pago que el cliente ve en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: MultiSafepay. Obligatorio, hasta 128 caracteres.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmar. Por defecto: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

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

Geo Zone: ofrece MultiSafepay solo para direcciones de pago dentro de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el importe, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca MultiSafepay. Déjalo vacío para ofrecer MultiSafepay con cualquier importe.

Claves API

Encuentra la clave API en MultiSafepay Control > Manage settings > Website settings. La sección enlaza con la cuenta de prueba (testmerchant.multisafepay.com) y con la cuenta real (merchant.multisafepay.com). Tienen claves distintas. El modo de prueba usa solo la clave de prueba, y el modo real usa solo la clave real.

Test mode: usa el entorno de prueba de MultiSafepay (sin pagos reales). Cambia tanto la dirección de la API como la clave API. Los pagos ya realizados siguen usando el entorno en el que se hicieron para las comprobaciones de estado y 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 API key: la clave API de tu cuenta de prueba de MultiSafepay.

Live API key: la clave API de tu cuenta real de MultiSafepay.

Las claves guardadas no se vuelven a mostrar nunca. 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

No hay nada que configurar. El campo Notification URL muestra la dirección que se envía a MultiSafepay con cada pago. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_multisafepay_gateway/webhook, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_multisafepay_gateway/payment/wcp_multisafepay_gateway.webhook. Se construye a partir de la dirección pública de tu instalación de OpenCart. Una notificación solo indica a la extensión qué pago ha cambiado: el estado, el importe y la moneda siempre se leen de la API de MultiSafepay, con la clave API del entorno del pago, antes de modificar el pedido. Las notificaciones de pagos que no se iniciaron en tu tienda se ignoran. La notificación también funciona mientras la tienda está en modo mantenimiento, porque OpenCart 3 deja pasar las peticiones de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para ello, que además permite que el cliente vuelva desde MultiSafepay.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido ausente). El pedido recibe un estado solo cuando MultiSafepay ha informado del pago. Cada campo de abajo enumera tus estados de pedido de OpenCart.

Order status after payment: el estado de un pedido pagado. Por defecto: En curso. Elige Complete para completar de inmediato los pedidos pagados.

MultiSafepay payment on hold status: el pago necesita atención (ver Order statuses). Por defecto: Pendiente, porque OpenCart no tiene estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Payment error status: un pago no liquidado o reservado fue rechazado, cancelado, caducado o anulado después. Por defecto: Fallido.

Refunded status: se establece cuando el pago se reembolsa por completo desde la página del pedido. Por defecto: Reembolsado.

Advanced

Debug log: registra las llamadas a la API y las notificaciones en mspg_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 API y los datos de los clientes 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 los ajustes de la pasarela y el registro. Los datos de pago de MultiSafepay de los pedidos siempre se conservan, de modo que los reembolsos de pedidos antiguos siguen siendo posibles. Desactivar la extensión nunca borra nada. Por defecto: desactivado.

Import / Export

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

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

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto MultiSafepay). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to MultiSafepay to choose a payment method and pay. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea un pago de MultiSafepay por el total del pedido en la moneda del pedido y envía al cliente a la página de pago de MultiSafepay. Allí el cliente elige cualquier método de pago activado en tu cuenta de MultiSafepay y paga. 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 finalización de compra. La dirección de facturación, el correo electrónico, el teléfono y el idioma del cliente se envían a MultiSafepay, y el pago aparece con Order #, el número de pedido y el nombre de tu tienda.

Tras pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando MultiSafepay lo confirma, mediante la notificación o mediante una comprobación con la API de MultiSafepay cuando el cliente regresa. Después el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de pedido completado de OpenCart con Your payment with MultiSafepay has been received. En un pedido en espera, la página muestra We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. Si el pago falla más tarde, la página muestra Your MultiSafepay payment was not completed. Please contact us about this order. Si MultiSafepay todavía no ha confirmado el pago cuando el cliente vuelve (por ejemplo, si se espera una transferencia bancaria), una página Payment confirmation muestra el mismo texto de confirmación y un botón Check again. La notificación establece el estado del pedido en cuanto MultiSafepay informa del pago.

Si el cliente cancela en la página de MultiSafepay, o el pago es rechazado o caduca, el cliente vuelve a la finalización de compra con el carrito conservado y con uno de estos mensajes: The MultiSafepay payment was cancelled. You can try again or choose another payment method., The payment was declined. Please try again or choose another payment method. o The payment session has expired. Please try again. En OpenCart 4 estos mensajes 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; OpenCart 4 mantiene un único pedido para la compra y paga de nuevo ese mismo pedido. Antes de crear un pago nuevo, la extensión comprueba en MultiSafepay los pagos anteriores del mismo carrito. Si uno ya está pagado o en curso, ese pago se confirma y el cliente va a la página de éxito en lugar de pagar otra vez. Si el pago de este pedido sigue abierto con el mismo entorno, importe y moneda, se reutiliza la misma página de pago. Si no, el pago anterior se cancela en MultiSafepay para que ya no se pueda pagar.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, si su pago fue rechazado o caducó después de estar en espera, o lo cancelaste), el cliente vuelve a la finalización de compra con el mensaje Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., y el siguiente Confirm Order paga un pedido nuevo. Si el pedido se pagó y después lo cerró la tienda (por ejemplo, con un reembolso), el mensaje es Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. Si el pedido de la finalización de compra ya está realizado y el carrito ha cambiado desde entonces, el mensaje es Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Cualquier cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago. Un pedido del carrito que se pagó y después se canceló o reembolsó ya no retiene el carrito.

Si MultiSafepay no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un mensaje breve encima del botón, por ejemplo Could not connect to MultiSafepay. Please try again in a moment. o MultiSafepay cannot accept this order amount or currency. Please choose another payment method. El motivo técnico se escribe en el registro.

La extensión ofrece un único método de pago que lleva a la página de MultiSafepay. No tiene métodos de pago de OpenCart separados para cada método de MultiSafepay, ni campos de tarjeta integrados, ni botones express de Apple Pay o Google Pay, ni suscripciones, pagos recurrentes o tarjetas guardadas, ni captura o anulación desde OpenCart. No se envían datos del carrito, así que los métodos de pago aplazado que los requieren (por ejemplo Klarna, in3 o Riverty) no los ofrece MultiSafepay para estos pedidos.

Pedidos y reembolsos

Order statuses

No status (missing order): el cliente fue enviado a MultiSafepay y no ha pagado, MultiSafepay todavía no ha confirmado el pago, o el pago se canceló, rechazó o caducó. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Order status after payment (default Processing): MultiSafepay confirmó el pago (completado o enviado) con el importe y la moneda exactos del pedido. Una nota muestra el pago, el método de pago y el entorno.

MultiSafepay payment on hold status (default Pending), before payment: el pago no está liquidado (MultiSafepay lo está revisando) o está reservado (autorizado). Captura un pago reservado en MultiSafepay Control para recibir el dinero. El pedido pasa a Order status after payment automáticamente cuando MultiSafepay informa de que está completado, o a Payment error status cuando se rechaza, cancela, caduca o anula.

MultiSafepay payment on hold status, after payment: MultiSafepay confirmó un importe o una moneda distintos del total del pedido, se completó un pago de prueba mientras la extensión estaba en modo real (no se recibió dinero real), o el pago se completó después de que el pedido hubiera recibido otro estado, por ejemplo cancelado. La nota lo explica. Revisa la transacción en MultiSafepay Control y completa o reembolsa el pedido.

MultiSafepay payment on hold status, after a chargeback: MultiSafepay informó de un contracargo del pago de un pedido pagado: el dinero se retiró de tu cuenta.

Payment error status (default Failed): un pago no liquidado o reservado fue rechazado, cancelado, caducado o anulado después.

Refunded status (default Refunded): el pago se reembolsó por completo a través de la extensión.

Un pedido pagado o reembolsado nunca se reabre por una notificación tardía. Si se completa un segundo pago para un carrito que ya está pagado, el pedido pagado no cambia. Una nota te pide que reembolses el duplicado en MultiSafepay Control.

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

Pestaña VibeFox MultiSafepay Gateway

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

Refunds

En la pestaña VibeFox MultiSafepay Gateway introduce el Amount (se rellena el importe aún no reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via MultiSafepay. Confirma la pregunta Refund this amount through MultiSafepay? 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 en el importe y la moneda que cobró MultiSafepay, así que, tras una diferencia de importe, puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía al entorno en el que se hizo el pago (prueba o real), por lo que la clave API de ese entorno debe estar configurada. Si MultiSafepay no acepta el reembolso, la pestaña muestra MultiSafepay refund failed: con el error de MultiSafepay, y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID de reembolso de MultiSafepay. Un reembolso total establece el pedido en Refunded status sin notificar al cliente y sin devolver los productos al stock, igual que un cambio manual de estado. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando MultiSafepay ha informado del pago.

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

Los reembolsos hechos en MultiSafepay Control se añaden a las notas cuando MultiSafepay los informa. El estado del pedido no cambia automáticamente. Actualízalo 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 MultiSafepay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox MultiSafepay Gateway > 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-multisafepay 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 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 el servidor de licencias no está disponible, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, MultiSafepay 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. Un usuario administrador que haya iniciado sesión en el panel 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 panel, así que sin una clave activa el método de pago queda oculto para todo el mundo. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. 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 al abrir el Dashboard o la página Edit del panel: 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 ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y su estado.

Solución de problemas

MultiSafepay does not appear at checkout: comprueba que la licencia está activa, que Enable/Disable está activado y que el modo actual tiene una clave API: Test API key en modo de prueba, Live API key en modo real. La página de ajustes muestra una advertencia cuando falta la clave. El cliente debe pagar en una moneda que acepte MultiSafepay (la moneda seleccionada en la tienda). Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total configurado.

The payment went through, but the order stays without a status: la notificación no llegó a tu tienda. Comprueba que la tienda es accesible desde internet y que la clave API del entorno del pago está configurada, porque la extensión lee el estado desde la API de MultiSafepay. Si no se puede acceder a la API o falta la clave, la notificación responde ERROR y MultiSafepay la reintenta. El pedido también recibe su estado cuando el cliente vuelve a la tienda y cuando intenta pagar de nuevo el mismo carrito.

Notification answers Invalid request: la petición no tenía un ID de transacción válido. Las notificaciones de MultiSafepay siempre lo tienen.

The customer sees an error after Confirm Order: activa Debug log y revisa el campo Log en la página de la extensión. This payment method is not available. significa que la sesión de finalización de compra ya no coincide con el pedido, o que el método de pago se desactivó entretanto: el cliente debe recargar la finalización de compra. This payment method is temporarily unavailable. Please choose another payment method. suele indicar una clave API incorrecta o ausente. MultiSafepay cannot accept this order amount or currency. Please choose another payment method. significa que MultiSafepay rechazó el importe o la moneda.

The customer comes back and sees Payment verification failed.: la dirección de retorno no coincidía con un pago de esta tienda, por ejemplo por un enlace antiguo o modificado. El cliente puede volver a pagar desde la finalización de compra.

Order is in the on hold status: lee las notas de la pestaña VibeFox MultiSafepay Gateway. El pago puede no estar liquidado o estar reservado, el importe o la moneda pagados pueden diferir del pedido, puede haber llegado un pago de prueba en modo real, el pago pudo llegar después de cancelar el pedido, o puede haber habido un contracargo. Revisa la transacción en MultiSafepay Control.

Test payments do not confirm a live order: un pago de prueba nunca paga un pedido mientras la extensión está en modo real; en su lugar, el pedido queda en espera. Los pagos de prueba anteriores siguen comprobándose y reembolsándose con la clave de prueba después de cambiar a modo real.

No refund form in the tab: la pestaña indica el motivo: el pago todavía no está informado, está reembolsado por completo, o tu grupo de usuarios no tiene permiso para modificar la extensión.

Refund fails with a message about the environment: el pago se hizo en el entorno de prueba o real, y la clave API de ese entorno no está configurada. Introdúcela y vuelve a intentarlo.

Para desarrolladores: la extensión dispara los eventos de OpenCart mspg_supported_currencies y mspg_order_request para cambiar las monedas admitidas y los datos de pago que se envían a MultiSafepay.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox MultiSafepay Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart elimina siempre sus propios ajustes 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. El evento de OpenCart de la extensión también se elimina (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar las notificaciones en modo mantenimiento). Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, claves API, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de MultiSafepay siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsá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 MultiSafepay Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

MultiSafepay es una marca registrada de su respectivo titular. Esta extensión no está afiliada a MultiSafepay ni cuenta con su respaldo.