VibeFox Quickpay for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Compte Quickpay : vous avez besoin de deux valeurs du gestionnaire Quickpay : la clé API d'un utilisateur API (pour créer les paiements, capturer et rembourser) et la clé privée du compte (pour vérifier la signature des callbacks Quickpay). Rien d'autre n'est à configurer dans Quickpay. Votre boutique doit être accessible depuis Internet, sans protection par mot de passe, pour que les callbacks Quickpay puissent arriver.

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 Quickpay Gateway 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, puis cliquez sur Activate (voir Clé de licence).

4. Collez la clé API et la clé privée depuis le gestionnaire Quickpay, puis cliquez sur Test API key (voir Configuration).

5. Choisissez le mode de capture et le statut de commande après paiement, activez Enable/Disable et cliquez sur Save. Tant que votre compte Quickpay est en mode test, activez Test payments et effectuez un paiement avec une carte de test Quickpay.

À l'installation, le module crée un statut de commande : Quickpay payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Le module est lié aux pays actifs au moment de l'installation. Vous pouvez tous les modifier dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Tant que la clé API et la clé privée ne sont pas enregistrées, la page affiche Quickpay nécessite une configuration : saisissez la clé API et la clé privée. Tant que les deux ne sont pas enregistrées, le moyen de paiement est masqué au moment du paiement. Lorsque Test payments est activé, la page vous rappelle de le désactiver quand votre compte Quickpay passe en production.

Quickpay

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

Title : le nom du moyen de paiement que les clients voient au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Quickpay. Obligatoire : un titre vide n'est pas enregistré.

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely by card or MobilePay on the Quickpay payment page.

Identifiants API Quickpay

Dans le gestionnaire Quickpay (manage.quickpay.net), ouvrez Settings > Integration. Copiez la clé API d'un utilisateur API (Settings > Users) et la clé privée du compte.

Callback URL : affiche l'URL de callback de votre boutique. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay l'appelle après chaque opération de paiement (autorisation, capture, remboursement, annulation). Elle est transmise automatiquement avec chaque paiement, il n'y a donc rien à configurer dans Quickpay.

API key : la clé API d'un utilisateur API Quickpay. Elle sert à créer les paiements, capturer et rembourser.

Private key : la clé privée du compte. Elle sert à vérifier la signature (HMAC-SHA256) des callbacks Quickpay. Sans elle, aucun paiement ne peut être confirmé et les callbacks sont rejetés.

Les clés enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Enregistrée : laissez vide pour la conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Effacer les secrets enregistrés : cochez API key ou Private key et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Test payments : accepte les paiements effectués avec des cartes de test Quickpay. Quickpay n'a pas de bac à sable séparé : tant que votre compte Quickpay est en mode test, les paiements se font avec des cartes de test et sont signalés comme tels. N'activez ce réglage que pendant les tests. Lorsqu'il est désactivé, un paiement de test ne marque jamais une commande comme payée. Lorsqu'il est activé, le paiement affiche Mode test : les cartes de test Quickpay sont acceptées. sous le moyen de paiement. Par défaut : désactivé.

Test API key : ce bouton vérifie la clé saisie dans le champ API key (ou la clé enregistrée, si le champ est vide) par une requête authentifiée vers Quickpay, sans l'enregistrer. Il répond Connexion réussie : la clé API est valide., Quickpay a rejeté la clé API., La clé API n'est pas configurée. ou Échec de la connexion : suivi de la raison.

Paiement

Capture : le moment où l'argent est prélevé sur la carte.

Order status after payment : le statut de la commande une fois que Quickpay a confirmé le paiement capturé.

Avancé

Debug log : écrit dans logs/qpg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements, comme les callbacks rejetés et les erreurs de l'API Quickpay, sont toujours journalisés. Activez ce réglage pour journaliser aussi le détail de chaque requête et de chaque callback. Les clés API, les données de carte et les données clients ne sont jamais journalisées. 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 : si activé, la désinstallation du module supprime les réglages de la passerelle et le journal. Les données de commande (paiements Quickpay, remboursements, notes) et le statut de commande Quickpay payment on hold sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Quickpay, avec une icône de carte) et confirme. Le module crée un paiement Quickpay pour le panier dans la devise du panier, ainsi qu'un lien de paiement pour le total du panier, et envoie le client vers la fenêtre de paiement Quickpay. Aucune commande n'existe encore à ce stade. Le client paie dans cette fenêtre avec l'une des méthodes activées dans votre fenêtre de paiement Quickpay. L'adresse e-mail du client est transmise à Quickpay. La fenêtre de paiement s'ouvre dans la langue du client lorsque Quickpay la propose (danois, allemand, anglais, espagnol, finnois, français, italien, néerlandais, norvégien, polonais, suédois), sinon en anglais.

Après le paiement, le client revient sur votre boutique. Ce retour ne marque lui-même rien comme payé. La commande n'est marquée payée qu'après confirmation de Quickpay : le callback signé crée la commande dès que le montant capturé et la devise correspondent au panier. Le client voit ensuite la page standard de confirmation de commande. Avec Authorize only, la commande est créée en Quickpay payment on hold à la place, et vous capturez le paiement plus tard. Si le callback n'est pas encore arrivé quand le client revient, une page Payment confirmation affiche Votre paiement est en cours de confirmation par Quickpay. Vous recevrez un e-mail dès que la commande sera confirmée. avec les boutons Check again et Back to checkout.

Si le client annule sur la fenêtre de paiement, le lien de paiement est supprimé dans Quickpay et le client revient au paiement avec le message Le paiement a été annulé. Vous pouvez réessayer ou choisir un autre moyen de paiement. Si la carte a été refusée, le message est Le paiement n'a pas été finalisé. Vous pouvez réessayer ou choisir un autre moyen de paiement. Le panier est conservé. Une nouvelle tentative réutilise le paiement Quickpay du panier avec un lien neuf, si bien qu'un ancien lien ne peut jamais être payé en parallèle. Tant qu'un paiement du panier est autorisé et attend sa capture, aucun second paiement n'est lancé ; le client voit la page Payment confirmation.

Si le paiement ne peut pas être lancé, le client reste au paiement avec le message Le paiement Quickpay n'a pas pu être lancé. Veuillez réessayer ou choisir un autre moyen de paiement. La raison technique est écrite dans le journal. Si les clés sont absentes, le message est Quickpay n'est pas disponible pour le moment. Veuillez choisir un autre moyen de paiement.

Le callback fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction par pays de votre boutique.

Le module ne gère que les paiements uniques. Il n'a ni abonnements ni paiements récurrents, ni cartes enregistrées, ni capture partielle, n'envoie aucune ligne de panier ou de facture à Quickpay et n'a pas de méthodes séparées MobilePay, Apple Pay ou Klarna : le client choisit parmi les méthodes de votre fenêtre de paiement Quickpay.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Quickpay et n'a pas payé, la carte a été refusée, ou le paiement est autorisé et attend la capture automatique. Seul le panier existe.

Payment accepted or Delivered : Quickpay a confirmé le paiement capturé avec le bon montant et la bonne devise. Le statut suit Order status after payment. Le paiement est enregistré avec l'identifiant de paiement Quickpay comme identifiant de transaction, et une note affiche le paiement (marqué TEST pour les paiements de test).

Quickpay payment on hold : le paiement est seulement autorisé et attend Capture Quickpay payment ; ou Quickpay a signalé un montant ou une devise différents du total de la commande (par exemple, le panier a été modifié après le début du paiement, ou un autre montant a été capturé dans le gestionnaire Quickpay) ; ou la capture automatique a échoué et le montant est toujours seulement réservé. La note l'explique. Lorsque de l'argent a été capturé pour un montant différent, le paiement est enregistré sur la commande pour le montant capturé par Quickpay.

Canceled : vous avez annulé la commande, ou le paiement d'une commande en attente a été annulé dans le gestionnaire Quickpay.

Refunded : le paiement a été entièrement remboursé via le module.

Un paiement qui arrive pour une commande déjà payée, annulée ou remboursée ne modifie pas la commande. Une note vous demande de vérifier le paiement dans le gestionnaire Quickpay, par exemple pour rembourser un double paiement.

Lorsque vous annulez une commande non payée, son lien de paiement est supprimé dans Quickpay. Annuler une commande autorisée ne libère pas automatiquement le montant réservé : une note vous rappelle d'annuler le paiement dans le gestionnaire Quickpay ; sinon, la réservation prend fin à l'expiration de l'autorisation.

Bloc Quickpay

La page de commande affiche un bloc Quickpay payment avec l'identifiant du paiement, le statut du paiement, le montant et le montant remboursé, un badge Test payment pour les paiements de test, la liste de tous les paiements Quickpay du panier (s'il y en a plusieurs), l'historique des remboursements et les Quickpay notes de la commande. La capture et les remboursements nécessitent le droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire.

Capture

Avec Authorize only, cliquez sur Capture Quickpay payment dans le bloc Quickpay et confirmez Capturer le total de la commande via Quickpay ? Le total de la commande est capturé ; la capture partielle n'est pas disponible. Si Quickpay confirme immédiatement, la commande passe au statut de Order status after payment. Sinon, une note indique que la capture a été demandée, et la commande est marquée payée lorsque le callback Quickpay la confirme. Une capture refusée est affichée dans le bloc et notée sur la commande.

Remboursements

Dans le bloc Quickpay, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Quickpay. Confirmez la question Rembourser ce montant via Quickpay ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge pour les paiements capturés. Les remboursements sont effectués dans le montant et la devise capturés par Quickpay : après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non le total de la commande. Quickpay traite les remboursements de manière asynchrone : l'historique des remboursements affiche requested, et le callback le passe à confirmed ou failed et ajoute le résultat aux notes. Si Quickpay rejette le remboursement immédiatement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement total place la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Un paiement autorisé qui n'a jamais été capturé ne peut pas être remboursé ; annulez-le dans le gestionnaire Quickpay.

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

Les remboursements effectués directement dans le gestionnaire Quickpay sont seulement ajoutés aux notes. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Quickpay Gateway est le premier bloc de Modules > Module Manager > VibeFox Quickpay Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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 figurent la ligne Product: presta-payment-quickpay et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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 : le domaine 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, Quickpay n'est pas affiché aux clients au moment du paiement. 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 : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et la capture et les remboursements 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é automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après 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 la licence.

Dépannage

Quickpay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que API key et Private key sont enregistrées. Sans les deux clés, le moyen de paiement est masqué. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : le callback Quickpay n'a pas atteint votre boutique ou a été rejeté. Vérifiez que votre boutique est accessible depuis Internet (sans protection par mot de passe) et que Private key est la clé privée du même compte Quickpay. Les callbacks rejetés sont toujours écrits dans le journal de la page du module. Activez Debug log pour voir chaque callback.

Le journal affiche Callback rejected: invalid checksum.: la clé privée des réglages n'appartient pas au compte qui a envoyé le callback. Recopiez-la depuis Settings > Integration dans le gestionnaire Quickpay.

Le journal affiche Callback rejected: the private key is not configured.: saisissez la clé privée. Les callbacks ne sont jamais acceptés sans elle.

Le journal affiche Callback: no cart found for payment … : le callback concerne un paiement Quickpay que cette boutique n'a pas créé, par exemple un paiement effectué en dehors de PrestaShop.

Le journal affiche Could not lock the cart ou Cannot create the order : un autre callback du même panier était en cours d'application à ce moment-là, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Le callback reçoit une réponse d'erreur, donc Quickpay le renvoie.

Un paiement de test n'a pas marqué la commande comme payée : Test payments est désactivé. Le journal (et la note, si la commande existe) indique que le paiement de test n'a pas été accepté. Activez le réglage pendant les tests, et désactivez-le lorsque votre compte passe en production.

La commande est en Quickpay payment on hold après le paiement : lisez les notes du bloc Quickpay. Le paiement n'est peut-être qu'autorisé et attend Capture Quickpay payment, le montant ou la devise payés peuvent différer de la commande, ou la capture a échoué. Capturez, traitez la commande ou remboursez le paiement.

Test API key affiche « Quickpay a rejeté la clé API. » : la clé est erronée ou appartient à un utilisateur sans accès API. Copiez la clé API d'un utilisateur API depuis le gestionnaire Quickpay.

Le client voit « Le paiement Quickpay n'a pas pu être lancé. » : regardez le champ Log de la page du module. Il affiche l'erreur Quickpay, par exemple une devise que votre compte Quickpay n'accepte pas.

Le remboursement échoue : la commande doit avoir un paiement Quickpay capturé. Le message Le paiement Quickpay de cette commande n'a pas été capturé — il n'y a rien à rembourser. signifie que le paiement est seulement autorisé ; capturez-le ou annulez-le dans le gestionnaire Quickpay. Montant de remboursement invalide : au maximum … signifie que le montant dépasse ce qui reste du paiement capturé.

Les développeurs peuvent modifier les paramètres du lien de paiement Quickpay avec le hook actionQpgQuickpayLinkData.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Quickpay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data est activé, les réglages de la passerelle et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les paiements Quickpay, les remboursements et le statut de commande Quickpay payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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