VibeFox Paystack 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.

Devise : le panier doit être dans une devise acceptée par Paystack : NGN, USD, GHS, ZAR, KES, XOF, EGP ou RWF, selon ce qui est activé sur votre compte Paystack. Pour les autres devises, le moyen de paiement est masqué. En XOF et RWF, Paystack n'accepte que des montants entiers.

Compte Paystack : vous avez besoin des clés secrètes de votre compte Paystack : la clé secrète de test (sk_test_...) et/ou la clé secrète réelle (sk_live_...). Les clés publiques (pk_...) ne sont pas nécessaires, car le paiement s'effectue sur la page hébergée de Paystack. Dans le tableau de bord Paystack, vous définissez aussi l'URL du webhook de votre boutique (voir Configuration). Votre boutique doit être accessible depuis Internet pour recevoir les webhooks.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour 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 Paystack Payment 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 vos clés secrètes depuis le tableau de bord Paystack et configurez l'URL du webhook dans le tableau de bord Paystack (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Laissez Test Mode activé jusqu'à avoir effectué un paiement test, puis désactivez-le pour accepter de vrais paiements.

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

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Paystack Payment > Configure. Chaque section comportant des champs possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, un encadré d'état indique le mode : Mode test : aucun argent réel n'est débité. ou Mode réel : les paiements réels sont acceptés. Il avertit également lorsque la clé secrète du mode actuel est vide, lorsqu'une clé publique (pk_...) a été saisie dans un champ de clé secrète, lorsque le mode réel contient une clé de test (sk_test_...) ou que le mode test contient une clé réelle (sk_live_...), et lorsque Paystack n'accepte pas la devise par défaut de votre boutique. Tant qu'un problème de clé existe, le moyen de paiement est masqué au moment du paiement.

Paystack

La première section s'intitule Paystack et affiche un badge TEST ou LIVE correspondant au mode actuel.

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

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

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely using your debit card, credit card, or bank account via Paystack.

Clés API

Copiez les clés secrètes depuis le tableau de bord Paystack, page Settings > API Keys & Webhooks. La section contient un lien vers cette page.

Test Mode : utilise la clé secrète de test pour les nouveaux paiements, et aucun argent réel n'est débité. Désactivez-le pour accepter de vrais paiements avec la clé secrète réelle. Les paiements effectués dans l'autre mode continuent d'utiliser la clé de leur propre mode pour la vérification et les remboursements. Par défaut : activé. Tant qu'il est activé, les clients voient MODE TEST ACTIVÉ. Aucun débit réel ne sera effectué. sous le moyen de paiement.

Test Secret Key : votre clé secrète de test Paystack. Elle commence par sk_test_.

Live Secret Key : votre clé secrète réelle Paystack. Elle commence par sk_live_.

Les clés enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Enregistrée : laissez vide pour la conserver. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

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

Webhook

Le webhook indique à votre boutique qu'un paiement a été effectué, même lorsque le client ne revient pas sur la boutique. Dans le tableau de bord Paystack, page Settings > API Keys & Webhooks, renseignez l'URL affichée dans Webhook URL de cette section comme Test Webhook URL et comme Live Webhook URL. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_paystack_payment/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'affichée dans les réglages.

Paystack signe chaque webhook avec votre clé secrète, il n'y a donc rien d'autre à configurer. Les webhooks sans signature valide sont rejetés. Le module utilise l'événement charge.success :

Les autres événements reçoivent la réponse OK et sont ignorés. Sans webhook, une commande n'est confirmée que lorsque le client revient sur la boutique après le paiement. Les virements bancaires et les paiements USSD qui se terminent plus tard ne sont confirmés que par le webhook.

Commandes

Autocomplete Order : lorsqu'elle est activée, les commandes payées reçoivent le statut Delivered au lieu de Payment accepted, avec un seul changement de statut. Par défaut : désactivée.

Avancé

Debug log : enregistre les événements Paystack et les appels à l'API dans logs/paystack_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours journalisés. Les clés 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 on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages du module et le journal. Les données de paiement enregistrées sur les commandes sont toujours conservées. Par défaut : désactivée.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Paystack) et confirme la commande. Le module démarre une transaction Paystack pour le total du panier dans la devise du panier, avec l'adresse e-mail du client, puis envoie le client sur la page de paiement hébergée de Paystack. Il y paie avec l'un des canaux activés sur votre compte Paystack. Le paiement affiche le numéro du panier et le nom du client. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation de Paystack : lorsque le client revient et lorsque le webhook arrive, le module lit la transaction via l'API Paystack et vérifie la référence, le statut, le montant et la devise. La commande est alors créée et le client voit la page de confirmation de commande standard.

Si le paiement est encore en cours de traitement, par exemple un virement bancaire, la commande est créée dans Awaiting Paystack payment au retour du client, et la page de confirmation affiche Votre paiement est en cours de confirmation par Paystack. Vous recevrez un e-mail dès qu'il sera confirmé. Le webhook finalise la commande plus tard. Si Paystack est injoignable au retour du client, une page Payment confirmation demande au client de ne pas payer à nouveau et propose Check again et Back to checkout ; le webhook crée la commande dès son arrivée. Pour une commande en attente de vérification, la page de confirmation affiche Votre paiement a bien été reçu et votre commande est en cours de vérification. Nous vous contacterons si quelque chose est nécessaire.

Si le client annule sur la page Paystack ou la quitte sans payer, aucune commande n'est créée et le panier est conservé. Le client revient au paiement avec un message, par exemple Le paiement a été annulé. Vous pouvez réessayer ou choisir un autre moyen de paiement., Le paiement n'a pas été finalisé. Vous pouvez réessayer ou choisir un autre moyen de paiement. ou Votre paiement a été refusé. Vous pouvez réessayer ou choisir un autre moyen de paiement. Chaque nouvelle tentative lance une nouvelle transaction Paystack. Une page de paiement plus ancienne du panier reste valide : si elle est payée plus tard, le paiement est tout de même accepté.

La page de confirmation de commande ne s'ouvre que dans le navigateur propre au client. Si le lien de retour est ouvert ailleurs, le paiement est tout de même vérifié, mais la commande n'est pas affichée : le visiteur voit un message neutre au moment du paiement.

Si Paystack ne peut pas lancer le paiement, le client reste au paiement avec un bref message, par exemple Paystack n'a pas pu lancer le paiement : suivi du motif indiqué par Paystack, ou Paystack est temporairement indisponible. Veuillez réessayer dans un instant ou choisir un autre moyen de paiement. Le total du panier doit être supérieur à zéro, et le client doit fournir une adresse e-mail valide.

Le webhook 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 propose pas de formulaire de paiement intégré ou en pop-up, ni cartes enregistrées, ni abonnements, ni paiements fractionnés ou sous-comptes, ni choix des canaux de paiement dans PrestaShop.

Commandes et remboursements

Statuts de commande

Aucune commande pour l'instant : le client a été envoyé vers Paystack et n'a pas payé, a quitté la page Paystack, ou Paystack n'a pas encore confirmé le paiement. Seul le panier existe.

Awaiting Paystack payment : le client est revenu alors que Paystack traitait encore le paiement, par exemple un virement bancaire ou USSD. La commande passe au statut payé lorsque Paystack confirme le paiement. Si ce paiement n'est jamais finalisé, la commande reste dans ce statut jusqu'à ce que vous le modifiez.

Payment accepted ou Delivered : le paiement a été confirmé. Le statut est Livré lorsque Autocomplete Order est activé. Le paiement est enregistré avec la référence Paystack (pscart_...) comme identifiant de transaction. Une note indique le montant, la référence, le numéro de transaction, le mode (test ou réel), le canal de paiement, le type de carte et les derniers chiffres pour les paiements par carte, ainsi que les frais Paystack éventuellement payés par le client.

Paystack payment on hold : le montant ou la devise payé ne correspond pas à la commande (note Écart de montant ou de devise Paystack), par exemple parce que le panier a été modifié après le lancement du paiement, ou parce que le paiement est arrivé après l'annulation de la commande. La note explique quoi vérifier. Traitez la commande ou remboursez le paiement.

Erreur de paiement : Paystack signale que la dernière tentative de paiement d'une commande en Awaiting Paystack payment a échoué ou a été annulée. L'échec d'une tentative plus ancienne ne modifie pas la commande.

Si un second paiement arrive pour un panier dont la commande est déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans le tableau de bord Paystack. Un paiement arrivant pour une commande dans un autre statut, par exemple Expédié, est simplement signalé sur la commande.

Bloc Paystack payment

La page de commande affiche un bloc Paystack payment avec la référence, l'identifiant de transaction, le mode avec un badge Test mode pour les paiements test, le statut du paiement, le canal et la carte, la date du paiement, les montants payés et remboursés, l'historique des remboursements et les Payment notes de la commande.

Remboursements

Dans le bloc Paystack payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Paystack. Confirmez la question Rembourser ce montant via Paystack ? Cette action est irréversible. Les remboursements complets et partiels sont pris en charge. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Le remboursement est envoyé à la transaction qui a réglé la commande, avec la clé secrète du mode (test ou réel) dans lequel elle a été effectuée ; cette clé doit donc être configurée. Les remboursements sont effectués dans le montant et la devise encaissés par Paystack : pour une commande en attente 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. En XOF et RWF, les remboursements doivent être des montants entiers. Paystack met les remboursements en file d'attente : la note et l'historique des remboursements affichent le statut renvoyé par Paystack, par exemple pending, ainsi que l'identifiant du remboursement. Si Paystack n'accepte pas le remboursement, le bloc affiche Échec du remboursement Paystack : avec le motif, et aucun remboursement n'est enregistré. Un remboursement complet passe la commande au statut Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Paystack a confirmé le paiement.

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

Les remboursements effectués dans le tableau de bord Paystack, ainsi que le statut final des remboursements mis en file d'attente par Paystack, ne sont pas synchronisés avec PrestaShop. Si nécessaire, enregistrez-les manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Paystack Payment est le premier bloc de Modules > Module Manager > VibeFox Paystack Payment > 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 de fin de validité de la licence 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. Sous ceux-ci figurent la ligne Product: presta-payment-paystack 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 pour 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, Paystack n'est pas proposé aux clients au moment du paiement. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. La boutique 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 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é à 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

Paystack n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose d'une clé secrète correcte (Test Secret Key avec sk_test_... en mode test, Live Secret Key avec sk_live_... en mode réel) et que la devise du panier fait partie de celles acceptées par Paystack. L'encadré d'état en haut des réglages indique le problème. 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 été effectué, mais aucune commande n'a été créée : le webhook n'a pas atteint votre boutique et le client n'est pas revenu. Dans le tableau de bord Paystack, vérifiez que la Test Webhook URL et la Live Webhook URL correspondent exactement à l'URL affichée dans Webhook URL, et qu'aucun pare-feu ni aucune protection par mot de passe ne la bloque. Activez Debug log et consultez le champ Log pour repérer les webhooks rejetés.

Le webhook répond Invalid signature : le webhook n'a pas été signé avec la clé secrète de test ou réelle saisie dans les réglages, par exemple parce que les clés appartiennent à un autre compte Paystack. Saisissez les clés du compte qui envoie le webhook.

Le webhook répond Secret key not configured : aucune clé secrète n'est définie. Saisissez les clés secrètes dans les réglages.

Le webhook répond Verification failed, Busy, retry later ou Order could not be created, retry later : la transaction n'a pas pu être lue via l'API Paystack à ce moment-là, le panier était traité au même moment par le retour du client, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Paystack renvoie le webhook. Le journal indique la raison.

Le webhook répond OK - unknown reference : le paiement n'a pas été effectué pour un panier de cette boutique, par exemple une page de paiement Paystack ou une autre intégration sur le même compte. Il est ignoré.

L'URL du webhook affiche Empty body dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Paystack.

Le client voit le message « La passerelle de paiement n'est pas correctement configurée » : la clé secrète du mode actuel est absente ou incorrecte. Corrigez-la en suivant l'encadré d'état en haut des réglages.

La commande est en Paystack payment on hold après le paiement : lisez les notes de paiement dans le bloc Paystack payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

La commande reste en Awaiting Paystack payment : Paystack n'a pas encore confirmé le paiement. Vérifiez la transaction dans le tableau de bord Paystack et les réglages du webhook. Si le client n'a jamais finalisé le paiement, modifiez le statut manuellement.

Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou réel, et la clé secrète de ce mode n'est pas configurée. Saisissez-la et réessayez.

Les développeurs peuvent modifier la requête de transaction et la liste des devises à l'aide des hooks du module actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies et actionWcpPaystackCurrencyDecimals.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Paystack Payment 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 du module 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 données de paiement Paystack des commandes, les remboursements et les statuts de commande Awaiting Paystack payment et Paystack payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Paystack est une marque déposée de son titulaire. Ce module n'est ni affilié à Paystack ni approuvé par Paystack.