VibeFox PayMongo 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 : peso philippin (PHP). PayMongo n'est affiché au paiement que pour les paniers en PHP. Si la devise par défaut de votre boutique n'est pas PHP, la page de configuration vous en avertit, et vos clients doivent passer en PHP pour voir PayMongo.

Compte PayMongo : vous avez besoin des clés API secrètes de votre compte PayMongo et d'un webhook pour chaque mode (voir Configuration). Seules les clés secrètes (sk_test_..., sk_live_...) et les secrets de signature des webhooks (whsk_...) sont utilisés. Les clés publiques ne sont pas nécessaires, car la page de paiement est hébergée par PayMongo. Les modes de paiement que vous proposez doivent être activés pour votre compte PayMongo.

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 PayMongo 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 PayMongo, créez les webhooks dans PayMongo et collez leurs secrets de signature (voir Configuration).

5. Sélectionnez les modes de paiement, activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test mode activé, puis désactivez-le.

À l'installation, le module crée deux statuts de commande, Awaiting PayMongo payment et PayMongo payment on hold. Dans Payment > Preferences, vérifiez que le module est autorisé pour le peso philippin, les pays de vos clients et leurs groupes de clients.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PayMongo 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 la devise par défaut de la boutique n'est pas PHP, lorsque le mode actuel n'a pas de clé secrète (PayMongo n'est alors pas affiché au paiement) ou pas de secret de webhook (les paiements ne sont alors confirmés que lorsque le client revient dans votre boutique), et affiche Test mode is on: no real payments are made. tant que le mode test est activé.

PayMongo

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

Title: le nom du mode de paiement que voient les clients au moment du paiement. C'est aussi le nom enregistré dans la commande. Par défaut : PayMongo (Card, GCash, GrabPay, Maya). Obligatoire.

Description: le texte affiché sous le mode de paiement au moment du paiement. Par défaut : You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: les modes proposés sur la page de paiement PayMongo. Ne sélectionnez que les modes activés pour votre compte PayMongo, sinon PayMongo refuse le paiement. Si aucun n'est sélectionné, les valeurs par défaut sont utilisées. Par défaut : Cards, GCash, GrabPay and Maya.

Clés API

Copiez les clés secrètes depuis PayMongo Dashboard > Developers > API keys. Les clés publiques ne sont pas nécessaires. Chaque clé doit commencer par le préfixe attendu. Une valeur avec un mauvais préfixe n'est pas enregistrée : la page indique que le champ must start with le préfixe et que The previous value was kept.

Test mode: Enable test mode (no real payments). Les nouveaux paiements utilisent les clés de test. Les paiements effectués auparavant conservent le mode dans lequel ils ont été réalisés : les vérifications de statut et les remboursements utilisent donc la clé correspondante. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements.

Test secret key: la clé secrète du mode test. Elle commence par sk_test_.

Test webhook secret: le secret de signature du webhook du mode test. Il commence par whsk_.

Live secret key: la clé secrète du mode production. Elle commence par sk_live_.

Live webhook secret: le secret de signature du webhook du mode production. Il commence par whsk_.

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 pour la modifier.

Clear saved secrets: cochez une clé ou un secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Webhook

Le webhook informe votre boutique qu'un paiement a été effectué, y compris lorsque le client ferme le navigateur après avoir payé. Créez un webhook dans le tableau de bord PayMongo (ou via l'API PayMongo) pour chaque mode, test et production, avec l'URL affichée sous Webhook URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_paymongo_payment_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages.

Sélectionnez ces événements (ils sont aussi listés dans cette section) :

Copiez le secret de signature (whsk_...) de chaque webhook dans Test webhook secret ou Live webhook secret. Les webhooks sans signature valide sont rejetés. La signature est vérifiée avec le secret de son propre mode, et le mode de l'événement doit correspondre, de sorte qu'un webhook test ne confirme jamais un paiement réel. Chaque événement est à nouveau vérifié via l'API PayMongo avec la clé secrète du mode du paiement avant qu'une commande ne soit créée ou modifiée. PayMongo envoie les événements de tout le compte à chaque webhook ; les événements des paiements qui n'ont pas été lancés dans cette boutique sont ignorés. Sans webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Commandes

Order status after payment: le statut de commande défini après un paiement réussi.

Les paiements encore en cours de traitement attendent en Awaiting PayMongo payment. Les écarts de montant ou de devise et les paiements test sur une boutique en production vont toujours en PayMongo payment on hold.

Avancé

Debug log: enregistre les appels à l'API PayMongo et les événements de webhook dans logs/paymongo_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours enregistrés, même lorsque l'option est désactivée. Les clés et les données clients ne sont jamais enregistrées. Par défaut : désactivé.

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 et le journal. Les identifiants PayMongo enregistrés pour les commandes, les remboursements et les statuts de commande du module sont toujours conservés, car ils sont nécessaires aux remboursements et à la comptabilité. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut PayMongo (Card, GCash, GrabPay, Maya)) et voit sa description. En mode test, le paiement affiche également Test mode: no real payment will be made. PayMongo n'est proposé que pour les paniers en PHP d'un montant total d'au moins 100,00 ₱.

Après confirmation, le module crée une Checkout Session PayMongo pour le total du panier en PHP, avec une ligne Cart # et le numéro du panier, puis envoie le client sur la page de paiement PayMongo. Le nom, l'adresse e-mail, le téléphone et l'adresse de facturation du client sont transmis à PayMongo. Là, le client choisit l'un des modes sélectionnés et paie. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par PayMongo : le module interroge l'API PayMongo sur le paiement lorsque le client revient et lorsque le webhook arrive. La commande est alors créée, et le client voit la page standard de confirmation de commande avec Your PayMongo payment has been received. Si PayMongo traite encore le paiement lorsque le client revient, la commande est créée en Awaiting PayMongo payment et la page affiche PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Si ce paiement échoue par la suite, la page affiche Your PayMongo payment was not completed. Please contact us about this order. Si PayMongo est injoignable lorsque le client revient, une page Payment confirmation lui demande de ne pas payer à nouveau et affiche un bouton Check again ; le webhook crée la commande dès son arrivée.

Si le client annule sur la page PayMongo ou ne termine pas le paiement, il revient au paiement avec You cancelled the PayMongo payment. You can try again or choose another payment method. ou Your PayMongo payment was not completed. You can try again or choose another payment method. Le panier est conservé. Une nouvelle tentative vérifie d'abord la précédente : si elle a été payée entre-temps, la commande est créée sans nouveau paiement ; sinon, le lien de paiement PayMongo précédent expire, de sorte que le panier ne peut pas être payé deux fois. Tant que le paiement précédent est encore en cours de traitement, le client voit Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

Si PayMongo ne peut pas démarrer le paiement, le client reste au paiement avec un bref message, par exemple The payment could not be started. Please try again or choose another payment method. ou PayMongo could not be reached. Please try again in a moment. La raison technique est écrite dans le journal.

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

Le module accepte les paiements uniques sur la page PayMongo. Il ne prévoit ni champs de carte sur votre propre page de paiement, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni paiements échelonnés, ni autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

No order yet: le client a été envoyé vers PayMongo et n'a pas encore payé, ou PayMongo n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted or Delivered: le paiement a été confirmé. Le statut suit Order status after payment. Le paiement est enregistré avec l'identifiant de paiement PayMongo (pay_...) comme ID de transaction, et une note indique le paiement, le montant, le moyen de paiement, le mode et la manière dont il a été confirmé (webhook ou retour).

Awaiting PayMongo payment: le client est revenu alors que PayMongo traitait encore le paiement. La commande passe au statut payé lorsque PayMongo le confirme.

PayMongo payment on hold: le montant ou la devise payés ne correspondent pas au total du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement) ; ou un paiement a été effectué en mode test alors que la boutique était en mode production, de sorte qu'aucun argent n'a été reçu et qu'aucun paiement n'est enregistré ; ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Payment error: un webhook payment.failed signé indiquait que la dernière tentative de paiement d'une commande en Awaiting PayMongo payment a échoué. La note affiche le code d'erreur et le message de PayMongo. Si le même paiement réussit plus tard, la commande passe au statut payé.

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

Si un second paiement arrive pour une commande déjà payée, par exemple via un ancien lien de paiement, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans le tableau de bord PayMongo. Une commande payée puis annulée ou remboursée n'est jamais rouverte.

Bloc PayMongo payment

La page de commande affiche un bloc PayMongo payment avec l'identifiant et le moyen de paiement PayMongo, le payment intent, le checkout, le mode, le statut, le montant payé et le montant remboursé, un badge Test mode pour les paiements test, les notes PayMongo de la commande et l'historique des remboursements.

Remboursements

Dans le bloc PayMongo payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via PayMongo. Confirmez la question Refund this amount through PayMongo? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, avec deux décimales maximum. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Les remboursements sont limités au montant effectivement débité par PayMongo : après un écart de montant, vous pouvez donc rembourser jusqu'au montant payé par le client, et non le total de la commande. Le remboursement est envoyé avec la clé secrète du mode dans lequel le paiement a été effectué (test ou production), donc cette clé doit être renseignée. Le motif que vous saisissez est transmis à PayMongo comme note de remboursement. Si PayMongo refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant et le statut du remboursement PayMongo. 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 PayMongo. Les remboursements effectués dans le tableau de bord PayMongo ne sont pas reportés dans PrestaShop. Effectuez le remboursement depuis le bloc de la commande, ou mettez la commande à jour manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PayMongo Payment Gateway est le premier bloc de la page Modules > Module Manager > VibeFox PayMongo 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) 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. Sous ces boutons figurent la ligne Product: presta-payment-paymongo 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, PayMongo 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. 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 paiement. Un rappel apparaît dans Modules > Module Manager, sur 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é à nouveau 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

PayMongo n'apparaît pas au 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), que le panier est en PHP et que le total est d'au moins 100,00 ₱. 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 : le webhook ne fonctionne pas et le client n'est pas revenu dans la boutique. Dans le tableau de bord PayMongo, vérifiez qu'un webhook existe dans le mode utilisé, que son URL est exactement celle affichée sous Webhook URL et que les trois événements sont sélectionnés. Vérifiez que son secret de signature se trouve dans le champ correspondant (Test webhook secret ou Live webhook secret).

Le webhook répond Invalid signature : le secret de signature de ce mode est absent ou appartient à un autre webhook. Collez le secret de signature du webhook dans le champ de son mode.

Le webhook répond Mode mismatch : un événement test a été signé comme réel, ou l'inverse. Vérifiez que chaque webhook appartient au bon mode.

Le webhook répond Temporary error : le paiement n'a pas pu être vérifié via l'API PayMongo, par exemple parce que la clé secrète du mode du paiement est absente. PayMongo relance automatiquement le webhook.

Le webhook répond Busy, retry : la commande é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, parce que le module est désactivé). PayMongo relance automatiquement le webhook. La raison figure dans le Log.

Le webhook répond Ignored : l'événement appartient à un paiement qui n'a pas été lancé dans cette boutique, ou à un autre mode. Rien n'est modifié.

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

La valeur n'a pas été enregistrée : une clé a été collée dans le mauvais champ. Les clés secrètes commencent par sk_test_ ou sk_live_, les secrets de webhook par whsk_.

Le client voit une erreur en choisissant PayMongo : consultez le champ Log sur la page du module. Une mauvaise clé secrète affiche le message indiquant que le mode de paiement est temporairement indisponible. Un mode de paiement non activé pour votre compte PayMongo fait refuser le paiement par PayMongo ; retirez-le de Payment methods.

Paiements test sur une boutique en production : un paiement test reçu alors que la boutique est en mode production place la commande en PayMongo payment on hold avec une note indiquant qu'aucun argent n'a été reçu. Les paiements réels sont toujours reconnus, y compris après le retour au mode test, et sont remboursés avec la clé de production.

La commande est en PayMongo payment on hold après le paiement : lisez les notes du bloc PayMongo payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou production, et la clé secrète de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Les développeurs peuvent modifier les données de la Checkout Session avec le hook actionPaymongoPCheckoutSessionData.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PayMongo Payment 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 et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les identifiants PayMongo des commandes, les remboursements et les statuts de commande Awaiting PayMongo payment et PayMongo payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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