Skip to main content

Paysera Smart Checkout for Magento

Paysera Smart Checkout adds Paysera Checkout as a payment method to Magento Open Source and authenticates with the Client ID and Client Secret of your Paysera Checkout project.

Requirements​

  • Magento Open Source 2.4.7, 2.4.8 or 2.4.9
  • A PHP version that your Magento release supports: PHP 8.3 on 2.4.7; PHP 8.3 or 8.4 on 2.4.8; PHP 8.3, 8.4 or 8.5 on 2.4.9
  • Composer
  • A Paysera Checkout project with a Client ID and Client Secret — see Obtaining Credentials

Installation​

Install the extension with Composer from the Adobe Commerce Marketplace, or from an archive.

Production mode

If the store runs in production mode, enable maintenance mode first with php bin/magento maintenance:enable. After php bin/magento setup:di:compile, run php bin/magento setup:static-content:deploy, then php bin/magento cache:flush and php bin/magento maintenance:disable. Run all commands as the Magento file-system owner, not as root.

Install from an Archive​

  1. In the Magento base directory, open app/code. If the code folder does not exist, create it.
  2. Inside app/code, create the folder Paysera, and inside it the folder Checkout.
  3. Download the extension archive and extract it into app/code/Paysera/Checkout.
  4. In a terminal, go to the Magento base directory and run:
composer require evp/money "^2"
composer require nyholm/psr7 "^1.8"
composer require paysera/lib-checkout-integration-sdk "^3.6"
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Install with Composer (Adobe Commerce Marketplace)​

  1. On the Adobe Commerce Marketplace, add Paysera Smart Checkout to your account. The extension is free.
  2. Make sure Composer on your server can reach the Marketplace repository (https://repo.magento.com/) with your Marketplace access keys.
  3. In a terminal, go to the Magento base directory and run:
composer require "payserauk/magento2-paysera-smart-checkout-module:^1.0"
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

After installation, sign in to the Magento Admin, open Stores → Configuration → Sales → Payment Methods → Paysera Smart Checkout, set Enabled to Yes, enter the Client ID and Client Secret, adjust the other settings as described in Configuration, and save.

Configuration​

All settings are in Stores → Configuration → Sales → Payment Methods → Paysera Smart Checkout. Every setting can be set at the default, website and store view scope.

General​

SettingDefaultDescription
EnabledNoTurns the payment method on. Switching to Yes is refused while the legacy Paysera extension is enabled in the same scope — see Coexistence with the Legacy Paysera Extension. Switching to Yes without entering new credentials is also refused, with "Paysera: Stored credentials are invalid. Update them before enabling the payment method.", when the stored Client ID and Client Secret no longer pass the Paysera check. Switching to No keeps every setting, including the credentials.
Client ID—Client ID of your Paysera Checkout project. Shown after Enabled is set to Yes. Required when the extension is enabled. Stored encrypted.
Client Secret—Client Secret of the same project. Shown after Enabled is set to Yes. Required when the extension is enabled. Stored encrypted. On save, the extension checks the Client ID and Client Secret with Paysera and refuses to save an invalid pair with the message "Paysera: Invalid credentials".

Paysera Extra Settings​

SettingDefaultDescription
TitleAll popular payment methodsThe title shown on the checkout page. Order pages and emails show "All popular payment methods" and, when the buyer picked a method in the list, a separate "Payment method" line with its name — see How It Works. Up to 255 characters: the field shows a current / maximum counter and stops accepting input at the limit, and a longer value is refused on save, including through bin/magento config:set and configuration imports.
DescriptionChoose a payment method on the Paysera pageShown under the payment method only while List of Payments is No. Up to 1000 characters, with the same counter and save check as Title.
List of PaymentsYesYes shows the Paysera payment methods in the checkout, grouped by country; a country dropdown selects the group when more than one country is offered or Specific Countries is set. No shows a single Paysera entry that redirects the buyer to the Paysera payment page.
Payment method appearanceIcon and nameIcon and name shows a round icon next to each method's name. Full logo shows the methods as a grid of equal tiles, each with the method's full brand logo; a method without a full logo shows its round icon and name in the tile. The number of columns follows the width of the payment area. With Full logo, where a method has a full logo made for the country selected in the checkout country dropdown (for example Inbank in Lithuania, Latvia and Estonia), that logo is used; "All countries" and "Other countries" keep the standard logo. The round icon is always the standard one. Shown only while List of Payments is Yes.
Payments Grid ViewYesShows the payment methods in two columns instead of a list. Shown only while Payment method appearance is Icon and name.
Payment from Applicable CountriesAll Allowed CountriesAll Allowed Countries or Specific Countries — see Country Restriction.
Payment from Specific CountriesEmptyThe countries offered when Specific Countries is selected. The field is shown greyed out while All Allowed Countries is selected, and the saved selection is kept.

Paysera Order Status​

Each of the three dropdowns lists every order status of the store, including Pending Payment, Payment Review and statuses you created yourself. Saving an empty selection, or a status that does not exist in the store, is refused.

SettingDefaultDescription
New Order StatusProcessingThe status the order is created with when the buyer places it. The buyer is then sent to the Paysera payment page and the order moves to Order Status for pending checkout. A status of the Complete, Closed or Canceled state, or the same status as Completed payment Order Status, is ignored: the order is created in Magento's default status, Pending, and a warning is written to the log.
Completed payment Order StatusCompleteSet when Paysera confirms the payment. The order state is set to Processing whichever status you pick, so the order can still be invoiced and shipped.
Order Status for pending checkoutPending PaymentSet when the buyer is redirected to the Paysera payment page. Keep the built-in Pending Payment status so that abandoned orders are cleaned up — see Order Cancellation and Abandoned Payments.

How It Works​

  • With List of Payments, the buyer can pick a payment method in the Magento checkout and is taken straight to that method on the Paysera payment page. A buyer who places the order without picking a method chooses it on the Paysera payment page.
  • Without List of Payments, the buyer picks the single Paysera entry and chooses the payment method on the Paysera payment page.
  • With List of Payments, each method shows the name Paysera uses for it in the country selected in the checkout country dropdown, or its standard name when there is no local one. When the buyer picks a method, the order keeps that name and shows it as "Payment method" in the admin order view, the customer account, order emails and PDFs. If the name cannot be resolved, the order is still placed and shows only "All popular payment methods". Without List of Payments, or when the buyer does not pick a method, the order also shows only "All popular payment methods".
  • The list shows the methods your Paysera project offers, such as banks, cards and wallets like Apple Pay or Google Pay, for the cart amount (the subtotal after discounts), the currency and the selected country. The extension adds no payment methods or wallet buttons of its own.
  • If no Paysera payment method matches the cart amount and currency, the checkout shows "Paysera: no methods available" and the order cannot be placed with Paysera.
  • The checkout always shows a notice under the Paysera payment methods, or under the Description text without List of Payments, that Paysera provides the account information and payment initiation services under its rules, with a link to the rules. The notice is shown in the store's language where Paysera provides a translation, otherwise in English.
  • The payment method is offered only while the extension is enabled, the legacy Paysera extension is not enabled for the store, and the Client ID and Client Secret are valid.
  • The extension creates the payment link through the Paysera Checkout API and reuses the same link for repeated payment attempts on the same order.
  • The Paysera payment page is requested in the store's language.
  • The extension sends the payer country to Paysera: the country selected in the checkout dropdown, otherwise the billing address country, otherwise the shipping address country, otherwise the region of the browser language, otherwise the store default country.
  • Paysera confirms the payment with a signed server-to-server callback. The extension checks the signature, the amount and the currency before it sets the Completed payment Order Status.
  • A partial payment adds a comment with the paid and expected amounts to the order's status history and leaves the order status unchanged. An overpayment sets the Completed payment Order Status and is flagged in the confirmation comment.
  • A repeated callback for an order that is already paid changes nothing.

Test Mode​

Test mode is a setting of your Paysera project, not of the extension; the extension has no test-mode setting of its own.

  • While the project is in test mode, the Paysera Smart Checkout configuration group shows the notice "Test mode: your Paysera project is in test mode. Payments are simulated and no real money is collected. Switch the project to live mode in your Paysera account to accept real payments."
  • The notice reflects the project of the default-scope credentials (the Client ID and Client Secret saved at the Default Config scope), whichever scope you are viewing. The state is checked with Paysera at most every 15 minutes; changing the credentials or Enabled refreshes it at once, and so does php bin/magento cache:clean config. If the check fails, no notice is shown.
  • The order-history comments of a payment made in test mode — paid, paid with an overpayment, partially paid, and payment received for a canceled order — start with [Test]. The marking comes from the payment itself, as reported by Paysera when the payment link is created, so it does not change when the project later goes live.

Country Restriction​

Payment from Applicable Countries and Payment from Specific Countries limit the countries offered in the checkout country dropdown.

Checkout display only

The restriction shapes only the country dropdown of the payment-method list, and only while List of Payments is Yes. It does not hide the Paysera payment method, and it is not enforced when the order is placed or through the REST and GraphQL APIs. Treat it as a checkout-display preference, not as a compliance control.

  • All Allowed Countries, or Specific Countries with an empty list, means no restriction. The dropdown keeps the "All countries" and "Other countries" entries.
  • Specific Countries with a non-empty list offers only those selected countries for which Paysera has payment methods. The "All countries" and "Other countries" entries are removed.
  • The dropdown pre-selects the buyer's billing country, or the shipping country when the billing address has none, if Paysera offers payment methods for it. Otherwise, unless the buyer's country is outside the allowed list, it pre-selects "Other countries", or the first country in the dropdown when that entry is not available, as with Specific Countries.
  • If the buyer's country (billing, or shipping when the billing address has none) is outside the allowed list, no country is pre-selected (the dropdown shows "Select a country") and no payment methods are shown until the buyer picks an allowed country.

Order Cancellation and Abandoned Payments​

Back to shop. When the buyer presses Back to shop on the Paysera payment page, the extension cancels the order, adds "Order canceled by the buyer on the Paysera payment page." to its status history, and returns the buyer to the cart with the same items. The link is signed per order and valid for one hour; a changed or expired link opens the store home page and changes nothing. If the order is already paid, the link also opens the store home page and changes nothing. The link works only in the browser session that placed the order. Anywhere else, it opens the store home page and the order stays pending. If the order is already canceled, for example by the Pending Payment Order Lifetime, the link returns the buyer to the cart with the same items and changes nothing else.

Abandoned payments. If the buyer closes the Paysera payment page, the order stays in the Order Status for pending checkout status. Magento's Pending Payment Order Lifetime in Stores → Configuration → Sales → Sales → Orders Cron Settings cancels such orders after the configured number of minutes (Magento's default is 480). This cleanup applies only to the built-in Pending Payment status; if you select a different status, cancel those orders by hand. If you accept payment methods that settle slowly, set the lifetime longer than such a payment can take. An order whose buyer never reaches the Paysera payment page, for example because the browser was closed before the redirect, keeps the New Order Status, and the Pending Payment Order Lifetime does not cancel it. To cover such orders, set New Order Status to Pending Payment as well.

Payment for a canceled order. If a payment is completed after the order was canceled, the order is not reopened. The extension adds a "Paysera payment received for a canceled order" comment to the order's status history; refund the buyer or re-create the order by hand.

Coexistence with the Legacy Paysera Extension​

Paysera Smart Checkout and the legacy Paysera extension can both be installed, but only one of them can be enabled.

  • Enabling Paysera Smart Checkout while the legacy extension is enabled in the same scope is refused with "Conflict: Multiple Paysera Plugins Detected. Only one version of the Paysera Checkout plugin can be active at a time. Please deactivate the currently enabled version before activating another." Disable the legacy extension first in Stores → Configuration → Sales → Payment Methods → All popular payment methods | Paysera, then enable Paysera Smart Checkout.
  • Older versions of the legacy extension may not check for Paysera Smart Checkout, so always disable one extension before you enable the other.
  • If both end up enabled, for example through bin/magento config:set --lock-env, a configuration import, or in different scopes, Paysera Smart Checkout is hidden from the checkout for the affected store views and the Magento Admin shows a critical system message until one of them is disabled.

Updating​

If you installed the extension from an archive, delete the contents of app/code/Paysera/Checkout and extract the latest archive into it. The extension requires the Paysera Checkout SDK (paysera/lib-checkout-integration-sdk) 3.6 or later, so update the SDK explicitly before setup:upgrade:

composer require paysera/lib-checkout-integration-sdk "^3.6"
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

If you installed the extension with Composer from the Adobe Commerce Marketplace, run:

composer update payserauk/magento2-paysera-smart-checkout-module
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

If the store runs in production mode, add the maintenance and static-content steps from Production mode under Installation.

Updating keeps every setting. Never uninstall the extension to update it: uninstalling deletes the settings and the credentials.

Uninstalling​

Uninstalling deletes every Paysera Smart Checkout setting in every scope (default, websites and store views), including the Client ID and Client Secret, and the cached Paysera access token and authorization status. It keeps your orders and the Paysera payment details stored on them, which stay visible in the admin order view, the customer account, order emails and PDFs, and the settings of the legacy Paysera extension.

If you installed the extension with Composer, run:

php bin/magento module:uninstall --remove-data Paysera_Checkout

The --remove-data option is required: without it Magento removes the code but keeps the settings and credentials in the database, and does not ask about them.

If you installed the extension from an archive into app/code/Paysera/Checkout, run:

php bin/magento module:uninstall --non-composer Paysera_Checkout

Then delete the folder app/code/Paysera/Checkout and run:

php bin/magento setup:upgrade
php bin/magento cache:flush

Disabling is not uninstalling: setting Enabled to No, or running php bin/magento module:disable Paysera_Checkout, keeps every setting, so the extension can be enabled again without entering the credentials again.

Next Steps​