Przelewy24
Support payments via Przelewy24
A comprehensive Przelewy24 payment provider plugin for Medusa.js 2.0 — BLIK, cards, Visa Mobile, and general P24 redirect flows.
Features • Installation • Configuration • Usage • Payment Flows • Webhooks
Features
- ✅ Multiple Payment Methods — BLIK (regular and one-click), credit/debit cards, Visa Mobile, bank transfers, and general P24 redirect
- ✅ White-Label Integration — Card 2.0 iframe and BLIK charge flows without leaving your storefront
- ✅ Webhook Support — Real-time payment status updates with signature verification
- ✅ Modular Architecture — Multiple services in a single module provider for easy management
- ✅ TypeScript — Full TypeScript implementation with proper types
- ✅ Sandbox Mode — Built-in sandbox support for testing
Warning
This plugin has not been tested on a live store. Please conduct thorough testing before using it in a production environment. gmi.software is not responsible for any missed or failed payments resulting from the use of this plugin. If you encounter any issues, please report them on the GitHub issues tracker.
Prerequisites
- Medusa server v2.4.0 or later
- Node.js v20 or later
- A Przelewy24 merchant account with API credentials
Note
You can get your API credentials from your Przelewy24 merchant panel.
Installation
Configuration
Add the provider to the module in your file:
Configuration Options
| Option | Description | Required | Default |
|---|---|---|---|
| P24 Merchant ID | Yes | - | |
| P24 POS ID | Yes | - | |
| P24 API Key | Yes | - | |
| P24 CRC Key for signature verification | Yes | - | |
| Enable sandbox mode (/ or /) | No | ||
| P24 channel for card-only registration | No | ||
| P24 method id for Visa Mobile | No | ||
| Frontend URL for customer redirects | Yes | - | |
| Backend URL for webhook notifications | Yes | - | |
| Timeout for each P24 API request, in milliseconds | No | ||
| Minutes (1–99) a hosted redirect / Visa Mobile transaction stays payable (P24 ); BLIK and cards are not limited | No | unset (no limit) |
(sandbox, 2026-11-02): the countdown starts when the customer first opens the P24 payment page, not at registration, and reopening the link does not reset it. Once it runs out the link shows "Przekroczony czas na dokonanie transakcji" and cannot be paid. still answers "Transaction not found" for it; there is no expired status. The traditional bank transfer stays on offer; whether P24 accepts one booked after the limit is unconfirmed, so check with P24 before enabling it in production.
Environment Variables
Create or update your file with the following variables:
Usage
Once installed and configured, the Przelewy24 payment methods will be available in your Medusa admin. To enable them, log in to your Medusa Admin, browse to Settings > Regions, add or edit a region and select the desired P24 providers from the dropdown.
Make sure that the selected payment methods are enabled in your Przelewy24 merchant panel as well.
Client-Side Integration
To integrate with your storefront, implement the payment flow according to Przelewy24's and Medusa's documentation. Here are basic examples:
BLIK Payment
BLIK payments use a two-phase flow:
Phase 1: Create Payment Session
Phase 2: Process BLIK Code
Card Payment 2.0 (white-label iframe)
Per P24 Card Payment 2.0 docs:
Visa Mobile (redirect with pre-selected method)
Transaction status (poll timeout fallback)
General P24 Payment
Supported Payment Methods
| Payment Method | Provider ID | Notes |
|---|---|---|
| BLIK | White-label, channel 64 | |
| Cards | White-label iframe, channel 4096 | |
| Visa Mobile | Redirect with method | |
| General P24 | Redirect to P24 method picker |
Payment Flows
1. BLIK (white-label)
- Create payment session () → ,
- Customer enters 6-digit BLIK code
- → P24
- Customer approves in banking app
- Storefront polls until order is created
- P24 sends webhook to → capture, which verifies with P24 →
BLIK does not use redirect URLs.
is only called for paid transactions. When the customer rejects the payment in the banking app (or the bank declines it), P24 sends the additional BLIK notification to ; the plugin then marks the payment session , so fails and returns instead of a pending payment. A BLIK token is single-use: rejects sessions that were already charged or are no longer / — create a new payment session to retry. When P24 does not answer the charge (timeout, connection error or 5xx) the route returns and leaves the session , since P24 may have accepted it; poll the transaction status instead of charging again. applies the same lock and refuses a session that was already registered or paid. Charges and rejection notifications for one session are serialised through the Medusa Locking Module; with several Medusa instances, configure a shared locking provider such as .
2. Cards (P24 Card 2.0 white-label)
- Create payment session → tokenization fields only (, , , ) — no yet
- Load , render iframe; regulation checkbox is inside the P24 widget
- On Pay: → via postMessage
- with → + returns
- Browser runs (3DS in merchant UI)
- Storefront polls until order is created
- P24 webhook → capture, which verifies with P24
See P24 Card 2.0 docs.
3. Visa Mobile (redirect with pre-selected method)
- Create payment session → (P24 includes )
- Customer pays on P24 hosted Visa Mobile page
- Return to /
- Webhook confirms payment
4. General P24 (redirect)
- Create payment session →
- Customer pays on P24 hosted page
- Return to /
- Webhook confirms payment
Completion model (all white-label methods)
| Step | Mechanism |
|---|---|
| Order creation | Storefront polls ; Medusa queries P24 API; or (Medusa, every 2 min) when payment is already captured |
| Capture + | P24 webhook to , or job (every 5 min) |
rejects a transaction with when the amount P24 reports for it differs from the registered . skips such sessions.
runs one sweep at a time across workers when they share a locking provider (Redis or Postgres): with the default in-memory provider each process holds its own lock and runs its own sweep, so with several instances configure a shared one. It holds the lock for 15 minutes and renews it every minute, and a run stops taking sessions after 10 minutes. Its cursor is kept in the caching module (or the cache module); without either, it lives in process memory and a restart starts the sweep over. With , a worker killed mid-run leaves the lock row behind, and the provider never takes over an expired row from another owner. Once you are sure that no run is active, delete it: . Do not call : it truncates the whole table. Redis expires the lock on its own.
Do not add a separate store “confirm” route to replace webhooks. Production capture is webhook-driven.
Webhook Configuration
Webhook URLs (auto-registered)
On each , the plugin sets:
urlStatus: {backend_url}/hooks/payment/{service-identifier}_{payment-module-id}With config (recommended):
| Method | Webhook URL |
|---|---|
| Cards | |
| BLIK | |
| Visa Mobile | |
| General |
Medusa route: → → .
The webhook does not verify the transaction with P24. Verifying settles the money with the merchant, so it happens only in , which reaches once Medusa can record the payment. A notification for a payment session that was replaced or re-registered in the meantime therefore stays unverified, and P24 does not settle it.
A notification whose paid differs from the registered returns (logged with both amounts), so it is never captured. The customer keeps the money, because P24 does not settle unverified transactions.
BLIK transactions additionally register:
urlCardPaymentNotification: {backend_url}/hooks/p24/blik-notificationThe route accepts only P24 webhook IPs (plus localhost in sandbox) and a valid , and acts only on rejections for the session's current P24 registration while it is still pending and P24 does not report it as paid. Successful payments keep going through .
- must be the Medusa server URL (public HTTPS in production), not the storefront.
- Webhooks are registered per transaction; you do not paste these into the P24 panel for white-label flows.
- Return URL for redirects: (and cart-specific in session data).
Production checklist
- reachable from the internet (P24 cannot call )
- matches merchant panel (signature verification)
- P24 webhook source IPs allowed (see ; sandbox allows localhost)
- Region enables correct providers
Local development
Without a tunnel, webhooks will not arrive. Orders may still be created via poll , but can remain until the reconcile job runs (~5 min). Use ngrok + public for full webhook testing.
Extending the Plugin
To add support for additional Przelewy24 payment methods, create a new service in that extends the class:
Make sure to replace with the actual Przelewy24 payment method ID.
Export your new service from . Then add your new service to the list of services in .
Local Development
To customize and test the plugin locally, refer to the Medusa Plugin docs.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
MIT © gmi.software
Made with ❤️ by gmi.software

