VibeFox Paysera for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions de PHP antérieures.

Projet Paysera : vous avez besoin de l'identifiant de projet et du mot de passe de projet (sign key) de votre projet Paysera. Les moyens de paiement que voit le client sont ceux activés dans ce projet. Rien n'a besoin d'être configuré dans Paysera pour le callback : son URL est envoyée avec chaque requête de paiement.

Boutique accessible : les commandes sont créées par le callback Paysera ; votre boutique doit donc être accessible depuis Internet, et non derrière une connexion, une authentification de base ou un pare-feu. Le callback fonctionne même lorsque la boutique est en mode maintenance.

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. Lorsque le téléversement est terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Paysera Payment dans la liste des modules et cliquez sur Configure.

3. Collez 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 Project ID et le Project password de votre compte Paysera (voir Configuration).

5. Facultatif : activez Allow test payments dans le projet Paysera et Test payments dans le module pour essayer le fonctionnement sans débit d'argent. Désactivez-le avant de commencer à vendre.

6. Activez Enable/Disable et cliquez sur Save.

À l'installation, le module crée deux statuts de commande : Awaiting Paysera payment et Paysera 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.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Paysera Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Paysera is hidden at checkout until the project ID and the project password are entered. tant que l'un des deux manque, et Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. pendant que les paiements de test ou le bac à sable sont activés.

Paysera

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

Title: le nom du moyen de paiement que voit le client lors de la commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Paysera. Obligatoire.

Description: le texte affiché sous le moyen de paiement lors de la commande. Par défaut : Pay securely via Paysera.

Projet Paysera

Vous trouverez l'identifiant de projet et le mot de passe de projet dans votre compte Paysera, sous Projects and activities, puis votre projet, General project settings.

Callback URL: l'adresse que Paysera utilise pour confirmer chaque paiement. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_paysera_payment/callback, éventuellement avec un code de langue. Elle est envoyée automatiquement avec chaque paiement : rien n'a donc besoin d'être configuré dans Paysera, mais elle doit être accessible depuis Internet. Les commandes sont créées uniquement par ces callbacks signés.

Project ID: l'identifiant numérique de votre projet Paysera. Seuls les chiffres sont acceptés : toute autre valeur affiche l'erreur Project ID must be a number: the numeric ID of your Paysera project. et rien n'est enregistré.

Project password: le mot de passe de projet (sign key). Il signe les requêtes de paiement et vérifie les callbacks de Paysera. Le mot de passe enregistré n'est jamais affiché à nouveau. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved password: cochez Project password et cliquez sur Save pour supprimer le mot de passe enregistré. Un champ vide conserve la valeur enregistrée.

Tests

Test payments: envoie les paiements en mode test, donc aucun argent n'est débité. Paysera renvoie un paiement de test réussi sans débiter le client. Activez d'abord Allow test payments dans les paramètres du projet Paysera. Tant que cette option est active, les paiements de test marquent les commandes comme payées ; lorsqu'elle est désactivée, un paiement de test met la commande en attente. Par défaut : off. Tant qu'elle est active, les clients voient TEST MODE — no money will be charged. sous le moyen de paiement.

Environment: l'endroit où le client est envoyé. Gardez Production pour un projet Paysera normal, y compris pour les paiements de test. Par défaut : Production.

Avancé

Debug log: écrit les événements de paiement dans logs/wc_psr_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours écrits ; les autres étapes uniquement tant que cette option est active. Les mots de passe et les données clients ne sont jamais écrits. Par défaut : off.

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

Delete data: si cette option est active, la désinstallation du module supprime ses réglages et le journal. Les données de commande (commandes, enregistrements de paiement Paysera, statuts de commande) sont toujours conservées. Par défaut : off.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Paysera) et confirme la commande. Le module crée une requête de paiement signée avec le total du panier dans l'unité minimale de la devise du panier, le nom, l'e-mail et l'adresse de facturation du client, ainsi que la langue de la page de la boutique (lituanien, letton, estonien, russe, allemand, polonais, sinon anglais). Le client est envoyé vers la fenêtre de paiement Paysera et y choisit une banque, une carte ou un autre moyen. Aucune commande n'existe encore à ce stade.

Paysera confirme le paiement par un callback serveur à serveur. La commande n'est marquée comme payée qu'après la confirmation de Paysera par un callback signé ; le retour du client sur la boutique ne crée ni ne règle jamais une commande. Lorsque le client revient après le callback, la page standard de confirmation de commande s'affiche. Si la banque a accepté l'ordre de paiement sans l'avoir encore exécuté, la commande est créée dans le statut Awaiting Paysera payment et la page affiche Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Pour une commande en attente, la page affiche Your payment is being reviewed. We will contact you if anything else is needed.

Si le client revient avant le callback, une page Payment confirmation explique que la commande sera créée dès que Paysera confirmera le paiement, et propose Check again et Back to checkout.

Si le client annule dans la fenêtre Paysera, il revient au tunnel de commande avec The Paysera payment was cancelled. You can try again or choose another payment method. Si Paysera indique que le paiement n'a pas été exécuté, le message est The payment was not completed. You can try again or choose another payment method. Le panier est conservé dans les deux cas. Si le panier possède déjà une commande, une nouvelle tentative mène directement à la confirmation de commande, au lieu d'un second paiement.

Si le paiement ne peut pas être lancé, le client reste dans le tunnel de commande avec Paysera payments are temporarily unavailable. Please choose another payment method., ou, pour un total de commande invalide, avec This order cannot be paid via Paysera. La raison est écrite dans le journal.

Le callback fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le module ne propose pas de remboursements depuis le back-office, ni de choix de banque ou de moyen de paiement sur la page de commande, ni d'abonnements, ni de cartes enregistrées, ni de services de livraison ou de coursier Paysera.

Commandes

Statuts de commande

No order yet: le client a été envoyé vers Paysera et le callback n'est pas encore arrivé, ou le client a annulé. Seul le panier existe.

Payment accepted: Paysera a confirmé le paiement avec le montant et la devise correspondants. Le paiement est enregistré avec l'identifiant de requête Paysera comme identifiant de transaction, et une note indique la requête et le moyen de paiement, marquée (TEST — no money charged) pour les paiements de test.

Awaiting Paysera payment: Paysera a accepté l'ordre de paiement, mais la banque ne l'a pas encore exécuté. La commande passe à Payment accepted lorsque Paysera confirme le paiement.

Paysera payment on hold: le paiement nécessite une vérification manuelle. Le montant ou la devise payé diffère du panier ou du total de la commande, un paiement TEST est arrivé alors que Test payments est désactivé (aucun argent n'a été débité), ou le paiement a été confirmé après que le client l'a annulé. Le paiement n'est pas enregistré. La note l'explique, et le bloc Paysera vous demande de vérifier le paiement dans votre compte Paysera, puis de passer la commande à Payment accepted ou de l'annuler et de rembourser le paiement dans Paysera.

Cancelled: un paiement confirmé plus tard pour une commande annulée ne modifie pas son statut. Une note vous invite à rétablir la commande (la passer à Payment accepted) ou à rembourser le paiement dans Paysera. Un paiement TEST ultérieur ou un écart de montant pour une commande annulée ajoute aussi seulement une note.

Si un autre paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée et une note vous demande de rembourser le doublon dans votre compte Paysera. Les autres statuts Paysera (paiement non exécuté, informations complémentaires) ajoutent seulement une note.

Bloc de paiement Paysera

La page de commande affiche un bloc Paysera payment avec l'identifiant de commande Paysera (le numéro de panier et la tentative), l'identifiant de requête Paysera, l'environnement et une mention TEST payment, le statut du paiement, les montants demandé et payé, le moyen de paiement et les notes du module.

Remboursements

Les remboursements depuis le back-office ne sont pas pris en charge : le protocole de la fenêtre de paiement Paysera ne dispose pas d'API de remboursement. Effectuez les remboursements dans votre compte Paysera. Lorsque Paysera signale un remboursement, une note indiquant le montant remboursé est ajoutée à la commande, et le statut de la commande ne change pas. Enregistrez le remboursement manuellement dans PrestaShop si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox provenant de vibefox.net. Le bloc de licence License — VibeFox Paysera Payment est le premier bloc de Modules > Module Manager > VibeFox Paysera Payment > Configure, au-dessus des réglages. Collez 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-paysera 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 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, Paysera n'est pas affiché aux clients lors de la commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique ne sait pas que vous êtes connecté au back-office, de sorte que le moyen de paiement est également masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors de la commande. 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 callback.

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

Dépannage

Paysera n'apparaît pas lors de la commande : vérifiez que la licence est active, que Enable/Disable est activé et que Project ID et Project password sont saisis. La page des réglages affiche un avertissement tant que l'un d'eux manque. 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 abouti, mais aucune commande n'a été créée : la commande est créée par le callback Paysera, et non par le retour du client. Vérifiez que votre boutique est accessible depuis Internet à la Callback URL indiquée dans les réglages (et non derrière une connexion, une authentification de base ou un pare-feu), puis consultez le champ Log de la page du module.

Le callback répond Invalid signature : le Project password ne correspond pas au projet, ou le callback ne provient pas de Paysera. Copiez à nouveau le mot de passe de projet. Si vous avez modifié le projet ou le mot de passe, les paiements lancés avant la modification ne peuvent plus être vérifiés.

Le callback répond Project ID mismatch : le Project ID des réglages diffère du projet qui a effectué le paiement.

Le callback répond Order not found : le panier du callback n'a pas de paiement Paysera dans cette boutique, par exemple parce que le paiement a été lancé dans une autre boutique avec le même projet.

Le callback répond Gateway not configured, Busy ou Temporary error : l'identifiant ou le mot de passe du projet est vide, un autre callback pour le même panier est encore en cours, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Paysera relance le callback. Activez Debug log pour voir la raison.

Paysera refuse la fenêtre de paiement ou indique que le projet n'existe pas : vérifiez Environment. Un projet Paysera normal ne fonctionne qu'avec Production ; Sandbox nécessite un projet créé dans l'environnement sandbox de Paysera.

Le paiement de test ne règle pas la commande : un paiement TEST ne règle une commande que si Test payments est activé. Sinon, la commande est mise en attente avec une note indiquant qu'aucun argent n'a été débité. Activez aussi Allow test payments dans le projet Paysera.

Une commande est en Paysera payment on hold avec une note sur un écart de montant ou de devise : Paysera a confirmé un paiement dont le montant ou la devise diffère du total du panier, par exemple parce que le panier a été modifié dans un autre onglet après le début du paiement par le client. Comparez le paiement dans votre compte Paysera, puis acceptez la commande ou remboursez le paiement manuellement. Un paiement correct ultérieur pour la même commande la marque comme payée.

Le client voit Paysera payments are temporarily unavailable : consultez le champ Log. L'identifiant ou le mot de passe du projet peut être vide, ou l'une des adresses de la boutique envoyées à Paysera dépasse 255 caractères.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Paysera Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data 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 enregistrements de paiement Paysera et les statuts de commande Awaiting Paysera payment et Paysera payment on hold sont toujours conservés. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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