VibeFox GoPay for PrestaShop — Ayuda

Requisitos

PrestaShop: de 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Moneda: GoPay acepta CZK, EUR, PLN, USD, GBP, HUF, RON y BGN. Con otra moneda del carrito, el método de pago no se muestra en la finalización de compra.

Cuenta de GoPay: necesitas el GoID, el Client ID y el Client Secret de tu cuenta de comerciante de GoPay. Están en la configuración de integración de la cuenta. La cuenta sandbox (de prueba) tiene sus propias credenciales. No hay que configurar nada en la cuenta de GoPay para las notificaciones, pero tu tienda debe ser accesible desde internet.

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 GoPay 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 GoID, el Client ID y el Client Secret de sandbox, deja Test Mode activado, activa Enable/Disable y haz clic en Save.

5. Realiza un pedido de prueba. Cuando todo funcione, introduce las credenciales de producción y desactiva Test Mode.

Al instalar, el módulo crea el estado de pedido GoPay payment on hold. PrestaShop habilita el 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 GoPay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Sandbox mode — test payments only o Production mode — real payments. Avisa cuando falta el GoID, el Client ID o el Client Secret del modo actual, y cuando GoPay no acepta la moneda predeterminada de la tienda. En ambos casos, GoPay no se ofrece en la finalización de compra. Al guardar, se borran los tokens de acceso de GoPay en caché, de modo que las nuevas credenciales se usan de inmediato.

GoPay

Enable/Disable: Enable GoPay payment gateway activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el título del método de pago que se muestra en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: GoPay. Obligatorio: un título vacío no se guarda.

Description: la descripción del método de pago que se muestra en la finalización de compra. Predeterminado: Pay securely via GoPay - cards, wallets, bank transfers.

Credenciales de API

El GoID, el Client ID y el Client Secret aparecen en tu cuenta de comerciante de GoPay (configuración de integración). La cuenta sandbox (de prueba) tiene sus propias credenciales. La documentación de la API está en doc.gopay.com.

Test Mode: envía los pagos a gw.sandbox.gopay.com con las credenciales de sandbox. No se cobra dinero real. Desactívalo para aceptar pagos reales con las credenciales de producción. Predeterminado: activado.

Sandbox GoID: el GoID de tu cuenta de prueba (sandbox) de GoPay.

Sandbox Client ID: el Client ID OAuth de la cuenta sandbox.

Sandbox Client Secret: el Client Secret OAuth de la cuenta sandbox.

Production GoID: tu ID de comerciante de GoPay (GoID).

Production Client ID: el Client ID OAuth de GoPay.

Production Client Secret: el Client Secret OAuth de GoPay.

El GoID contiene solo dígitos, por ejemplo 8123456789. Si introduces otra cosa, la página muestra un error y se mantiene el valor anterior.

Los Client Secret guardados 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.

Clear saved client secrets: márcalo y haz clic en Save para eliminar los dos Client Secret guardados. Un campo vacío mantiene el valor guardado.

Pago

Payment Page Language: el idioma de la página de pago de GoPay. Predeterminado: Automatic (site language, then billing country). La opción automática usa el idioma del carrito del cliente; si GoPay no lo tiene, decide el país de facturación, y si no, se usa inglés. También puedes fijar uno de 19 idiomas: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian o Russian.

Order Status After Payment: el estado del pedido que se asigna cuando se confirma el pago.

Los pagos que no coinciden con el pedido, los pagos posteriores a una cancelación y los pagos preautorizados siempre pasan a GoPay payment on hold.

Notificaciones de pago

La notificación informa a tu tienda de que se ha realizado un pago. La Notification URL aparece en esta sección y se envía a GoPay con cada pago, así que no hay que configurar nada en la cuenta de GoPay. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_gopay_gateway/webhook, posiblemente con un código de idioma como /en/. Debe ser accesible desde internet: sin protección con contraseña ni cortafuegos delante. Funciona mientras la tienda está en modo mantenimiento y no la bloquea la restricción por país de tu tienda.

Las notificaciones de GoPay solo contienen el ID del pago y no llevan firma. Cada notificación se verifica consultando a la API de GoPay el estado del pago, con las credenciales del modo en que se realizó el pago, y el pago debe ser uno que el módulo creó para un carrito de tu tienda. Si el estado no se puede leer desde GoPay, tu tienda responde con un error y GoPay repite la notificación. Sin notificaciones, el pedido se crea solo cuando el cliente vuelve a la tienda después de pagar.

Avanzado

Logging: escribe los eventos de GoPay en logs/gopay_p_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias se registran siempre. Las credenciales, los tokens, los datos de tarjetas y el correo electrónico y el nombre del cliente nunca se registran. Predeterminado: 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 el módulo se eliminan sus ajustes, los tokens de acceso de GoPay en caché y el registro. Los pedidos, sus datos de pago de GoPay y el estado de pedido GoPay payment on hold siempre se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto GoPay) y confirma. El módulo crea un pago de GoPay por el total del carrito en la moneda del carrito, con los productos, el envío y el envoltorio de regalo, y envía al cliente a la página de pago de GoPay. Allí GoPay ofrece los métodos de pago habilitados en tu cuenta de GoPay, como tarjetas de pago, transferencias bancarias y monederos digitales. El nombre de facturación, el correo electrónico, el teléfono y la dirección del cliente se transmiten a GoPay; los campos vacíos no se envían. En GoPay, el pago aparece como Order PS- y el número del carrito. En este momento todavía no existe ningún pedido.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando GoPay lo confirma: mediante la notificación o mediante una consulta a la API de GoPay cuando el cliente vuelve. Si una notificación y un retorno llegan al mismo tiempo, se procesan uno tras otro, de modo que solo se crea un pedido. Después, el cliente ve la página estándar de confirmación del pedido. Si el pedido pasó a GoPay payment on hold, la página añade Your payment is being reviewed. We will contact you if anything else is needed.

Si GoPay todavía no ha confirmado el pago cuando el cliente vuelve (por ejemplo, una transferencia bancaria está en camino o no se puede contactar con GoPay), la página Payment confirmation muestra GoPay 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.

Si el pago no se completó, se canceló o caducó, el cliente vuelve a la finalización de compra con The GoPay payment was not completed. You can try again or choose another payment method. o The GoPay payment was cancelled or has expired. You can try again or choose another payment method. El carrito se conserva, y un nuevo intento crea un nuevo pago de GoPay. Un carrito que ya tiene un pedido nunca vuelve a cobrarse.

Si GoPay no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. o GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.

El cliente elige el método de pago en la página de GoPay; no se puede elegir en PrestaShop. El módulo no ofrece suscripciones ni pagos recurrentes, tarjetas guardadas, formulario de pago integrado ni captura o anulación de preautorizaciones desde PrestaShop.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a GoPay y no ha pagado, o GoPay todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted or Delivered: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el ID del pago de GoPay como ID de transacción, y una nota muestra el ID del pago y el medio de pago.

GoPay payment on hold: GoPay confirmó el pago, pero el importe, la moneda o el número de pedido no coinciden con el carrito (por ejemplo, el carrito se modificó después de iniciar el pago); o el pago llegó después de que el pedido se cancelara; o el pago solo está preautorizado y el dinero aún no se ha capturado. La nota lo explica. Un pago preautorizado debe capturarse en GoPay; después, el pedido pasa al estado de pagado cuando GoPay informa de que el pago está realizado.

Refunded: el pago de GoPay del pedido se reembolsó por completo, a través del módulo o en la cuenta de GoPay.

Si otro intento de pago de un pedido que ya está pagado también se paga, el pedido no cambia. Una nota pide que reembolses el duplicado en la cuenta de GoPay. Se añade una nota similar cuando se paga un pago de GoPay de un pedido que ya se había marcado como pagado sin GoPay, por ejemplo manualmente. Un pedido cancelado o reembolsado nunca se vuelve a abrir por una notificación posterior.

Bloque de pago de GoPay

La página del pedido muestra un bloque GoPay payment con el ID del pago de GoPay, el estado de GoPay y el medio de pago, el importe del pago, el importe pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el motivo de una revisión manual, el historial de reembolsos y las GoPay notes del pedido.

Reembolsos

En el bloque GoPay payment, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via GoPay. Confirma la pregunta Refund this amount through GoPay? 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 Modules. GoPay acepta reembolsos parciales solo durante las 24 horas posteriores al pago. Los reembolsos se realizan por el importe y en la moneda que cobró GoPay, de modo que, tras un desajuste de importe o moneda, puedes reembolsar hasta lo que el cliente pagó realmente. El reembolso se envía en el modo en que se realizó el pago (sandbox o producción), por lo que las credenciales de ese modo deben estar configuradas. Si GoPay rechaza el reembolso, el bloque muestra el mensaje de GoPay y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas; un reembolso que GoPay aceptó para procesarlo más tarde se anota como aceptado. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.

El módulo no crea notas de crédito (credit slips). Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de GoPay.

Los reembolsos realizados en la cuenta de GoPay llegan mediante notificación. Un reembolso total cambia el pedido a Refunded; un reembolso parcial añade una nota. No se añaden al historial de reembolsos del bloque.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox GoPay Gateway es el primer bloque de Modules > Module Manager > VibeFox GoPay 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 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 de ellos están la línea Product: presta-payment-gopay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 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 solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su dominio. Libera el dominio en tu cuenta de vibefox.net.

Sin una clave activa, GoPay no se muestra a los clientes en la finalización de compra. Si, aun así, se inicia un pago, el cliente ve This payment method is not available. Please choose another one. El front office de PrestaShop 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 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 después de introducir la clave, y después una vez por 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

GoPay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene su GoID, Client ID y Client Secret, y que la moneda del carrito es una de CZK, EUR, PLN, USD, GBP, HUF, RON o BGN. La página de ajustes muestra una advertencia cuando faltan las credenciales. 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: GoPay no pudo acceder a la Notification URL que aparece en los ajustes, y el cliente no volvió a la tienda. Elimina la protección con contraseña o las reglas de cortafuegos que bloquean la URL. Comprueba que están configuradas las credenciales del modo en que se realizó el pago, porque cada notificación se verifica con ellas. Activa Logging y revisa el campo Log. GoPay repite las notificaciones que no obtuvieron una respuesta correcta.

Notification answers Order not found: el pago no lo creó esta tienda, o se eliminó su carrito.

Notification answers Payment state could not be verified: no se pudo acceder a la API de GoPay, o las credenciales de ese modo faltan o son incorrectas. GoPay repite la notificación.

Notification answers Busy, retry later: el carrito estaba siendo procesado por otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). GoPay repite la notificación. Activa Logging para ver el motivo.

El cliente ve un error al elegir GoPay: activa Logging y revisa el campo Log. Las credenciales incorrectas, o las del otro modo, son el motivo habitual. Un mensaje sobre los datos de facturación significa que GoPay no aceptó el correo electrónico, el teléfono o la dirección.

Los pagos de prueba no confirman un pedido real: sandbox y producción están separados. Cada pago se comprueba en el modo en que se creó. Cambia Test Mode al modo que quieras y usa las credenciales de ese modo.

Order is GoPay payment on hold after payment: lee las notas del bloque GoPay payment. El importe o la moneda pagados no coincidían con el carrito, el pago llegó después de cancelar el pedido, o el pago solo está preautorizado.

El reembolso falla: lee el mensaje de GoPay en el bloque. Un reembolso parcial solo es posible durante las 24 horas posteriores al pago. Un mensaje sobre el modo significa que el pago se realizó en modo sandbox o producción y que las credenciales de ese modo no están configuradas.

Para desarrolladores: el hook actionGopayPaymentPayload modifica la solicitud de pago antes de enviarla a GoPay.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox GoPay 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 del módulo, los tokens de acceso de GoPay en caché y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de pago de GoPay de los pedidos y el estado de pedido GoPay payment on hold siempre se conservan, de modo que los pedidos pagados antes se pueden seguir reembolsando tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

GoPay es una marca comercial de su respectivo titular. Este módulo no está afiliado a GoPay ni cuenta con su respaldo.