VibeFox Tpay for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior. La extensión OpenSSL y el acceso HTTPS saliente a secure.tpay.com son necesarios para la comprobación de la firma JWS de las notificaciones.

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

Acceso a Internet a tu sitio: 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 el modo de mantenimiento, un cortafuegos o la 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 la 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 WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_tpay_payment a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Tpay > Manage, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Introduce las claves de Sandbox y las 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.

6. Activa Enable/Disable, prueba un pago en modo sandbox y después desmarca Sandbox mode para aceptar pagos reales.

Configuración

Todos los ajustes están en una misma página: WooCommerce > Settings > Payments > Tpay. 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. Avisa cuando las claves del modo actual están incompletas (en ese caso Tpay no aparece en la finalización de compra), cuando la moneda de la tienda no es PLN y cuando falta la extensión OpenSSL de PHP mientras la comprobación JWS está activada (los pagos no se confirmarían). En la lista de métodos de pago, Tpay aparece como pendiente de configuración hasta que se introducen las claves del modo actual. Los espacios pegados junto al Merchant ID o al Client ID se eliminan al guardar.

General

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

Title: el título del método de pago que ven los clientes en la finalización de compra. Por defecto: Tpay.

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

Sandbox mode: Use the Tpay sandbox (test payments, no real money). El modo sandbox usa las claves de Sandbox y la API de sandbox de Tpay. 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. Por defecto: activado.

Claves de producción

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 de comprobación MD5 de las notificaciones de Tpay.

Claves de sandbox

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.

Notificaciones de pago

Tpay confirma los pagos a la dirección que aparece en esta sección. Tiene este aspecto: https://your-site/wc-api/wc_tp_payment/. 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 solo se marca como pagado tras una notificación con suma de comprobación y firma válidas y con un importe coincidente. Tpay repite una notificación hasta que tu tienda la acepta.

JWS signature: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Requiere la extensión OpenSSL de PHP y acceso HTTPS saliente a secure.tpay.com. La suma MD5 siempre se verifica. Por defecto: activado.

Avanzado

Debug log: Log payment events. Solo eventos técnicos (sin claves ni datos de clientes) en WooCommerce > Status > Logs, origen wcp_tpay_payment. Por defecto: desactivado.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Desactivar el plugin nunca elimina nada. Los pedidos y sus datos de pago de Tpay siempre se conservan. Por defecto: desactivado.

Los ajustes de la versión 1.0 se trasladan automáticamente: las claves usadas con el modo de prueba activado pasan a ser las claves de Sandbox.

Finalización de compra

El cliente elige el método de pago (por defecto Tpay) y realiza el pedido. En modo sandbox, la finalización de compra muestra Sandbox mode — no real money is charged. El plugin crea una transacción de Tpay por el total del pedido en PLN con la descripción Order # y el número de pedido, pasa el nombre, el correo electrónico, la dirección y el teléfono del cliente, y redirige 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 del sitio (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.

El pedido se marca como pagado solo cuando Tpay lo confirma. Tpay envía una notificación a tu tienda; el plugin comprueba la suma MD5 con el código de seguridad, el Merchant ID y (si está activada) la firma JWS, y luego el importe: debe ser igual al solicitado para este intento de pago y al total del pedido, y el importe pagado no puede ser inferior. Las notificaciones sin suma de comprobación o firma válidas se rechazan.

Tras pagar, el cliente vuelve a la página de pedido recibido. Volver por sí solo no marca el pedido como pagado. Si la notificación todavía no ha llegado, la página 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, la página 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 enlace Pay again. Cuando Tpay informa de un pago fallido, la página muestra Tpay reports that the payment did not go through. You can try again: con el mismo enlace. Si el pago falla en la página de Tpay, Tpay devuelve al cliente a la página Pay for order del mismo pedido.

Cada intento de pago tiene su propia referencia. Cuando el cliente vuelve a pagar, las transacciones de Tpay anteriores no pagadas del pedido se cancelan en Tpay; un pago que ya se completó con un enlace anterior se sigue aceptando. La misma cancelación se produce cuando se cancela un pedido no pagado, por ejemplo por el tiempo de espera de reserva de stock de WooCommerce.

Si Tpay no puede iniciar el pago, el cliente ve The Tpay payment could not be started. Please try again or choose another payment method. y el motivo se escribe en el registro.

El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

El plugin funciona solo en PLN. No hay selección de banco ni de código BLIK en la tienda (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

Pending payment: se creó la transacción de Tpay y el pago aún no está confirmado. La nota del pedido muestra la transacción de Tpay y el entorno.

Processing: Tpay confirmó el pago. Es el estado estándar de WooCommerce tras el pago (los pedidos con solo productos descargables virtuales pasan a Completado). La nota indica si el pago fue confirmado por la notificación o por la comprobación de estado, y muestra cualquier pago excedente. El ID de la transacción es el título de la transacción de Tpay (TR-...).

On hold: llegó un pago, pero su importe difería del solicitado o del total del pedido, solo se pagó una parte, o el pedido se había cancelado. La nota del pedido lo explica. Revisa el pago en el panel de Tpay y completa o reembolsa el pedido.

Failed: Tpay informó de que el pago falló. Solo un pedido pendiente de pago pasa a Fallido. El cliente puede volver a pagar.

Si Tpay informa de otro pago para un pedido que ya está pagado o reembolsado, el pedido no cambia; 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.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Tpay (el botón muestra tu Title). Se admiten reembolsos totales y parciales de pedidos con un pago recibido a través de Tpay; en los pedidos no pagados el botón no aparece. 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 se considera hecho solo cuando Tpay lo confirma; un reembolso rechazado o no confirmado por Tpay se muestra como error y no se registra en WooCommerce. Un reembolso correcto se añade a las notas del pedido, junto con el motivo que hayas introducido (el motivo no se envía a Tpay).

Los reembolsos hechos en el panel de comerciante de Tpay no se añaden automáticamente a WooCommerce.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Tpay. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Tpay 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. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

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 de la tienda (o la moneda del pedido en la página Pay for order) es PLN. La página de ajustes muestra un aviso por cada uno de estos problemas.

El pago se realizó, pero el pedido sigue en Pending payment: Tpay no pudo entregar la notificación o fue rechazada. Activa Debug log y revisa WooCommerce > Status > Logs, origen wcp_tpay_payment. Las causas habituales son un código de seguridad o un Merchant ID incorrectos para el modo actual, una dirección de notificación bloqueada (modo de mantenimiento, cortafuegos, autenticación HTTP) o un servidor sin OpenSSL o sin HTTPS saliente para la comprobación JWS. La página de pedido recibido también comprueba el estado cuando el cliente vuelve.

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: no se pudo verificar la firma, 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.

El pedido está On hold: lee la nota del pedido. El importe pagado no coincidía con el pedido, o el pago llegó para un pedido cancelado. Revisa el pago en el panel de Tpay y completa o reembolsa el pedido.

El cliente vio el mensaje The Tpay payment could not be started: las claves del modo actual son incorrectas o Tpay rechazó la solicitud. El registro muestra el error 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 Tpay no confirmó el reembolso, revisa la transacción en el panel de comerciante de Tpay antes de volver a intentarlo.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan, al igual que los tokens de acceso de Tpay y los certificados en caché. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los datos de transacción de Tpay y los ID de transacción.

Tpay es una marca comercial de su respectivo titular. Este plugin no está afiliado ni respaldado por Tpay.