VibeFox Satispay for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Devise : EUR. Satispay n'encaisse qu'en euros ; le mode de paiement est donc masqué lorsque la devise du panier n'est pas l'EUR.

Compte Satispay : un compte Satispay Business. Vous ne copiez aucune clé API : le module se connecte avec un code d'activation à usage unique que vous générez dans le Satispay Business Dashboard (voir Configuration). Pour les tests, vous avez besoin d'un compte sandbox Satispay, que vous demandez à Satispay pour les développeurs.

Boutique publique : votre boutique doit être accessible depuis Internet, afin que Satispay puisse l'appeler lorsqu'un paiement change. Rien n'est à configurer dans Satispay pour cela.

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 Satispay Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Choisissez l'environnement : activez Sandbox Mode pour les tests, laissez-le désactivé pour les paiements réels.

5. Collez un code d'activation de cet environnement dans Activation Code et cliquez sur Save. Le champ Status affiche alors Connected avec le Key ID.

6. Activez Enable/Disable et cliquez sur Save. Testez un paiement dans le sandbox, puis désactivez Sandbox Mode et connectez l'environnement de production avec un code d'activation de production.

À l'installation, le module crée le statut de commande Satispay 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. Le module doit y être autorisé pour l'euro.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Satispay Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière.

Paiement

Ce que les clients voient dans la liste des modes de paiement.

Enable/Disable : Enable Satispay payment active ou désactive le mode de paiement. Par défaut : off.

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

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Connexion Satispay

Status : l'état des deux environnements, par exemple Live: Connected avec le Key ID ou Sandbox: Not connected, et l'environnement utilisé. Tant que l'environnement utilisé n'est pas connecté, le champ affiche Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode : utilise l'environnement sandbox (de test) de Satispay. Les paiements sandbox ne sont pas débités. Par défaut : off. Sandbox et production ont des clés séparées : connectez chaque environnement avec un code d'activation de cet environnement. Tant que le sandbox est utilisé, les clients voient Sandbox mode: no real money is charged. sous le mode de paiement.

Activation Code : pour connecter l'environnement sélectionné ci-dessus, collez un nouveau code d'activation à 6 caractères et cliquez sur Save. Les codes de production sont générés dans le Satispay Business Dashboard, section Online shop. Les codes sandbox sont fournis avec un compte sandbox Satispay. Le code est utilisé une seule fois et n'est pas stocké. Laissez le champ vide pour conserver la connexion actuelle.

Lorsque vous enregistrez avec un code, le module crée une paire de clés RSA, envoie la clé publique et le code à Satispay, puis stocke le Key ID et les clés de cet environnement dans la configuration de la boutique. Les clés privées ne sont jamais affichées. En cas de succès, la page affiche par exemple Satispay Live connected. Key ID: suivi de l'identifiant. Si Satispay rejette le code, la page affiche Satispay activation failed: avec le message de Satispay et vous demande de vérifier que le code correspond à cet environnement et n'a pas encore été utilisé. Un code contenant des caractères autres que des lettres et des chiffres est refusé avant tout envoi. Enregistrer un nouveau code pour un environnement remplace sa connexion précédente.

Notifications de paiement

Rien à configurer dans Satispay. Chaque paiement porte sa propre URL de callback, que Satispay appelle lorsque le paiement change, et le module relit le paiement depuis l'API Satispay avant de créer ou de modifier une commande. Le champ Callback URL affiche un exemple de cette URL. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}, éventuellement avec un code de langue comme /en/. L'URL doit être accessible depuis Internet : pas d'authentification basique devant elle. Le callback fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction par pays de votre boutique.

Avancé

Debug log : écrit les appels à l'API et les événements de paiement dans logs/satispay_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas journalisées. Les erreurs sont toujours journalisées, même lorsque l'option est désactivée. 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 on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages, les clés Satispay des deux environnements et le journal. Les paiements et remboursements Satispay enregistrés pour les commandes ainsi que le statut de commande Satispay payment on hold sont toujours conservés. Par défaut : off.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Satispay) et confirme la commande. Le module crée un paiement Satispay pour le total du panier en euros, avec le numéro du panier comme référence, et envoie le client vers la page de paiement Satispay. Sur un ordinateur, le client scanne le QR code avec l'application Satispay. Sur un téléphone, le client confirme le paiement dans l'application. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'une fois que Satispay l'a confirmé : le module relit le paiement depuis l'API Satispay, vérifie qu'il a été créé pour ce panier et compare son statut, son montant (en centimes) et sa devise avec ceux du panier. Cela se produit à la fois lorsque Satispay appelle l'URL de callback et lorsque le client revient, selon ce qui arrive en premier. La commande est alors créée et le client voit la page standard de confirmation de commande. Si Satispay n'a pas encore confirmé le paiement au retour du client, une page Payment confirmation affiche Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. ainsi qu'un bouton Check again. Le callback crée la commande dès son arrivée.

Si le client quitte la page Satispay sans payer, le module annule le paiement chez Satispay, de sorte que la page abandonnée ne peut plus être payée. Le client revient au paiement avec le message Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. Le même message s'affiche lorsque le client refuse le paiement dans l'application. Le panier est conservé.

Avant de créer un nouveau paiement Satispay pour le même panier, le précédent est vérifié : un paiement en attente est annulé chez Satispay et, s'il avait déjà été payé, la commande est créée avec lui sans effectuer de second paiement.

Si le paiement ne peut pas être lancé, le client reste au moment du paiement avec un message bref : Satispay is not available at the moment. Please choose another payment method. lorsque la boutique n'est pas connectée ou que Satispay rejette les clés, ou Unable to create the Satispay payment. Please try again or choose another payment method. pour les autres erreurs. La raison est écrite dans le journal.

Le module n'accepte que des paiements uniques en euros. Il ne gère ni abonnements, ni moyens de paiement enregistrés, ni pré-autorisations, ni titres-restaurant. Il n'existe pas de vérification programmée des paiements en attente : si ni le callback de Satispay ni le retour du client n'atteint votre boutique, aucune commande n'est créée, et le paiement reste visible dans le Satispay Dashboard.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Satispay et n'a pas payé, ou Satispay n'a pas encore confirmé le paiement. Seuls le panier et le paiement Satispay du module existent.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant du paiement Satispay comme ID de transaction, et une note indique le paiement Satispay, le montant et la manière dont il a été vérifié (callback, redirect or checkout).

Satispay payment on hold : Satispay a signalé un montant ou une devise différent du total du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement), ou le paiement a été accepté après l'annulation de la commande. L'argent reçu est enregistré sur la commande, et la note l'explique. Vérifiez le paiement dans le Satispay Dashboard, puis traitez la commande ou remboursez le paiement. Si un autre paiement du même panier, avec le bon montant, est accepté plus tard, la commande passe en Payment accepted.

Refunded : le paiement a été intégralement remboursé via le module.

Si un second paiement est accepté pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double depuis le Satispay Dashboard. Une confirmation répétée ne rouvre jamais une commande annulée ou remboursée.

Bloc de paiement Satispay

La page de commande affiche un bloc Satispay payment avec l'identifiant du paiement Satispay, son statut, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements, la liste Satispay payments of this cart avec chaque tentative de paiement et son environnement, ainsi que les Satispay notes de la commande.

Remboursements

Dans le bloc Satispay payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Satispay. Confirmez la question Refund this amount through Satispay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont limités au montant que Satispay a encaissé pour le paiement : après un écart de montant, vous pouvez donc rembourser jusqu'à concurrence de ce que le client a réellement payé, et non du total de la commande. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué (production ou sandbox), cet environnement doit donc toujours être connecté. Un remboursement n'est considéré comme effectué que lorsque Satispay l'accepte : un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant du remboursement Satispay et le motif. Si Satispay n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Satispay. Les remboursements effectués dans le Satispay Dashboard ne sont pas enregistrés dans PrestaShop. Mettez la commande à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Satispay Gateway est le premier bloc de Modules > Module Manager > VibeFox Satispay 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 valable 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-satispay 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, Satispay 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. La vitrine PrestaShop ne sait pas que vous êtes connecté au back office : le mode de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. 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 module continue de fonctionner, mais les mises à jour et le support 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 licence.

Dépannage

Satispay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'environnement utilisé est connecté (le champ Status affiche Connected pour lui) et que la devise du panier est l'EUR. Dans Payment > Preferences, vérifiez que le module est autorisé pour l'euro, 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 lorsque Satispay appelle votre boutique ou lorsque le client revient. Vérifiez que votre boutique est accessible depuis Internet, sans authentification basique devant l'URL de callback, et activez Debug log pour voir les callbacks dans le champ Log. Le paiement est visible dans le Satispay Dashboard.

Le callback répond Payment status unavailable, retry later. ou Not configured. : le module n'a pas pu lire le paiement depuis Satispay, ou l'environnement du paiement n'est pas connecté. Aucune commande n'est modifiée. Satispay rappelle. Vérifiez l'état de la connexion et le journal.

Le callback répond Busy, retry later. : le panier était en cours de confirmation par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Satispay rappelle. Le journal indique la raison.

Le callback répond Unknown payment. ou Missing or invalid payment_id. : le paiement n'a pas été créé par cette boutique pour ce panier, ou la requête n'est pas un callback Satispay. Rien n'est modifié.

L'activation échoue : les codes d'activation ne peuvent être utilisés qu'une fois. Vérifiez que le code appartient à l'environnement sélectionné dans Sandbox Mode (un code de production pour la production, un code sandbox pour le sandbox), générez un nouveau code et enregistrez à nouveau. Si la page indique qu'une paire de clés RSA n'a pas pu être générée, demandez à votre hébergeur d'activer l'extension OpenSSL de PHP. Si Satispay est injoignable, vérifiez que votre serveur peut ouvrir des connexions HTTPS sortantes.

Satispay a disparu du paiement après le passage du sandbox à la production : le sandbox et la production utilisent des clés différentes. Collez un code d'activation de production avec Sandbox Mode désactivé, puis enregistrez.

Le client voit This payment method is not available. : le mode de paiement n'est pas autorisé pour le panier (pays, devise ou groupe de clients dans Payment > Preferences), il est désactivé ou l'environnement utilisé n'est pas connecté.

La commande est Satispay payment on hold après le paiement : lisez les notes du bloc Satispay payment (voir Statuts de commande), vérifiez le paiement dans le Satispay Dashboard, puis traitez la commande ou remboursez le paiement.

Le remboursement échoue parce que l'environnement n'est plus connecté : le paiement a été effectué en production ou en sandbox, et cet environnement n'a plus de clés. Reconnectez-le avec un code d'activation, ou remboursez le paiement depuis le Satispay Dashboard.

Le remboursement échoue avec Satispay did not accept the refund : Satispay a renvoyé un statut autre que accepted. PrestaShop n'a pas enregistré le remboursement, et une note l'indique. Vérifiez-le dans le Satispay Dashboard.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Satispay 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, les clés Satispay des deux environnements et le journal sont supprimés. Si l'option est désactivée, tous les réglages et clés sont conservés pour une réinstallation ultérieure. Les paiements et remboursements Satispay enregistrés pour les commandes ainsi que le statut de commande Satispay payment on hold sont toujours conservés : les commandes payées auparavant peuvent donc être remboursées après une réinstallation, une fois l'environnement reconnecté. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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