VibeFox Moyasar for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 8.0 ou ultérieur, installé et activé. Avec une version plus ancienne de WooCommerce, le plugin affiche un avis et ne se charge pas.
PHP : 8.0 ou ultérieur.
Devise : la devise de la boutique ou de la commande doit être SAR, AED, USD, EUR, KWD, BHD ou OMR. Pour toute autre devise, le moyen de paiement est masqué lors du paiement.
Compte Moyasar : vous avez besoin des clés API secrètes de votre compte Moyasar (test et production). Seules les clés secrètes sont utilisées. La clé publiable n'est pas nécessaire, car le paiement a lieu sur la page Moyasar. Un webhook dans Moyasar Dashboard est recommandé (voir Configuration).
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 transférer le dossier wcp_moyasar_payment_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Moyasar > Manage, ou cliquez sur Settings sous le nom du plugin sur 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. Collez vos clés secrètes Moyasar et enregistrez. Configurez le webhook dans Moyasar Dashboard avec l'URL et le secret partagé affichés dans les réglages (voir Configuration).
6. Activez Enable/Disable. Passez une commande test en mode test, puis décochez Test mode.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Moyasar. Le titre de la page affiche un badge TEST MODE ou LIVE. Au-dessus des champs, la page vous avertit lorsque le mode actuel n'a pas de clé secrète (le moyen de paiement est alors masqué lors du paiement) ou lorsque la devise de la boutique n'est pas prise en charge, et affiche Test mode is active: payments are simulated, no money is charged. tant que le mode test est activé. Dans la liste des moyens de paiement, Moyasar est signalé comme nécessitant une configuration tant que le mode actuel n'a pas de clé secrète. À l'enregistrement, le plugin refuse une clé publiable, une clé de l'autre mode ou une clé contenant des espaces, conserve la valeur précédente et indique la raison. Il vous avertit également lorsque la passerelle est activée mais que la clé secrète du mode actuel est vide.
Général
Enable/Disable : Enable Moyasar active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement que voient les clients lors du paiement. Par défaut : Pay with Moyasar.
Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. En mode test, le paiement ajoute (Test mode: no real payment is made.).
Clés API
Copiez les clés secrètes depuis Moyasar Dashboard > Settings > API Keys. Les clés de test et de production sont distinctes. Le mode test n'utilise que la clé de test, et le mode production uniquement la clé de production.
Test mode : Enable test mode utilise la clé secrète de test : les paiements sont simulés et aucun argent n'est débité. Par défaut : activé. Désactivez-le pour accepter de vrais paiements avec la clé secrète de production.
Test secret key : la clé secrète du mode test. Elle commence par sk_test_.
Live secret key : la clé secrète du mode production. Elle commence par sk_live_.
Notifications de paiement (webhook)
Le webhook est recommandé, mais pas obligatoire. Les commandes sont aussi confirmées lorsque le client revient sur la boutique et par la notification de facture que Moyasar envoie automatiquement à votre boutique lorsque la facture est payée. Le webhook couvre les clients qui ferment leur navigateur avant de revenir et vous informe des remboursements effectués dans Moyasar Dashboard. Dans Moyasar Dashboard > Settings > Webhooks, ajoutez un webhook avec l'URL et le secret partagé de cette section, méthode HTTP POST.
Webhook URL : affichée en lecture seule avec un bouton Copy. Elle ressemble à https://your-site/wp-json/moyasar_p/v1/webhook. Méthode HTTP : POST.
Webhook shared secret : saisissez la même valeur que Shared secret du webhook dans Moyasar. Laissez le champ vide et enregistrez pour générer un secret aléatoire, puis cliquez sur Show et copiez-le dans Moyasar. Les webhooks sans le bon secret partagé sont rejetés.
Sélectionnez ces événements pour le webhook :
Aucun webhook ni aucune notification n'est accepté directement : pour chacun, le plugin lit la facture via l'API Moyasar avec la clé secrète du mode de la commande et vérifie qu'elle a été créée pour cette commande. Les paiements d'autres intégrations sur le même compte Moyasar sont ignorés.
Commandes
Status after payment : le statut de commande défini après un paiement confirmé. Le statut est appliqué immédiatement, sans second changement de statut.
Avancé
Debug log : Log API calls and notifications enregistre les détails dans WooCommerce > Status > Logs, source wcp_moyasar_payment_gateway. Les erreurs sont toujours journalisées. Les clés API, les données de carte et les données client ne sont jamais journalisées. Par défaut : désactivé.
Clean uninstall : Delete the plugin settings and logs when the plugin is deleted. Les données de paiement enregistrées sur les commandes (identifiants de facture et de paiement Moyasar) sont conservées, afin que les remboursements restent traçables. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut Pay with Moyasar) et passe sa commande. Le plugin crée une facture Moyasar pour le total de la commande dans la devise de la commande et envoie le client sur sa page de paiement. Là, le client paie avec n'importe quel moyen actif sur votre compte Moyasar, par exemple mada, Visa, Mastercard, Apple Pay ou STC Pay. La facture affiche Order, le numéro de commande et le nom de votre site.
La commande n'est marquée comme payée qu'après confirmation de Moyasar : le plugin lit la facture via l'API Moyasar et vérifie qu'elle est payée, qu'elle appartient à cette commande et qu'elle correspond exactement au montant et à la devise de la commande. Après le paiement, le client revient sur la page de confirmation de commande de votre boutique. S'il revient sans avoir payé (par exemple avec le bouton Précédent de la page de paiement), il retourne au paiement ou à la page Pay for order avec l'un de ces messages : The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method., ou, lorsque le paiement ne peut pas encore être vérifié, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again.
Un client peut payer à nouveau une commande non payée. Si la page de paiement encore ouverte de la commande correspond toujours au même montant et à la même devise, elle est réutilisée. Si le total de la commande a changé, l'ancienne page de paiement est annulée et une nouvelle est créée, de sorte que l'ancienne ne peut plus être payée. Si la facture précédente est déjà payée, la commande est confirmée au lieu de créer un nouveau paiement.
Si Moyasar ne peut pas démarrer le paiement, le client voit un court message, par exemple The Moyasar payment service is not responding. Please try again in a few minutes., et peut choisir un autre moyen de paiement. Les détails sont enregistrés dans le journal.
Le moyen de paiement fonctionne avec le paiement classique, le bloc Paiement et la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
Le plugin ne gère que les paiements uniques sur la page Moyasar. Il n'y a pas de formulaire de carte sur votre propre tunnel de commande, ni de cartes enregistrées ou de tokenisation, ni d'abonnements WooCommerce, ni d'autorisation et de capture séparées.
Commandes et remboursements
Statuts de commande
Pending payment : la facture a été créée et le client n'a pas encore payé. La note de commande affiche l'identifiant de la facture, le montant et le mode.
Processing, Completed or On hold : le paiement a été confirmé. Le statut suit Status after payment. La note de commande indique comment le paiement a été confirmé (webhook, notification de facture, retour du client ou paiement), l'identifiant de la facture, l'identifiant du paiement et le moyen de paiement. L'identifiant de transaction est l'identifiant de paiement Moyasar.
On hold after payment : Moyasar a signalé un montant ou une devise différent du total de la commande (la commande n'est pas marquée comme payée), ou la facture a été payée après l'annulation de la commande. La note de commande l'explique. Vérifiez le paiement dans Moyasar Dashboard, puis traitez la commande ou remboursez le paiement.
On hold before payment : Moyasar retient le paiement pour examen. La commande est mise à jour lorsque Moyasar a pris sa décision.
Failed : la dernière facture d'une commande non payée a échoué, expiré ou été annulée. Le client peut tenter de payer à nouveau.
Cancelled : la commande a été annulée par le client, par vous ou par le délai de réservation des stocks de WooCommerce. La facture Moyasar ouverte de la commande est également annulée, de sorte qu'elle ne peut plus être payée.
Une commande payée, annulée ou remboursée n'est jamais modifiée par des événements ultérieurs. Si une seconde facture d'une commande déjà payée est réglée (par exemple depuis deux onglets du navigateur), la commande n'est pas modifiée à nouveau. Une note vous invite à rembourser le doublon dans Moyasar Dashboard.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Pay with Moyasar (le bouton reprend le titre du moyen de paiement). Les remboursements totaux et partiels sont pris en charge pour les commandes payées avec Moyasar. Un remboursement total d'un paiement par carte effectué il y a moins de 2 heures est envoyé comme annulation (annulation avant règlement) ; sinon, il s'agit d'un remboursement. Le remboursement utilise la clé secrète du mode dans lequel le paiement a été effectué (test ou production), cette clé doit donc être renseignée. Avant de rembourser, le plugin vérifie le paiement auprès de Moyasar : sa devise, son statut et le montant encore remboursable. Si Moyasar n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement ou une annulation réussi est ajouté aux notes de commande.
Les remboursements et annulations effectués dans Moyasar Dashboard vous parviennent par le webhook. Si Moyasar indique un montant remboursé supérieur à celui de WooCommerce, une note est ajoutée à la commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser Refund via Pay with Moyasar.
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 > Moyasar. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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 cet emplacement dans votre compte vibefox.net.
Sans clé active, Moyasar 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. Les gestionnaires de la boutique connectés voient toujours le moyen 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 Extensions 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. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Moyasar n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose d'une clé secrète (Test secret key en mode test, Live secret key en mode production) et que la devise de la boutique ou de la commande est SAR, AED, USD, EUR, KWD, BHD ou OMR. La page de réglages affiche un avertissement lorsque la clé est manquante ou que la devise n'est pas prise en charge.
Le paiement a été effectué, mais la commande reste en Pending payment : les confirmations n'ont pas atteint votre boutique. Configurez le webhook : dans Moyasar Dashboard, vérifiez qu'il existe, que son URL correspond exactement à la Webhook URL des réglages, que la méthode est POST, que les quatre événements sont sélectionnés et que son secret partagé est identique à Webhook shared secret. La commande est aussi confirmée lorsque le client revient sur la boutique et lorsqu'il tente de payer à nouveau la même commande.
Le webhook répond Unauthorized : le secret partagé dans Moyasar est différent de Webhook shared secret. Cliquez sur Show, copiez la valeur et collez-la dans le webhook de Moyasar.
Le webhook répond Webhook secret not configured : les réglages n'ont pas encore été enregistrés avec un secret partagé. Enregistrez les réglages pour en générer un, puis copiez-le dans Moyasar.
Le webhook répond Key not configured : la commande a été payée dans un mode (test ou production) dont la clé secrète est vide. Saisissez cette clé.
Le webhook répond Verification failed ou Try again later : la facture n'a pas pu être lue via l'API Moyasar, ou la commande était en cours de mise à jour par une autre requête au même moment. Moyasar relance le webhook.
Erreur lors de l'enregistrement concernant la clé : une clé publiable (pk_...) ou une clé de l'autre mode a été collée. La valeur précédente a été conservée. Les clés de test commencent par sk_test_, les clés de production par sk_live_.
Le client voit une erreur lors de la commande : activez Debug log et consultez WooCommerce > Status > Logs, source wcp_moyasar_payment_gateway. This payment method is temporarily unavailable. Please choose another payment method or contact us. signale généralement une clé secrète incorrecte ou manquante. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. signifie que la commande a déjà une facture payée qui doit être examinée par vos soins.
La commande est On hold after payment : lisez la note de commande. Le montant ou la devise payés différaient de la commande, ou le paiement est arrivé après l'annulation de la commande. Traitez la commande ou remboursez le paiement.
Le remboursement échoue : lisez le message. Si le paiement a été effectué dans l'autre mode, saisissez la clé secrète de ce mode. Si le montant est supérieur au montant encore remboursable chez Moyasar, une partie du paiement a déjà été remboursée, par exemple dans Moyasar Dashboard. Si Moyasar n'a pas confirmé le montant remboursé, vérifiez le paiement dans Moyasar Dashboard avant de réessayer.
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 injoignable, 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 sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Clean 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.
Moyasar est une marque commerciale de son propriétaire respectif. Ce plugin n'est ni affilié à Moyasar ni approuvé par Moyasar.