VibeFox Peach Payments for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension OpenSSL (utilisée pour déchiffrer les webhooks). Le module refuse de s'installer sans elles.

Devise : la devise du panier doit être ZAR, KES ou MUR. Pour les paniers dans une autre devise, le moyen de paiement est masqué. La page de configuration vous avertit lorsque la devise par défaut de la boutique ne fait pas partie de ces devises.

Compte Peach Payments : vous avez besoin des identifiants Card API de votre compte Peach Payments : l'Entity ID et l'Access Token. Les identifiants de test proviennent du tableau de bord sandbox de Peach Payments, les identifiants de production du tableau de bord de Peach Payments ; ils sont différents. Pour les webhooks, vous avez aussi besoin d'une clé de déchiffrement des webhooks, que Peach Payments vous envoie lorsqu'il active les webhooks Card pour 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 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 Peach Payments 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 l'Entity ID et l'Access Token de test du tableau de bord sandbox de Peach Payments, puis demandez à Peach Payments d'activer les webhooks Card pour l'URL du webhook affichée sur la page de configuration (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Gardez Test mode activé et effectuez un paiement avec une carte de test de la sandbox Peach Payments. Désactivez ensuite Test mode, saisissez les identifiants de production et la clé de webhook de production, puis cliquez sur Save.

À l'installation, le module crée deux statuts de commande : Awaiting Peach Payments payment et Peach Payments payment on hold. PrestaShop propose un nouveau module de paiement pour les devises, pays et groupes de clients actifs à ce moment-là. Les pays ajoutés plus tard doivent être activés pour le module dans Payment > Preferences, où vous pouvez aussi les limiter.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche des avis : Test mode is on: payments go to the Peach Payments sandbox and no real money is charged. ; une erreur lorsque l'Entity ID ou l'Access Token du mode actuel est absent (tant qu'il manque, le moyen de paiement n'est pas affiché au paiement) ; un avertissement lorsque la clé de déchiffrement des webhooks du mode actuel est absente (les paiements ne sont alors confirmés que lorsque le client revient dans la boutique) ; et une erreur lorsque la devise par défaut de la boutique n'est pas prise en charge. À l'enregistrement, les espaces sont supprimés des identifiants, et une clé de webhook qui n'est pas une valeur hexadécimale de 64 caractères est signalée par un avertissement.

Peach Payments

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

Title : le nom du moyen de paiement affiché au client lors du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit / Debit Card (Peach Payments). Obligatoire.

Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API credentials

L'Access Token et l'Entity ID de la Card API sont affichés dans le tableau de bord de Peach Payments (les identifiants de test se trouvent dans le tableau de bord sandbox). La section renvoie vers les deux tableaux de bord et vers la documentation développeur de Peach Payments.

Test mode : envoie les nouveaux paiements vers la sandbox de Peach Payments avec les identifiants de test ; aucun argent réel n'est débité. Désactivez-le pour accepter de vrais paiements avec les identifiants de production. Un paiement lancé dans un mode est toujours vérifié dans ce mode, même après un changement. Par défaut : activé.

Test Entity ID : l'Entity ID (canal 3-D Secure) de votre compte sandbox.

Test Access Token : le jeton d'accès bearer de votre compte sandbox.

Test Webhook Decryption Key : la clé hexadécimale de 64 caractères utilisée pour déchiffrer les webhooks Card de la sandbox.

Live Entity ID : l'Entity ID (canal 3-D Secure) de votre compte de production.

Live Access Token : le jeton d'accès bearer de votre compte de production.

Live Webhook Decryption Key : la clé hexadécimale de 64 caractères utilisée pour déchiffrer les webhooks Card de votre compte de production.

Les access tokens et les clés de webhook enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved secrets : cochez un access token ou une clé de webhook et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Webhook

Les webhooks confirment les paiements même lorsque le client ferme son navigateur avant de revenir dans la boutique. Le champ Webhook URL affiche l'URL du webhook de votre boutique. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_peach_pay/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages. Demandez à Peach Payments (support@peachpayments.com) d'activer les webhooks Card pour votre compte avec cette URL, puis saisissez la clé de déchiffrement reçue dans le champ Webhook Decryption Key du même mode.

Peach Payments chiffre chaque webhook (AES-256-GCM). Un webhook qui ne peut pas être déchiffré avec la clé de test ou de production est rejeté : seul Peach Payments peut donc modifier vos commandes. Un webhook déchiffré avec la clé d'un mode n'est appliqué qu'aux paiements lancés dans ce mode. Le module utilise les notifications de paiement suivantes :

Les autres notifications, par exemple la notification de test envoyée à l'activation du webhook, reçoivent la réponse ignored. Sans la clé de webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Payment form

Card brands : les marques affichées dans le formulaire de Peach Payments : Visa, Mastercard, American Express, Diners Club. Ne sélectionnez que les marques activées pour votre Entity ID. Par défaut : Visa et Mastercard. Si aucune marque n'est sélectionnée, l'enregistrement affiche un avertissement et le formulaire affiche Visa et Mastercard.

Advanced

Logging : enregistre les requêtes API et les résultats de paiement dans logs/peach_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être lu depuis le web. Les erreurs et avertissements sont toujours enregistrés. Les journaux ne contiennent aucune donnée de carte, aucune clé et aucune donnée client. 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 ses réglages et ses journaux. Les données Peach Payments des commandes (tentatives de paiement, ID de paiement) et les statuts de commande sont conservés, car ils font partie des commandes. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Credit / Debit Card (Peach Payments)) et confirme la commande. En mode test, le moyen de paiement affiche Test mode: no real payment will be made. Le module prépare un checkout Peach Payments pour le total du panier dans la devise du panier et affiche la page Peach Payments payment de votre boutique avec le formulaire de carte Peach Payments et les marques de carte sélectionnées, dans la langue du client lorsque Peach Payments la prend en charge. En mode test, la page affiche Test mode: use a Peach Payments test card, no real payment will be made. Les données de carte sont saisies dans le formulaire Peach Payments, et le script du formulaire est chargé avec un hachage Subresource Integrity. Le lien Choose another payment method ramène au paiement. Aucune commande n'existe encore à ce stade. Si la page est rechargée, le même checkout est réutilisé pendant 25 minutes au maximum, sauf si le panier a changé.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après la confirmation de Peach Payments : la boutique lit le résultat du checkout de ce panier via l'API Peach Payments, dans le mode où le checkout a été créé, et vérifie que le paiement appartient à ce panier. Le webhook fait de même de façon indépendante ; celui qui arrive en premier crée la commande, et l'autre ne modifie rien. Le client voit ensuite la page standard de confirmation de commande.

Si le paiement n'est pas finalisé, le client revient au paiement avec un message et peut réessayer : Payment failed: suivi du motif indiqué par Peach Payments et de Please try again or use another card., ou The payment was not completed. Please try again. Le panier est conservé. Si le résultat ne peut pas encore être confirmé (par exemple, Peach Payments n'a pas répondu, ou le webhook traite justement ce même panier à ce moment-là), le message est We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Lorsqu'aucune clé de webhook n'est définie pour le mode du paiement, le client est invité à vous contacter.

Si le formulaire de paiement ne peut pas être préparé, le client reste au paiement avec un court message : The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (identifiants absents ou incorrects), un message indiquant que certaines coordonnées de facturation n'ont pas été acceptées par le prestataire de paiement, ou The payment form could not be loaded. Please try again in a moment. La raison technique est écrite dans le journal.

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

Le module n'a pas de formulaire de carte à l'étape du paiement lui-même, ni de cartes enregistrées, ni d'abonnements, ni de préautorisation et capture, ni d'EFT, BNPL, QR ou autres moyens de paiement sans carte.

Commandes

Statuts de commande

No order yet : le client n'a pas payé, le paiement a été refusé ou n'a pas abouti, ou Peach Payments ne l'a pas encore confirmé. Seul le panier existe, et le client peut payer à nouveau.

Payment accepted : le paiement a été confirmé, et le montant et la devise correspondent au panier. Le paiement est enregistré avec l'ID de paiement Peach Payments comme ID de transaction, et une note affiche le code de résultat, la description et l'ID de paiement de Peach Payments. Si Peach Payments a signalé le paiement pour un examen manuel, la note vous demande de le vérifier dans le tableau de bord de Peach Payments avant l'expédition.

Awaiting Peach Payments payment : Peach Payments a signalé un paiement en attente de confirmation. Le webhook fait ensuite passer la commande à Payment accepted ou la marque comme échouée.

Peach Payments payment on hold : le montant ou la devise payé diffère du panier (note amount/currency mismatch — manual review required), ou le paiement est arrivé après l'annulation de la commande. La note explique ce qu'il faut vérifier. Contrôlez le paiement dans le tableau de bord de Peach Payments, puis traitez la commande ou remboursez le paiement.

Payment error : Peach Payments a refusé le paiement attendu par la commande en attente. Une tentative refusée ne modifie jamais une commande payée, en attente ou annulée.

Si un second paiement pour une commande déjà payée réussit, la commande n'est pas modifiée. Une note indique qu'il s'agit d'un paiement en double et vous demande de le rembourser dans le tableau de bord de Peach Payments. Un paiement reçu pour une commande remboursée est seulement noté sur la commande.

Bloc de paiement Peach Payments

La page de commande affiche un bloc Peach Payments payment avec l'ID du paiement, l'ID du checkout, l'ID de transaction du marchand, le montant envoyé à Peach Payments, le résultat et le code de résultat, un badge Test mode pour les paiements de test, et les Peach Payments notes de la commande.

Remboursements

Les remboursements depuis la page de commande PrestaShop ne sont pas disponibles. Remboursez le paiement dans le tableau de bord de Peach Payments, puis enregistrez-le dans PrestaShop (remboursement partiel ou avoir) si nécessaire. Avec le webhook configuré, les remboursements, annulations et rétrofacturations effectués dans Peach Payments sont ajoutés aux notes de la commande avec le montant et l'ID ; le statut de la commande n'est pas modifié.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Peach Payments Pay Gateway est le premier bloc de Modules > Module Manager > VibeFox Peach Payments 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) et 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-peach 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 : celui 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, Peach Payments 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 pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par le retour du client et par le webhook.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance 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

Peach Payments n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'Entity ID et l'Access Token du mode actuel sont saisis (Test Entity ID et Test Access Token en mode test, Live Entity ID et Live Access Token en mode production) et que la devise du panier est ZAR, KES ou MUR. Les avis en haut des réglages indiquent 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 client n'est pas revenu dans la boutique et le webhook n'est pas arrivé. Vérifiez que Peach Payments a activé les webhooks Card exactement pour l'URL affichée dans les réglages, que la Webhook Decryption Key du mode dans lequel le paiement a été effectué est saisie, et qu'aucun pare-feu ni aucune protection par mot de passe ne bloque l'URL. Activez Logging et consultez le champ Log pour voir les webhooks rejetés.

Le webhook répond Decryption failed : le webhook n'a pas pu être déchiffré avec la clé de test ni avec la clé de production. La clé est erronée ou appartient à un autre compte ou mode. Saisissez la clé que Peach Payments a envoyée pour cette URL de webhook.

Le webhook répond Webhook key not configured : ni la clé de webhook de test ni celle de production ne sont définies ou valides. Saisissez la clé de 64 caractères. Peach Payments renverra le webhook plus tard.

Le webhook répond Busy, retry later : le panier était en cours de traitement par le retour du client au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Rien n'a été modifié, et Peach Payments renvoie le webhook. Le journal indique la raison.

Le webhook répond Missing or malformed data : la requête ne contenait pas de corps chiffré ni les en-têtes X-Initialization-Vector / X-Authentication-Tag, par exemple parce qu'un proxy l'a modifiée. Rien n'a été modifié.

Le webhook répond ignored : la notification est authentique mais ne correspond à aucun checkout de cette boutique (une autre boutique avec le même Entity ID, un panier supprimé), ou elle provient d'un autre mode que celui du paiement. Rien n'a été modifié.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes de Peach Payments.

Le client voit The payment form is not available right now : l'Access Token ou l'Entity ID du mode actuel est erroné. Vérifiez les identifiants et le mode, et consultez le journal pour le code Peach Payments.

La commande est Peach Payments payment on hold après le paiement : lisez les notes du bloc Peach Payments payment. Le montant ou la devise payé différait du panier, ou le paiement est arrivé après l'annulation de la commande. Vérifiez le paiement dans le tableau de bord de Peach Payments, puis traitez la commande ou remboursez le paiement.

L'enregistrement indique que la clé du webhook doit être la clé hexadécimale de 64 caractères : la valeur n'est pas la clé fournie par Peach Payments. Les webhooks ne peuvent pas être déchiffrés tant qu'elle n'est pas corrigée.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Peach Payments Pay Gateway 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 et journaux du module sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les tentatives de paiement, les ID de paiement et les statuts de commande Awaiting Peach Payments payment et Peach Payments payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement, leurs ID de transaction et les données de checkout Peach Payments.

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