VibeFox PayFast 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 : rand sud-africain (ZAR). PayFast ne règle qu'en rand ; le panier doit donc être en ZAR. Ajoutez la devise dans International > Localization > Currencies si votre boutique ne l'a pas encore. 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 le module. Pour les tests, vous avez besoin des identifiants sandbox de PayFast.

Boutique accessible : l'URL de notification de paiement doit être accessible depuis Internet, sans authentification basique ni blocage par pare-feu.

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 l'envoi terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox PayFast Pay 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. Saisissez le Merchant ID, la Merchant Key et la passphrase. Pour les tests, laissez Test mode activé et saisissez vos identifiants sandbox.

5. Activez Enable/Disable et cliquez sur Save. Effectuez un paiement test, puis désactivez Test mode pour accepter de vrais paiements.

À l'installation, le module crée deux statuts de commande : Awaiting PayFast payment et PayFast 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 limiter dans Payment > Preferences ; vérifiez que le module reste autorisé pour le rand.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque les identifiants du mode actuel sont vides (PayFast est alors masqué au paiement), lorsque la devise par défaut de la boutique n'est pas ZAR, lorsque le mode live utilise le Merchant ID public du sandbox 10000100 et lorsqu'aucune passphrase n'est définie. Tant que le mode test est activé et que le module est actif, la page affiche : Le mode test est activé : les commandes sont payées dans le sandbox PayFast, aucun argent réel n'est débité. Un champ Title vide est refusé avec le message Saisissez un titre pour le mode de paiement.

PayFast

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

Title : le nom du mode de paiement affiché au client lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : PayFast. Obligatoire.

Description : le texte affiché sous le mode de paiement lors 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 mode live.

Merchant Key : votre Merchant Key PayFast en mode live. Elle est envoyée à PayFast avec chaque formulaire de paiement ; c'est donc un champ texte classique.

Passphrase : la passphrase de salage de 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 sont affichés 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. Lorsqu'il est activé, le client voit sous le mode de paiement : MODE TEST : les paiements sont envoyés au sandbox PayFast, aucun argent réel n'est débité. 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.

Les passphrases enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved passphrases : cochez Passphrase ou Sandbox Passphrase et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Notifications de paiement (ITN)

Notification URL : PayFast confirme chaque paiement par une notification serveur à serveur envoyée à l'URL affichée ici. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_payfast_pay/itn, éventuellement avec le code de langue de la langue par défaut. L'adresse est transmise avec chaque paiement : rien n'est à configurer dans PayFast, mais elle doit être accessible depuis Internet. Les commandes ne sont créées que par ces notifications vérifiées ; le client qui revient dans la boutique ne crée ni ne paie de commande.

Source check : n'acceptez les notifications en mode live que depuis les serveurs PayFast. Les adresses proviennent des enregistrements DNS de PayFast (mis en cache pendant 6 heures) et des plages d'adresses documentées par PayFast. Désactivez-le uniquement si votre boutique 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 vérifiées par adresse. Par défaut : activé.

Avancé

Debug log : enregistre les étapes du paiement dans logs/payfast_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours enregistrés, même lorsque l'interrupteur est désactivé. Aucune passphrase ni aucune donnée client n'est écrite. Par défaut : désactivé.

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

Uninstall : Delete the gateway settings when the module is uninstalled (réglages, adresses PayFast en cache et journal). Les enregistrements de paiements PayFast, les commandes et les statuts de commande sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut PayFast) et confirme. Une page affichant Merci pour votre commande. Vous êtes redirigé vers PayFast pour finaliser le paiement. envoie automatiquement le formulaire signé à PayFast. Si le navigateur ne poursuit pas seul, le client clique sur Pay with PayFast ; Cancel revient au paiement. Le formulaire transmet le total du panier en ZAR, Cart # avec le numéro du panier, le nom et l'e-mail du client, la référence du paiement (numéro du panier et tentative) et un token aléatoire de la tentative. Aucune commande n'existe encore à ce stade. Chaque nouvelle tentative reçoit une nouvelle référence et un nouveau token.

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 qu'après que PayFast l'a confirmée par une notification qui passe toutes les vérifications :

Les notifications d'un même panier sont traitées une à une. Si une autre notification du même panier est en cours de traitement, PayFast reçoit une réponse d'erreur et renvoie la notification. L'URL de notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Lorsque le client revient et que la commande existe, la page standard de confirmation de commande s'affiche. Si PayFast a signalé le paiement comme en attente, la page indique : PayFast confirme votre paiement. Vous recevrez un e-mail dès sa confirmation — inutile de payer à nouveau. Si la commande est mise en attente, elle indique : Votre paiement est en cours d'examen. Nous vous contacterons si autre chose est nécessaire. Si un paiement en attente a échoué plus tard, elle indique : Votre paiement PayFast n'a pas abouti. Veuillez nous contacter au sujet de cette commande. Si la notification n'est pas encore arrivée, une page Payment confirmation indique que PayFast confirme le paiement et que la commande sera créée dès sa confirmation, avec les boutons Check again et Back to checkout.

Si le client annule sur la page PayFast, il revient au paiement avec le message Le paiement PayFast a été annulé. Vous pouvez réessayer ou choisir un autre mode de paiement. Si PayFast a signalé l'échec du paiement, le message est Le paiement n'a pas abouti. Vous pouvez réessayer ou choisir un autre mode de paiement. Le panier est conservé et peut être payé à nouveau.

Le mode de paiement est masqué lorsque les identifiants du mode actuel sont absents, lorsque la devise du panier n'est pas ZAR ou n'est pas autorisée pour le module, ou lorsque le total est inférieur à R5,00. Si le client parvient tout de même au paiement, un bref message l'explique, par exemple PayFast accepte les paiements à partir de R5,00. Veuillez choisir un autre mode de paiement.

Le module n'accepte que des paiements uniques en ZAR. Il ne propose ni remboursements depuis la page de commande, ni abonnements, ni cartes enregistrées (tokenisées), ni paiements fractionnés.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers PayFast et la notification de paiement n'est pas encore arrivée, ou PayFast a signalé l'échec du paiement. Seul le panier existe.

Payment accepted : PayFast a confirmé le paiement. Le paiement est enregistré avec l'ID de paiement PayFast comme ID de transaction, et une note affiche l'ID de paiement. Un paiement sandbox reçoit la note indiquant qu'aucun argent réel n'a été débité.

Awaiting PayFast payment : PayFast a signalé le paiement comme en attente. La commande passe à Payment accepted lorsque PayFast le finalise.

Payment error : un paiement en attente a échoué. Si PayFast le finalise plus tard, la commande devient Payment accepted.

PayFast payment on hold : le montant payé diffère du total du panier, ou le panier n'est pas en ZAR ; un paiement est arrivé pour une commande annulée ou dont le mode de paiement n'est plus PayFast ; ou un paiement sandbox est arrivé alors que la passerelle est en mode live. Le montant reçu par PayFast est enregistré sur la commande (pas pour un paiement sandbox), et la note l'explique. Vérifiez la commande et votre tableau de bord PayFast, puis passez la commande à Payment accepted ou annulez-la et remboursez le paiement dans PayFast.

Une notification répétée pour le même paiement ne change rien. Les notifications tardives d'échec ou d'attente ne modifient jamais une commande payée. Si un autre paiement finalisé arrive pour une commande déjà payée, une note vous demande de rembourser le doublon dans PayFast. Un paiement pour une commande remboursée ajoute seulement une note.

Bloc de paiement PayFast

La page de commande affiche un bloc PayFast payment avec la référence du paiement (m_payment_id), l'ID de paiement PayFast, l'environnement (live ou sandbox), le statut, les montants brut, frais et net en ZAR, et les notes du module. Pour une commande en attente, il affiche un rappel pour examiner le paiement.

Remboursements

Les remboursements depuis la page de commande ne sont pas pris en charge. Remboursez le paiement dans votre tableau de bord PayFast, puis mettez la commande à jour manuellement dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PayFast Pay Gateway est le premier bloc de Modules > Module Manager > VibeFox PayFast Pay Gateway > 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 figurent la ligne Product: presta-payment-payfast 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 : 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, PayFast n'est pas affiché aux clients lors 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 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 ne pouvez pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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

Dépannage

PayFast n'apparaît pas au 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 le panier est en ZAR et que le total de la commande est d'au moins R5,00. La page de réglages affiche un avertissement lorsqu'un élément manque. Dans Payment > Preferences, vérifiez que le module est autorisé pour le rand, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : PayFast n'a pas pu remettre la notification de paiement, ou elle a été rejetée. Consultez le champ Log sur la page du module ; les erreurs et les notifications rejetées sont toujours enregistrées, et Debug log ajoute chaque étape. Causes habituelles : la boutique n'est pas accessible depuis Internet (authentification basique, pare-feu), une passphrase différente dans PayFast et dans le module, ou, en mode live derrière un proxy ou un CDN, la vérification de l'origine. Dans ce cas, désactivez Source check.

La notification répond Invalid signature : la passphrase du module n'est pas celle définie dans PayFast pour le mode dans lequel le paiement a été effectué.

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 boutique 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 tentative de paiement. Rien n'est modifié.

La notification répond Order not found : la référence du paiement est inconnue de cette boutique. Rien n'est modifié.

La notification répond Confirmation unavailable, Busy ou Temporary error : PayFast n'a pas pu être joint pour la confirmation serveur, une autre notification du même panier était en cours de traitement au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). PayFast renouvelle la notification. Le journal indique la raison.

La notification répond Not configured : les identifiants du mode dans lequel le paiement a été lancé sont absents. Saisissez-les à nouveau, par exemple les identifiants sandbox pour un paiement test.

Le client voit le message PayFast accepte uniquement les paiements en rand sud-africain (ZAR) : le panier est dans une autre devise. Demandez au client de payer en rand ou de choisir un autre mode de paiement.

La commande est en PayFast payment on hold : lisez les notes du bloc PayFast payment (voir Statuts de commande) et votre tableau de bord PayFast, puis acceptez la commande ou remboursez le paiement.

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.

Pour les développeurs : le hook actionPayfastPPaymentData peut modifier les champs du formulaire de paiement avant leur signature. Les identifiants marchands, les URL, la référence du paiement, le montant et le token ne peuvent pas être modifiés par ce biais.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayFast Pay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete the gateway settings when the module is uninstalled est activé, les réglages de la passerelle, les adresses PayFast en cache 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 enregistrements de paiements PayFast, les commandes et les statuts de commande Awaiting PayFast payment et PayFast payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement et leurs ID de transaction.

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