Integration Module 2.0 for Medusa is outRead the announcement
Przelewy24 logo

Przelewy24

Support payments via Przelewy24

npm install @gmisoftware/przelewy24-payments-medusa
Category
Built by
Regions
Service
Version
0.1.9
Last updated
2 weeks ago
Monthly downloads
Loading downloads
Przelewy24 Medusa

A comprehensive Przelewy24 payment provider plugin for Medusa.js 2.0 — BLIK, cards, Visa Mobile, and general P24 redirect flows.

npm version License: MIT TypeScript Medusa v2

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

OptionDescriptionRequiredDefault
P24 Merchant IDYes-
P24 POS IDYes-
P24 API KeyYes-
P24 CRC Key for signature verificationYes-
Enable sandbox mode (/ or /)No
P24 channel for card-only registrationNo
P24 method id for Visa MobileNo
Frontend URL for customer redirectsYes-
Backend URL for webhook notificationsYes-
Timeout for each P24 API request, in millisecondsNo
Minutes (1–99) a hosted redirect / Visa Mobile transaction stays payable (P24 ); BLIK and cards are not limitedNounset (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 MethodProvider IDNotes
BLIKWhite-label, channel 64
CardsWhite-label iframe, channel 4096
Visa MobileRedirect with method
General P24Redirect to P24 method picker

Payment Flows

1. BLIK (white-label)

  1. Create payment session () → ,
  2. Customer enters 6-digit BLIK code
  3. → P24
  4. Customer approves in banking app
  5. Storefront polls until order is created
  6. 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)

  1. Create payment session → tokenization fields only (, , , ) — no yet
  2. Load , render iframe; regulation checkbox is inside the P24 widget
  3. On Pay: → via postMessage
  4. with → + returns
  5. Browser runs (3DS in merchant UI)
  6. Storefront polls until order is created
  7. P24 webhook → capture, which verifies with P24

See P24 Card 2.0 docs.

3. Visa Mobile (redirect with pre-selected method)

  1. Create payment session → (P24 includes )
  2. Customer pays on P24 hosted Visa Mobile page
  3. Return to /
  4. Webhook confirms payment

4. General P24 (redirect)

  1. Create payment session →
  2. Customer pays on P24 hosted page
  3. Return to /
  4. Webhook confirms payment

Completion model (all white-label methods)

StepMechanism
Order creationStorefront 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):

MethodWebhook 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-notification

The 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

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

License

MIT © gmi.software


Made with ❤️ by gmi.software