VibeFox Paystack for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. Le plugin refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise : la commande 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. Dans 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 renseignez aussi l'URL du webhook de votre boutique (voir Configuration). Votre site doit être accessible depuis Internet pour recevoir les webhooks.

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 du plugin et cliquez sur Install Now. Vous pouvez aussi transférer le dossier wcp_paystack_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Paystack > Manage, ou cliquez sur Settings sous le nom du plugin sur la page des extensions.

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

5. Collez vos clés secrètes depuis le tableau de bord Paystack et renseignez l'URL du webhook dans le tableau de bord Paystack (voir Configuration).

6. Activez Enable/Disable et enregistrez. Gardez Test Mode activé jusqu'à avoir effectué un paiement de test, puis décochez-le pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Paystack. 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 de votre boutique. Tant qu'un problème de clé existe, le moyen de paiement est masqué au moment du paiement. Dans la liste des moyens de paiement, Paystack est signalé comme nécessitant une configuration tant que le mode actuel ne dispose pas d'une clé secrète.

Paiement

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. Par défaut : Paystack.

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 y renvoie par un lien.

Test Mode: Enable Test Mode utilise la clé secrète de test pour les nouveaux paiements, et aucun argent réel n'est débité. Décochez-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é.

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

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 cette section à la fois dans Test Webhook URL et dans Live Webhook URL. Elle ressemble à https://your-site/wc-api/paystack_p_webhook/. Copiez l'URL exactement telle que les réglages l'affichent.

Paystack signe chaque webhook avec votre clé secrète, rien d'autre n'est donc à configurer. Les webhooks de test sont vérifiés avec la clé secrète de test, et les webhooks réels avec la clé secrète réelle. Les webhooks sans signature valide sont rejetés. Le plugin 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 avoir payé. Les virements bancaires et les paiements USSD qui se terminent plus tard ne sont confirmés que par le webhook.

Commandes

Autocomplete Order: Automatically mark orders as completed after successful payment. Lorsque la case est cochée, les commandes payées passent à Terminée au lieu de Processing, avec un seul changement de statut et un seul e-mail au client. Par défaut : désactivé.

Avancé

Debug log: Log Paystack events and API calls for debugging écrit les détails dans WooCommerce > Status > Logs, source wcp_paystack_payment. Les erreurs sont toujours journalisées. Les clés et les données clients ne sont jamais journalisées. Par défaut : désactivé.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. La désactivation du plugin ne supprime jamais rien. Les données de paiement enregistrées sur les commandes sont toujours conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Paystack) et passe la commande. En mode test, la page de paiement affiche MODE TEST ACTIVÉ. Aucun débit réel ne sera effectué. Le plugin lance une transaction Paystack pour le total de la commande, dans la devise de la commande, avec l'adresse e-mail de facturation de la commande, et 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.

Après le paiement, le client revient dans 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 plugin lit la transaction via l'API Paystack avec la clé secrète du mode dans lequel le paiement a été lancé, et vérifie la référence, le statut, le montant et la devise. Si le paiement est encore en cours de traitement, par exemple un virement bancaire, la page de commande reçue 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 le client annule sur la page Paystack ou la quitte sans payer, la commande reste en attente de paiement. Le client revient au paiement ou à la page Pay for order 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. Le client peut payer à nouveau la même commande. Une ancienne page de paiement de la commande reste valide : si elle est payée plus tard, le paiement est tout de même accepté.

La page de commande reçue ne s'ouvre que pour le client de la commande : via le lien de retour signé, la session de paiement qui a créé la commande ou le compte client. Toute autre personne est renvoyée au paiement avec un message neutre, et la page de commande n'est pas affichée.

Si Paystack ne peut pas lancer le paiement, le client voit un court message, par exemple Paystack n'a pas pu lancer le paiement : suivi de la raison donnée par Paystack, ou Paystack est temporairement indisponible. Réessayez dans un instant ou choisissez un autre moyen de paiement. Le total de la commande doit être supérieur à zéro, et la commande doit avoir une adresse e-mail valide.

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

Le plugin 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 WooCommerce.

Commandes et remboursements

Statuts de commande

Pending payment: le client a été redirigé vers Paystack et n'a pas encore payé, a quitté la page Paystack sans payer, ou le paiement est toujours en cours de traitement par Paystack. Lorsque le client revient sans avoir payé, une note indique que la commande attend toujours le paiement.

Processing or Completed: le paiement a été confirmé. Le statut est Terminée lorsque Autocomplete Order est activé. La note de commande affiche le montant, la référence Paystack, 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 payés par le client. L'identifiant de transaction de la commande est la référence Paystack (order_...).

On hold: le montant ou la devise payés diffèrent de la commande (note Paystack amount or currency mismatch), ou le paiement est arrivé après l'annulation de la commande. La note de commande explique ce qu'il faut vérifier. Traitez la commande ou remboursez le paiement.

Failed: Paystack signale que la dernière tentative de paiement d'une commande en attente a échoué ou a été annulée. L'échec d'une tentative plus ancienne ne modifie pas la commande. Le client peut payer à nouveau.

Si une seconde tentative de paiement pour une commande déjà payée est également réglée, la commande n'est pas modifiée. Une note vous invite à rembourser le paiement en double dans le tableau de bord Paystack. Un paiement qui arrive pour une commande dans un autre statut, par exemple Refunded, est seulement noté sur la commande.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant puis cliquez sur Refund via Paystack. Les remboursements complets et partiels sont pris en charge. Le bouton de remboursement n'est proposé que pour les commandes payées via une transaction Paystack vérifiée. 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. En XOF et RWF, les remboursements doivent être des montants entiers. Paystack met les remboursements en file d'attente : la note de commande affiche le statut renvoyé par Paystack, par exemple pending, ainsi que l'identifiant du remboursement. Si Paystack n'accepte pas le remboursement, WooCommerce affiche Paystack refund failed: avec la raison, et aucun remboursement n'est enregistré.

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 WooCommerce. Si nécessaire, enregistrez-les manuellement.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox achetée sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Paystack. 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 sa place de domaine. Libérez-la dans votre compte vibefox.net.

Sans clé active, Paystack 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. 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 le plugin avant d'acheter une clé. Un rappel s'affiche sur la page des extensions 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 fonctionnent.

Lorsqu'une licence expire, le plugin 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

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 de la commande est acceptée par Paystack. L'encadré d'état en haut des réglages indique le problème.

Le paiement a été effectué, mais la commande reste en Pending payment : 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 les réglages, et qu'aucun mode maintenance, pare-feu ou protection par mot de passe ne bloque l'accès. Consultez WooCommerce > Status > Logs, source wcp_paystack_payment, pour repérer les webhooks rejetés.

Le webhook répond Invalid signature : le webhook n'est pas 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 ou Busy, retry later : la transaction n'a pas pu être lue via l'API Paystack à ce moment-là, ou la commande était en cours de mise à jour par le retour du client. La commande n'est pas modifiée, et Paystack renvoie le webhook.

Le webhook répond OK - unknown reference : le paiement ne concernait pas une commande de cette boutique, par exemple une page de paiement Paystack ou une autre intégration sur le même compte. Il est ignoré.

Le client voit Payment gateway is not properly configured : 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 On hold après le paiement : lisez la note de commande. Le montant ou la devise payés différaient de la commande, ou le paiement est arrivé après l'annulation de la commande. Traitez la commande ou remboursez le paiement.

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. Le message No verified Paystack payment was found for this order signifie que la commande n'a pas été payée via une transaction Paystack vérifiée. Remboursez-la dans le tableau de bord Paystack.

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 une place 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é sur le nouveau domaine. Si le serveur de licences est injoignable, le plugin continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation du plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages de la passerelle 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 de transaction et leurs références Paystack.

Paystack est une marque commerciale de son titulaire respectif. Ce plugin n'est ni affilié à Paystack ni approuvé par Paystack.