VibeFox Moyasar for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Devise : la devise du panier doit être SAR, AED, USD, EUR, KWD, BHD ou OMR. Pour toute autre devise, le moyen de paiement est masqué à l'étape de commande.

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é publique 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 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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Moyasar Payment 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. Collez vos clés secrètes Moyasar et cliquez sur Save. Configurez le webhook dans Moyasar Dashboard (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Passez une commande test en mode test, puis désactivez Test mode.

À l'installation, le module crée deux statuts de commande : Awaiting Moyasar payment et Moyasar 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 Moyasar Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. 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é à l'étape de commande), lorsqu'aucun secret partagé du webhook n'est enregistré (le webhook rejette alors tous les appels) ou lorsque la devise par défaut de la boutique n'est pas prise en charge. Lorsque le module est activé en mode test, il affiche Test mode is active: payments are simulated, no money is charged. Lors de l'enregistrement, le module refuse une clé publique, une clé de l'autre mode ou une clé contenant des espaces, conserve la valeur précédente et indique la raison.

Moyasar

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

Title : le nom du moyen de paiement affiché au client à l'étape de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Pay with Moyasar. Obligatoire.

Description : le texte affiché sous le moyen de paiement à l'étape de commande. 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, l'étape de commande 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 ; le mode production n'utilise que la clé de production.

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_.

Les clés et secrets 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 si vous souhaitez la modifier.

Notifications de paiement (webhook)

Le webhook est recommandé, sans être obligatoire. Les commandes sont aussi confirmées lorsque le client revient dans 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 signale les remboursements effectués dans Moyasar Dashboard. Ajoutez-le dans Moyasar Dashboard > Settings > Webhooks.

Webhook URL : affichée en lecture seule avec un bouton Copy. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_moyasar_payment_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages. Méthode HTTP : POST.

Webhook shared secret : saisissez la même valeur que Shared secret du webhook dans Moyasar. Si rien n'est enregistré, Save génère un secret aléatoire ; Generate a new secret remplace le secret enregistré. Un secret généré n'est affiché qu'une seule fois, au-dessus des réglages, après l'enregistrement, puis jamais plus : copiez-le immédiatement dans Moyasar. Les webhooks sans le bon secret partagé sont rejetés.

Sélectionnez ces événements pour le webhook (ils sont également listés dans cette section) :

Aucune donnée d'un webhook ou d'une notification n'est acceptée telle quelle : pour chacun, le module lit la facture via l'API Moyasar avec la clé secrète du mode dans lequel la facture a été créée, et vérifie qu'elle a été créée pour ce panier. Les paiements d'autres intégrations sur le même compte Moyasar sont ignorés. Un seul secret partagé sert aux deux modes.

Commandes

Status after payment : le statut de commande attribué après un paiement confirmé. La commande est créée directement dans ce statut.

Avancé

Clear saved secrets : cochez Test secret key, Live secret key ou Webhook shared secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Debug log : journalise les appels à l'API et les notifications dans logs/moyasar_p_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés. Les clés API, les données de carte et les données client ne sont jamais journalisées. Par défaut : désactivé.

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

Clean uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages du module et le journal. Les données de paiement enregistrées avec les commandes (identifiants de facture et de paiement Moyasar) sont conservées, afin que les remboursements restent traçables. Par défaut : désactivé.

Étape de commande

À l'étape du paiement, le client choisit le moyen de paiement (par défaut Pay with Moyasar) et confirme. Le module crée une facture Moyasar pour le total du panier, dans la devise du panier, et envoie le client sur sa page de paiement. Il y paie avec l'un des moyens actifs sur votre compte Moyasar. La facture affiche Order #, le numéro du panier et le nom de votre boutique. À ce stade, aucune commande n'existe encore.

La commande n'est marquée comme payée qu'après la confirmation de Moyasar : le module lit la facture via l'API Moyasar et vérifie qu'elle est payée, qu'elle appartient à ce panier et qu'elle correspond exactement au montant et à la devise du panier. La commande est alors créée, et le client voit la page standard de confirmation de commande avec Your payment with Moyasar has been received. Si Moyasar retient le paiement pour examen, la page affiche Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Si la commande est en attente de votre examen, la page indique que le paiement a été reçu et que la commande est en cours d'examen. Si un paiement en cours d'examen échoue ensuite, ou si la commande non payée est annulée, la page affiche Your Moyasar payment was not completed. Please contact us about this order.

Si le client revient sans payer (par exemple avec le bouton retour de la page de paiement), il retrouve l'étape de commande 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. Le panier est conservé.

Le client peut réessayer. Si la page de paiement ouverte du panier affiche toujours le même montant et la même devise, elle est réutilisée. Si le total du panier a changé, l'ancienne page de paiement est annulée chez Moyasar et une nouvelle est créée, de sorte que l'ancienne ne peut plus être payée. Si la facture précédente s'avère déjà payée, la commande est créée au lieu d'un nouveau paiement.

Si Moyasar ne peut pas démarrer le paiement, le client reste à l'étape de commande avec un bref 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 écrits dans le journal.

Le webhook et la notification de facture fonctionnent lorsque la boutique est en mode maintenance et ne sont pas bloqués par la restriction géographique de votre boutique.

Le module n'accepte que les paiements uniques sur la page Moyasar. Il n'a pas de formulaire de carte sur votre propre étape de commande, pas de cartes enregistrées ni de tokenisation, pas d'abonnements et pas d'autorisation et de capture séparées.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé vers Moyasar et n'a pas payé, ou Moyasar n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted, Delivered ou Moyasar payment on hold : le paiement a été confirmé. Le statut suit Status after payment. Le paiement est enregistré avec l'identifiant de paiement Moyasar comme identifiant de transaction, et une note indique comment le paiement a été confirmé (webhook, notification de facture, retour du client ou étape de commande), ainsi que l'identifiant de la facture, l'identifiant du paiement et le moyen de paiement.

Awaiting Moyasar payment : Moyasar retient le paiement pour examen. La commande passe au statut payé lorsque Moyasar confirme le paiement.

Erreur de paiement : le paiement en cours d'examen a échoué.

Moyasar payment on hold after payment : Moyasar 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 la facture a été payée après que vous avez annulé la commande. La commande n'est pas marquée comme payée, mais le montant réellement reçu est enregistré lorsqu'il est dans la devise de la commande. La note l'explique. Vérifiez le paiement dans Moyasar Dashboard, puis traitez la commande ou remboursez le paiement.

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

Une commande payée n'est jamais remise en arrière par des événements ultérieurs. Si une seconde facture d'un panier déjà payé est également réglée (par exemple depuis deux onglets du navigateur), la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans Moyasar Dashboard.

Bloc de paiement Moyasar

La page de commande affiche un bloc Moyasar payment avec l'identifiant de la facture Moyasar, l'identifiant du paiement, le moyen (par exemple la marque de la carte et les quatre derniers chiffres), le statut, les montants payés et remboursés, un badge Test mode pour les paiements de test, l'historique des remboursements et les Moyasar notes de la commande.

Remboursements

Dans le bloc Moyasar payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Moyasar. Confirmez la question Refund this amount through Moyasar? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont effectués dans le montant et la devise débités par Moyasar : après un écart de montant, vous pouvez donc rembourser jusqu'à ce que le client ait réellement payé, et non le total de la commande. Un remboursement total d'un paiement par carte effectué il y a moins de 2 heures est envoyé sous forme d'annulation (void) : une annulation avant règlement, sans frais. 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. Le module vérifie d'abord chez Moyasar la devise, le statut et le montant remboursable du paiement. Si Moyasar n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement ou une annulation réussi est ajouté à l'historique des remboursements et aux notes. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Moyasar a confirmé le paiement.

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 Moyasar.

Les remboursements et annulations effectués dans Moyasar Dashboard arrivent par le webhook. Si Moyasar indique un montant remboursé supérieur à celui enregistré par le module, une note est ajoutée à la commande. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à jour manuellement si nécessaire, sans utiliser Refund via Moyasar.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Moyasar Payment Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Moyasar Payment 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. Sous ces boutons se trouvent la ligne Product: presta-payment-moyasar et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant du droit 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, Moyasar n'est pas proposé aux clients à l'étape de commande. 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, donc le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de 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, et les remboursements fonctionnent.

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

Moyasar n'apparaît pas à l'étape de commande : 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 du panier est SAR, AED, USD, EUR, KWD, BHD ou OMR. La page des réglages affiche un avertissement lorsque la clé est absente ou que la devise de la boutique n'est pas prise en charge. 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 : les confirmations n'ont pas atteint votre boutique. Configurez le webhook : dans Moyasar Dashboard, vérifiez qu'il existe, que son URL est 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 à celui enregistré dans Webhook shared secret. La commande est aussi créée lorsque le client revient dans la boutique ou tente de payer à nouveau le même panier.

Le webhook répond Unauthorized : le secret partagé dans Moyasar diffère de celui enregistré. Saisissez le secret du webhook Moyasar dans Webhook shared secret et enregistrez, ou cochez Generate a new secret, enregistrez, puis collez dans Moyasar le secret affiché.

Le webhook répond Webhook secret not configured : aucun secret partagé n'est enregistré, par exemple après sa suppression avec Clear saved secrets. Cliquez sur Save pour en générer un et copiez-le dans Moyasar.

Le webhook répond Key not configured : la facture a été créé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, le panier était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Moyasar réessaie le webhook. Activez Debug log pour voir la raison.

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

Erreur à l'enregistrement concernant la clé : une clé publique (pk_...) ou une clé de l'autre mode a été collée, ou la clé contient des espaces. 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 en choisissant Moyasar : activez Debug log et consultez le champ Log sur la page du module. This payment method is temporarily unavailable. Please choose another payment method or contact us. signale en général une clé secrète incorrecte ou absente. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. signifie que le panier a déjà une facture payée qui n'a pas pu être transformée en commande ; consultez le journal.

Order is Moyasar payment on hold after payment : lisez les Moyasar notes dans le bloc Moyasar payment. Le montant ou la devise payé(e) différait du panier, ou le paiement est arrivé après l'annulation de la commande. Traitez la commande ou remboursez le paiement.

Échec du remboursement : 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.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Moyasar Payment Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Clean uninstall 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 factures, paiements et remboursements Moyasar, ainsi que les statuts de commande Awaiting Moyasar payment et Moyasar payment on hold, sont toujours conservés, afin que les anciennes commandes puissent être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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