VibeFox Przelewy24 for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: the order must be in PLN, EUR, GBP or CZK. In other currencies the payment method is hidden at checkout. The order is charged in its own currency; the plugin 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 plugin sends its notification URL with every payment. Your site 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_przelewy24_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Przelewy24 > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

6. Enter the live keys, untick Test Mode and save to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Przelewy24. 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 store currency, 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.

Checkout

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

Title: the payment method name customers see at checkout. Default: Przelewy24.

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: Enable sandbox (test) mode. When on, new payments go to the Przelewy24 sandbox (sandbox.przelewy24.pl) with the Sandbox keys, and no real money is charged. Untick it to accept real payments on secure.przelewy24.pl with the Live keys. Default: on.

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, together with the POS ID.

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.

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

This section shows the notification URL of your store. It looks like https://your-site/wc-api/wc_p24_payment/. The plugin sends this URL to Przelewy24 with every payment, so nothing has to be configured in the Przelewy24 panel. The same URL receives refund results. The URL must be reachable from the internet: no firewall, maintenance mode or HTTP authentication in front of it. Without notifications, a payment is still confirmed when the customer comes back to the order received page (see Checkout); if the customer does not come back, the order stays Pending payment.

Advanced

Debug Log: Enable logging writes technical events (order numbers, P24 transaction IDs, errors) to WooCommerce > Status > Logs, source wcp_przelewy24_payment. Errors and warnings are always logged. Keys, request bodies and personal data are never logged. Default: off.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Orders and their payment data are never deleted. Deactivating the plugin keeps everything. Default: off.

Checkout

The customer chooses the payment method (by default Przelewy24, with the P24 logo on the Checkout block) and places the order. In sandbox mode the Checkout block shows Sandbox mode — no real money is charged. The plugin registers a Przelewy24 transaction for the order total in the order currency, with the customer's e-mail, name and billing country, and adds an order note with the session ID and the mode (sandbox or live). 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 site language if Przelewy24 supports it, otherwise in English.

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

After paying, the customer comes back to the order received page. If the notification has not arrived yet, the plugin asks Przelewy24 for the transaction status with an authenticated server-to-server request (at most once every 10 seconds per order) and applies the same checks. The return page alone never marks an order as paid. While the payment is not confirmed, the 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 Pay again button that opens the Pay for order page. If the order is on hold, the page shows Your payment is being verified. We will send you an e-mail as soon as it is confirmed. A payment made later on an older Przelewy24 page of the same order is still accepted.

If the payment cannot be started, the customer sees 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 order currency, or The order total must be greater than zero. An order that is already paid or on hold is not sent to Przelewy24 again (This order does not need a payment any more.).

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

Pending payment: the customer was sent to Przelewy24 and has not paid yet, or the payment is not confirmed yet.

Processing or Completed: the payment was verified. WooCommerce sets Processing, or Completed for orders with only virtual downloadable products. The order note shows the P24 order ID, the amount and the mode. The transaction ID of the order is the P24 order ID. Each payment is applied once.

On hold: the amount or currency reported by Przelewy24 differs from the order (for example, the order total 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 second payment arrives for an order that 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.

Refunds

Open the order, click Refund, enter the amount and click Refund via Przelewy24. Full and partial refunds are supported. The refund is sent in the mode the payment was made in (sandbox or live), so the keys of that mode must be set. Przelewy24 processes refunds asynchronously: the order note first says the refund was requested, and the result arrives later at the notification URL and is added as a note: Przelewy24: refund of … completed. or a note that the refund was rejected and the money was not returned. If a refund is rejected, check it in the Przelewy24 panel; the WooCommerce refund already recorded on the order is not removed automatically.

If Przelewy24 does not accept the refund request, WooCommerce shows Przelewy24 refund failed: with the reason, and no refund is recorded. Refunds made directly in the Przelewy24 panel are not added to the order.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Przelewy24. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 order currency is PLN, EUR, GBP or CZK. The warnings at the top of the settings name the problem. Developers can change the list of currencies with the filter wc_p24_supported_currencies (only currencies with two decimal places enabled for your Przelewy24 account).

The payment went through, but the order stays Pending payment: the notification from Przelewy24 did not reach your store and the customer did not come back to the order received page. Check that the URL shown in Payment notifications is reachable from the internet (no maintenance mode, firewall or HTTP authentication in front of /wc-api/wc_p24_payment/) and that the Merchant ID, POS ID and CRC key of the mode of the payment are correct. Rejected notifications are logged in WooCommerce > Status > Logs, source wcp_przelewy24_payment, even with Debug Log off.

How the store 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, or 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) and 503 Busy, retry later (the order was being updated 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.

The order is On hold after payment: read the order note. The amount or currency differed from the order, 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the short-lived return-page markers are always removed. The plugin settings and its logs (log files, including rotated ones, and database log entries of the source wcp_przelewy24_payment) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and Przelewy24 payment data.

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