VibeFox Tap for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

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

PHP: 8.0 o posterior.

Moneda de la tienda: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR o USD. Para otras monedas, el método de pago se oculta en la finalización de compra.

Acceso a Internet a tu sitio: Tap envía el resultado del pago a un webhook de tu tienda, así que el sitio debe ser accesible desde Internet. La URL del webhook se envía con cada pago; no hay que configurar nada en el panel de Tap.

Cuenta de Tap: necesitas las claves de API de tu panel de Tap (goSell, credenciales de API). Las claves de prueba empiezan por pk_test_ / sk_test_, las de producción por pk_live_ / sk_live_. La clave secreta siempre es necesaria; la clave publicable, solo para la ventana emergente de Tap Checkout. Los métodos de pago que se ofrecen (mada, KNET, Benefit y otros) y la verificación del dominio de Apple Pay se configuran en tu cuenta de Tap.

Licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_tap_payment_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Tap Payments > Manage, o haz clic en Settings debajo del nombre del plugin en la página 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 tus claves de prueba y de producción de Tap, y elige la acción de pago, el tipo de finalización de compra y el idioma de la página de Tap (consulta Configuración).

6. Activa Enable / Disable y guarda. Haz una prueba con las tarjetas de prueba de Tap y, después, desmarca Test mode.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Tap Payments. Encima de los campos, la página muestra Test mode is on: payments use your Tap test keys and no real money is charged. mientras el modo de prueba está activado. También indica cuándo faltan las claves del modo actual (entonces la pasarela no se muestra en la finalización de compra) y cuándo la moneda de la tienda no la admite Tap. En la lista de métodos de pago, Tap Payments aparece como pendiente de configuración hasta que el modo actual tenga una clave secreta (y, para la ventana emergente, una clave publicable).

Al guardar, una clave con un prefijo que no corresponde a su campo no se guarda: aparece un error y se mantiene el valor anterior. Por ejemplo, una clave de producción en un campo de prueba se rechaza.

General

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

Title: el nombre del método de pago que se muestra en la finalización de compra. Por defecto: Tap Payments.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Claves de API de Tap

Encuentra tus claves en el panel de Tap (goSell, credenciales de API). Las claves de prueba empiezan por pk_test_ / sk_test_, las de producción por pk_live_ / sk_live_.

Test mode: Use the test keys (no real money is charged). Los pagos, las comprobaciones de estado y los reembolsos siempre usan las claves del modo en el que se hizo el pago; así, un pago de prueba se sigue comprobando y reembolsando con la clave de prueba aunque cambies a producción. Por defecto: activado.

Test publishable key: empieza por pk_test_. Necesaria para la ventana emergente.

Test secret key: empieza por sk_test_.

Live publishable key: empieza por pk_live_. Necesaria para la ventana emergente.

Live secret key: empieza por sk_live_.

Merchant ID: opcional. Tu ID de comerciante de Tap; solo es necesario si Tap te pidió dirigir los pagos a una cuenta de comerciante concreta.

Pago

Payment action: qué ocurre con el dinero cuando el cliente paga.

Checkout type: dónde paga el cliente.

Tap page language: English (por defecto) o Arabic.

Notificaciones de pago (webhook)

Tap envía el resultado del pago a la URL que aparece en esta sección. Tiene este formato: https://your-site/wc-api/tap_p_webhook/. La URL se envía con cada pago, así que no hay que configurar nada en el panel de Tap. Solo asegúrate de que sea accesible desde Internet (que no la bloquee un cortafuegos, el modo de mantenimiento ni la autenticación HTTP). Cada notificación se verifica con la firma hashstring (HMAC-SHA256 con la clave secreta del modo del pago). Los webhooks sin una firma válida se rechazan. Ni siquiera una notificación firmada se considera fiable: el plugin vuelve a leer el pago desde la API de Tap antes de cambiar el pedido. Sin un webhook que funcione, el pedido solo se actualiza cuando el cliente vuelve a la tienda después de pagar.

Avanzado

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Los errores siempre se registran. El registro nunca contiene claves ni datos de la tarjeta o del cliente. Por defecto: desactivado.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). Por defecto: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto Tap Payments) y realiza el pedido. En modo de prueba, la finalización de compra muestra Test mode: no real payment will be made.

Tap payment page: el plugin crea un cargo de Tap (o una autorización en el modo Authorize only) por el total del pedido en la moneda del pedido, con la descripción Order # y el número del pedido, y envía al cliente a la página de pago de Tap. Allí el cliente elige una tarjeta, mada, KNET, Benefit, Apple Pay o Google Pay (según lo activado en tu cuenta de Tap) y paga. Si Tap no puede iniciar el pago, el cliente ve The Tap payment could not be started. Please try again or choose another payment method. y el motivo se añade a las notas del pedido.

Tap checkout popup: el cliente va a la página de pago del pedido, donde se abre el formulario de pago de Tap. La página también muestra el enlace Pay on the Tap payment page instead. Si se cierra la ventana, el botón Pay now la vuelve a abrir. Si el formulario no se puede cargar, se pide al cliente que use la página de pago de Tap.

Después de pagar, el cliente vuelve a la página de pedido recibido. El pedido se marca como pagado solo cuando Tap lo confirma: el plugin lee el pago desde la API de Tap con la clave del modo del pago, comprueba que se refiere a este pedido y que lo inició su finalización de compra, y compara el importe y la moneda con los del pedido. El ID de Tap en la dirección de regreso, por sí solo, nunca marca un pedido como pagado. El webhook hace la misma comprobación en segundo plano. Los webhooks y los regresos repetidos nunca cambian el pedido dos veces (un cambio a la vez por pedido).

Si el pago todavía no está confirmado, la página de pedido recibido muestra We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. En un pago autorizado muestra Your payment has been authorized. We will process the order as soon as the payment is captured.

Si el pago fue rechazado o abandonado, el pedido se marca como Fallido y el cliente vuelve a la página Pay for order con el mensaje Your payment was not completed. Please try again or choose another payment method. (con el motivo de Tap cuando Tap lo indica). Un pago sin terminar muestra The payment was not completed. You can try again below. El cliente puede volver a pagar el pedido desde esa página.

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 no tiene tarjetas guardadas ni tokenización, ni suscripciones, ni campos de tarjeta integrados en tu página de finalización de compra. Capture Tap payment siempre captura el total del pedido; la captura parcial no es compatible.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a Tap y aún no ha pagado, o Tap todavía no ha confirmado el pago.

Processing: Tap confirmó un pago capturado. Es el estado estándar de WooCommerce tras el pago (los pedidos con solo productos descargables virtuales pasan a Completado). La nota del pedido muestra el importe, el ID del cargo de Tap (chg_...), el método de pago y, en modo de prueba, que el pago es de prueba. El ID de transacción es el ID del cargo de Tap.

On hold: el pago solo se autorizó y espera la captura; o el importe o la moneda pagados no coincidían con el pedido (Tap: amount/currency mismatch — manual review required.); o llegó un pago después de que el pedido se cancelara. La nota del pedido lo explica.

Failed: el pago fue rechazado, abandonado, cancelado o caducó. Solo un pedido que aún espera el pago se marca como Fallido; un intento fallido nunca cambia un pedido pagado, autorizado o cancelado. El cliente puede volver a pagar.

Cancelled: la autorización se anuló con Void Tap authorization, por lo que los fondos reservados se liberaron.

Si llega un segundo pago correcto para un pedido que ya está pagado, el pedido no se vuelve a cambiar. Una nota indica que es un pago duplicado y pide reembolsarlo en el panel de Tap. Un pago que se refiere al pedido pero que no lo inició su finalización de compra solo se anota.

Captura y anulación

En el modo Authorize only, abre el pedido en espera y elige en Order actions: Capture Tap payment captura el total del pedido; el pedido pasa entonces a pagado. Void Tap authorization libera los fondos y cancela el pedido. Si Tap rechaza la acción, se muestra un error y se añade a las notas del pedido. Si una autorización se captura directamente en el panel de Tap, el webhook marca el pedido como pagado; los reembolsos de ese pago deben hacerse en el panel de Tap.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Tap Payments (el botón muestra tu Title). Se admiten reembolsos totales y parciales de cargos de Tap capturados. El reembolso se envía con la clave secreta del modo en el que se hizo el pago, así que esa clave debe estar configurada. Un reembolso aceptado por Tap se añade a las notas del pedido con el ID y el estado del reembolso de Tap. Si Tap lo rechaza, WooCommerce muestra el error y no se registra ningún reembolso. Los reembolsos hechos en el panel de Tap no aparecen en 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 > Tap Payments. 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 solo 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, Tap Payments no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, 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 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, la captura y la anulación funcionan.

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

Solución de problemas

Tap Payments no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado y que el modo actual tenga una clave secreta (y una clave publicable cuando Checkout type sea la ventana emergente). Comprueba que la moneda de la tienda (o la moneda del pedido en la página Pay for order) sea una de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR o USD. La página de ajustes muestra un aviso para cada uno de estos problemas.

El pago se realizó, pero el pedido sigue en Pending payment: el webhook no puede llegar a tu sitio. Comprueba que la URL que aparece en los ajustes (/wc-api/tap_p_webhook/) sea accesible desde Internet (sin cortafuegos, modo de mantenimiento ni autenticación HTTP) y revisa WooCommerce > Status > Logs, origen wcp_tap_payment_gateway. El pedido también se actualiza cuando el cliente vuelve desde Tap.

Webhook answers invalid signature: la notificación no se firmó con la clave secreta del modo del pago. Revisa las claves secretas en los ajustes.

Webhook answers gateway not configured: la clave secreta del modo del pago (prueba o producción) está vacía. Introdúcela.

Webhook answers verification failed: no se pudo contactar con la API de Tap para comprobar el pago. Tap vuelve a intentar el webhook más tarde.

Una clave no se guarda: la clave debe empezar por el prefijo de su campo: pk_test_, sk_test_, pk_live_ o sk_live_.

El pedido está On hold: lee la nota del pedido. El pago solo se autorizó (captúralo desde las acciones del pedido), el importe o la moneda pagados no coincidían con el pedido, o el pago llegó después de que el pedido se cancelara.

El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o de producción, y no hay ninguna clave secreta configurada para ese modo. Introdúcela e inténtalo de nuevo. Si la nota dice que no se encontró ningún cargo de Tap capturado, reembolsa el pago en el panel de Tap.

Hooks para desarrolladores: están disponibles los filtros tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url y tap_p_payment_page_hosts.

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 en el nuevo dominio. Si el servidor de licencias no responde, 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. Los ajustes de la pasarela, las demás opciones del plugin 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 ID de Tap y los ID de transacción.

Tap Payments es una marca comercial de su respectivo titular. Este plugin no está afiliado ni cuenta con el respaldo de Tap Payments.