VibeFox Tap for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension ne s'active pas sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR ou USD. Pour les autres devises, le moyen de paiement est masqué sur la page de paiement.

Accès Internet à votre site : Tap envoie le résultat du paiement à un webhook de votre boutique ; le site doit donc être joignable depuis Internet. L'URL du webhook est envoyée avec chaque paiement ; rien n'est à configurer dans le tableau de bord Tap.

Compte Tap : vous avez besoin des clés API de votre tableau de bord Tap (goSell, identifiants API). Les clés de test commencent par pk_test_ / sk_test_, les clés de production par pk_live_ / sk_live_. La clé secrète est toujours nécessaire ; la clé publique uniquement pour la fenêtre Tap Checkout. Les moyens de paiement proposés (mada, KNET, Benefit et d'autres) et la vérification du domaine Apple Pay se configurent dans votre compte Tap.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_tap_payment_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Tap Payments > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez vos clés Tap de test et de production, puis choisissez l'action de paiement, le type de paiement et la langue de la page Tap (voir Configuration).

6. Activez Enable / Disable et enregistrez. Testez avec les cartes de test Tap, puis décochez Test mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Tap Payments. Au-dessus des champs, la page affiche Test mode is on: payments use your Tap test keys and no real money is charged. tant que le mode test est activé. Elle indique aussi lorsque les clés du mode actuel manquent (la passerelle n'apparaît alors pas au paiement) et lorsque la devise de la boutique n'est pas proposée avec Tap. Dans la liste des moyens de paiement, Tap Payments est signalé comme nécessitant une configuration tant que le mode actuel ne dispose pas d'une clé secrète (et, pour la fenêtre, d'une clé publique).

À l'enregistrement, une clé dont le préfixe ne correspond pas à son champ n'est pas enregistrée : un message d'erreur s'affiche et la valeur précédente est conservée. Par exemple, une clé de production saisie dans un champ de test est refusée.

Général

Enable / Disable : Enable Tap Payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement affiché au paiement. Par défaut : Tap Payments.

Description : le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Clés API Tap

Retrouvez vos clés dans le tableau de bord Tap (goSell, identifiants API). Les clés de test commencent par pk_test_ / sk_test_, les clés de production par pk_live_ / sk_live_.

Test mode : Use the test keys (no real money is charged). Les paiements, les vérifications de statut et les remboursements utilisent toujours les clés du mode dans lequel le paiement a été effectué ; ainsi, un paiement de test continue d'être vérifié et remboursé avec la clé de test même après le passage en production. Par défaut : activé.

Test publishable key : commence par pk_test_. Nécessaire pour la fenêtre.

Test secret key : commence par sk_test_.

Live publishable key : commence par pk_live_. Nécessaire pour la fenêtre.

Live secret key : commence par sk_live_.

Merchant ID : facultatif. Votre identifiant de marchand Tap ; nécessaire uniquement si Tap vous a demandé d'acheminer les paiements vers un compte marchand précis.

Paiement

Payment action : ce qui se passe avec l'argent lorsque le client paie.

Checkout type : l'endroit où le client paie.

Tap page language : English (par défaut) ou Arabic.

Notifications de paiement (webhook)

Tap envoie le résultat du paiement à l'URL affichée dans cette section. Elle ressemble à https://your-site/wc-api/tap_p_webhook/. L'URL est envoyée avec chaque paiement ; rien n'est donc à configurer dans le tableau de bord Tap. Vérifiez seulement qu'elle est joignable depuis Internet (non bloquée par un pare-feu, le mode maintenance ou une authentification HTTP). Chaque notification est vérifiée par la signature hashstring (HMAC-SHA256 avec la clé secrète du mode du paiement). Les webhooks sans signature valide sont rejetés. Même une notification signée n'est pas considérée comme fiable en soi : l'extension relit le paiement depuis l'API Tap avant de modifier la commande. Sans webhook fonctionnel, la commande n'est mise à jour que lorsque le client revient à la boutique après avoir payé.

Avancé

Debug log : Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Les erreurs sont toujours journalisées. Le journal ne contient jamais de clés, de données de carte ou de données client. Par défaut : désactivé.

Delete data on uninstall : Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Tap Payments) et passe la commande. En mode test, la page de paiement affiche Test mode: no real payment will be made.

Tap payment page : l'extension crée un débit Tap (ou une autorisation en mode Authorize only) pour le total de la commande dans la devise de la commande, avec la description Order # suivie du numéro de commande, puis envoie le client sur la page de paiement Tap. Il y choisit une carte, mada, KNET, Benefit, Apple Pay ou Google Pay (selon les moyens activés dans votre compte Tap) et paie. Si Tap ne peut pas démarrer le paiement, le client voit The Tap payment could not be started. Please try again or choose another payment method., et la raison est ajoutée aux notes de commande.

Tap checkout popup : le client accède à la page de paiement de la commande, où s'ouvre le formulaire de paiement Tap. La page affiche aussi le lien Pay on the Tap payment page instead. Si la fenêtre est fermée, le bouton Pay now la rouvre. Si le formulaire ne peut pas se charger, le client est invité à utiliser la page de paiement Tap.

Après le paiement, le client revient sur la page de confirmation de commande. La commande n'est marquée payée qu'après confirmation de Tap : l'extension relit le paiement depuis l'API Tap avec la clé du mode du paiement, vérifie qu'il se rapporte à cette commande et qu'il a été lancé par son paiement, puis compare le montant et la devise à ceux de la commande. L'identifiant Tap présent dans l'adresse de retour ne marque jamais une commande comme payée à lui seul. Le webhook effectue la même vérification en arrière-plan. Les webhooks et les retours répétés ne modifient jamais une commande deux fois (une seule modification à la fois par commande).

Si le paiement n'est pas encore confirmé, la page de confirmation affiche 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. Pour un paiement autorisé, elle affiche Your payment has been authorized. We will process the order as soon as the payment is captured.

Si le paiement a été refusé ou abandonné, la commande passe au statut Échoué et le client revient à la page Pay for order avec le message Your payment was not completed. Please try again or choose another payment method. (avec la raison donnée par Tap, lorsqu'elle est fournie). Un paiement inachevé affiche The payment was not completed. You can try again below. Le client peut payer à nouveau la commande depuis cette page.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne gère ni cartes enregistrées ni tokenisation, ni abonnements, ni champs de carte intégrés à votre page de paiement. Capture Tap payment capture toujours le total de la commande ; la capture partielle n'est pas prise en charge.

Commandes et remboursements

Statuts de commande

Pending payment : le client a été envoyé vers Tap et n'a pas encore payé, ou Tap n'a pas encore confirmé le paiement.

Processing : Tap a confirmé un paiement capturé. C'est le statut WooCommerce standard après paiement (les commandes ne contenant que des produits virtuels téléchargeables passent à Terminée). La note de commande indique le montant, l'identifiant de débit Tap (chg_...), le moyen de paiement et, en mode test, la mention de paiement de test. L'identifiant de transaction est l'identifiant de débit Tap.

On hold : le paiement a seulement été autorisé et attend sa capture ; ou le montant ou la devise payé(e) ne correspondait pas à la commande (Tap: amount/currency mismatch — manual review required.) ; ou un paiement est arrivé après l'annulation de la commande. La note de commande l'explique.

Failed : le paiement a été refusé, abandonné, annulé ou a expiré. Seule une commande qui attend encore le paiement passe au statut Échoué ; une tentative échouée ne modifie jamais une commande payée, autorisée ou annulée. Le client peut payer à nouveau.

Cancelled : l'autorisation a été annulée avec Void Tap authorization, de sorte que les fonds réservés ont été libérés.

Si un second paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée à nouveau. Une note indique qu'il s'agit d'un paiement en double et vous demande de le rembourser dans le tableau de bord Tap. Un paiement qui se rapporte à la commande mais qui n'a pas été lancé par son paiement est seulement noté.

Capture et annulation

En mode Authorize only, ouvrez la commande en attente et choisissez dans Order actions : Capture Tap payment capture le total de la commande ; la commande passe alors à payée. Void Tap authorization libère les fonds et annule la commande. Si Tap refuse l'action, une erreur s'affiche et est ajoutée aux notes de commande. Si une autorisation est capturée directement dans le tableau de bord Tap, le webhook marque la commande comme payée ; les remboursements de ce paiement doivent être effectués dans le tableau de bord Tap.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Tap Payments (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge pour les débits Tap capturés. Le remboursement est envoyé avec la clé secrète du mode dans lequel le paiement a été effectué ; cette clé doit donc être renseignée. Un remboursement accepté par Tap est ajouté aux notes de commande avec l'identifiant et le statut du remboursement Tap. Si Tap le refuse, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Les remboursements effectués dans le tableau de bord Tap n'apparaissent pas dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Tap Payments. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas l'emplacement de domaine correspondant. Libérez-le dans votre compte vibefox.net.

Sans clé active, Tap Payments n'est pas affiché aux clients au paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les remboursements, la capture et l'annulation fonctionnent.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Tap Payments n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel dispose d'une clé secrète (et d'une clé publique lorsque Checkout type est la fenêtre). Vérifiez que la devise de la boutique (ou la devise de la commande sur la page Pay for order) fait partie de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. La page des réglages affiche un avis pour chacun de ces problèmes.

Le paiement a abouti, mais la commande reste en Pending payment : le webhook ne peut pas atteindre votre site. Vérifiez que l'URL affichée dans les réglages (/wc-api/tap_p_webhook/) est joignable depuis Internet (pas de pare-feu, de mode maintenance ni d'authentification HTTP), puis consultez WooCommerce > Status > Logs, source wcp_tap_payment_gateway. La commande est aussi mise à jour lorsque le client revient de Tap.

Webhook answers invalid signature : la notification n'a pas été signée avec la clé secrète du mode du paiement. Vérifiez les clés secrètes dans les réglages.

Webhook answers gateway not configured : la clé secrète du mode du paiement (test ou production) est vide. Saisissez-la.

Webhook answers verification failed : l'API Tap n'a pas pu être jointe pour vérifier le paiement. Tap relance le webhook plus tard.

Une clé n'est pas enregistrée : la clé doit commencer par le préfixe de son champ : pk_test_, sk_test_, pk_live_ ou sk_live_.

La commande est On hold : lisez la note de commande. Le paiement a seulement été autorisé (capturez-le depuis les actions de commande), le montant ou la devise payé ne correspondait pas à la commande, ou le paiement est arrivé après l'annulation de la commande.

Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode test ou production, et aucune clé secrète n'est configurée pour ce mode. Saisissez-la et réessayez. Si la note indique qu'aucun débit Tap capturé n'a été trouvé, remboursez le paiement dans le tableau de bord Tap.

Hooks pour développeurs : les filtres tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url et tap_p_payment_page_hosts sont disponibles.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les autres options de l'extension et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs identifiants Tap et leurs identifiants de transaction.

Tap Payments est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Tap Payments ni approuvée par Tap Payments.