VibeFox Przelewy24 for Adobe Commerce — ヘルプ

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.

Currency: the order currency must be PLN, EUR, GBP or CZK. In other currencies the payment method is hidden at checkout. The order 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 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 module sends its notification URL with every payment.

Reachable store: Przelewy24 sends payment notifications to your store, so the site must be reachable from the internet, without a firewall or basic authentication in front of it.

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-przelewy24-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/Przelewy24Payment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_Przelewy24Payment 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 Przelewy24 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 sandbox keys (Merchant ID, API key, CRC key; POS ID only if it differs from the Merchant ID), keep Test mode at Yes, set Enable to Yes, click Save Config and place a test order. When everything works, enter the live keys, set Test mode to No and click Save Config.

The module adds the Przelewy24 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 Przelewy24 payment attempts and refunds. The notification URL is sent to Przelewy24 automatically, so nothing has to be configured in the Przelewy24 panel.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Przelewy24 Payment, in the standard Magento configuration form. The fields are one list in the order below. They can be changed for a website or a store view with the Scope switcher at the top of the page; a payment uses the settings of the store view where the order was placed. Delete data on uninstall is read from the Default Config only. The license block, Gateway notices and Log are shown only in the Default Config. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

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 (Enter a title for the payment method (1 to 128 characters).); 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 must be a number, 0 or greater.). Spaces and line breaks copied together with the IDs and keys from the Przelewy24 panel are removed when you save. A Merchant ID or POS ID that is not numeric is saved without an error, but the payment method stays hidden at checkout until it is corrected.

Enable: shows or hides Przelewy24 at checkout. It is shown only when the Merchant ID, the API key and the CRC key of the current mode are set. Default: No.

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

Description: the text shown under the payment method when the customer selects it. Default: Pay with BLIK, online bank transfer or card via Przelewy24.

Test mode: uses the Przelewy24 sandbox (sandbox.przelewy24.pl) and the Sandbox keys. No real money is charged. Set it to No to accept real payments on secure.przelewy24.pl with the Live keys. Default: Yes. While it is on, customers see TEST MODE — no real charges will be made. under the payment method.

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

Live POS ID: the Shop ID (posId), numbers only. Leave empty to use the Merchant ID.

Live API key: the API key (report 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 Merchant ID: the Merchant ID of your Przelewy24 sandbox account.

Sandbox POS ID: the Shop ID (posId) of the sandbox account. Leave empty to use the Merchant ID.

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

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

Magento stores the API keys and CRC keys encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved key, type a new value to change it. To delete a saved key, clear the field and click Save Config.

Live and sandbox keys are different. 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 from Applicable Countries: All Allowed Countries offers Przelewy24 for every country your store allows, Specific Countries only for the countries below.

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

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

Maximum Order Total: offer Przelewy24 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; a negative number is allowed.

Debug log: the log setting of the module. The module writes errors, such as a failed API request or a failed verification, to var/log/wc_p24_debug.log.php in the Magento folder with this setting on or off. The file cannot be opened from the web and is rotated at 5 MB. Keys, request bodies and personal data are not logged. Default: No.

Delete data on uninstall: Removes settings and log only. Payment and refund history is always retained. When Yes, uninstalling the module with its data removes the module settings of all scopes and the log (see Uninstall). The license key is always removed. Default: No.

Gateway notices: shows the Notification URL, the address that receives notifications from Przelewy24. It looks like https://your-store/wcpprzelewy24payment/checkout/notify and is built for the default store view. Each payment and each refund sends the URL of the store view where the order was placed, so nothing has to be configured in the Przelewy24 panel. The URL only has to be reachable from the internet. While Enable is Yes, the row also shows warnings: Przelewy24: test mode is enabled.; Przelewy24: enter Merchant ID, POS ID, API key and CRC key for the current environment.; and Przelewy24: supported currencies: PLN, EUR, GBP, CZK. when the default currency of your store is not one of them. The warnings check the values of the Default Config.

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

Checkout

At the payment step the customer chooses the payment method (by default Przelewy24) and sees the description and the note You will be redirected to Przelewy24 to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module 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 Magento order number. 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 store view if Przelewy24 supports it, otherwise in English. If the customer opens the payment step again for the same order, the same Przelewy24 payment page is used.

The order is marked paid only after Przelewy24 confirms it. Przelewy24 sends a signed notification to your store. The module checks the signature with the CRC key, the Merchant ID and POS ID, that the session was registered by this store 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). Webhooks without a valid signature are rejected. Notifications are accepted from any store view, and notifications, returns and refunds work also when Enable is No or the license is not active.

After a successful verification Magento creates the invoice with the P24 order ID as the transaction ID, the order moves to Processing and the order e-mail is sent. If the same order was already confirmed, nothing happens a second time.

After paying, the customer comes back to your store. The return link contains a random token of the payment attempt. If the notification has not arrived yet, the module asks Przelewy24 for the transaction status of the latest attempt with an authenticated server-to-server request (at most once every 10 seconds) 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 success page.

While the payment is not confirmed, a Przelewy24 payment status page shows the order number and status and Your payment has not been received yet. Check again after paying on Przelewy24. with a Check again button. While the order is in Pending Payment, the page also shows Previous Przelewy24 payment links may still accept a payment. Use only one payment link. and a Pay again button, which starts a new Przelewy24 payment for the same order. A customer who cancels on the Przelewy24 page comes back to this page too: the order is not cancelled and stays in Pending Payment.

The status page works only in the browser session that placed the order. In another browser the customer lands on the home page with The payment status is available in the checkout that placed the order.; the payment is still confirmed by the notification. A return link that does not match the payment attempt shows The payment return link is invalid. in the cart.

If the first payment cannot be started, the order is cancelled (the stock goes back), the cart is restored and the customer sees a short message in the cart: The Przelewy24 payment could not be started. Please try again or choose another payment method. (the reason goes to the log), Przelewy24 is currently unavailable. (the module is disabled, the keys of the current mode are missing or the license is not active), Przelewy24 does not support this order currency or amount. or This cart already has a payment. Contact the store before paying again. If Pay again fails, the customer sees the message in the cart and the order stays in Pending Payment.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop such a cancellation, and a Przelewy24 payment page that is already open is not closed. See Order statuses for a payment that arrives after the cancellation.

The module works with the standard Magento checkout. It has no saved cards or one-click payments, no subscriptions or recurring payments, no reservation or delayed capture, no choice of the P24 payment method (for example a BLIK code field) on your checkout page, and does not send the order items to Przelewy24. Przelewy24 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 Przelewy24, but the payment is not confirmed yet. There is no invoice. A note is added for every registered payment, with the mode.

Processing: the payment was verified. The invoice is created with the P24 order ID as the transaction ID, and the note Przelewy24 verified and captured payment shows the ID. As usual in Magento, an order with nothing to ship becomes Complete.

On Hold: the amount or currency reported by Przelewy24 differs from the payment attempt or the order. The payment is not verified, no invoice is created and the note says Przelewy24 amount/currency mismatch. Payment was not verified; review required. Check the payment in the Przelewy24 panel. If a correct payment arrives later for this order, the hold is removed and the order is invoiced.

Canceled: the payment could not be started, or the order was cancelled in Magento or by the Pending Payment Order Lifetime. If a payment arrives later for such an order, it is verified, so the money is received, but the order is not reopened and not invoiced. The note says Money received; manual review/refund required. Refund it in the Przelewy24 panel if you do not fulfil the order.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for a cart that is already paid (an older payment link, two browser tabs), it is not verified, so Przelewy24 does not credit it. A note on the order asks you to review that payment manually. Repeated notifications never invoice an order twice. The notes are order comments that the customer does not see.

Przelewy24 payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Environment, P24 session, P24 transaction, Payment method (the numeric P24 method ID), Paid amount (minor units), Refund status, one P24 attempt row per payment attempt (session, mode, status, amount, P24 ID) and one P24 refund row per refund (refund ID, amount, status, P24 status). It is shown also when the module is disabled. On the storefront the customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The refund request is sent to Przelewy24. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Przelewy24.

The refund is made in the order currency, up to the amount paid minus the amounts already refunded through the module, and in the mode (sandbox or live) the payment was made in, so the keys of that mode must be set. Refunds are available once the payment is verified and the order has an invoice. An order on hold or a late payment on a cancelled order has no invoice, so refund it in the Przelewy24 panel.

Przelewy24 processes refunds asynchronously. When Przelewy24 accepts the request, Magento creates the credit memo with the Przelewy24 request as the transaction ID, and a full refund closes the order. The result arrives later at the notification URL: the note Przelewy24 refund completed, or Przelewy24 refund REJECTED with Money was not returned. Native credit memo remains; reconcile manually. A rejected refund does not cancel the credit memo and does not reopen the order, so check it in the Przelewy24 panel and return the money there.

Every refund request is recorded before it is sent. If Przelewy24 rejects the request, Magento shows Przelewy24 did not confirm the refund. Check the payment in its panel before trying again., the credit memo is not created and you can try again. If the answer of Przelewy24 is lost or unclear, the same message is shown and the refund is marked as unconfirmed. No second online refund is then sent for this payment, so a refund is never sent twice blindly: check it in the Przelewy24 panel and, if needed, finish the refund there and record it with Refund Offline. Refunds made in the Przelewy24 panel are not recorded in Magento. Create a credit memo with Refund Offline to record them.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Przelewy24 Payment is the first row of the VibeFox Przelewy24 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-przelewy24 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, Przelewy24 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 Przelewy24 is currently unavailable. 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, and refunds work.

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

Przelewy24 does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the Merchant ID, API key and CRC key of the current mode are entered (the Sandbox keys while Test mode is Yes, the Live keys otherwise; Merchant ID and POS ID numbers only). Check that the cart currency is PLN, EUR, GBP or CZK. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. Gateway notices shows a warning when keys are missing. Developers can change the list of currencies with the Magento event 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 store. Check that the Notification URL is reachable from the internet (no firewall or basic authentication in front of it) and that the Merchant ID, POS ID and CRC key of the mode of the payment are correct. Look at the Log field for failed verifications.

How the store answers notifications: a processed, repeated or unknown notification is answered with HTTP 200 (OK, Duplicate, Ignored, Already paid, Amount mismatch: order held, Paid: manual review). Otherwise Przelewy24 can send it again later: 400 (Invalid payload, Missing field with the field name, Invalid orderId, Refund mismatch), 401 Invalid signature (wrong CRC key, another Merchant ID or POS ID, or a notification signed with the keys of the other mode than the payment), 405 POST expected (not a POST request), 500 Verification failed (the verification with Przelewy24 failed; a note is added to the order once and the error goes to the log) and 503 Busy or Busy, retry (the order was being updated by another request at the same moment, or an error occurred).

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by a later notification or return that reaches the store.

The customer sees The Przelewy24 payment could not be started: Przelewy24 rejected the transaction or could not be reached, usually because of wrong keys of the current mode (sandbox keys work only in sandbox mode, live keys only in live mode). The error is in the log. The order of that attempt is cancelled.

The customer sees This cart already has a payment: a payment of this cart was already verified, also when its order was cancelled later. Check the payment in the Przelewy24 panel before the customer pays again.

The order is On Hold or a note asks for manual review: read the note on the order, check the payment in the Przelewy24 panel, then fulfil the order or refund the payment in the Przelewy24 panel.

A refund fails: No verified Przelewy24 payment found. means the order has no verified Przelewy24 payment. The credentials of the payment environment are not configured. means the keys of the mode of the payment are missing; enter them again and retry, nothing was sent. Refund exceeds the remaining payment or has an invalid currency/amount. means the amount is more than the amount not refunded yet or has more than two decimals. This payment is being updated. Try again shortly. means another request is working on the same order.

A refund says A previous refund is unconfirmed or An accepted Przelewy24 refund has no credit memo: an earlier request has an uncertain result, or Przelewy24 accepted a refund but Magento could not save its credit memo. No new online refund is sent for this payment. Check the refunds in the Przelewy24 panel, finish the refund there if needed and record it with Refund Offline.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice cannot be refunded online; refund it in the Przelewy24 panel.

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_Przelewy24Payment. It removes the data and the code.

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

The license key and license status are always removed. If Delete data on uninstall is Yes in the Default Config, the module settings of all scopes and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the Przelewy24 payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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