VibeFox Przelewy24 for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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 extension 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 store 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 extension sends its notification URL with every payment. Your store 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_przelewy24_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_przelewy24_payment.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_przelewy24_payment-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Przelewy24 Payment and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_przelewy24_payment.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Przelewy24 Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Przelewy24 keys as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the notification URL is different (see Payment notifications).

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Przelewy24 Payment > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store, the warning names the currency and the supported ones. After you save, the warnings follow the new mode and keys at once. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, nothing is saved if a field is wrong: Title must not be empty (Enter a title for the payment method (at most 128 characters).), Sort Order must be a whole number (negative values are allowed), Total a number 0 or greater, and Geo Zone and the order statuses must exist. Missing keys do not block saving. 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, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay with BLIK, online bank transfer or card via Przelewy24.

Sort Order: the position of Przelewy24 among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Przelewy24 only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Przelewy24 is offered. Leave it empty to offer Przelewy24 for any total.

API credentials

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

Test Mode: uses the Przelewy24 sandbox and the Sandbox keys. No real money is charged. Turn it off to accept real payments with the Live keys. Default: on. While it is on, customers see Sandbox mode - no real money is charged at the Confirm Order step.

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. To remove a saved key, tick Clear the saved value under the field and click Save.

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. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_przelewy24_payment/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_przelewy24_payment/payment/wcp_przelewy_24payment.notify. It is built from the storefront address of your OpenCart installation. The extension 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 store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action for the notification URL and the return of the customer. Without notifications, a payment is still confirmed when the customer comes back to the store (see Checkout); if the customer does not come back, the order stays without a status.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Przelewy24 has confirmed the payment and the extension has verified it. Each field below lists your OpenCart order statuses.

Paid Order Status: the status after a verified payment. Default: Processing.

On Hold (Review) Status: payments whose amount or currency do not match the order (not verified), or that arrive after the order was cancelled, get this status and a note explaining why. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: the extension never sets it. A payment verified for an order in this status puts the order on hold instead of silently reopening it. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Debug Log: writes technical events (order numbers, P24 transaction IDs, errors) to wc_p24_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to wc_p24_debug.old.log.php. 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 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 extension removes the gateway settings and the log. Orders and their Przelewy24 payment data are never deleted. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The API and CRC keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved API and CRC keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Przelewy24). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure Przelewy24 page to complete the payment. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension registers a Przelewy24 transaction for the order total in the order currency, with the customer's e-mail, name and billing country, and the description Order # with the order number and your store 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 order if Przelewy24 supports it, otherwise in English. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

The order is marked paid only after Przelewy24 confirms it. Przelewy24 sends a signed notification to your store. The extension 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 order total. Only then it verifies the transaction with Przelewy24 (Przelewy24 credits only verified payments) and sets Paid Order Status the standard OpenCart way, with the usual order e-mails and stock update. Webhooks without a valid signature are rejected.

After paying, the customer comes back to your store. If the notification has not arrived yet, the extension asks Przelewy24 for the transaction status with an authenticated server-to-server request (at most once every 10 seconds per attempt) and applies the same checks. The return page alone never marks an order as paid. When the payment is confirmed, the customer sees the OpenCart order success 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 is still accepted. If the order is on hold, the success page shows Your payment is being verified. We will send you an e-mail as soon as it is confirmed. When a payment later moves the order from the on hold status to Paid Order Status, the customer is notified by e-mail. If you cancelled the order before it was paid and Przelewy24 has no payment for it, the customer who comes back sees Order #… was cancelled by the store before the payment was completed. No Przelewy24 payment was received for it. Please place a new order or contact us.

If the payment cannot be started, the customer stays at the Confirm Order step with a short message above the button: 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. OpenCart 3 creates a new order every time the Confirm Order step is shown; an order or cart that is already paid is not sent to Przelewy24 again, and the customer goes to the success page.

OpenCart 4 keeps one order for the checkout and updates it each time the Confirm Order step is shown, so Pay again starts a new Przelewy24 transaction for the same order. If that order was closed by the store meanwhile (for example cancelled or refunded), the customer is sent back to the checkout with Your previous order was closed by the store. Please confirm the order again to place and pay a new order. (for an order cancelled before any payment, with the message about the cancelled order above), and the next Confirm Order pays a new order. If the order of the checkout is already paid but the cart has changed since, including a new quantity, the customer sees Your previous order #… has already been placed. Your cart has changed: please confirm the new order to pay for it. and the new cart is paid with a new order. On OpenCart 4 these messages, and We could not match this payment to an order. If you were charged, please contact us., are shown above the checkout page.

The extension 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 status (missing order): the customer was sent to Przelewy24 and has not paid, or the payment is not confirmed yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Paid Order Status (default Processing): the payment was verified. A note shows the P24 order ID, the amount and the mode. Each payment is applied once.

On Hold (Review) Status (default Pending): the amount or currency reported by Przelewy24 differs from the order; the payment was not confirmed and the note says so. Or the payment arrived and was verified for an order in the cancelled status; 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 Paid Order Status.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

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

Notes are entries in the order History that the customer does not see.

VibeFox Przelewy24 Payment tab

In Sales > Orders open an order paid with Przelewy24. At the bottom of the order page, next to History and Additional, the VibeFox Przelewy24 Payment tab shows the P24 order ID, the Session, the Environment (Sandbox or Live), the payment Status and how it was verified (notification or return), the amounts Paid / refunded, the refund form, the refund history and the Payment notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Przelewy24 Payment tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 modify the extension (set in System > Users > User Groups). 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 tab 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 Status when it is requested, without notifying the customer and without returning products to stock, like a manual status change. 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 tab shows Przelewy24 refund failed: with the reason, and no refund is recorded. Product returns in Sales > Returns do not send money back through Przelewy24, and refunds made directly in the Przelewy24 panel are not added to the order.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Przelewy24 Payment is the first block on Extensions > Extensions > Payments > VibeFox Przelewy24 Payment > Edit, 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: opencart-payment-przelewy24 and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still verified and confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 order currency is PLN, EUR, GBP or CZK. The warnings at the top of the settings name the problem. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the notification from Przelewy24 did not reach your store and the customer did not come back to the store. 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 extension page.

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), 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), 500 Order could not be updated (the order status could not be set; the next notification sets it without a new verification) and 503 Busy, retry later (the order 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.

The customer sees We could not match this payment to an order: the return link from Przelewy24 did not match an order of the store. If the customer was charged, find the payment in the Przelewy24 panel.

Order is in the review status after payment: read the notes in the VibeFox Przelewy24 Payment tab. 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. Invalid refund amount means the amount is empty, not a number, or more than the amount not refunded yet.

For developers: the list of currencies can be changed with the OpenCart event wc_p24_supported_currencies (only currencies with two decimal places).

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Przelewy24 Payment. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notifications and the return of the customer through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, test mode, keys, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The Przelewy24 payment data of orders (sessions, P24 order IDs, refunds) is always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Przelewy24 Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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