VibeFox Satispay for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et actif. Le plugin refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur avec l'extension OpenSSL. Sans OpenSSL, le plugin affiche une erreur dans l'administration et le mode de paiement n'est pas chargé.

Devise : EUR. Satispay n'encaisse qu'en euros ; le mode de paiement est donc masqué lorsque la devise de la boutique (ou, sur la page Pay for order, la devise de la commande) n'est pas EUR.

Compte Satispay : un compte Satispay Business. Vous ne copiez aucune clé API : le plugin se connecte avec un code d'activation à usage unique que vous générez dans le Satispay Business Dashboard (voir Configuration). Pour les tests, il vous faut un compte sandbox Satispay, à demander auprès de Satispay for developers.

Site public : votre site 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_satispay_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Satispay > Manage, ou cliquez sur Settings sous le nom du plugin dans la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Choisissez l'environnement : cochez Sandbox Mode pour les tests, laissez-le décoché pour les paiements réels.

6. Collez un code d'activation de cet environnement dans Activation Code et enregistrez. L'état de la connexion affiche alors le Key ID.

7. Activez Enable/Disable et enregistrez. Testez un paiement en sandbox, puis décochez Sandbox Mode et connectez l'environnement de production avec un code d'activation de production.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Satispay. La section Satispay connection affiche l'état des deux environnements, par exemple Live: Connected avec le Key ID ou Sandbox: Not connected, et indique l'environnement utilisé. Tant que l'environnement utilisé n'est pas connecté, la page indique : Satispay est masqué au paiement tant que l'environnement utilisé n'est pas connecté. Dans la liste des modes de paiement de WooCommerce, Satispay est signalé comme nécessitant une configuration tant que l'environnement utilisé n'est pas connecté, et affiche un badge de mode test tant que Sandbox Mode est activé.

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

Checkout

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

Title : le nom du mode de paiement affiché au paiement. Par défaut : Satispay.

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.

Satispay connection

Sandbox Mode : Use the Satispay sandbox (staging) environment. Les paiements sandbox ne sont pas débités. Par défaut : désactivé. Le sandbox et la 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 Mode sandbox : aucun argent réel n'est débité. 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 enregistrez. Les codes de production sont générés dans le Satispay Business Dashboard, section Online shop. Les codes sandbox proviennent d'un compte sandbox Satispay. Le code n'est utilisé qu'une fois et n'est pas enregistré. Laissez le champ vide pour conserver la connexion actuelle.

Lorsque vous enregistrez avec un code, le plugin crée une paire de clés RSA, envoie la clé publique et le code à Satispay, et enregistre dans la base de données WordPress le Key ID ainsi que les clés de cet environnement. En cas de succès, la page affiche par exemple Satispay Live connected. Key ID: suivi de l'identifiant. Si Satispay refuse le code, la page affiche le message de Satispay et vous invite à vérifier que le code correspond à cet environnement et n'a pas encore été utilisé. Un code contenant d'autres caractères que des lettres et des chiffres est refusé avant tout envoi. Enregistrer un nouveau code pour un environnement remplace sa connexion précédente.

Payment notifications

Rien à configurer dans Satispay. Chaque paiement porte sa propre URL de callback, que Satispay appelle lorsque le paiement change, et le plugin relit le paiement depuis l'API Satispay avant de modifier une commande. La section affiche un exemple de cette URL. Elle ressemble à ceci : https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}. L'URL doit être accessible depuis Internet : pas de mode maintenance ni de protection par mot de passe sur /wc-api/.

Advanced

Debug log : Log API calls and payment events écrit dans WooCommerce > Status > Logs, source wcp_satispay_gateway, sans clés ni données clients. Les erreurs sont toujours journalisées, même si cette option est désactivée. Par défaut : désactivé.

Delete data on uninstall : Remove the settings and Satispay keys when the plugin is deleted. Les données de paiement enregistrées sur les commandes sont conservées. Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut Satispay) et clique sur Pay with Satispay. Le plugin crée un paiement Satispay pour le total de la commande en euros, avec le numéro de commande comme référence, puis envoie le client sur 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.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation de Satispay : le plugin relit le paiement depuis l'API Satispay, vérifie qu'il a été créé pour cette commande et compare son statut, son montant (en centimes) et sa devise à ceux de la commande. Cela se produit lorsque Satispay appelle l'URL de callback et lorsque le client revient, selon ce qui arrive en premier. Si le paiement n'est pas encore confirmé, la page de réception de commande affiche : Satispay n'a pas encore confirmé votre paiement. La commande sera mise à jour automatiquement dès que la confirmation arrivera.

Si le client quitte la page Satispay sans payer, le plugin annule le paiement chez Satispay, de sorte que la page abandonnée ne peut plus être payée. Le client est renvoyé au paiement (ou à la page Pay for order) avec le message : Votre paiement Satispay a été annulé et rien n'a été débité. Vous pouvez réessayer ou choisir un autre mode de paiement. Le même message s'affiche si le client refuse le paiement dans l'application.

Un client peut payer à nouveau une commande non payée, par exemple depuis la page Pay for order. Avant la création d'un nouveau paiement Satispay, le précédent est vérifié : un paiement en attente est annulé chez Satispay, et s'il a déjà été payé, la commande est marquée comme payée avec ce paiement, sans créer de second paiement.

Si le paiement ne peut pas être lancé, le client voit un bref message et peut choisir un autre mode de paiement : Satispay n'est pas disponible pour le moment. Veuillez choisir un autre mode de paiement. lorsque la boutique n'est pas connectée ou que Satispay refuse les clés, ou Impossible de créer le paiement Satispay. Veuillez réessayer ou choisir un autre mode de paiement. pour les autres erreurs. La raison est écrite dans le journal.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

Le plugin 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 site, la commande reste « En attente de paiement », et le paiement est visible dans le Satispay Dashboard.

Commandes et remboursements

Order statuses

Pending payment : le client a été envoyé vers Satispay et n'a pas encore payé, ou Satispay n'a pas encore confirmé le paiement. La note de commande affiche l'identifiant du paiement Satispay, le montant et l'environnement (Live ou Sandbox).

Processing or Completed : le paiement a été confirmé. La commande suit la règle standard de WooCommerce : « En cours », ou « Terminée » pour les commandes ne contenant que des produits téléchargeables virtuels. La note de commande affiche le paiement Satispay, le montant et la méthode de vérification (callback, redirection ou paiement). L'identifiant de transaction est l'identifiant du paiement Satispay.

On hold : Satispay a signalé un montant ou une devise différent du total de la commande, ou le paiement a été accepté après l'annulation de la commande. La note de commande l'explique, et le paiement est enregistré comme identifiant de transaction, afin de pouvoir être remboursé. Vérifiez le paiement dans le Satispay Dashboard, puis finalisez la commande ou remboursez le paiement.

Cancelled : le dernier paiement Satispay de la commande a été annulé ou a expiré, par exemple parce que le client a quitté la page Satispay. Un paiement plus ancien qui expire n'annule pas une commande dont un paiement plus récent est en cours. Les commandes que vous avez créées dans l'administration (liens de paiement) ne sont pas annulées : elles restent « En attente de paiement » avec une note, afin que le client puisse toujours les régler.

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.

Refunds

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Satispay. Les remboursements totaux et partiels sont pris en charge pour les commandes payées avec Satispay. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué (production ou sandbox), cet environnement doit donc rester connecté. Un remboursement n'est considéré comme effectué que si Satispay l'accepte : un remboursement réussi est ajouté aux notes de la commande avec l'identifiant du remboursement Satispay et le motif. Si Satispay n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré.

Les remboursements effectués dans le Satispay Dashboard ne sont pas convertis en remboursements WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser Refund via Satispay.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Satispay. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Satispay n'est pas affiché aux clients au moment du paiement. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés de la boutique voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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 plugin continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Satispay n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'environnement utilisé est connecté (la section Satispay connection affiche Connected pour lui) et que la devise est EUR.

Le paiement a été effectué, mais la commande reste « En attente de paiement » : la commande est mise à jour lorsque Satispay appelle votre site ou lorsque le client revient. Vérifiez que votre site est accessible depuis Internet, sans mode maintenance ni protection par mot de passe sur /wc-api/, et consultez WooCommerce > Status > Logs, source wcp_satispay_gateway. Le paiement est visible dans le Satispay Dashboard.

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

Le callback répond Busy, retry later : la commande était en cours de mise à jour par une autre requête au même moment. La commande n'est pas modifiée par ce callback. Elle sera mise à jour par le callback suivant ou lorsque le client reviendra.

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

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 PHP OpenSSL.

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, Sandbox Mode étant décoché, puis enregistrez.

La commande est On hold et la note ne correspond pas à la commande : Satispay a signalé un montant ou une devise différent du total de la commande, par exemple parce que la commande a été modifiée après le lancement du paiement. Vérifiez le paiement dans le Satispay Dashboard, puis finalisez 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. WooCommerce n'a pas enregistré le remboursement. Vérifiez-le dans le Satispay Dashboard.

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 inaccessible, le plugin continue de fonctionner avec le dernier statut connu.

Désinstallation

Désactiver le plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le depuis la page Plugins. La clé de licence et l'état de licence de ce plugin sont toujours supprimés. Les réglages de la passerelle, les clés Satispay des deux environnements et les journaux du plugin ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Satispay est une marque déposée de son titulaire. Ce plugin n'est ni affilié à Satispay ni approuvé par Satispay.