VibeFox Tpay for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP. Para la comprobación de la firma JWS de las notificaciones se necesitan la extensión OpenSSL y el acceso HTTPS saliente a secure.tpay.com.

Moneda de la tienda: solo złoty polaco (PLN). Tpay liquida en PLN y su Open API no tiene campo de moneda, por lo que el método de pago se oculta cuando el carrito usa otra moneda.

Acceso a Internet a tu tienda: Tpay envía las notificaciones de pago a tu tienda, así que la dirección de notificación debe ser accesible desde Internet (no bloqueada por un cortafuegos ni por autenticación HTTP).

Cuenta de Tpay: necesitas estos valores del panel de comerciante de Tpay: el Merchant ID (el ID de tu cuenta de Tpay), las claves de Open API Client ID y Client secret (Integration, API) y el código de seguridad (Settings, Notifications). Las claves de sandbox proceden de una cuenta de sandbox de Tpay independiente.

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 Tpay 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 (consulta Clave de licencia).

4. Introduce las claves de Sandbox y las claves de Producción (véase Configuración). En el panel de Tpay no hay que configurar nada salvo el código de seguridad: la dirección de notificación se envía con cada transacción.

5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo sandbox y después desactiva Sandbox mode para aceptar pagos reales.

Al instalarse, el módulo crea el estado de pedido Tpay payment on hold. PrestaShop ofrece un módulo de pago nuevo para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; PLN debe seguir permitido para el módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Tpay Payment > 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 is on: payments go to the Tpay sandbox and no real money is charged. mientras el modo sandbox está activado. También avisa cuando las claves del modo actual están incompletas (entonces Tpay no se muestra en la finalización de compra), cuando la moneda predeterminada de la tienda no es PLN y cuando falta la extensión OpenSSL de PHP con la comprobación JWS activada (los pagos entonces no se confirmarían). Los espacios pegados junto al Merchant ID o al Client ID se eliminan al guardar.

Tpay

Enable/Disable: Enable Tpay payments activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el título 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 guardado en el pedido. Predeterminado: Tpay. Obligatorio.

Description: la descripción del método de pago que ven los clientes en la finalización de compra. Predeterminado: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: usa el sandbox de Tpay (pagos de prueba, sin dinero real) con las claves de Sandbox y openapi.sandbox.tpay.com. Desactívalo para aceptar pagos reales con las claves de Producción. Los reembolsos siempre se envían al entorno en el que se pagó el pedido. Predeterminado: activado.

Production keys

Dónde encontrarlas: en el panel de comerciante de Tpay, en Integration, API (claves de Open API: Client ID y Secret); el Merchant ID es el ID de tu cuenta de Tpay; el código de seguridad está en Settings, Notifications.

Merchant ID: el ID de tu cuenta de Tpay (dígitos). Tpay lo envía en cada notificación.

Client ID: el Open API Client ID.

Client secret: el Open API Client secret.

Security code: se usa para verificar la suma MD5 de las notificaciones de Tpay.

Sandbox keys

El sandbox es una cuenta de prueba de Tpay independiente con sus propias claves (véase la documentación de la API de Tpay). Se usan solo mientras Sandbox mode esté activado.

Sandbox Merchant ID: el Merchant ID de la cuenta de sandbox.

Sandbox Client ID: el Open API Client ID de la cuenta de sandbox.

Sandbox Client secret: el Open API Client secret de la cuenta de sandbox.

Sandbox Security code: el código de seguridad de las notificaciones de la cuenta de sandbox.

Los secretos guardados (Client secret y Security code de ambos entornos) 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 secrets: marca un secreto y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Payment notifications

Notification URL: Tpay confirma los pagos a la dirección que se muestra aquí. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_tpay_payment/notify, posiblemente con un código de idioma como /en/. La dirección se envía automáticamente con cada transacción; no hay que configurar nada en el panel de Tpay salvo el código de seguridad. Un pedido se crea solo después de una notificación con suma de comprobación y firma válidas y un importe correspondiente (o de una comprobación de estado correspondiente cuando el cliente vuelve). Tpay repite una notificación hasta que tu tienda la acepta.

JWS signature: verifica además la X-JWS-Signature de las notificaciones con el certificado de Tpay (recomendado). Requiere la extensión OpenSSL de PHP y acceso HTTPS saliente a secure.tpay.com. Los certificados se guardan en caché durante un día. La suma MD5 siempre se verifica. Predeterminado: activado.

Advanced

Debug log: registra los eventos de pago: solo eventos técnicos (sin claves ni datos del cliente) en logs/wc_tp_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Predeterminado: desactivado. Mientras está desactivado no se escribe nada, tampoco los errores, así que actívalo antes de buscar la causa de un problema.

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 y el registro. Los pedidos y sus datos de pago de Tpay siempre se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Tpay). En modo sandbox, la opción de pago muestra Sandbox mode - no real money is charged. Tras confirmar, el módulo crea una transacción de Tpay por el total del carrito en PLN con la descripción Cart # y el número del carrito, pasa el nombre, el correo electrónico, la dirección de facturación y el teléfono del cliente, y envía al cliente a la página de pago de Tpay. La página se muestra en polaco, inglés o ucraniano, según el idioma de la tienda (los demás idiomas reciben inglés). Allí el cliente elige BLIK, una transferencia bancaria, una tarjeta u otro método habilitado en tu cuenta de Tpay, y paga. En este punto todavía no existe ningún pedido.

El pedido se marca como pagado solo cuando Tpay lo confirma. Tpay envía una notificación a tu tienda; el módulo comprueba la suma MD5 con el código de seguridad, el Merchant ID y (si está activada) la firma JWS, usando las claves del entorno en el que se inició el pago, y después el importe: debe ser igual al importe solicitado para este intento de pago y al total del carrito, y el importe pagado no puede ser inferior. Las notificaciones sin suma o firma válidas se rechazan. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido.

Después de pagar, el cliente vuelve a tu tienda. Volver por sí solo no marca nada como pagado. Si la notificación todavía no ha llegado, el módulo consulta a la API de Tpay el estado de la transacción (como máximo cada 10 segundos) y aplica las mismas comprobaciones. Mientras el pago no esté confirmado, una página de Payment confirmation muestra Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: con un botón Refresh y un botón Pay again que lleva de vuelta a la finalización de compra. La notificación crea el pedido en cuanto llega.

Si Tpay informa de que el pago no se realizó, el cliente vuelve a la finalización de compra con Tpay reports that the payment did not go through. Please try again or choose another payment method. Si el pago falla en la página de Tpay, Tpay envía al cliente de vuelta a la página de finalización de compra. El carrito se conserva en ambos casos. Si el pedido pasó a espera, la página de confirmación muestra Your payment is being verified. We will contact you as soon as it is confirmed.

Cada intento de pago tiene su propia referencia. Cuando el cliente vuelve a pagar, las transacciones de Tpay anteriores sin pagar del carrito se cancelan en Tpay; un pago que ya se realizó a través de un enlace anterior se acepta igualmente. Si el carrito ya tiene un pedido, el cliente va a la página de confirmación de ese pedido en lugar de iniciar un nuevo pago.

Si Tpay no puede iniciar el pago, el cliente se queda en la finalización de compra con The Tpay payment could not be started. Please try again or choose another payment method. y el motivo se escribe en el registro (cuando Debug log está activado).

La dirección de notificación funciona mientras la tienda está en modo de mantenimiento y no se ve afectada por la restricción de países de tu tienda.

El módulo funciona solo en PLN. En la tienda no hay selección de banco ni de código BLIK (el cliente elige en la página de Tpay), ni tarjetas guardadas, ni suscripciones, ni botones de Apple Pay o Google Pay en la tienda, ni calculadoras de cuotas.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a Tpay y no ha pagado, o Tpay todavía no ha confirmado el pago. Solo existe el carrito. Un pago fallido tampoco crea ningún pedido.

Payment accepted: Tpay confirmó el pago. El pago se registra con el título de la transacción de Tpay (TR-...) como ID de transacción. Una nota indica si se confirmó mediante la notificación o mediante la comprobación de estado, el entorno y el importe excedente, si lo hubiera.

Tpay payment on hold: llegó un pago, pero su importe difería del importe solicitado o del total del carrito (por ejemplo, el carrito se cambió después de iniciar el pago), solo se pagó una parte, o el pago llegó después de que el pedido se cancelara. La nota lo explica. Revisa el pago en el panel de Tpay y después completa o reembolsa el pedido. Si el cliente paga después el importe correcto con un nuevo intento, el pedido pasa a Payment accepted.

Refunded: el pago se reembolsó por completo a través del módulo.

Si Tpay informa de otro pago para un pedido que ya está pagado o reembolsado, el pedido no se modifica; una nota te pide que reembolses el pago extra en el panel de Tpay si es necesario. Un contracargo notificado por Tpay añade una nota.

Bloque de pago de Tpay

La página del pedido muestra un bloque Tpay payment con el título y el ID de la transacción de Tpay, la referencia del pago (CRC), el entorno (con una etiqueta Sandbox para los pagos de sandbox), el estado del pago y cómo se confirmó, el importe pagado, el total del pedido y el importe reembolsado, el historial de reembolsos, todos los Payment attempts del carrito y las Payment notes del pedido.

Reembolsos

En el bloque Tpay payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Tpay. Confirma la pregunta Refund this amount through Tpay? This cannot be undone. Se admiten reembolsos totales y parciales de pedidos con un pago recibido a través de Tpay, incluidos los pedidos en espera. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Modules. Puedes reembolsar hasta el importe que cobró la transacción de Tpay que pagó, como máximo el total del pedido: después de un pago parcial o de un carrito modificado, el bloque muestra Refundable (paid through Tpay). El reembolso se envía al entorno (sandbox o producción) en el que se pagó el pedido, así que deben estar configuradas las claves de ese entorno. El reembolso solo cuenta como realizado cuando Tpay lo confirma; un reembolso rechazado o no confirmado por Tpay se muestra como error y no se registra. Un reembolso correcto se añade al historial de reembolsos y a las notas, junto con el motivo que introdujiste (el motivo no se envía a Tpay). Reembolsar todo el importe reembolsable cambia el pedido a Refunded. Un reembolso parcial no cambia el estado.

El módulo no crea facturas rectificativas. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Tpay. Los reembolsos hechos en el panel de comerciante de Tpay no se añaden a PrestaShop automáticamente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Tpay Payment es el primero de la página Modules > Module Manager > VibeFox Tpay 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 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-tpay 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 tras 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Tpay no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda 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 siguen funcionando.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 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

Tpay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que se han introducido las cuatro claves del modo actual (Merchant ID, Client ID, Client secret, Security code). Comprueba que la moneda del carrito es PLN y que el módulo está permitido para PLN, para el país del cliente y para el grupo del cliente en Payment > Preferences. La página de configuración muestra un aviso si faltan claves o si la moneda de la tienda no es PLN.

El pago se realizó, pero no se creó ningún pedido: Tpay no pudo entregar la notificación o esta fue rechazada. Activa Debug log y revisa el campo Log de la página del módulo. Las causas habituales son un código de seguridad o un Merchant ID incorrectos para el entorno del pago, una dirección de notificación bloqueada (cortafuegos, autenticación HTTP) o un servidor sin OpenSSL o sin HTTPS saliente para la comprobación JWS. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.

Notification answered FALSE - invalid checksum: el Merchant ID o el código de seguridad de los ajustes no coinciden con la cuenta de Tpay (sandbox o producción) del pago.

Notification answered FALSE - invalid JWS signature: la firma no se pudo verificar, por ejemplo porque falta OpenSSL o no se puede descargar el certificado de Tpay. Corrige el servidor o, si es necesario, desactiva JWS signature; la suma MD5 se sigue comprobando.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: el carrito estaba siendo procesado por otra petición en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Tpay repite la notificación automáticamente. Activa Debug log para ver el motivo.

La URL de notificación muestra FALSE - POST only in the browser: es normal. La URL solo acepta notificaciones de Tpay.

El pedido está en Tpay payment on hold: lee las notas del bloque Tpay payment (véase Estados del pedido), revisa el pago en el panel de Tpay y después completa el pedido o reembolsa el pago.

El cliente vio The Tpay payment could not be started: las claves del modo actual son incorrectas o Tpay rechazó la petición. Activa Debug log; el registro muestra el error de Tpay.

El cliente vio We could not match this payment to an order: el enlace de retorno no pertenecía al carrito del cliente. Si el cliente pagó, la notificación igualmente crea el pedido; revisa el panel de Tpay.

El reembolso falla: si el mensaje indica que faltan las claves, introduce las claves del entorno en el que se pagó el pedido. Si el mensaje indica que el importe es demasiado alto, solo se puede reembolsar como máximo el importe mostrado. Si Tpay no confirmó el reembolso, revisa la transacción en el panel de comerciante de Tpay antes de volver a intentarlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Tpay Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Los tokens de acceso de Tpay y los certificados guardados en caché siempre se eliminan. Si Delete data on uninstall está activado, también se eliminan los ajustes del módulo y el registro. Si está desactivado, los ajustes se conservan para una futura reinstalación. Las transacciones y reembolsos de Tpay y el estado de pedido Tpay payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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