VibeFox Tap for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise de la boutique : AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR ou USD. Pour les paniers dans d'autres devises, le moyen de paiement n'est pas proposé dans le tunnel de commande.

Accès à Internet pour votre boutique : Tap envoie le résultat du paiement à un webhook de votre boutique ; le site doit donc être accessible depuis Internet. L'URL du webhook est envoyée avec chaque paiement ; rien ne doit être configuré 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 autres) et la vérification de 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 le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Tap Payments dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, et cliquez sur Activate (voir Clé de licence).

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

5. Activez Enable / Disable et cliquez sur Save. Testez avec les cartes de test Tap, puis désactivez Test mode.

À l'installation, le module crée deux statuts de commande : Tap payment authorized et Tap payment on hold. PrestaShop active un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez le limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Tap Payments > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Test mode is on: payments use your Tap test keys and no real money is charged. ou Live mode: real payments are accepted. Elle vous avertit aussi lorsque les clés du mode actuel sont absentes (le moyen de paiement n'est alors pas affiché dans le tunnel de commande) et lorsque la devise par défaut de la boutique n'est pas proposée avec Tap.

Lors de l'enregistrement, une clé dont le préfixe ne correspond pas à son champ n'est pas enregistrée : l'ancienne valeur est conservée, les autres réglages sont enregistrés et un message tel que Test secret key was not saved: a Tap key for this field starts with "sk_test_". s'affiche. Par exemple, une clé de production dans un champ de test est refusée. Un Title vide n'est pas accepté : la page affiche Enter a title for the payment method. et rien n'est enregistré.

Tap Payments

Le titre de la section affiche aussi TEST ou LIVE pour le mode actuel.

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é dans le tunnel de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Tap Payments. Obligatoire.

Description : le texte affiché sous le moyen de paiement dans le tunnel de commande. 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 : utilise les clés de test ; aucun argent réel n'est débité. Les paiements, les vérifications de statut, les captures et les remboursements utilisent toujours les clés du mode dans lequel le paiement a été effectué : un paiement de test continue donc d'être vérifié et remboursé avec la clé de test, même après le passage en production. Par défaut : activé. Tant qu'il est activé, les clients voient Test mode: no real payment will be made. sous le moyen de paiement.

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.

Les clés secrètes enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la modifier. Les clés publiques ne sont pas secrètes et restent visibles.

Clear saved secrets : cochez une clé secrète et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Payment action : ce qui arrive à 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 Webhook URL, dans cette section. Avec des URL réécrites, elle ressemble à https://your-shop/module/wcp_tap_payment_gateway/webhook, éventuellement avec un code de langue tel que /en/. L'URL est envoyée avec chaque paiement : rien n'est donc à configurer dans le tableau de bord Tap. Vérifiez simplement qu'elle est accessible depuis Internet (non bloquée par un pare-feu ou une authentification HTTP). Chaque notification est vérifiée avec la signature hashstring (HMAC-SHA256 avec la clé secrète du mode dans lequel le paiement a été effectué). Les webhooks sans signature valide sont rejetés. Même une notification signée n'est pas considérée comme fiable en soi : le module relit le paiement depuis l'API Tap avant de créer ou de modifier la commande. Sans webhook fonctionnel, la commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Avancé

Debug log : enregistre les événements de paiement dans logs/tap_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être lu depuis le web. Les erreurs et avertissements sont toujours enregistrés ; activez cette option pour enregistrer aussi chaque événement de paiement. Le journal ne contient jamais de clés ni de données de carte ou de client. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les enregistrements de paiement des commandes sont conservés. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Tap Payments) et confirme la commande. Aucune commande n'existe encore à ce stade.

Tap payment page : le module crée un débit Tap (ou une autorisation en mode Authorize only) pour le total du panier dans la devise du panier, avec la description Cart # et le numéro du panier, puis envoie le client sur la page de paiement Tap. Le nom, l'adresse e-mail et le numéro de téléphone du client sont transmis à Tap. Là, le client choisit une carte, mada, KNET, Benefit, Apple Pay ou Google Pay (selon ce qui est activé dans votre compte Tap) et paie. Si Tap ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec The Tap payment could not be started. Please try again or choose another payment method. et la raison est consignée dans le journal.

Tap checkout popup : le client accède à la page Tap payment du module, 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 être chargé, le client est invité à utiliser la page de paiement Tap. Recharger la page réutilise la même tentative de paiement.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Tap : le module lit le paiement depuis l'API Tap avec la clé du mode du paiement, vérifie qu'il se rapporte à ce panier et qu'il a été lancé par son tunnel de commande, et compare le montant et la devise avec ceux du panier. L'identifiant Tap présent dans l'adresse de retour ne crée jamais une commande à lui seul. Le webhook effectue la même vérification en arrière-plan. La commande est ensuite créée et le client voit la page standard de confirmation de commande. Pour un paiement autorisé, la page affiche Your payment has been authorized. We will process the order as soon as the payment is captured. ; pour une commande en attente, elle affiche Your payment is being reviewed. We will contact you if anything else is needed.

Si Tap n'a pas encore confirmé le paiement au retour du client, une page Payment 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. avec les boutons Check again et Back to checkout. Le webhook crée la commande dès son arrivée.

Si le paiement a été refusé, abandonné ou annulé, aucune commande n'est créée. Le client revient au tunnel de commande avec 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 or choose another payment method. Le panier est conservé et peut être payé à nouveau.

Autres messages dans le tunnel de commande : Tap does not accept payments in, suivi de la devise, lorsque la devise du panier n'est pas prise en charge, et The order total must be greater than zero to pay with Tap.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le module ne gère ni cartes enregistrées ni tokenisation, ni abonnements, ni champs de carte intégrés à votre tunnel de commande. 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

Pas encore de commande : le client a été envoyé vers Tap et n'a pas payé, ou Tap n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : Tap a confirmé un paiement capturé. Le paiement est enregistré avec l'identifiant de débit Tap (chg_...) comme identifiant de transaction, et une note indique le montant, l'identifiant du débit, le moyen de paiement et, en mode test, qu'il s'agit d'un paiement de test.

Tap payment authorized : le paiement n'a été qu'autorisé et attend une capture ou une annulation.

Tap payment on hold : le montant ou la devise payé(e) ne correspondait pas au panier (Tap: amount/currency mismatch — manual review required.), ou un paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez la commande et traitez-la, ou remboursez le paiement.

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

Refunded : le paiement a été intégralement remboursé via le module.

Une tentative échouée ne modifie jamais une commande payée, autorisée ou annulée. Si un second paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. 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 au panier mais n'a pas été lancé par son tunnel de commande est simplement noté.

Bloc de paiement Tap

La page de commande affiche un bloc Tap payment avec l'identifiant Tap, l'autorisation et le débit, le mode (un badge Test mode pour les paiements de test), le statut et le moyen de paiement, Charged / refunded, l'historique des remboursements, les tentatives de paiement du panier et les Payment notes de la commande. Les boutons du bloc fonctionnent directement sur la page de commande ; il faut avoir le droit de modifier les commandes, et non l'accès aux réglages du module.

Capture et annulation

En mode Authorize only, ouvrez la commande au statut Tap payment authorized. Capture Tap payment (avec le total de la commande sur le bouton) capture le total de la commande après la question Capture the reserved funds of this order through Tap? ; la commande passe ensuite à Payment accepted. Void Tap authorization demande Release the reserved funds? The order will be canceled., libère les fonds et passe la commande à Canceled. Si Tap refuse l'action, une erreur s'affiche dans le bloc et est ajoutée aux notes. 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

Dans le bloc Tap payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Tap. Confirmez la question Refund this amount through Tap? This cannot be undone. Les remboursements totaux et partiels sont pris en charge pour les débits Tap capturés. Vous pouvez rembourser jusqu'au montant et à la devise que Tap a réellement débités, même si la commande a été modifiée ensuite. 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é à l'historique des remboursements et aux notes, avec l'identifiant et le statut du remboursement Tap. Si Tap le refuse, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement total passe la commande à Refunded ; un remboursement partiel ne modifie pas le statut. Pour une commande autorisée, les remboursements sont disponibles une fois l'autorisation capturée. Une commande en attente après un écart de montant ou de devise se rembourse dans le tableau de bord Tap.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Tap. Les remboursements effectués dans le tableau de bord Tap n'apparaissent pas dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Tap Payments est le premier bloc de Modules > Module Manager > VibeFox Tap Payments > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous, se trouvent la ligne Product: presta-payment-tap et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : celui de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Tap Payments n'est pas proposé aux clients dans le tunnel de commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office, donc le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. 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, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

Tap Payments n'apparaît pas dans le tunnel de commande : 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 du panier fait partie de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR et USD. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. La page des réglages affiche un avertissement pour les clés manquantes et pour une devise de boutique non prise en charge.

Le paiement a été effectué, mais aucune commande n'a été créée : le webhook ne parvient pas à votre boutique. Vérifiez que l'URL affichée dans Webhook URL est accessible depuis Internet (ni pare-feu ni authentification HTTP) et activez Debug log pour voir les réponses dans le champ Log. La commande est aussi créée lorsque le client revient depuis 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.

Webhook answers order not found : la notification désigne un panier qui n'a aucune tentative de paiement Tap dans cette boutique.

Webhook answers busy, retry later or order could not be updated, retry later : la commande était confirmée par une autre requête au même moment, ou elle n'a pas pu être créée (par exemple, parce que le module est désactivé). Tap relance le webhook. Consultez le champ Log pour en connaître la raison.

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_.

Le client voit The Tap payment could not be started : consultez le champ Log de la page du module. Une clé incorrecte ou une requête refusée y est consignée.

Le client voit We could not match this payment to an order : le paiement n'appartient pas à ce panier ou n'a pas été lancé par son tunnel de commande. Si de l'argent a été prélevé, vérifiez le paiement dans le tableau de bord Tap.

La commande est Tap payment on hold : lisez les notes du bloc Tap payment. Le montant ou la devise payé ne correspondait pas au panier, 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 le bloc 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 hooks actionWcpTapChargePayload, actionWcpTapSupportedCurrencies et actionWcpTapCurrencyDecimals permettent à un développeur de modifier la requête de paiement, les devises prises en charge et les décimales des devises.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Tap Payments et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages de la passerelle et le journal sont supprimés. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les tentatives de paiement et les remboursements Tap ainsi que les statuts de commande Tap payment authorized et Tap payment on hold sont toujours conservés : les commandes payées auparavant peuvent donc être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Tap Payments est une marque de son propriétaire respectif. Ce module n'est ni affilié à Tap Payments, ni approuvé par Tap Payments.