Payplug Payments Module

Installation

Pre-requirements

• Adobe Commerce / Magento Open Source 2.4.1 – 2.4.8
• PHP 8.1 – 8.4
• PHP extension openssl (required)

Installation via Magento Back Office

You can follow Magento’s instruction provided at
https://devdocs.magento.com/guides/v2.3/comp-mgr/extens-man/extensman-main-pg.html

Installation via composer

Composer

How to get Composer :
Please follow instructions on https://getcomposer.org/download/

How to update your Composer version :
Please follow instructions on https://getcomposer.org/doc/03-cli.md#self-update-selfupdate-

Installation

Run the following commands in Magento root directory:

composer require payplug/payplug-magento2  # (*)
composer install
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 <languages>  # (**)(***)
php bin/magento cache:clean

(*) If you didn’t save them when you installed Magento 2, this command will ask for your Magento authentication keys (https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html).
Login = Public Key
Password = Private Key

(**) With the languages option, you can define for which language you want to generate your static content. Languages should be separated with a space.
For example, to generate content for locales en_US and fr_FR, you can run the command:

php bin/magento setup:static-content:deploy en_US fr_FR

(***) If you are not running on production mode, use the --force option. Otherwise the command will fail.
For example, to generate content for locales en_US and fr_FR, you can run the command:

php bin/magento setup:static-content:deploy --force en_US fr_FR  # --force # if you are not running on production mode

Troubleshooting:

If you get a missing class error message while following the install process:

[ReflectionException] Class Payplug\Authentication does not exist

It’s likely that the Payplug PHP library was not installed along with the Magento module. This will happen if you did not run composer to install the module.
To fix it, you should require the missing dependency with composer :

composer require payplug/payplug-php:^3.0

You will then need to install another library which we use to normalize the customers' phone number

composer require giggsey/libphonenumber-for-php:^8.10

Cron Job Configuration

The Payplug Payments module introduces new cron tasks that are grouped under the payplug cron group in etc/crontab.xml. These cron jobs must run for the module to function properly.

• payplug_payments_check_order_consistency: Checks and updates the consistency of orders with Payplug.
• payplug_payments_auto_capture_deferred_payments: Capture the deferred payments after too much time elapsed.
• If your orders get stuck in payment review status, it typically indicates that payplug_payments_check_order_consistency is not running. Be sure to include this cron in your system’s crontab so that it is executed regularly (every 15 min by default, but you can override it to run it more frequently).

Verifying Crons and Logs

• Ensure your Magento crontab is correctly configured to run all Magento cron groups, including the payplug group which should be handled by default with the cron:run native command, deployed by the other native cron:install command.
• If you need to investigate any issues with these jobs, you can consult the var/log/payplug_payments.log file to see detailed logs and errors related to the Payplug Payments module’s cron executions.

For more information on how to properly configure and schedule Magento 2 cron jobs, consult
Magento’s official documentation

For more information about the new payplug_payments_check_order_consistency cron, consult
the Payplug CRON documentation

Update Payplug Payments Module

Run the following commands in Magento root directory:

composer require --update-with-all-dependencies payplug/payplug-magento2:VERSION_YOU_WANT_TO_UPDATE_TO  # (*)
composer install
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy <languages>  # (**)
php bin/magento cache:clean

(*) To determine which value for VERSION_YOU_WANT_TO_UPDATE_TO, you can check out our last releases
For example, you can run:

composer require --update-with-all-dependencies payplug/payplug-magento2:^1.5

(**) With the languages option, you can define for which language you want to generate your static content. Languages should be separated with a space.
For example, to generate content for locales en_US and fr_FR, you can run the command:

php bin/magento setup:static-content:deploy en_US fr_FR

Changelog - Payplug Payments Module

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

4.7.1 - 2026-05-18

Features

• Fix incorrect loader handling and adjust onCompleted event placement (MAG-609)
• Add Satispay to no-cancel-failure support list (MAG-711)
• Send invoice email upon invoice creation (MAG-701)
• Send order confirmation email on transaction approval (paid or authorized) (MAG-708)
• Refactor PPRO methods handling for improved readability and maintainability (MAG-714)
• Fix Scalapay threshold formatting exception (MAG-705)
• Remove IPN debug mode (MAG-703)
• Fix wording on payment info block (MAG-700)
• Fix error log message during cancel and rollback operation (MAG-702)
• Update CheckOrderConsistency to check orders within a new delayed window (MAG-669)
• Make country restriction for APM available in GraphQL (MAG-671)
• Fix TypeError in Oney ViewModel currency method by casting value to float (MAG-683)
• Fix invoice status on payment when invoice is created at order placement (MAG-684)

View diff

Added

• Add Satispay to no-cancel-failure support list (MAG-711) #1976b621
• Send invoice email upon invoice creation (MAG-701) #8639b315
• Send order confirmation email on transaction approval (paid or authorized) (MAG-708) #626e4d1d
• Make country restriction for APM available in GraphQL (MAG-671) #edcdf75b

Changed

• Refactor PPRO methods handling for improved readability and maintainability (MAG-714) #cfa07c53
• Remove IPN debug mode (MAG-703) #84796085
• Update CheckOrderConsistency to check orders within a new delayed window (MAG-669) #b12d42c7

Fixed

• Fix incorrect loader handling and adjust onCompleted event placement (MAG-609) #3b17ec88
• Fix Scalapay threshold formatting exception (MAG-705) #b69ec467
• Fix wording on payment info block (MAG-700) #54eec070
• Fix error log message during cancel and rollback operation (MAG-702) #71fb08f5
• Fix TypeError in Oney ViewModel currency method by casting value to float (MAG-683) #eca79afd
• Fix invoice status on payment when invoice is created at order placement (MAG-684) #5c8a9097

4.7.0 - 2026-04-10

⚠ ACTION REQUIRED

This notice applies only to the Standard payment method using authorization only mode.

Authorization metadata storage on order payments has been improved.

Impact:
If you rely on the AutoCaptureDeferredPayments CRON for automatic capture, some orders created in the last 7 days prior to upgrading to this version may have inconsistent authorization data, potentially preventing captures.

Required action:
You must run a data realignment to synchronize authorization metadata from quote payments to order payments for the past 10 days:

bin/magento payplug:migrate-authorization-metadata

Failure to perform this action may result in missed captures, especially if no manual capture is performed via the Magento backend or API.

Features

• Redirect 3D Secure for OneClick option (MAG-613)
• Add quote retrieval logic to TransactionDataBuilder with enhanced error handling (MAG-618)
• Add Bizum and Wero payment methods (MAG-603)
• Handle Wero cancel operation (forward from PaymentReturn to Cancel action) (MAG-603)
• Add custom metadata field to config and integrate metadata plugin in order placement process (MAG-612)
• Add multilingual translations including OAuth2 and Standard Auth labels (MAG-623)
• Create invoice message queue after order status is updated (MAG-652)
• Remove bizum whitelisted phone from codebase (MAG-666)
• Fix duplicate authorization when capturing with missing authorization flag (MAG-672)
• Add Scalapay payment method (MAG-661)
• Replace the iDEAL logo with the co-branded iDEAL/Wero version (MAG-619)
• Enable coupon code rollback by using OrderService cancellation (MAG-682)
• Add headless compatibility for cart rollback on Cancel / Payment Return (MAG-677)
• Add CLI to migrate authorization metadata from quote to order (MAG-683)
• Fix Scalapay country restriction logic (MAG-687)
• Fix cart rollback with Scalapay user cancellation (MAG-690)
• Change Scalapay payment title to reflect 3x/4x option (MAG-696)
• Fix order status persisting as “Pending Payment” after successful order cancellation (MAG-694)

View diff

Added

• Add quote retrieval logic to TransactionDataBuilder with enhanced error handling (MAG-618) #7b3a0fbe
• Add Bizum and Wero payment methods (MAG-603) #cbae5396
• Handle Wero cancel operation (forward from PaymentReturn to Cancel action) (MAG-603) #5892d8b3
• Add custom metadata field to config and integrate metadata plugin in order placement process (MAG-612) #fa857bb2
• Add multilingual translations including OAuth2 and Standard Auth labels (MAG-623) #5d278de8
• Add Scalapay payment method (MAG-661) #664c13c6
• Add headless compatibility for cart rollback on Cancel / Payment Return (MAG-677) #15037601
• Add CLI to migrate authorization metadata from quote to order (MAG-683) #13dd906d

Changed

• Redirect 3D Secure for OneClick option (MAG-613) #7f71ef6d
• Remove bizum whitelisted phone from codebase (MAG-666) #dd87742f
• Replace the iDEAL logo with the co-branded iDEAL/Wero version (MAG-619) #50701821
• Change Scalapay payment title to reflect 3x/4x option (MAG-696) #59d2e99b

Fixed

• Create invoice message queue after order status is updated (MAG-652) #e9e47658
• Fix duplicate authorization when capturing with missing authorization flag (MAG-672) #e9e47658
• Fix coupon code rollback by using OrderService cancellation (MAG-682) #1beb43d3
• Fix Scalapay country restriction logic (MAG-687) #b1dcd985
• Fix cart rollback with Scalapay user cancellation (MAG-690) #ebcd1225
• Fix order status persisting as “Pending Payment” after successful order cancellation (MAG-694) #71188022

4.6.3 - 2026-03-09

Features

• Add full Magento Coding Standard ruleset compliance (MAG-601)
• Add React headless payment app example (MAG-549)
• Fix type casting for total amount and split count in installment plan generation (MAG-539)
• Fix undefined index error in PaymentConfigObserver (MAG-597)
• Fix double shipping rate calculation on configurable product (MAG-608)
• Update React components declaration to avoid PHP CS errors (MAG-617)
• Add GraphQL resolver for retrieving Payplug payment redirect URL on GraphQL Order type (V1) for Magento 2.4.6 compatibility (MAG-621)
• Update ApplePay order handling to reflect shipping method changes and add relevant order comment (MAG-629)
• Add null safe operator for authorized_at to prevent potential null reference error (MAG-628)
• Add Payplug Copyright comments (MAG-615)
• Update failure redirect URL to improve error handling and pass failure msg (MAG-656)
• Refactor cache key logic to support website-specific OAuth2 access token caching (MAG-665)
• Add customizable URL scope option for return/cancel success redirects and encode base64 all custom return urls (MAG-646)
• Refactor custom return URL encoding logic on place order (MAG-655)
• Fix website scope legacy login and refactor config fields behavior (MAG-650)
• Handle additional store scope type during OAuth connection validation (MAG-647)

View diff

Changed

• Refactor custom return URL encoding logic on place order (MAG-655) #4aec1a07
• Update React components declaration to avoid PHP CS errors (MAG-617) #9998c7c9

Added

• Add full Magento Coding Standard ruleset compliance (MAG-601) #ae4a9a48
• Add React headless payment app example (MAG-549) #8c342895
• Add GraphQL resolver for retrieving Payplug payment redirect URL on GraphQL Order type (V1) for Magento 2.4.6 compatibility (MAG-621) #f886d4c3
• Add Payplug Copyright comments (MAG-615) #90990a4a
• Add customizable URL scope option for return/cancel success redirects and encode base64 all custom return urls (MAG-646) #a0418795

Fixed

• Fix type casting for total amount and split count in installment plan generation (MAG-539) #a7152128
• Fix undefined index error in PaymentConfigObserver (MAG-597) #807de5db
• Fix double shipping rate calculation on configurable product (MAG-608) #89f16080
• Fix ApplePay order handling to reflect shipping method changes and add relevant order comment (MAG-629) #e0f1b726
• Add null safe operator for authorized_at to prevent potential null reference error (MAG-628) #8b4d4040
• Update failure redirect URL to improve error handling and pass failure msg (MAG-656) #14d91ead
• Refactor cache key logic to support website-specific OAuth2 access token caching (MAG-665) #2cdc5dc6
• Fix website scope legacy login and refactor config fields behavior (MAG-650) #1ea1877f
• Handle additional store scope type during OAuth connection validation (MAG-647) #1e9cae78

4.6.2 - 2026-01-26

Features

• Fix exception when selecting PayPlug payment method in checkout (e.g., Hyvä Checkout) (MAG-590)

View diff

Fixed

• Fix exception when selecting PayPlug payment method in checkout (e.g., Hyvä Checkout) #339

4.6.1 - 2025-12-24

Features

• Fix Cron auto-capture failing on carts with missing info (MAG-562)
• Fix OAUTH2 login UI with Legacy panel causing confusion (MAG-564)
• Fix error when configuring Payplug on a specific website scope (MAG-574)
• Improve ACL permission granularity for the Payplug admin section (MAG-575)
• Fix OAuth2 login redirection blank page during Unified Auth process (MAG-578)
• Anonymize personal data logged by Payplug module (MAG-581)
• Enable REDIRECT mode for integrated payment 3DS validation (MAG-584)
• Fix unclear error message in Legacy connection mode (MAG-585)
• Fix PayPlug payment status mismatch in Authorization-only mode (MAG-593)
• Fix module 4.6.0 incompatibility with Magento 2.4.8-p3 (MAG-598)
• Fix forced captures attempted 10 minutes after authorization expiration (MAG-599)

View diff

Changed

• Improve ACL permission granularity for the Payplug admin section (MAG-575) #330
• Anonymize personal data logged by Payplug module (MAG-581) #329
• Enable REDIRECT mode for integrated payment 3DS validation (MAG-584) #327

Fixed

• Fix Cron auto-capture failing on carts with missing info #335
• Fix OAUTH2 login UI with Legacy panel causing confusion #334
• Fix error when configuring Payplug on a specific website scope #317
• Fix OAuth2 login redirection blank page during Unified Auth process #328
• Fix unclear error message in Legacy connection mode #326
• Fix PayPlug payment status mismatch in Authorization-only mode (MAG-593) #337
• Fix module 4.6.0 incompatibility with Magento 2.4.8-p3 #340
• Fix forced captures attempted 10 minutes after authorization expiration #341

4.6.0 - 2025-11-17

WARNING
Orders are no longer assigned to the Payment Review status by default after creation. They will now remain in Pending Payment until the next valid status update, regardless of the payment flow. This prevents premature triggering of business processes such as invoicing and shipping.

Features

• Fix Apple pay button disabled after payment cancel (MAG-537)
• Create invoice after a transaction is valid only (MAG-521)
• Add invoice increment ID into payplug transaction metadata (MAG-484)
• Enable refunds for PPro transactions in the Magento Admin (MAG-468)
• Conditional display of APMs based on the user’s country (MAG-434)
• Set initial order status to Pending Payment instead of Payment Review (MAG-517)
• Unified authentication : restrict "live" mode when Merchant KYC is uncompleted (MAG-526)
• Missing magento transaction entity on Authorization Only orders (MAG-540)
• Fix transaction ID on refund. Check existing refund transaction durant IPN callback (MAG-542)
• Fix auto-capture cron marking orders as Failed Capture (MAG-546)
• Fix invoicing / refunding concurrency (IPN vs PaymentReturn) by moving logics to message queue system (MAG-541)
• Add enriched metadata on refund lines (MAG-467)
• Fix JS dependency missing for Installment Plan payment method (MAG-554)
• Fix order status on Payment Return with Autorization only mode (MAG-555)
• Fix order status (stays on payment_review state) when invoice is generated manually (MAG-571)

View diff

Added

• Add invoice increment ID into payplug transaction metadata #291
• Enable refunds for PPro transactions in the Magento Admin #292
• Add enriched metadata on refund lines #307
• Missing magento transaction entity on Authorization Only orders #311

Changed

• Create invoice after a transaction is valid only #290
• Conditional display of APMs based on the user’s country #298
• Set initial order status to Pending Payment instead of Payment Review #306

Fixed

• Fix Apple pay button disabled after payment cancel #305
• Fix checkout payment methods render on Safari #304
• Unified authentication : restrict "live" mode when Merchant KYC is uncompleted #310
• Fix transaction ID on refund. Check existing refund transaction durant IPN callback #312
• Fix invoicing / refunding concurrency (IPN vs PaymentReturn) by moving logics to message queue system #314
• Fix method parameter type #314
• Fix auto-capture cron marking orders as Failed Capture #313
• Fix JS dependency missing for Installment Plan payment method #315
• Fix order status on Payment Return with Autorization only mode #316
• Fix order status (stays on payment_review state) when invoice is generated manually #319

4.5.0 - 2025-09-03

Features

• Implement OAuth2 redirect handling and securely store credentials
• Set up automatic JWT generation and refresh
• Integrate OAuth2 login UI (button)
• Sign every API request with the JWT token
• Support both legacy authentication and OAuth2 (dual mode)

View diff

4.4.0 - 2025-06-24

Features

• Add Apple Pay button to product view page
• Add Apple Pay button to cart page
• Add Chrome and Firefox Apple button support
• Limit the module to PHP >=8.1 and <8.5
• Update payplug/payplug-php dependency version for PHP 8.4 compatibility

View diff

Added

• Add Apple Pay conditionnal render from configuration #263
• Add Apple Pay button to product view page #275
• Add Apple Pay button to cart page #275 #252 #251
• Add Apple Pay workflowType parameter to place order fetch #250
• Add Chrome and Firefox Apple button support #272

Changed

• Upgrade Apple Pay JS SDK version #272
• Enable CB by default and expose brand selector in Apple Pay #272
• Prevent invoice auto-generation on Apple Pay #275
• Change payplug/payplug-php dependency version

Fixed

• Fix apple pay payments on cart page when having configurable products in cart #275

4.3.4 - 2025-04-28

Features

• Add Payplug information block on the back-office ondemand orders. (MAG-440)
• Allow to capture a deferred payment even with an order increment id in the metadata. (MAG-453)
• Fix cropped logo in Oney popin. (MAG-424)
• Fix the installment plan payment not redirecting to the failure page post checkout. (MAG-441)

View diff

Added

• Add Payplug information block on the back-office ondemand orders. #269

Changed

• Allow to capture a deferred payment even with an order increment id in the metadata. #270

Fixed

• Fix cropped logo in Oney popin. #266
• Fix the installment plan payment not redirecting to the failure page post checkout. #268

4.3.3 - 2025-04-09

Features

• Fix an SQL crash happening in some case when updating the order. (MAG-443)

View diff

Fixed

• Fix an SQL crash happening in some case when updating the order. (MAG-443). #262

4.3.2 - 2025-04-02

Features

• Add a documentation about the crons usage in 4.3.0 and above. (MAG-433)
• Fix a case were the crons didn't unstucks payments from payment_review state. (SMP-3116)
• Fix the checkout redirecting to success page on non-authorized deferred payment. (MAG-436)
• Fix an error on creating an order from the back-office, due to null iso code. (MAG-437)

View diff

Added

• Add a documentation about the crons usage in 4.3.0 and above. #257

Fixed

• Fix a case were the crons didn't unstucks payments from payment_review state in production. #257
• Prevent the manual order creation to crash if isoCode is null #258
• Prevent successfully redirecting to the success page if the deferred payment isn't authorized. #259

4.3.0 - 2025-03-19

Features

• Support Magento 2.4.7
• Add a queue system feature
• Synchronize orders status with Payplug servers post payment
• Compatibility with php 8.1 and Magento 2.4.4 and above. (SMP-3032)

View diff

Added

• Add queue system payment feature #246

Removed

• Removed the unions type in the base code. #246

Fixed

• Fix the scripts for the 2.4.7 with the secureHtmlRenderer class #253

4.2.0 - 2025-01-13

Features

• Add deferred payment feature
• Update and optimize payment methods cards render
• Checkout render improvements
• A11Y improvements

View diff

Added

• Add deferred payment feature #238
• Add Oney method payment title #240
• Add alternative texts on payment methods logos for A11Y #240

Changed

• Move payment images to dedicated logos images folder #240
• Optimize and normalize payment methods styles #240
• Optimize and normalize payment methods logos #240
• Update standard payment schemes A11Y #240

Removed

• Remove useless payment logos #240

4.1.0 - 2024-10-02

Features

• Remove Giropay and Sofort payment methods
• PHP 8.1 upgrade
• Security and controllers improvements
• Fix various escpaers
• Update and optimize payment methods logos

View diff

Added

• Add the new cb Logo to Magento 2 #219 #233
• Add security via form key to multiple controllers along with php 8 #230
• Add form key validation and php 8 to the Block/Adminhtml/Config/Logout.php controller #230

Changed

• Update and optimize payment cards logos #219 #233 #234 #237
• Replace escapeHtml by escapeUrl in formjs.phtml #220
• Use an escapeHtmlAttr for the code in the ondemand template #220
• Prevent using NamingConvention\true\string as string #230
• Update apple pay controller to php 8 and fix argument must be of type string #230
• Upgrade to php 8.1 and add security to Ipn, Simulation, SimulationCheckout.php and AsbtractPayment controler #230
• Update Standard and PaymentReturn.php controllers, along with Cancel controller and all the relative depending classes #230
• Update controllers classes to php 8.0+ and use the form key #230
• Update InstallmentPlanAbort.php and subclasses to php 8 and add form key security #230

Removed

• Remove Sofort payment method #235
• Remove Giropay payment method #235
• Remove the old unused pictures #219 #233

Fixed

• Fix cardList escapeUrl #220
• Fix escapers #220
• Fix phtmls escapers and add strict types for php 8 #220

4.0.0 - 2024-08-28

NOTE
This version goes directly from 1.27.4 to 4.0.0 to make a clean slate and avoid maintaining two logics as was done on previous versions (one in 1.27.X and the other one in 3.5.X).

Features

• Optimize Oney payment load and script
• Fix bad redirection after 3DS payment failure
• Fix wrong return URL in case of pending file Oney
• Fix transaction stays indefinitely in payment review with 3DS integrated payment
• Php 8.1 support

View diff

Added

• Add CHANGELOG.md #211
• Add declare strict types along with real returns and php 8.0 #209
• Add missing xml version declarations #208
• Add secure-magenta.dalenys.com in CSP whitelist #212
• Add strict returns and fix typos for CheckPayment class #209
• Add the real exceptions throw to function declaration #209

Changed

• Factorize payment simulation Ajax calls #208
• Get popin payment option navigation back #208
• Optimize Oney popin script show/hide #208
• Type more thoroughly the returns #218
• Update and refacto Oney view handler script #208
• Update oney popin script constructor #208
• Update order status #209
• Update payment standard method script indentation and declaration #209
• Update Payplug Integrated Payments library call aliasing #208

Removed

• Remove Oney script head tag call #208
• Remove residual comment - Update order status #209

Fixed

• Allow success order placement on oney pending payment #218
• Prevent type error on order placements #226
• Fix Undefined array key after 3DS failed payment #225
• Fix the use of phrases instead of string in php 8 #217

1.27.4 - 2024-05-02

view diff

1.27.3 - 2024-03-28

view diff

1.27.2 - 2023-10-26

view diff

1.27.1 - 2023-10-10

view diff

1.27.0 - 2023-09-21

view diff

1.26.0 - 2023-09-06

view diff

1.25.0 - 2023-07-10

view diff