VibeFox Paysera for Adobe Commerce — Ajuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4.

Paysera project: you need the project ID and the project password (sign key) of your Paysera project. The payment methods the customer sees are the ones enabled in this project. Nothing has to be configured in Paysera for the callback: its URL is sent with every payment request.

Reachable store: orders are marked paid by the Paysera callback, so your store must be reachable from the internet, not behind a login, basic authentication or a firewall.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-paysera-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/PayseraPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_PayseraPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Paysera Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the Project ID and the Project password from your Paysera account (see Configuration). Optional: enable Allow test payments in the Paysera project and set Test payments to Yes to try the flow without charging money. Set Enable to Yes, click Save Config and place a test order. Set Test payments back to No before selling.

The module adds the Paysera payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates its own tables for the Paysera payment attempts and the processed callbacks.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Paysera Payment, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall exists only in the Default Config. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Payment method title is required and must not exceed 128 characters.); a Project ID with anything but digits (Project ID must be a number: the numeric ID of your Paysera project.); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total limit must be a non-negative number.). Spaces at the start and end of the values are removed.

Paysera project and callback

The first row after the license block shows The callback URL is sent with every payment automatically., the callback URL of the store view of the selected scope (in the Default Config, of the default store view), and the hints Find Project ID and Project password in your Paysera account, Projects and activities, General project settings. and Paysera uses signed or authenticated encrypted callbacks. It has no status or online refund API. Each payment sends the callback URL of the store view where the order was placed. It looks like https://your-store/wcppayserapayment/checkout/callback/?store=1. Nothing has to be configured in Paysera, but this address must be reachable from the internet. Orders are marked paid only by these signed callbacks.

While Enable is Yes, the row also shows Paysera is hidden at checkout until Project ID and Project password are entered. while one of them is missing, and Paysera test mode is on. Select Production and turn off Test payments before accepting real orders. while Test payments is on or Environment is Sandbox. It always ends with Keep project credentials unchanged until pending payments have settled. Changing them invalidates earlier callback signatures.

General

Enable: shows or hides Paysera at checkout. It is shown only when the Project ID and the Project password are set. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Paysera. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely via Paysera.

Paysera project

Project ID: the numeric ID of your Paysera project (Projects and activities, your project, General project settings). Only digits are accepted.

Project password: the project password (sign key). It signs payment requests and verifies Paysera callbacks. Magento stores it encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved password, type a new value to change it. To delete the saved password, clear the field and click Save Config.

The callbacks are verified with the current Project ID and Project password of the store view. If you change them, payments started before the change can no longer be verified, so change them only when no payments are pending.

Testing

Test payments: sends payments in test mode, so no money is charged. Enable Allow test payments in the Paysera project settings first. While this option is Yes, a successful test payment marks the order paid; while it is No, a test payment puts the order On Hold with a note that no money was charged. Default: No.

Environment: where the customer is sent. Production also supports test payments. Sandbox is for a sandbox project. Default: Production.

While Test payments is Yes or Environment is Sandbox, customers see TEST MODE — no money will be charged. under the payment method.

Orders

Order status after payment: what happens to the order after a confirmed payment. The invoice is always created first.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Paysera for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Paysera only for billing addresses in these countries.

Minimum Order Total: offer Paysera only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Paysera only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number, including negative values.

The countries and the order total limits are checked again when the payment is started.

Advanced

Debug log: writes payment events to var/log/wc_psr_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always recorded; the other steps only while this option is Yes. Passwords, raw callbacks and customer data are never written. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes, its cache and the log (see Uninstall). The license key is always removed. Orders and the Paysera payment and callback records are always kept. Default: No.

Debug log viewer: shows the size and the latest entries of the log (up to 50 KB). Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Paysera) and sees the description and the note You will be redirected to the Paysera payment window. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.

The module builds a signed payment request with the order total in the minor unit of the order currency, the customer's name, e-mail and billing address, and the language of the store view (Lithuanian, Latvian, Estonian, Russian, German, Polish, otherwise English). The Paysera order ID is the internal Magento order ID. The customer is sent to the Paysera payment window and chooses a bank, card or other method there.

Paysera confirms the payment with a server-to-server callback. The order is marked paid only after Paysera confirms it with a signed callback, and only if the amount and the currency match the order. Then Magento creates the invoice with the Paysera request ID as the transaction ID, the order follows Order status after payment and the order e-mail is sent. The customer's return to the store never marks an order paid. The callback is handled even when Enable is No or the license is not active, as long as the Project ID and the Project password are set.

When the customer comes back after the callback, the standard order success page is shown. A customer who comes back to a paid order in another browser lands on the home page with Your Paysera payment has been confirmed. If the customer comes back before the callback, or the bank has accepted the payment order but not executed it yet, a Paysera payment confirmation page shows Paysera is confirming your payment. Your order will be paid only after a signed callback. There is no need to pay again. with a Check again link and, while the payment is not confirmed yet, Cancel and return to checkout. For an order on hold the page shows Your Paysera payment is being reviewed. We will contact you if anything else is needed.

If the customer cancels in the Paysera window, clicks Cancel and return to checkout, or Paysera reports that the payment was not executed, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your Paysera payment was not completed. You can choose a payment method again. The customer can pay again or choose another payment method. If the cart is already paid by another order, or another payment of the cart is still awaiting confirmation or review, the cart is not restored and no second payment is started.

If the payment cannot be started, the order is cancelled with the note Paysera: payment could not be started., the cart is restored and the customer sees a short message in the cart, for example Paysera payments are temporarily unavailable. Please choose another payment method. (the module is disabled, the Project ID or Project password is missing, or a store address sent to Paysera is longer than 255 characters), This order does not meet the Paysera total limits., Paysera is not available for this billing country. or This order cannot be paid via Paysera. A warning is written to the log.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module marks the payment attempt of such an order, or of an order you cancel yourself, as cancelled. Paysera has no API to stop a started payment, so if Paysera later confirms the payment, the order is not invoiced and not reopened: it stays Canceled and a note asks you to check or refund the payment in Paysera.

The module works with the standard Magento checkout. It has no choice of bank or payment method on the checkout page, no subscriptions, no saved cards and no Paysera delivery or courier services. Paysera is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Paysera, but Paysera has not confirmed the payment yet. If Paysera accepted the payment order but the bank has not executed it yet, a note says so. There is no invoice. The order is invoiced when Paysera confirms the payment.

Processing, Complete or On Hold: Paysera confirmed the payment with the matching amount and currency. The state follows Order status after payment. The invoice is created with the Paysera request ID as the transaction ID, and a note shows the request and the payment method, marked (TEST) for test payments.

On Hold without an invoice: the payment needs a manual review. The paid amount or currency differs from the order total (the note shows the reported and the expected amount), a TEST payment arrived while Test payments is No (no money was charged), or another order of the same cart is already paid. Check the payment in your Paysera account, then refund it in Paysera or settle the order. A later correct payment for the same order releases the hold and marks it paid.

Canceled: the customer cancelled, the payment was not executed or could not be started, or the order was cancelled in Magento. A payment confirmed later does not change the order; a note asks you to check or refund the payment in Paysera.

If another successful payment arrives for an order that is already paid, the order is not changed, and a note asks you to refund the duplicate in your Paysera account. Repeated callbacks, even at the same moment, never invoice an order twice. Other Paysera statuses (payment not executed, additional information) only add a note. The notes are order comments that the customer does not see.

Paysera payment block

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after a confirmed payment, Paysera request ID, Environment, Paysera payment method and Test payment. The customer sees only the payment method title. Below the order information a VibeFox Paysera Payment block lists every payment attempt with Native order ID, Request ID, Environment, Test payment, the Requested amount, the amount Reported by Paysera, the State and the Paysera status, followed by Paysera private notes. The block is shown also when the module is disabled.

Refunds

Online refunds are not supported: the Paysera payment window protocol has no refund API, and the order block says Paysera has no online refund API. Refund in Paysera and record native accounting manually if needed. Make refunds in your Paysera account. When Paysera reports a refund, a note with the refunded amount is added to the order and the order status is not changed. To record the refund in Magento, open the invoice, click Credit Memo and use Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Paysera Payment is the first row of the VibeFox Paysera Payment group in Stores > Configuration > Sales > Payment Methods (Default Config scope), above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-paysera and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Paysera is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed by the callback.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Paysera does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that both Project ID and Project password are entered. The Paysera project and callback row shows a warning while they are missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the order is marked paid by the Paysera callback, not by the customer's return. Check that your store is reachable from the internet at the callback URL shown in the Paysera project and callback row (not behind a login, basic authentication or firewall), and that the Project ID and Project password of the store view are the ones of the project that took the payment. If the bank has not executed the payment order yet, the order waits until Paysera confirms it. Look at the Debug log viewer.

The callback answers Invalid signature: the Project password does not match the project, or the callback is not from Paysera. Copy the project password again. If you changed the project or the password, payments started before the change can no longer be verified.

The callback answers Project ID mismatch: the Project ID in the settings differs from the project that made the payment.

The callback answers Order not found or Store mismatch: the order in the callback has no Paysera payment in this store, for example the payment was started in another installation or store view with the same project.

The callback answers Gateway not configured, Busy or Temporary error: the Project ID or Project password is empty, another callback for the same cart is still running, or an error occurred while the order was being updated. Paysera retries the callback. Turn on Debug log to see the reason.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL too. The order is confirmed by the next callback that reaches the store.

Paysera rejects the payment window or says the project does not exist: check Environment. A normal Paysera project works only with Production; Sandbox needs a project created in the Paysera sandbox environment.

The test payment does not pay the order: a TEST payment pays an order only while Test payments is Yes. Otherwise the order is put On Hold with a note that no money was charged. Also enable Allow test payments in the Paysera project.

The order is On Hold with a note about an amount or currency mismatch: Paysera confirmed a payment whose amount or currency differs from the order total. Compare the payment in your Paysera account and settle the order or refund the payment in Paysera. A later correct payment for the same order marks it paid.

The customer is back in the cart with Paysera payments are temporarily unavailable: look at the Debug log viewer. The Project ID or Project password may be empty, the module may be disabled for that website, or one of the store addresses sent to Paysera is longer than 255 characters.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_PayseraPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_PayseraPayment to remove the data, then bin/magento module:disable Vibefox_PayseraPayment, delete the folder app/code/Vibefox/PayseraPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings of all scopes, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Paysera payment attempts and callbacks are always kept. Existing orders keep their invoices, payment notes and transaction IDs.

Paysera is a trademark of its respective owner. This module is not affiliated with or endorsed by Paysera.