Przelewy24

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 @medusajs/payment module in your medusa-config.ts file:

Configuration Options

Environment Variables

Create or update your .env 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

Legacy route POST /payments/blik remains as a deprecated wrapper.

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 Flows

1. BLIK (white-label)

1. Create payment session (initiatePayment) → token, session_id
2. Customer enters 6-digit BLIK code
3. POST /store/payments/blik/charge → P24 chargeByCode
4. Customer approves in banking app
5. Storefront polls POST /store/carts/{id}/complete until order is created
6. P24 sends webhook to urlStatus → verify + capture → payment_collection.completed_at

BLIK does not use redirect URLs.

urlStatus 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 {backend_url}/hooks/p24/blik-notification; the plugin then marks the payment session error, so complete fails and POST /store/payments/transaction/status returns status: "error" instead of a pending payment. A BLIK token is single-use: POST /store/payments/blik/charge rejects sessions that were already charged or are no longer pending/requires_more — create a new payment session to retry. 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 @medusajs/medusa/locking-redis.

2. Cards (P24 Card 2.0 white-label)

1. Create payment session → tokenization fields only (merchant_id, session_id, card_tokenization_sign, amount_grosze) — no transaction/register yet
2. Load cardTokenizationIframe.min.js, render iframe; regulation checkbox is inside the P24 widget
3. On Pay: tokenize("temporary") → refId via postMessage
4. POST /store/payments/card/charge with ref_id → transaction/register + returns chargeScriptUrl
5. Browser runs Przelewy24CardWhileLabelHandler (3DS in merchant UI)
6. Storefront polls POST /store/carts/{id}/complete until order is created
7. P24 webhook → verify + capture

See P24 Card 2.0 docs.

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

1. Create payment session → redirect_url (P24 transaction/register includes method: 198)
2. Customer pays on P24 hosted Visa Mobile page
3. Return to frontend_url / return_url
4. Webhook confirms payment

4. General P24 (redirect)

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

Completion model (all white-label methods)

authorizePayment rejects a transaction with amount_mismatch when the amount P24 reports for it differs from the registered amount_grosze. reconcile-p24-payments skips such sessions.

Do not add a separate store “confirm” route to replace webhooks. Production capture is webhook-driven.

Webhook Configuration

Webhook URLs (auto-registered)

On each transaction/register, the plugin sets:

urlStatus: {backend_url}/hooks/payment/{service-identifier}_{payment-module-id}

With payment-module config id: "przelewy24" (recommended):

Medusa route: POST /hooks/payment/:provider → getWebhookActionAndData → processPaymentWorkflow.

A notification whose paid amount differs from the registered originAmount is not verified with P24 and returns FAILED (logged with both amounts). 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 sign, 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 urlStatus.

• backend_url 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: {frontend_url} (and cart-specific return_url in session data).

Production checklist

• backend_url reachable from the internet (P24 cannot call localhost)
• crc matches merchant panel (signature verification)
• P24 webhook source IPs allowed (see P24_WEBHOOK_ALLOWED_IPS; sandbox allows localhost)
• Region enables correct pp_p24-*_przelewy24 providers

Local development

Without a tunnel, webhooks will not arrive. Orders may still be created via poll complete, but payment_collection can remain not_paid until the reconcile job runs (~5 min). Use ngrok + public backend_url for full webhook testing.

Extending the Plugin

To add support for additional Przelewy24 payment methods, create a new service in src/providers/przelewy24/services that extends the P24Base class:

Make sure to replace new_method with the actual Przelewy24 payment method ID.

Export your new service from src/providers/przelewy24/services/index.ts. Then add your new service to the list of services in src/providers/przelewy24/index.ts.

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