VibeFox PayMongo for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise : peso philippin (PHP). Le mode de paiement est masqué lorsque la devise de la boutique, ou la devise de la commande sur la page Pay for order, n'est pas PHP.

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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_paymongo_payment_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > PayMongo > Manage, ou cliquez sur Settings sous le nom de l'extension 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 PayMongo, créez les webhooks et collez leurs secrets de signature (voir Configuration).

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

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > PayMongo. Au-dessus des champs, la page vous avertit lorsque la devise de la boutique n'est pas PHP, lorsque le mode actuel n'a pas de clé secrète (PayMongo n'est alors pas affiché à la caisse) ou pas de secret de webhook (les paiements ne sont alors confirmés que lorsque le client revient), et affiche Test mode is on: no real payments are made. tant que le mode test est activé. Dans la liste des modes de paiement, PayMongo est signalé comme nécessitant une configuration tant que le mode actuel n'a pas de clé secrète.

Général

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 les clients voient à la caisse. Par défaut : PayMongo (Card, GCash, GrabPay, Maya).

Description : le texte affiché sous le mode de paiement à la caisse. 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. 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 au 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 précédemment conservent le mode dans lequel ils ont été faits, de sorte que les vérifications de statut et les remboursements utilisent la clé correspondante. Par défaut : activé. Désactivez-le pour accepter 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_.

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 dans cette section des réglages. Elle ressemble à https://your-site/?wc-api=paymongo_p_webhook.

Sélectionnez ces événements :

Copiez le secret de signature (whsk_...) de chaque webhook dans Test webhook secret ou Live webhook secret. Les webhooks sans signature valide sont refusés, et le mode de l'événement doit correspondre au mode de la signature. Chaque événement est revérifié via l'API PayMongo avant que la commande ne soit modifiée. PayMongo envoie les événements de tout le compte à chaque webhook ; les événements de paiements qui n'ont pas été créés par cette boutique sont ignorés. Sans webhook, les paiements ne sont confirmés que lorsque le client revient sur votre boutique.

Commandes

Statut de commande après paiement : le statut de commande défini après un paiement réussi. Le statut est appliqué immédiatement, sans second changement de statut.

Avancé

Debug log : Log API calls and webhook events les écrit dans WooCommerce > Status > Logs, source wcp_paymongo_payment_gateway. Les erreurs sont toujours journalisées. Les clés et les données clients ne sont jamais journalisées. Par défaut : désactivé.

Delete data on uninstall : Delete the settings and logs when the plugin is deleted. Les identifiants PayMongo enregistrés sur les commandes sont conservés, car ils sont nécessaires pour les remboursements et la comptabilité. Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut PayMongo (Card, GCash, GrabPay, Maya)) et passe commande. En mode test, la caisse affiche Test mode: no real payment will be made. L'extension crée une session de paiement PayMongo pour le total de la commande en PHP, avec une ligne Order # et le numéro de commande, puis envoie le client sur la page de paiement PayMongo. Le nom, l'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.

Le mode de paiement n'est affiché que pour les commandes d'au moins ₱100,00. Un total inférieur ne peut pas être payé avec PayMongo.

Après le paiement, le client revient sur la page de confirmation de commande de votre boutique. La commande n'est marquée payée qu'après confirmation de PayMongo : l'extension interroge l'API PayMongo sur le paiement lorsque le client revient et lorsque le webhook arrive. Si PayMongo traite encore le paiement ou ne peut pas être joint, le client arrive tout de même sur la page de confirmation de commande, et le webhook finalise la commande plus tard.

Si le client annule sur la page PayMongo ou n'achève pas le paiement, il arrive sur la page Pay for order avec le message 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. La commande reste impayée. Une nouvelle tentative vérifie d'abord la précédente : si elle a été payée entre-temps, la commande est finalisée sans nouveau paiement ; sinon, le lien de paiement PayMongo précédent expire, de sorte que le client ne peut pas payer deux fois. Tant que le paiement précédent est 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 voit un court 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 ajoutée aux notes de commande.

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

L'extension prend en charge les paiements uniques sur la page PayMongo. Elle ne propose pas de 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

Pending payment : le client a été envoyé vers PayMongo et n'a pas encore payé, ou PayMongo n'a pas encore confirmé le paiement. Une note enregistre chaque session de paiement PayMongo créée pour la commande. Pendant que PayMongo traite un paiement, une note l'indique.

Processing ou Completed : le paiement a été confirmé. Le statut suit Order status after payment. La note de commande indique le paiement PayMongo, le montant, la méthode de paiement et le mode (test ou production). L'ID de transaction est l'identifiant de paiement PayMongo (pay_...). L'écran de commande affiche la session de paiement, l'intention de paiement et le mode PayMongo sous l'adresse de facturation.

On hold : le montant ou la devise payés diffèrent de la commande (note amount/currency mismatch) ; ou un paiement a été effectué en mode test alors que la boutique est en production, de sorte qu'aucun argent n'a été reçu ; ou le paiement est arrivé après l'annulation de la commande, par exemple à cause de l'expiration de la réservation de stock. La note de commande l'explique. Vérifiez la commande et traitez-la ou remboursez le paiement.

Failed : un webhook payment.failed signé a indiqué que la dernière tentative de paiement d'une commande en attente a échoué. La note affiche le code et le message d'erreur PayMongo. Le client peut payer à nouveau.

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 annulée ou remboursée qui avait été payée n'est jamais rouverte.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via PayMongo (Card, GCash, GrabPay, Maya) (le bouton affiche le titre de votre mode de paiement). Les remboursements totaux et partiels sont pris en charge. 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. Si PayMongo n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec l'identifiant et le statut du remboursement PayMongo.

Les remboursements effectués dans le tableau de bord PayMongo ne sont pas reportés dans WooCommerce. Remboursez depuis la commande WooCommerce, ou créez un remboursement manuel dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > PayMongo. 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, PayMongo n'est pas affiché aux clients à la caisse. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension 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, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

PayMongo n'apparaît pas à la caisse : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel possède une clé secrète (Test secret key en mode test, Live secret key en mode production), que la devise de la boutique est PHP et que le total de la commande est d'au moins ₱100,00. Les développeurs peuvent modifier le minimum avec le filtre paymongo_p_minimum_amount.

Le paiement a abouti, mais la commande reste en Pending payment : le webhook ne fonctionne pas et le client n'est pas revenu sur 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 dans les réglages 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 de test a été signé comme production, 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, ou la commande était en cours de traitement par une autre requête au même moment. PayMongo renouvelle automatiquement le webhook.

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 lors de la commande : ouvrez les notes de commande ou consultez WooCommerce > Status > Logs, source wcp_paymongo_payment_gateway. Une clé secrète erronée affiche le message indiquant que le mode de paiement est temporairement indisponible. Un mode de paiement non activé pour votre compte PayMongo amène PayMongo à refuser le paiement ; retirez-le de Payment methods.

Paiements de test sur une boutique en production : un paiement de test reçu alors que la boutique est en mode production place la commande en attente avec une note indiquant qu'aucun argent n'a été reçu. Les vrais paiements sont toujours reconnus, même après un retour au mode test, et sont remboursés avec la clé de production.

La commande est On hold après paiement : lisez la note de commande. Le montant ou la devise payés ne correspondaient pas à la commande, le paiement était un paiement de test, ou il est arrivé après l'annulation de la commande. 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.

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, l'extension continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les données temporaires et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs identifiants de transaction et leurs identifiants PayMongo.

PayMongo est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à PayMongo ni approuvée par PayMongo.