VibeFox Tap for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

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

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

Acceso a Internet a tu tienda: 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_, y las de producción, por pk_live_ / sk_live_. La clave secreta siempre es necesaria; la clave publicable, solo para la ventana emergente. Los métodos de pago que se ofrecen (mada, KNET, Benefit y otros) y la verificación de dominio de Apple Pay se configuran en tu cuenta de Tap.

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 VibeFox Tap Payments más tarde 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 tus claves de prueba y de producción de Tap, 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).

5. Activa Enable / Disable y haz clic en Save. Prueba con las tarjetas de prueba de Tap y luego desactiva Test mode.

Al instalarse, el módulo crea dos estados de pedido: Tap payment authorized y Tap payment on hold. PrestaShop activa el 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 Tap Payments > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Test mode is on: payments use your Tap test keys and no real money is charged. o Live mode: real payments are accepted. También avisa cuando faltan las claves del modo actual (en ese caso el método de pago no se muestra en la finalización de compra) y cuando la moneda predeterminada de la tienda no está disponible con Tap.

Al guardar, una clave con un prefijo que no corresponde a su campo no se guarda: se mantiene el valor anterior, los demás ajustes sí se guardan y aparece un mensaje como Test secret key was not saved: a Tap key for this field starts with "sk_test_".. Por ejemplo, una clave de producción en un campo de prueba se rechaza. Un Title vacío no se acepta: la página muestra Enter a title for the payment method. y no se guarda nada.

Tap Payments

El título de la sección también muestra TEST o LIVE según el modo actual.

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. También es el nombre del método de pago guardado en el pedido. Por defecto: Tap Payments. Obligatorio.

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_, y las de producción, por pk_live_ / sk_live_.

Test mode: usa las claves de prueba; no se cobra dinero real. Los pagos, las comprobaciones de estado, las capturas y los reembolsos siempre usan las claves del modo en el que se hizo el pago, así que un pago de prueba se sigue comprobando y reembolsando con la clave de prueba aunque hayas cambiado a producción. Por defecto: activado. Mientras esté activado, los clientes ven Test mode: no real payment will be made. debajo del método de pago.

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.

Las claves secretas guardadas 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 cambiar la clave. Las claves publicables son públicas y siguen visibles.

Clear saved secrets: marca una clave secreta y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.

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 Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_tap_payment_gateway/webhook, posiblemente con un código de idioma como /en/. 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 esté bloqueada por un cortafuegos ni por autenticación HTTP). Cada notificación se comprueba con la firma hashstring (HMAC-SHA256 con la clave secreta del modo en el que se hizo el pago). Los webhooks sin una firma válida se rechazan. Ni siquiera una notificación firmada se considera fiable sin más: el módulo vuelve a leer el pago desde la API de Tap antes de crear o cambiar el pedido. Sin un webhook que funcione, el pedido solo se crea cuando el cliente vuelve a la tienda después de pagar.

Avanzado

Debug log: registra los eventos de pago en logs/tap_p_debug.log.php, en la carpeta del módulo. El archivo no se puede leer desde la web. Los errores y las advertencias siempre se registran; activa esta opción para registrar también todos los eventos de pago. El registro nunca contiene claves ni datos de tarjetas o clientes. Por defecto: desactivado.

Log: muestra el tamaño y las entradas más recientes 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 registros de pago de los pedidos se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto, Tap Payments) y confirma el pedido. En este punto todavía no existe ningún pedido.

Tap payment page: el módulo crea un cargo de Tap (o una autorización en el modo Authorize only) por el total del carrito en la moneda del carrito, con la descripción Cart # y el número de carrito, y envía al cliente a la página de pago de Tap. El nombre, el correo electrónico y el teléfono del cliente se envían a Tap. Allí el cliente elige una tarjeta, mada, KNET, Benefit, Apple Pay o Google Pay (según lo que tengas activado en tu cuenta de Tap) y paga. Si Tap no puede iniciar el pago, el cliente se queda en la finalización de compra con The Tap payment could not be started. Please try again or choose another payment method. y el motivo se guarda en el registro.

Tap checkout popup: el cliente va a la página Tap payment del módulo, 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 puede cargarse, se pide al cliente que use la página de pago de Tap. Al recargar la página se reutiliza el mismo intento de pago.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Tap lo confirma: el módulo lee el pago desde la API de Tap con la clave del modo del pago, comprueba que se refiere a este carrito y que lo inició su finalización de compra, y compara el importe y la moneda con los del carrito. El ID de Tap de la dirección de retorno por sí solo nunca crea un pedido. El webhook hace la misma comprobación en segundo plano. Después se crea el pedido y el cliente ve la página estándar de confirmación del pedido. En caso de pago autorizado, la página muestra Your payment has been authorized. We will process the order as soon as the payment is captured.; para un pedido en espera, muestra Your payment is being reviewed. We will contact you if anything else is needed.

Si Tap todavía no ha confirmado el pago cuando el cliente vuelve, aparece una página Payment confirmation con el texto 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. y los botones Check again y Back to checkout. El webhook crea el pedido en cuanto llega.

Si el pago fue rechazado, abandonado o cancelado, no se crea ningún pedido. El cliente vuelve a la finalización de compra con 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 or choose another payment method. El carrito se conserva y puede volver a pagarse.

Otros mensajes en la finalización de compra: Tap does not accept payments in seguido de la moneda, cuando la moneda del carrito no es compatible, y The order total must be greater than zero to pay with Tap.

El webhook funciona aunque la tienda esté en modo de mantenimiento y no se ve afectado por la restricción por país de tu tienda.

El módulo no tiene tarjetas guardadas ni tokenización, ni suscripciones, ni campos de tarjeta integrados en la 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

Sin pedido todavía: el cliente fue enviado a Tap y no ha pagado, o Tap todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: Tap confirmó un pago capturado. El pago se registra con el ID del cargo de Tap (chg_...) como ID de transacción, y una nota muestra el importe, el ID del cargo, el método de pago y, en modo de prueba, que se trata de un pago de prueba.

Tap payment authorized: el pago solo fue autorizado y espera captura o anulación.

Tap payment on hold: el importe o la moneda pagados no coincidían con el carrito (Tap: amount/currency mismatch — manual review required.), o el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Revisa el pedido y procésalo, o reembolsa el pago.

Canceled: la autorización se anuló con Void Tap authorization, así que los fondos reservados se liberaron.

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

Un intento fallido nunca cambia un pedido pagado, autorizado o cancelado. Si llega un segundo pago correcto para un pedido que ya está pagado, el pedido no se modifica. Una nota indica que es un pago duplicado y te pide reembolsarlo en el panel de Tap. Un pago que hace referencia al carrito pero que no lo inició su finalización de compra solo se anota.

Bloque de pago de Tap

La página del pedido muestra un bloque Tap payment con el ID de Tap, la autorización y el cargo, el modo (una insignia Test mode para los pagos de prueba), el estado y el método de pago, Charged / refunded, el historial de reembolsos, los intentos de pago del carrito y las Payment notes del pedido. Los botones del bloque funcionan en la propia página del pedido; necesitas el permiso para editar pedidos, no acceso a la configuración del módulo.

Captura y anulación

En el modo Authorize only, abre el pedido en estado Tap payment authorized. Capture Tap payment (con el total del pedido en el botón) captura el total del pedido tras la pregunta Capture the reserved funds of this order through Tap?; a continuación, el pedido pasa a Payment accepted. Void Tap authorization muestra Release the reserved funds? The order will be canceled., libera los fondos y pone el pedido en Canceled. Si Tap rechaza la acción, se muestra un error en el bloque y se añade a las notas. 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

En el bloque Tap payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Tap. Confirma la pregunta Refund this amount through Tap? This cannot be undone. Se admiten reembolsos totales y parciales de cargos de Tap capturados. Puedes reembolsar hasta el importe y la moneda que Tap cobró realmente, aunque el pedido se haya editado después. El reembolso se envía con la clave secreta del modo en el que se hizo el pago, por lo que esa clave debe estar configurada. Un reembolso aceptado por Tap se añade al historial de reembolsos y a las notas con el ID y el estado del reembolso de Tap. Si Tap lo rechaza, el bloque muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. En un pedido autorizado, los reembolsos están disponibles una vez capturada la autorización. Un pedido en espera tras una diferencia de importe o de moneda se reembolsa en el panel de Tap.

El módulo no genera 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 Tap. Los reembolsos hechos en el panel de Tap no aparecen en PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Tap Payments es el primero de la página Modules > Module Manager > VibeFox Tap Payments > 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-tap 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, Tap Payments 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, la captura y la anulación 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

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 tiene una clave secreta (y una clave publicable cuando Checkout type es la ventana emergente). Comprueba que la moneda del carrito es una de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR o USD. 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. La página de ajustes muestra una advertencia por las claves que faltan y por una moneda de tienda no compatible.

El pago se realizó, pero no se creó ningún pedido: el webhook no puede llegar a tu tienda. Comprueba que la URL que aparece en Webhook URL es accesible desde Internet (sin cortafuegos ni autenticación HTTP) y activa Debug log para ver las respuestas en el campo Log. El pedido también se crea cuando el cliente vuelve desde Tap.

Webhook answers invalid signature: la notificación no se firmó con la clave secreta del modo del pago. Comprueba 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 reintenta el webhook más tarde.

Webhook answers order not found: la notificación nombra un carrito que no tiene ningún intento de pago de Tap en esta tienda.

Webhook answers busy, retry later or order could not be updated, retry later: otra petición estaba confirmando el pedido en ese mismo momento, o el pedido no se pudo crear (por ejemplo, porque el módulo está desactivado). Tap reintenta el webhook. Consulta el campo Log para ver el motivo.

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

El cliente ve The Tap payment could not be started: consulta el campo Log de la página del módulo. Allí se registra una clave incorrecta o una petición rechazada.

El cliente ve We could not match this payment to an order: el pago no pertenece a este carrito o no lo inició su finalización de compra. Si se cobró dinero, comprueba el pago en el panel de Tap.

El pedido está en Tap payment on hold: lee las notas del bloque Tap payment. El importe o la moneda pagados no coincidían con el carrito, o el pago llegó después de que el pedido se hubiera cancelado.

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 el bloque dice que no se encontró ningún cargo de Tap capturado, reembolsa el pago en el panel de Tap.

Hooks para desarrolladores: los hooks actionWcpTapChargePayload, actionWcpTapSupportedCurrencies y actionWcpTapCurrencyDecimals permiten a un desarrollador modificar la petición de pago, las monedas admitidas y los decimales de cada moneda.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Tap Payments 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. Los intentos y reembolsos de pago de Tap y los estados de pedido Tap payment authorized y Tap 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 ID de transacción.

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