VibeFox Comgate for PrestaShop — Ayuda
Requisitos
PrestaShop: de la 8.0 a la 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
HTTPS: tu tienda debe ser accesible por HTTPS desde internet, para que Comgate pueda enviar la notificación en segundo plano.
Moneda: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK o SEK. Para otras monedas y para totales por debajo del mínimo de Comgate, el método de pago se oculta. Los pagos en HUF se redondean a forintos enteros, como exige Comgate.
Cuenta de Comgate: necesitas el Merchant ID y el secreto (contraseña para la comunicación en segundo plano) de la conexión de tu tienda en el portal de cliente de Comgate, y la URL de notificación configurada allí (véase Configuración). Comgate usa el mismo Merchant ID y secreto para los pagos de prueba y los reales.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 carga, haz clic en Configure, o busca más tarde VibeFox Comgate Gateway 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. Introduce el Merchant ID y el Secret del portal de cliente de Comgate y configura allí la URL de notificación (véase Configuración).
5. Activa Enable / Disable y haz clic en Save. Mantén Test Mode activado para un pago de prueba y después desactívalo.
Al instalarse, el módulo crea el estado de pedido Comgate payment on hold. PrestaShop añade un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Comgate Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si Comgate está activado pero falta el Merchant ID o el secreto (en ese caso el método de pago se oculta en el checkout hasta que se completen ambos) y si la moneda predeterminada de la tienda no es compatible con Comgate. Mientras el modo de prueba está activado, se muestra Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.
Comgate
Enable / Disable: Enable Comgate Payment Gateway activa o desactiva el método de pago. Default: off.
Title: el nombre del método de pago que ven los clientes en el checkout. También es el nombre del método de pago guardado en el pedido. Default: Comgate. Obligatorio.
Description: el texto que se muestra debajo del método de pago en el checkout. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. En modo de prueba se añade TEST MODE: no real money is charged., o se muestra solo si la descripción está vacía.
Conexión con Comgate
Toma el identificador de la tienda (Merchant ID) y la contraseña (secreto) del portal de cliente de Comgate, Integration > shop connection settings. En el mismo lugar, configura la URL for passing the payment result (notificación en segundo plano) con la URL que aparece en Notification URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_comgate_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes. Comgate la llama después de cada pago; el módulo entonces vuelve a comprobar el pago con la API de estado de Comgate antes de cambiar nada. Las URL de retorno para el cliente se envían con cada pago. Si el portal también pide URL de retorno (pagado, cancelado, pendiente), usa la segunda URL que aparece en esta sección, que termina en return?id=${id}&refId=${refId}.
Merchant ID: el identificador de tu tienda (merchant) en Comgate.
Secret: la contraseña para la comunicación en segundo plano (secreto) de esta conexión de tienda. Un secreto guardado nunca se vuelve a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Clear the saved secret: márcalo y haz clic en Save para eliminar el secreto guardado. Un campo vacío mantiene el valor guardado.
Test Mode: crea pagos de prueba (no se cobra dinero). Comgate usa el mismo Merchant ID y secreto para los pagos de prueba y los reales; los pagos de prueba se marcan con test=true. Los reembolsos siempre se envían en el modo del pago original. Default: on.
Página de pago
Payment Methods: qué métodos de pago de Comgate puede elegir el cliente. Solo se muestran los métodos activados para tu tienda en Comgate.
Language: el idioma de la página de pago de Comgate. Automatic (shop language, English as fallback) (predeterminado) o uno de los 26 idiomas.
Pedidos
Order Status After Payment: el estado que se asigna cuando Comgate confirma el pago.
Los pagos que no coinciden con el pedido, los pagos de prueba en modo real y los pagos preautorizados siempre van a Comgate payment on hold.
Avanzado
Debug Log: escribe las solicitudes a la API y las notificaciones en logs/comgate_p_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. El secreto y los datos personales nunca se registran. Los errores siempre se registran. Default: off.
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 el módulo se eliminan los ajustes de la pasarela y el registro. Los pedidos y sus IDs de transacción de Comgate siempre se conservan. Default: off.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto Comgate) y confirma el pedido. El módulo crea el pago en Comgate por el total del carrito en la moneda del carrito y redirige al cliente a la página de pago de Comgate. El correo electrónico y el nombre del cliente se envían a Comgate, y el pago se etiqueta como Cart y con el número del carrito. Se requiere una dirección de correo electrónico válida. En la página de Comgate, el cliente paga con uno de los métodos que hayas permitido. En este punto todavía no existe ningún pedido.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo después de que Comgate lo confirme: el módulo lee el pago desde la API de estado de Comgate, tanto cuando llega la notificación en segundo plano como cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Si el pedido se puso en espera, la página añade Your payment is being reviewed. We will contact you if anything else is needed. Si un pedido preautorizado se canceló más tarde, la página muestra Your Comgate payment was not completed. Please contact us about this order.
Si el pago todavía no está confirmado cuando el cliente vuelve, por ejemplo una transferencia bancaria en camino, aparece una página Payment confirmation con el mensaje Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again., con un botón Check again y un botón Back to checkout.
Si el pago se cancela o caduca, el cliente vuelve al checkout con The Comgate payment was cancelled or has expired. You can try again or choose another payment method. El carrito se conserva. Cada nuevo intento comprueba antes el anterior, así que un pago que ya se completó no se cobra dos veces, y el intento anterior se cancela en Comgate si sigue abierto. Un pago tardío de un intento anterior sigue creando el pedido.
Si Comgate no puede iniciar el pago, el cliente permanece en el checkout con un mensaje breve, por ejemplo The Comgate payment could not be started. Please try again or choose another payment method., que Comgate no puede aceptar este importe o esta moneda, o que el método de pago de Comgate seleccionado no está disponible. El motivo técnico se escribe en el registro.
La 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.
El módulo admite pagos únicos solo en la página de Comgate. No tiene pagos recurrentes, suscripciones ni tarjetas guardadas, ni checkout de Comgate integrado, ni botones de Apple Pay o Google Pay en tu sitio (están disponibles en la página de Comgate), ni captura o cancelación de preautorizaciones desde PrestaShop. Sin la notificación, el estado del pago no se consulta automáticamente; solo se comprueba cuando el cliente vuelve.
Pedidos y reembolsos
Estados de pedido
Pedido aún no creado: el cliente fue enviado a Comgate y todavía no ha pagado, o Comgate informa del pago como pendiente. Solo existe el carrito.
Payment accepted or Delivered: Comgate informó del pago como PAID con el mismo importe y moneda. El estado sigue a Order Status After Payment. El pago se registra con el ID de transacción de Comgate. Los pagos de prueba reciben la nota Comgate test payment — no money was charged.
Comgate payment on hold: el importe o la moneda pagados no coinciden con el pedido, se confirmó un pago de prueba con la tienda en modo real (no se recibió dinero), o el pago solo está autorizado (preautorización en tu cuenta de Comgate). Un pago autorizado pasa a pagado automáticamente cuando lo captures en el portal de Comgate. La nota explica el motivo.
Canceled: un pago autorizado se canceló o caducó en Comgate. Si Comgate confirma el pago después de eso, el pedido se reabre como pagado con una nota para comprobar el stock antes del envío.
Refunded: el pago se reembolsó por completo a través del módulo.
Si Comgate informa de otro pago PAID para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo compruebes en el portal de Comgate y reembolses el duplicado. Una confirmación reenviada nunca reabre un pedido reembolsado.
Bloque de pago de Comgate
La página del pedido muestra un bloque Comgate payment con el ID de transacción, el estado de Comgate, el importe pagado, el total del pedido y el importe reembolsado, una insignia Test mode para los pagos de prueba, el motivo de una revisión, el historial de reembolsos y las Comgate notes del pedido.
Reembolsos
En el bloque Comgate payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Comgate. Confirma la pregunta Refund this amount through Comgate? 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. El reembolso se envía a la transacción de Comgate pagada y en el modo (prueba o real) del pago original. Comgate solo reembolsa pagos PAID y como máximo el importe pagado; los reembolsos en HUF deben ser en forintos enteros. Si Comgate no acepta el reembolso, el bloque 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 importe, la transacción de Comgate y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
Los reembolsos solo están disponibles para pedidos pagados. Un pedido en espera tras una diferencia de importe o de moneda no se puede reembolsar desde PrestaShop; reembólsalo en el portal de Comgate. El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Comgate. Los reembolsos hechos en el portal de Comgate no se comunican a la tienda.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Comgate Gateway es el primer bloque de Modules > Module Manager > VibeFox Comgate Gateway > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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: presta-payment-comgate 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 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 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 plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Comgate no se muestra a los clientes en el checkout. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda online no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en el checkout. Aparece un aviso 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 renovarla. 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 después de introducir la clave, y después una vez a la semana. No hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Comgate no aparece en el checkout: comprueba que la licencia esté activa, que Enable / Disable esté activado, que Merchant ID y Secret estén rellenados, que la moneda del carrito sea compatible y que el total del pedido no esté por debajo del mínimo de Comgate (por ejemplo 1 CZK, 0,10 EUR o 100 HUF). En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo de clientes.
El pago se realizó, pero no se creó ningún pedido: Comgate no ha entregado la notificación en segundo plano. Comprueba la URL for passing the payment result en el portal de Comgate (exactamente la Notification URL de los ajustes), que tu tienda sea accesible por HTTPS desde internet y el registro (activa Debug Log). Comgate repite las notificaciones no entregadas; el módulo responde con un error siempre que no la haya procesado, así que se volverá a intentar. El pedido también se crea cuando el cliente vuelve a la tienda.
La notificación responde Invalid merchant or secret: el Merchant ID o el secreto de los ajustes no coincide con la conexión de tienda del portal de Comgate.
La notificación responde Gateway not configured: el Merchant ID o el secreto de los ajustes está vacío. Comgate lo vuelve a intentar cuando se completen.
La notificación responde Unknown transaction, Order not found o Reference mismatch: la notificación pertenece a un pago que esta tienda no creó para ese carrito. No se cambia nada.
La notificación responde Status verification failed, Status verification rejected o Busy, retry later: no se pudo contactar con la API de estado de Comgate, esta rechazó la solicitud, o el carrito estaba siendo procesado por otra solicitud en ese mismo momento. Busy también es la respuesta cuando no se pudo crear el pedido; el motivo está en el registro. Comgate vuelve a intentar la notificación.
La URL de notificación muestra code=1&message=POST%20required en el navegador: es normal. La URL solo acepta solicitudes de Comgate.
El cliente ve We could not verify the Comgate payment: el enlace de retorno no coincidía con el carrito. Si se cobró dinero, la notificación sigue creando el pedido. Comprueba el pago en el portal de Comgate antes de que el cliente vuelva a pagar.
El cliente ve The order total is below the minimum amount accepted by Comgate o A valid billing e-mail address is required for Comgate payments: el carrito no se puede pagar con Comgate tal como está.
El pedido está en Comgate payment on hold después del pago: lee las notas del bloque Comgate payment. El importe o la moneda pagados eran distintos, llegó un pago de prueba en modo real, o el pago solo está autorizado. Comprueba el pago en el portal de Comgate y completa o reembolsa el pedido manualmente.
El reembolso falla: lee el mensaje del bloque. Comgate rejected the refund: the amount exceeds the refundable amount. significa que el importe es mayor que lo que queda por reembolsar; un pago en un estado distinto de PAID no se puede reembolsar. Comgate could not be reached. The refund was not made — please try again later. significa un problema de conexión.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Comgate Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Comgate y el estado de pedido Comgate payment on hold 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 y sus IDs de transacción.
Comgate es una marca comercial de su respectivo titular. Este módulo no está afiliado a Comgate ni avalado por Comgate.