VibeFox Przelewy24 for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: the cart must be in PLN, EUR, GBP or CZK. In other currencies the payment method is hidden at checkout. The cart is charged in its own currency; the module does not convert currencies.

Przelewy24 account: you need a Przelewy24 merchant account and its API data: the Merchant ID, the API key (called report key in the Przelewy24 panel), the CRC key and, if your shop has its own ID, the POS ID (Shop ID). You find them in the Przelewy24 merchant panel at panel.przelewy24.pl, under My data > API data and configuration. Sandbox keys come from a separate sandbox account at sandbox.przelewy24.pl/panel. Nothing else has to be set up in the Przelewy24 panel: the module sends its notification URL with every payment. Your shop must be reachable from the internet, because Przelewy24 sends payment notifications to it.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Przelewy24 Payment in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the sandbox keys (Merchant ID, API key, CRC key; POS ID only if it differs from the Merchant ID), turn on Enable/Disable, click Save and make a test payment in sandbox mode.

5. Enter the live keys, turn off Test Mode and click Save to accept real payments.

On install the module creates the order status Przelewy24 payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Przelewy24 Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows warnings when something is missing. While the sandbox is on: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. When the keys of the current mode are incomplete: Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (or the same for the Live keys). When Przelewy24 does not accept the default currency of your shop, the warning names the currency and the supported ones. After you save, the warnings follow the new mode and keys at once. Spaces and line breaks copied together with the keys from the Przelewy24 panel are removed when you save.

Przelewy24

Enable/Disable: Enable Przelewy24 Payment turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Przelewy24. Required: saving with an empty title shows Enter a title for the payment method.

Description: the text shown under the payment method at checkout. Default: Pay with BLIK, online bank transfer or card via Przelewy24.

API credentials

The section explains where to find the keys (My data > API data and configuration in the Przelewy24 merchant panel) and links to panel.przelewy24.pl and sandbox.przelewy24.pl/panel.

Test Mode: uses the Przelewy24 sandbox (sandbox.przelewy24.pl) and the Sandbox keys. No real money is charged. Turn it off to accept real payments on secure.przelewy24.pl with the Live keys. Default: on. While it is on, customers see Sandbox mode - no real money is charged under the payment method.

Live keys

Live Merchant ID: your Przelewy24 merchant ID, numbers only.

Live POS ID (optional): the Shop ID (posId). Leave it empty if it is the same as the Merchant ID.

Live API key (report key): the API key from the Przelewy24 panel. It is used for API authentication.

Live CRC key: used to sign requests to Przelewy24 and to check the signature of Przelewy24 notifications.

Sandbox keys

Sandbox Merchant ID: the Merchant ID of your Przelewy24 sandbox account.

Sandbox POS ID (optional): the Shop ID (posId) of the sandbox account. Leave it empty if it is the same as the Merchant ID.

Sandbox API key (report key): the API key of the sandbox account.

Sandbox CRC key: the CRC key of the sandbox account, used to sign requests and to check sandbox notifications.

Saved API keys and CRC keys are never shown again. The field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a key and click Save to remove it. An empty field keeps the saved value.

Live and sandbox keys are different. The Merchant ID and POS ID must contain digits only; until the Merchant ID, API key and CRC key of the current mode are entered, the payment method is not shown at checkout. A payment started in one mode is always verified and refunded with the keys of that mode, even after you switch, so keep the keys of the old mode while its payments are still open or may be refunded.

Payment notifications

Notification URL: the address that receives payment notifications from Przelewy24. With friendly URLs it looks like https://your-shop/module/wcp_przelewy24_payment/notify, possibly with a language code such as /en/. The module sends this URL to Przelewy24 with every payment and every refund, so nothing has to be configured in the Przelewy24 panel. The URL must be reachable from the internet: no firewall or HTTP authentication in front of it. It keeps working while the shop is in maintenance mode and is not blocked by the country restriction of your shop. Without notifications, a payment is still confirmed when the customer comes back to the shop (see Checkout); if the customer does not come back, no order is created.

Advanced

Debug Log: writes technical events (cart numbers, P24 transaction IDs, errors) to logs/wc_p24_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings, such as rejected notifications or a failed verification or refund, are always logged; turn the switch on to log every step as well. Keys, request bodies and personal data are never logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the module settings and the log. Orders and their Przelewy24 payment data are never deleted. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Przelewy24, with the P24 logo) and confirms the order. The module registers a Przelewy24 transaction for the cart total in the cart currency, with the customer's e-mail, name and billing country, and the description Cart # with the cart number and your shop name. Every payment attempt gets its own session ID. The customer is sent to the Przelewy24 payment page and pays with BLIK, an online bank transfer, a card or another method enabled for your Przelewy24 account. The payment page is shown in the language of the customer's cart if Przelewy24 supports it, otherwise in English. No order exists yet at this point.

The order is marked paid only after Przelewy24 confirms it. Przelewy24 sends a signed notification to your shop. The module checks the signature with the CRC key, the Merchant ID and POS ID, that the session was registered for this cart and in the same mode, and that the amount and currency match the payment attempt and the current cart total. Only then it verifies the transaction with Przelewy24 (Przelewy24 credits only verified payments) and creates the order in Payment accepted. Webhooks without a valid signature are rejected.

After paying, the customer comes back to your shop. If the notification has not arrived yet, the module asks Przelewy24 for the transaction status with an authenticated server-to-server request (at most once every 10 seconds per cart) and applies the same checks. The return page alone never marks an order as paid. When the payment is confirmed, the customer sees the standard order confirmation page. While it is not confirmed, a Payment confirmation page shows We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: with a Check again button and a Pay again button that opens the checkout. The cart is kept, and a payment made later on an older Przelewy24 page of the same cart is still accepted. If the order is on hold, the confirmation page shows Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

If the payment cannot be started, the customer stays at checkout with a short message: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (the reason goes to the log), Payment gateway is not configured properly. Please contact the administrator. (keys of the current mode missing), a message that Przelewy24 cannot accept payments in the cart currency, or The order total must be greater than zero. A cart that already has an order is not sent to Przelewy24 again; the customer goes to the order confirmation.

The module has no saved cards or one-click payments, no subscriptions or recurring payments, no choice of the P24 payment method (for example a BLIK code field) on your checkout page, no installment widgets and does not send cart contents to Przelewy24.

Orders and refunds

Order statuses

No order yet: the customer was sent to Przelewy24 and has not paid, or the payment is not confirmed yet. Only the cart exists.

Payment accepted: the payment was verified. The payment is recorded with the P24 order ID as the transaction ID, and a note shows the P24 order ID, the amount and the mode. Each payment is applied once.

Przelewy24 payment on hold: the amount or currency reported by Przelewy24 differs from the cart (for example, the cart was changed after the payment was started); the payment was not confirmed and the note says so. Or the payment arrived and was verified for an order that had been cancelled; the order is not reopened silently, the note asks you to ship it or refund the payment. Check the payment in the Przelewy24 panel. If a correct payment of another attempt arrives later for an order on hold after a mismatch, the order moves to Payment accepted.

Refunded: the payment was fully refunded through the module.

If a second payment arrives for a cart whose order is already paid or refunded (an older payment link, two browser tabs), it is not confirmed, so Przelewy24 does not credit it. A note on the order asks you to check it in the Przelewy24 panel and return it to the buyer if needed.

Przelewy24 payment block

The order page shows a Przelewy24 payment block with the P24 order ID, the session, the environment (a Sandbox badge for sandbox payments), the payment status and how it was verified (notification or return), the paid and refunded amounts, the refund form, the refund history and the Payment notes of the order.

Refunds

In the Przelewy24 payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Przelewy24. Confirm the question Refund this amount through Przelewy24? This cannot be undone. Full and partial refunds are supported, up to the amount not refunded yet. You need the right to edit orders; access to the Modules pages is not needed. The refund is sent in the mode the payment was made in (sandbox or live), so the keys of that mode must be set. Refunds are available once Przelewy24 has verified the payment.

Przelewy24 processes refunds asynchronously. The block shows Refund of … requested at Przelewy24. The result will be added as an order note., the refund history shows the status requested, and a note is added. The result arrives later at the notification URL: the status becomes completed with the note Przelewy24: refund of … completed., or rejected with a note that the money was not returned to the buyer. A full refund sets the order to Refunded when it is requested; a partial refund does not change the status. If a refund is rejected, check it in the Przelewy24 panel; the order status is not changed back automatically.

If Przelewy24 does not accept the refund request, the block shows Przelewy24 refund failed: with the reason, and no refund is recorded. The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Przelewy24, and refunds made directly in the Przelewy24 panel are not added to the order.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Przelewy24 Payment is the first block on Modules > Module Manager > VibeFox Przelewy24 Payment > Configure, 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 shop. Below them are the line Product: presta-payment-przelewy24 and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Przelewy24 is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still verified and confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Przelewy24 does not appear at checkout: check that the license is active, Enable/Disable is on, the Merchant ID, API key and CRC key of the current mode are entered (the Sandbox keys while Test Mode is on, the Live keys otherwise; Merchant ID and POS ID digits only) and the cart currency is PLN, EUR, GBP or CZK. The warnings at the top of the settings name the problem. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. Developers can change the list of currencies with the hook actionWcpPrzelewy24SupportedCurrencies (only currencies with two decimal places enabled for your Przelewy24 account).

The payment went through, but no order was created: the notification from Przelewy24 did not reach your shop and the customer did not come back to the shop. Check that the Notification URL is reachable from the internet (no firewall or HTTP authentication in front of it) and that the Merchant ID, POS ID and CRC key of the mode of the payment are correct. Rejected notifications are written to the log even with Debug Log off; look at the Log field on the module page.

How the shop answers notifications: a processed, repeated or unknown notification is answered with HTTP 200. Otherwise Przelewy24 sends it again later: 400 (missing or malformed data), 401 Invalid signature (wrong CRC key, other Merchant ID or POS ID), 401 Invalid signature for this payment (a notification signed with the keys of the other mode than the payment), 405 (not a POST request), 500 Verification failed (the verification with Przelewy24 failed; a note is added to the order once if it exists), 500 Order could not be created (for example, the module is disabled; the next notification creates the order without a new verification) and 503 Busy, retry later (the cart was being confirmed by another request at the same moment).

The customer sees Payment error: Przelewy24 could not start the payment: Przelewy24 rejected the transaction, usually because of wrong keys of the current mode (sandbox keys work only in sandbox mode, live keys only in live mode). The error from Przelewy24 is in the log.

Order is Przelewy24 payment on hold after payment: read the notes in the Przelewy24 payment block. The amount or currency differed from the cart, or the payment arrived for an order that had been cancelled. Check the payment in the Przelewy24 panel, then process the order or refund the payment.

A refund fails: This order has no verified Przelewy24 payment. Cannot process refund. means the order was not paid through a verified Przelewy24 payment. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (or the same for live) means the keys of the payment's mode were removed; enter them again. Invalid refund amount means the amount is empty, not a number, or more than the amount not refunded yet.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Przelewy24 Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Przelewy24 payment data of orders (sessions, P24 order IDs, refunds) and the order status Przelewy24 payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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