VibeFox Montonio 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: la moneda del carrito debe ser EUR o PLN. Con cualquier otra moneda, el método de pago no se muestra en la finalización de compra.
Cuenta de Montonio: necesitas la clave de acceso y la clave secreta de tu tienda del Montonio Partner System. Las claves de sandbox y de live son diferentes, así que necesitas un par para cada entorno que uses. No hay que configurar nada más en Montonio: la dirección de notificación se envía con cada pago.
Sitio público: tu tienda debe ser accesible desde internet para recibir las notificaciones de Montonio. Si no lo es, los pedidos se crean igualmente cuando el cliente vuelve a la tienda.
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 más tarde VibeFox Montonio Payment en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. En el Montonio Partner System, abre Stores > your store > API keys y copia la clave de acceso y la clave secreta de sandbox. Pégalas en la configuración y deja activado Sandbox mode.
5. Activa Enable/Disable, haz clic en Save y prueba un pago en sandbox. Después, introduce las claves de live y desactiva Sandbox mode.
Al instalarse, el módulo crea el estado de pedido Montonio payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Montonio Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando faltan las claves del entorno actual (en ese caso el método de pago no se muestra en la finalización de compra), cuando la moneda de la tienda no es EUR o PLN, y muestra Sandbox mode is on: payments are simulated and no real money is charged. mientras el sandbox está activado. Title no puede estar vacío.
Montonio
Enable/Disable: Enable Montonio bank payments 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 finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Bank payment (Montonio). Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.
Claves API
Obtén las claves en el Montonio Partner System en Stores > your store > API keys. Las claves de sandbox y de live son diferentes. El sandbox usa solo las claves de sandbox, y el modo live solo las claves de live.
Sandbox mode: usa el sandbox de Montonio (pagos de prueba, sin dinero real). Cambia tanto la dirección de la API de Montonio como el par de claves. Por defecto: activado. Desactívalo solo después de introducir las claves de live. Los pagos hechos en el otro entorno siguen usando las claves de su propio entorno para las confirmaciones y los reembolsos.
Sandbox access key: la clave de acceso (UUID) de tu tienda en el sandbox de Montonio.
Sandbox secret key: la clave secreta de tu tienda en el sandbox de Montonio.
Live access key: la clave de acceso (UUID) de tu tienda en el entorno live de Montonio.
Live secret key: la clave secreta de tu tienda en el entorno live de Montonio.
Las claves secretas guardadas no se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarlo.
Clear saved secret keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Notification URL: la dirección a la que Montonio envía las notificaciones de pago. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_montonio_payment/webhook. No necesitas introducirla en ningún sitio: el módulo la envía a Montonio con cada pago.
Avanzado
Debug log: escribe los eventos de pago en logs/wc_mnt_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso cuando esta opción está desactivada. Las claves, los tokens 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: si está activado, al desinstalar el módulo se eliminan sus ajustes y su registro. Desactivar el módulo nunca borra nada. Los datos de los pedidos (UUID de Montonio, notas) siempre se conservan. Por defecto: desactivado.
Notificaciones de pago
Montonio informa a tu tienda de cada pago mediante un token firmado. El token llega de dos formas: mediante una notificación de servidor a servidor a la URL de notificación y con el cliente cuando vuelve a la tienda. Se comprueban ambos: la firma con la clave secreta del entorno en el que se creó el pago, la fecha de caducidad, tu clave de acceso y que el pago lo haya creado tu tienda para ese carrito. Un token firmado con la clave del otro entorno se rechaza. Cada estado se aplica una sola vez, así que las notificaciones repetidas no añaden notas, correos electrónicos ni cambios de stock. La URL de notificación funciona mientras la tienda está en modo de mantenimiento y no está bloqueada por la restricción de países de tu tienda.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto, Bank payment (Montonio)) y confirma. El módulo crea un pago de Montonio por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de Montonio. Allí el cliente elige un banco y paga. Primero se muestran los bancos del país de facturación del cliente (Polonia para los carritos en PLN). El pago aparece como Order seguido del número del carrito. La página de Montonio se abre en el idioma de la tienda cuando es alemán, inglés, estonio, finlandés, lituano, letón, polaco o ruso; en caso contrario, en inglés. En modo sandbox, la finalización de compra muestra SANDBOX MODE — test payment, no real money is charged. debajo de la descripción. En este punto todavía no existe ningún pedido.
El pedido se marca como pagado solo después de que Montonio lo confirme: mediante la notificación o con el regreso del cliente. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your Montonio bank payment has been received. Si el banco todavía no ha confirmado el pago, o el pedido está en espera, la página muestra We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. Si el banco rechaza más tarde un pago autorizado, la página muestra Your Montonio payment was not completed. Please contact us about this order.
Si Montonio informa de que el pago sigue pendiente cuando el cliente regresa, una página Payment confirmation muestra el mismo texto y un botón Check again. El botón pide a Montonio el estado actual del pago. La notificación crea el pedido en cuanto llega.
Si el pago se canceló o el banco lo rechazó, el cliente vuelve a la finalización de compra con uno de estos mensajes: The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. o Montonio could not complete the payment. Please try again or choose another payment method. El carrito se conserva. Antes de crear un nuevo pago, el módulo pregunta a Montonio por el anterior. Si ya está pagado, se crea el pedido y no se realiza un segundo pago.
Si Montonio no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. El motivo técnico se escribe en el registro.
El módulo solo acepta pagos bancarios (iniciación de pagos). No incluye pagos con tarjeta, BLIK, Apple Pay ni Google Pay, Pay Later ni financiación, envío de Montonio, suscripciones, métodos de pago guardados ni selección de banco en tu propio sitio.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Montonio y no ha pagado, o Montonio informa de que el pago está pendiente. Solo existe el carrito.
Payment accepted: Montonio confirmó el pago (PAID) con el importe y la moneda exactos del carrito. El pago se registra con el UUID del pedido de Montonio como ID de transacción, y una nota muestra el banco, el UUID, el importe y el entorno.
Montonio payment on hold: el banco todavía no ha confirmado el pago (AUTHORIZED); el pedido pasa a Payment accepted cuando Montonio informa de PAID. Un pedido también se pone en espera cuando Montonio informó de un importe o una moneda diferentes del total del carrito, cuando llegó un pago de sandbox mientras la tienda está en modo live (no se registra ningún pago, porque no se recibió dinero), o cuando el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Comprueba el pago en el Montonio Partner System y tramita el pedido o reembolsa el pago.
Payment error: el banco rechazó un pago autorizado, o el cliente no lo completó. Solo el último pago del carrito puede cambiar el pedido.
Refunded: el pago se reembolsó por completo a través del módulo.
Los pedidos pagados, cancelados o reembolsados nunca se reabren con notificaciones posteriores. Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que reembolses el segundo pago en el Montonio Partner System.
Bloque Montonio payment
La página del pedido muestra un bloque Montonio payment con el UUID del pedido de Montonio, el entorno (con una etiqueta Sandbox para los pagos de prueba), el banco, el estado del pago, el importe pagado y reembolsado, el historial de reembolsos y las Montonio notes del pedido.
Reembolsos
En el bloque Montonio payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo (solo se guarda en la nota del pedido), y haz clic en Refund via Montonio. Confirma la pregunta Refund this amount through Montonio? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos están limitados al importe que cobró Montonio, así que después de una diferencia de importe puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. El reembolso se envía al entorno en el que se hizo el pago (sandbox o live), por lo que las claves de ese entorno deben estar configuradas. Si Montonio no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso enviado se añade al historial de reembolsos y a las notas con su estado y el ID de reembolso de Montonio. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Montonio ha informado de que el pago está pagado.
Montonio confirma o rechaza cada reembolso más tarde mediante una notificación. La confirmación se añade a las notas. Si Montonio rechaza el reembolso, la nota indica que el dinero no se devolvió al cliente; compruébalo en el Montonio Partner System y corrige el reembolso en PrestaShop.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Montonio. Los reembolsos hechos en el Montonio Partner System se añaden a las notas cuando Montonio los informa. El estado del pedido y las facturas de abono no se cambian automáticamente. Actualízalos manualmente si es necesario.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Montonio Payment es el primer bloque de Modules > Module Manager > VibeFox Montonio Payment > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que está activa la licencia 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 están la línea Product: presta-payment-montonio y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del Back Office (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 después de liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, 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. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, Montonio 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 de PrestaShop no sabe que tienes sesión iniciada 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 se siguen confirmando 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. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.
Solución de problemas
Montonio no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que están configuradas ambas claves del entorno actual (Sandbox access key y Sandbox secret key en modo sandbox, Live access key y Live secret key en modo live) y que la moneda del carrito es EUR o PLN. La página de ajustes muestra una advertencia cuando faltan claves o la moneda de la tienda no es compatible. En Payment > Preferences, comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: la notificación no llegó a tu tienda. Comprueba que la tienda es accesible desde internet y que las claves de la configuración pertenecen al entorno del pago. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar, cuando el cliente hace clic en Check again y cuando el cliente intenta pagar de nuevo el mismo carrito.
La notificación responde Invalid token: la firma, la caducidad o la clave de acceso del token no coincidieron. Comprueba que la clave de acceso y la clave secreta están copiadas correctamente y pertenecen al entorno correcto, y que el reloj del servidor es correcto. Un token firmado con la clave del otro entorno también se rechaza.
La notificación responde Payment does not belong to this order: el pago no lo creó esta tienda para este carrito. Esto ocurre cuando dos tiendas usan la misma cuenta de Montonio y los mismos números de carrito.
La notificación responde Gateway not configured: no hay claves de Montonio configuradas, o faltan las claves del entorno del pago. Introduce las claves; Montonio reintenta la notificación.
La notificación responde Temporarily unavailable: el carrito se estaba confirmando en ese mismo momento con otra solicitud, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). Montonio reintenta la notificación. Consulta el campo Log para ver el motivo.
El cliente ve un error al elegir Montonio: consulta el campo Log en la página del módulo. This payment method is temporarily unavailable. Please choose another payment method. suele significar que las claves son incorrectas o faltan. Montonio could not start the payment. Please check your order details or choose another payment method. significa que Montonio rechazó los datos del pago; el registro contiene el motivo.
El pedido queda en Montonio payment on hold tras el pago: lee las notas del bloque Montonio payment (consulta Estados del pedido) y luego tramita el pedido o reembolsa el pago.
Los pagos de sandbox no confirman un pedido live: un pago de sandbox nunca completa un pedido mientras la tienda está en modo live; el pedido se pone en espera. Cambia Sandbox mode al entorno que quieras y usa las claves de ese entorno.
El reembolso falla con un mensaje sobre el entorno: el pago se hizo en el entorno de sandbox o de live, y no están configuradas las claves de ese entorno. Introdúcelas y vuelve a intentarlo.
Para los desarrolladores, el módulo ofrece los hooks actionWcpMontonioSupportedCurrencies, actionWcpMontonioOrderData y actionWcpMontonioLocale para cambiar las monedas admitidas, los datos del pago y el idioma de la página de Montonio.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Montonio Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data 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 pagos y reembolsos de Montonio y el estado de pedido Montonio payment on hold siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Montonio es una marca comercial de su respectivo titular. Este módulo no está afiliado a Montonio ni cuenta con su aprobación.