Le module PayPlug pour Magento 2 s'installe avec Composer, depuis la ligne de commande. Un accès SSH au serveur est donc indispensable.
En bref : installez le module, connectez votre compte, activez les moyens de paiement, vérifiez les crons.
Sommaire :
1. Prérequis
3. Connecter le compte PayPlug
4. Activer les moyens de paiement
5. Vérifier que l'installation fonctionne
10. Arrêter d'utiliser le module
1. Prérequis
-
Version de Magento : Adobe Commerce ou Magento Open Source 2.4.4 à 2.4.9. Les versions 2.4.0 à 2.4.3 tournent en PHP 7.4 et ne peuvent pas installer le module.
-
PHP : 8.1 à 8.5, avec les extensions
openssletintl.
-
Accès serveur : Composer et un accès en ligne de commande à la racine de Magento.
-
Back-office : l'installation depuis le back-office n'est plus possible, Magento ayant retiré l'Extension Manager en 2.4.0.
2. Installer le module
Lancez ces commandes à la racine de Magento :
composer require payplug/payplug-magento2 php bin/magento module:enable Payplug_Payments --clear-static-content php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy fr_FR en_US php bin/magento cache:clean
composer require peut demander vos clés Adobe Commerce : login = Public Key, mot de passe = Private Key.
Important : hors mode production, ajoutez
--forceà la commandesetup:static-content:deploy, sinon elle échoue.
3. Connecter le compte PayPlug
Oauth2, le mode de connexion recommandé
Rien à ressaisir, aucun mot de passe stocké dans la configuration Magento.
- Allez dans Boutiques > Configuration > Ventes > Paiements PayPlug.
- Dans le bloc Authentification Oauth2, cliquez sur Se connecter à PayPlug et autorisez la connexion.
- Dans le bloc Configuration générale, réglez le Mode sur Test ou Live.
- Choisissez la Page de paiement : Intégrée, Redirigée ou Pop-up.
- Enregistrez la configuration.
L'authentification standard reste disponible
La connexion par e-mail et mot de passe existe toujours, dans le bloc Authentification Standard, juste en dessous. Un seul mode est actif à la fois : tant qu'Oauth2 est connecté, les champs e-mail et mot de passe sont masqués. Déconnectez Oauth2 pour y revenir.
Quelle page de paiement choisir ?
La page Intégrée exige un checkout conforme aux standards Magento. Si le bouton de commande a été personnalisé, choisissez Redirigée.
4. Activer les moyens de paiement
Connectez le compte avant cette étape : c'est la connexion qui remonte les moyens auxquels votre compte est éligible, avec leurs pays et leurs montants.
Chaque moyen a son bloc dans Boutiques > Configuration > Ventes > Modes de paiement, nommé « Paiements PayPlug - <moyen> » : Standard pour la carte, paiement en plusieurs fois, demande de paiement, Oney, Apple Pay, American Express, Bancontact, iDEAL, MyBank, Bizum, Wero, Satispay, Scalapay.
Pour chaque moyen :
- Passez Activé à Oui.
- Réglez le titre affiché au checkout, les statuts de commande, les pays, les montants plancher et plafond, l'ordre d'affichage.
- Enregistrez, puis videz le cache.
Un simple enregistrement de la configuration resynchronise l'éligibilité, les pays et les montants depuis notre API. C'est le premier réflexe quand un moyen n'apparaît pas au checkout.
Important : le bloc Hosted Fields Advanced demande des identifiants que nous fournissons au cas par cas. Ne l'activez pas sans eux.
5. Vérifier que l'installation fonctionne
Restez en Mode Test et passez une commande de bout en bout, avec les cartes de test de notre documentation. Trois contrôles :
- Le moyen de paiement apparaît bien en fin de panier.
- Après le paiement, la commande quitte En attente de paiement pour le statut configuré dans son bloc.
- La transaction apparaît dans votre portail PayPlug, en mode test.
Côté back-office, la commande porte alors le statut configuré et le bloc Payment Information affiche l'identifiant PayPlug, la date de paiement, la carte utilisée et le mode.
Si le paiement aboutit côté PayPlug mais que la commande reste En attente de paiement, passez à la section suivante : ce sont les crons.
6. Vérifier les crons
Le module a besoin de deux groupes de cron. Sans eux, l'installation semble fonctionner, puis les commandes se bloquent dès le premier paiement confirmé avec du retard.
| Groupe de cron | Rôle |
|---|---|
| payplug | Rattrape les paiements confirmés tardivement, capture les paiements différés en fin de délai. |
| default | Traite les files de messages qui créent les factures et les avoirs. |
La commande bin/magento cron:install couvre les deux. Le détail des jobs et des consumers se trouve dans la documentation Asynchronous Processing (order statuses, invoices & refunds).
7. Boutique sous thème Hyvä
Le module principal reste indispensable, il porte les paiements, les notifications et les commandes. Deux modules s'y ajoutent pour l'affichage :
composer require payplug/payplug-magento-hyva-checkout composer require payplug/payplug-magento-hyva-theme
Ces modules exigent une version exacte du module principal, pas une plage de versions. Vous ne pourrez donc pas le mettre à jour seul, Composer refusera, et une version fraîche du module principal peut n'avoir encore aucun équivalent Hyvä.
Important : avant toute mise à jour, ouvrez le
composer.jsondu module Hyvä et vérifiez la version demandée dans sonrequire.
8. Mettre à jour le module
composer require --update-with-all-dependencies payplug/payplug-magento2:^4.8 php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy fr_FR en_US php bin/magento cache:clean
Lisez les blocs ACTION REQUIRED du changelog du module pour toutes les versions traversées, pas seulement la dernière. Certaines demandent une opération manuelle.
9. Suivi des commandes
Une commande PayPlug naît en En attente de paiement et le reste jusqu'à la première mise à jour de statut valide, quel que soit le moyen utilisé. Trois mécanismes la font avancer : le retour du client depuis la page de paiement, la notification envoyée par nos serveurs à chaque changement d'état, et le cron de réconciliation qui rattrape les confirmations tardives.
Deux boutons complètent le dispositif en haut de la fiche de commande, tant que le paiement n'est pas résolu :
- Mettre à jour le paiement : interroge notre API à la demande.
-
Envoyer nouveau lien de paiement : relance un client dont le paiement n'a pas abouti.
Une fois la commande passée en Processing, ces boutons disparaissent : il n'y a plus rien à réconcilier.
Tant que la commande est en En attente de paiement, vous pouvez l'annuler depuis la liste des commandes, une par une ou en lot.
10. Arrêter d'utiliser le module
Ne le désinstallez pas : Magento a besoin de son code pour afficher les commandes déjà payées avec PayPlug, et lève une erreur s'il ne le trouve plus.
Passez Activé à Non sur chaque bloc « Paiements PayPlug - <moyen> ». PayPlug disparaît du checkout, les commandes existantes restent lisibles.
11. Problèmes courants
| Symptôme | Origine probable | Que faire |
|---|---|---|
| Class Payplug\Authentication does not exist | La librairie PHP PayPlug n'est pas installée |
composer require payplug/payplug-php:^4.2 puis composer require giggsey/libphonenumber-for-php:"^8.10|^9.0"
|
| Composer refuse de mettre à jour le module principal | Version épinglée par un module Hyvä | Mettre à jour les deux ensemble (section 7) |
| Un moyen de paiement n'apparaît pas au checkout | Éligibilité non synchronisée, pays ou montant hors limites | Enregistrer la configuration, puis vérifier pays et montants du bloc |
| Commande bloquée en En attente de paiement alors que le paiement est validé sur le portail | Le groupe de cron payplug ne tourne pas | Vérifier le cron (section 6) |
| Paiement validé sans facture, remboursement absent | Le groupe de cron default ne tourne pas, ou les consumers sont exclus | Vérifier le cron et app/etc/env.php
|
| La page de paiement Intégrée ne s'affiche pas | Checkout personnalisé | Basculer sur Redirigée |
Les logs du module se trouvent dans var/log/payplug_payments.log. Joignez-les à votre demande si vous nous contactez.