VibeFox PayFast for WooCommerce — Aide
Prérequis
WordPress : 6.2 ou ultérieur.
WooCommerce : 8.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
Devise : rand sud-africain (ZAR), défini dans WooCommerce > Settings > General. PayFast ne règle qu'en rand. Le montant minimum de commande est de R5.00.
Compte PayFast : le Merchant ID et la Merchant Key de votre compte PayFast, disponibles dans Settings > Developer Settings du tableau de bord PayFast. Une passphrase est fortement recommandée ; si elle est définie dans PayFast, la même passphrase doit être saisie dans l'extension. Pour les tests, vous avez besoin des identifiants du sandbox PayFast.
Site accessible : l'URL de notification de paiement doit être accessible depuis Internet, sans mode maintenance, sans authentification de base ni blocage par un pare-feu.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour 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_payfast_pay dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Réglez la devise de la boutique sur le rand sud-africain dans WooCommerce > Settings > General.
4. Ouvrez les réglages : WooCommerce > Settings > Payments > PayFast > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.
5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
6. Saisissez le Merchant ID, la Merchant Key et la passphrase. Pour les tests, gardez Test mode activé et saisissez vos identifiants sandbox.
7. Activez Enable/Disable et enregistrez. Effectuez un paiement de test, puis désactivez le mode test pour encaisser de vrais paiements.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > PayFast. Au-dessus des champs, la page vous avertit lorsque les identifiants du mode actuel sont vides (PayFast est alors masqué au moment du paiement), lorsque la devise de la boutique n'est pas ZAR, lorsque le mode live utilise l'identifiant marchand de test public 10000100, et lorsqu'aucune passphrase n'est définie ; elle affiche aussi Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. tant que le mode test est activé. Dans la liste des moyens de paiement, PayFast est signalé comme nécessitant une configuration tant que le Merchant ID et la Merchant Key du mode actuel ne sont pas saisis.
Général
Enable/Disable : Enable PayFast active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement affiché au client au moment du paiement. Par défaut : PayFast.
Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Compte PayFast (live)
Retrouvez votre Merchant ID et votre Merchant Key dans le tableau de bord PayFast, sous Settings > Developer Settings. Si vous y avez défini une passphrase, saisissez exactement la même ici.
Merchant ID : votre Merchant ID PayFast en production.
Merchant Key : votre Merchant Key PayFast en production. Elle est transmise à PayFast avec chaque formulaire de paiement.
Passphrase : la passphrase de salage fournie par PayFast, dans Settings > Developer Settings. Fortement recommandée : elle signe les paiements et les notifications.
Sandbox (mode test)
En mode test, les paiements sont envoyés au sandbox PayFast et aucun argent réel n'est débité. Les identifiants sandbox s'affichent après connexion au sandbox PayFast (le marchand de test public est 10000100 / 46f0cd694581a).
Test mode : Use the PayFast sandbox and the sandbox credentials below. Au moment du paiement, le client voit TEST MODE: payments go to the PayFast sandbox, no real money is charged. Par défaut : activé.
Sandbox Merchant ID : le Merchant ID de votre compte sandbox.
Sandbox Merchant Key : la Merchant Key de votre compte sandbox.
Sandbox Passphrase : uniquement si une passphrase est définie dans votre compte sandbox.
Lors d'une mise à jour depuis la version 1.0 en mode test, vos identifiants existants sont copiés dans les champs sandbox. Vérifiez vos identifiants live avant de désactiver le mode test.
Notifications de paiement (ITN)
PayFast confirme chaque paiement par une notification serveur à serveur envoyée à l'URL affichée dans cette section. Elle ressemble à ceci : https://your-site/wc-api/payfast_pay/. Cette adresse est transmise avec chaque paiement : il n'y a donc rien à configurer dans PayFast, mais elle doit être accessible depuis Internet.
Contrôle de la source : Accept live notifications only from PayFast servers. Les adresses proviennent des enregistrements DNS de PayFast. Ne désactivez cette option que si votre site se trouve derrière un proxy ou un CDN qui masque l'adresse du visiteur. La signature et la confirmation serveur sont toujours vérifiées. Les notifications sandbox ne sont pas contrôlées par adresse. Par défaut : activé.
Avancé
Debug log : Log payment steps écrit les étapes dans WooCommerce > Status > Logs, source wcp_payfast_pay. Les erreurs sont toujours journalisées. Aucune passphrase ni donnée client n'est écrite. Par défaut : désactivé.
Uninstall : Delete the gateway settings and logs when the plugin is deleted. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut PayFast) et valide sa commande. Il est dirigé vers la page Pay for order de la commande, qui affiche Thank you for your order. You are being redirected to PayFast to complete the payment. et envoie automatiquement le formulaire de paiement signé à PayFast. Si le navigateur ne poursuit pas seul, le client clique sur Pay with PayFast ; Cancel order annule la commande. Le formulaire contient le total de la commande en ZAR, Order # suivi du numéro de commande, le nom et l'e-mail du client, ainsi que la clé de la commande. Il est reconstruit à chaque ouverture de la page, afin que le client puisse la rouvrir après être revenu de PayFast.
Sur la page PayFast, le client paie par carte, Instant EFT ou un autre moyen de votre compte PayFast. PayFast envoie ensuite la notification de paiement (ITN) à votre boutique. La commande n'est marquée payée que lorsque la notification passe toutes les vérifications :
Le retour du client sur la page de confirmation de commande ne modifie pas la commande. Tant que la notification n'est pas arrivée, la page indique PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si la commande est en attente, elle indique Your payment is being reviewed. We will contact you if anything else is needed.
Si le client annule sur la page PayFast, la commande est annulée de la manière standard de WooCommerce. S'il quitte la page sans payer, la commande reste impayée et peut être réglée depuis la page Pay for order.
Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est masqué lorsque les identifiants du mode actuel manquent, lorsque la devise de la boutique ou de la commande n'est pas ZAR, ou lorsque le total est inférieur à R5.00. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension n'accepte que les paiements uniques en ZAR. Elle ne gère pas les remboursements depuis WooCommerce, ni les abonnements, ni les cartes enregistrées (tokenisées), ni les précommandes, ni les paiements fractionnés.
Commandes
Statuts de commande
Pending payment : le client a été envoyé vers PayFast et la notification de paiement n'est pas encore arrivée.
Processing : PayFast a confirmé le paiement. C'est le statut standard de WooCommerce après paiement ; les commandes ne contenant que des produits virtuels téléchargeables passent en « Terminée ». La note de commande affiche l'ID de paiement PayFast, qui est aussi l'ID de transaction de la commande. Un paiement sandbox reçoit la note indiquant qu'aucun argent réel n'a été débité. Les frais PayFast et le montant net sont enregistrés dans la commande.
On hold : PayFast a signalé le paiement comme en attente ; ou le montant payé diffère du total de la commande, ou la commande n'est pas en ZAR ; ou un paiement est arrivé pour une commande déjà annulée. La note de commande explique la situation. Vérifiez la commande et votre tableau de bord PayFast, puis expédiez-la ou remboursez le paiement dans PayFast.
Failed : PayFast a signalé le paiement comme échoué alors que la commande était impayée. Le client peut payer à nouveau.
Cancelled : le client a annulé sur la page PayFast, ou la commande a été annulée par vous ou par le délai de réservation de stock de WooCommerce.
Une notification répétée pour le même paiement ne change rien. Si un autre paiement complété arrive pour une commande déjà payée, une note vous invite à rembourser le doublon dans PayFast. Un paiement pour une commande remboursée ajoute seulement une note. Un paiement sandbox reçu alors que la passerelle est en mode live ajoute une note et ne marque pas la commande comme payée.
Remboursements
Les remboursements depuis WooCommerce ne sont pas pris en charge. Remboursez le paiement dans votre tableau de bord PayFast, puis créez un remboursement manuel 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 > PayFast. 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 pour 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, PayFast 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 que vous puissiez 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 concernées : les paiements déjà lancés sont toujours confirmés.
Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
PayFast n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le Merchant ID et la Merchant Key du mode actuel sont renseignés, que la devise de la boutique est ZAR et que le total de la commande est d'au moins R5.00. La page des réglages affiche un avertissement lorsqu'un élément manque.
Le paiement a abouti, mais la commande reste « En attente de paiement » : PayFast n'a pas pu remettre la notification de paiement, ou elle a été rejetée. Activez le Debug log et consultez WooCommerce > Status > Logs, source wcp_payfast_pay. Causes habituelles : le site n'est pas accessible depuis Internet (mode maintenance, authentification de base, pare-feu), une passphrase différente dans PayFast et dans l'extension, ou, en mode live derrière un proxy ou un CDN, le contrôle de la source. Dans ce cas, désactivez Source check.
La notification répond Invalid signature : la passphrase de l'extension n'est pas celle définie dans PayFast pour ce mode.
La notification répond Invalid source : la notification ne provient pas d'une adresse PayFast, ou un proxy ou un CDN masque l'adresse réelle. Désactivez Source check si votre site se trouve derrière un proxy ou un CDN.
La notification répond Merchant mismatch ou Order mismatch : le paiement a été effectué sur un autre compte PayFast ou n'appartient pas à cette commande. Rien n'est modifié.
La notification répond Confirmation unavailable ou Busy : PayFast n'a pas pu être joint pour la confirmation serveur, ou une autre notification pour la même commande était en cours de traitement au même moment. PayFast renouvelle la notification.
La notification répond Not configured : les identifiants du mode dans lequel la commande a été payée sont absents.
Le client voit PayFast accepts payments from R5.00 : le total de la commande est inférieur au minimum PayFast.
La commande est On hold : PayFast a confirmé un paiement qui ne correspond pas à la commande (montant différent, ou devise autre que ZAR), ou le paiement est arrivé pour une commande déjà annulée. Consultez les notes de commande et votre tableau de bord PayFast.
Un paiement sandbox n'a pas réglé la commande : la passerelle est en mode live. Les paiements sandbox ne règlent jamais une commande en mode live ; une note sur la commande l'indique.
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, les adresses PayFast en cache et ses journaux ne sont supprimés que si Delete the gateway settings and logs when the plugin is deleted était activé. Sinon, ils restent en place pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
PayFast est une marque déposée de son titulaire. Cette extension n'est ni affiliée ni approuvée par PayFast.