The PayPlug module for Magento 2 is installed with Composer, from the command line. SSH access to the server is therefore required.
In short: install the module, connect your account, enable the payment methods, check the crons.
Contents:
1. Requirements
3. Connect your PayPlug account
5. Check that the installation works
7. Stores using the Hyvä theme
1. Requirements
-
Magento version: Adobe Commerce or Magento Open Source 2.4.4 to 2.4.9. Versions 2.4.0 to 2.4.3 run on PHP 7.4 and cannot install the module.
-
PHP: 8.1 to 8.5, with the
opensslandintlextensions.
-
Server access: Composer and command line access to the Magento root directory.
-
Admin panel: installing from the admin panel is no longer possible, as Magento removed the Extension Manager in 2.4.0.
2. Install the module
Run these commands from the Magento root directory:
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 may ask for your Adobe Commerce keys: username = Public Key, password = Private Key.
Important: outside production mode, add
--forceto thesetup:static-content:deploycommand, otherwise it will fail.
3. Connect your PayPlug account
Oauth2, the recommended connection method
Nothing to re-enter, and no password stored in your Magento configuration.
- Go to Stores > Configuration > Sales > Payplug Payments.
- In the Oauth2 Authentication section, click Connect to Payplug and authorise the connection.
- In the General configuration section, set Mode to Test or Live.
- Choose the Payment Page: Embedded, Redirected or Pop-up.
- Save the configuration.
Standard authentication is still available
Connecting with an email address and password still works, in the Standard Auth section just below. Only one method is active at a time: as long as Oauth2 is connected, the email and password fields are hidden. Disconnect Oauth2 to go back to them.
Which payment page should you choose?
The Embedded page requires a checkout that follows Magento standards. If the place order button has been customised, choose Redirected.
4. Enable the payment methods
Connect your account before this step: the connection is what retrieves the methods your account is eligible for, along with their countries and amounts.
Each method has its own section under Stores > Configuration > Sales > Payment Methods, named "Payplug Payments - <method>": Standard for card payments, instalments, payment request, Oney, Apple Pay, American Express, Bancontact, iDEAL, MyBank, Bizum, Wero, Satispay, Scalapay.
For each method:
- Set Enabled to Yes.
- Set the title shown at checkout, the order statuses, the countries, the minimum and maximum amounts, and the sort order.
- Save, then flush the cache.
Simply saving the configuration re-syncs eligibility, countries and amounts from our API. That is the first thing to try when a method does not show up at checkout.
Important: the Hosted Fields Advanced section requires credentials that we provide on a case-by-case basis. Do not enable it without them.
5. Check that the installation works
Stay in Test Mode and place an order from start to finish, using the test cards from our documentation. Three checks:
- The payment method does appear at the end of the cart.
- After payment, the order leaves Pending Payment for the status configured in its section.
- The transaction appears in your PayPlug portal, in test mode.
In the admin panel, the order then carries the configured status and the Payment Information block shows the Payplug ID, the payment date, the card used and the mode.
If the payment succeeds on the PayPlug side but the order stays in Pending Payment, go to the next section: it is the crons.
6. Check the crons
The module needs two cron groups. Without them, the installation appears to work, then orders get stuck as soon as a payment is confirmed with a delay.
| Cron group | Role |
|---|---|
| payplug | Catches up on payments confirmed late, captures deferred payments at the end of the delay. |
| default | Processes the message queues that create invoices and credit memos. |
The bin/magento cron:install command covers both. Details of the jobs and consumers can be found in the Asynchronous Processing documentation (order statuses, invoices & refunds).
7. Stores using the Hyvä theme
The main module remains essential, as it handles payments, notifications and orders. Two modules are added on top of it for the display:
composer require payplug/payplug-magento-hyva-checkout composer require payplug/payplug-magento-hyva-theme
These modules require an exact version of the main module, not a version range. You will therefore not be able to update it on its own, Composer will refuse, and a freshly released version of the main module may not have a Hyvä counterpart yet.
Important: before any update, open the
composer.jsonof the Hyvä module and check the version requested in itsrequire.
8. Update the 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
Read the ACTION REQUIRED blocks in the module changelog for every version you go through, not just the latest one. Some of them require a manual operation.
9. Order tracking
A PayPlug order starts in Pending Payment and stays there until the first valid status update, whichever method was used. Three mechanisms move it forward: the customer returning from the payment page, the notification our servers send on every state change, and the reconciliation cron that catches up on late confirmations.
Two buttons complete the setup at the top of the order page, as long as the payment is not settled:
- Update Payment: queries our API on demand.
-
Send new payment link: follows up with a customer whose payment did not go through.
Once the order moves to Processing, these buttons disappear: there is nothing left to reconcile.
As long as the order is in Pending Payment, you can cancel it from the order list, one at a time or in bulk.
10. Stop using the module
Do not uninstall it: Magento needs its code to display orders already paid with PayPlug, and throws an error if it can no longer find it.
Set Enabled to No on each "Payplug Payments - <method>" section. PayPlug disappears from the checkout, and existing orders remain readable.
11. Common issues
| Symptom | Likely cause | What to do |
|---|---|---|
| Class Payplug\Authentication does not exist | The PayPlug PHP library is not installed |
composer require payplug/payplug-php:^4.2 then composer require giggsey/libphonenumber-for-php:"^8.10|^9.0"
|
| Composer refuses to update the main module | Version pinned by a Hyvä module | Update both together (section 7) |
| A payment method does not appear at checkout | Eligibility not synced, country or amount out of range | Save the configuration, then check the countries and amounts in the section |
| Order stuck in Pending Payment while the payment is confirmed in the portal | The payplug cron group is not running | Check the cron (section 6) |
| Payment confirmed with no invoice, refund missing | The default cron group is not running, or the consumers are excluded | Check the cron and app/etc/env.php
|
| The Embedded payment page does not display | Customised checkout | Switch to Redirected |
The module logs can be found in var/log/payplug_payments.log. Please attach them to your request if you contact us.