Multiple Payment Methods: Supports a wide range of Przelewy24 payment methods including:
- BLIK (Regular and One-Click)
- Credit/Debit Cards
- Bank Transfers
- White Label Integration
Modular Architecture: Multiple services in a single module provider for easy management.
Webhook Support: Full support for Przelewy24 webhooks for real-time payment status updates.
TypeScript Support: Full TypeScript implementation with proper types.
Sandbox Mode: Built-in sandbox support for testing.

Предупреждение

> 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 here.

Prerequisites

Medusa server v2.4.0 or later
Node.js v20 or later
A Przelewy24 merchant account with API credentials.

Примечание

> You can get your API credentials from your Przelewy24 merchant panel

Installation

yarn add p24-medusa-plugin

Configuration

Add the provider to the module in your file:

1import { Modules } from "@medusajs/framework/utils";
2
3module.exports = defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve:
            "@gmisoftware/przelewy24-payments-medusa/providers/przelewy24",
          id: "przelewy24",
          options: {
            api_key: process.env.P24_API_KEY,
            merchant_id: process.env.P24_MERCHANT_ID,
            pos_id: process.env.P24_POS_ID,
            crc: process.env.P24_CRC,
            sandbox: process.env.P24_IS_SANDBOX,
            frontend_url: process.env.MEDUSA_STORE_URL,
            backend_url: process.env.MEDUSA_BACKEND_URL,
          },
        },
      ],
    },
  },
],
plugins: ["@gmisoftware/przelewy24-payments-medusa"],
28});

Configuration Options

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	No
Frontend URL for customer redirects	No
Backend URL for webhook notifications	No

Environment Variables

Create or update your file with the following variables:

1# P24 Configuration
2P24_MERCHANT_ID=your_merchant_id
3P24_POS_ID=your_pos_id
4P24_API_KEY=your_api_key
5P24_CRC=your_crc_key
6
7# URL Configuration
8FRONTEND_URL=https://your-frontend-domain.com
9BACKEND_URL=https://your-backend-domain.com

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, you'll need to implement the payment flow according to Przelewy24's and Medusa's documentation. Here's a basic example:

BLIK Payment

BLIK payments use a two-phase flow:

Phase 1: Create Payment Session

1// Create payment session for BLIK
2const paymentSession = await medusa.payment.createPaymentSession({
3  provider_id: "p24-blik",
4  amount: 10000, // 100.00 PLN in grosze
5  currency_code: "PLN",
6  data: {
7    country: "PL", // Country code (defaults to "PL" if not provided)
8    language: "pl", // Language code (defaults to "pl" if not provided)
9  },
10  context: {
11    email: "customer@example.com",
12  },
13});
14
15// Response includes session_id and token, but no redirect_url
16console.log(paymentSession.data.session_id); // Use this for BLIK processing

Phase 2: Process BLIK Code

1// Call internal API to process BLIK code
2const blikResponse = await fetch("/admin/plugin/blik", {
method: "POST",
headers: {
  "Content-Type": "application/json",
},
body: JSON.stringify({
  token: paymentSession.data.token, // Token from payment session
  blikCode: "123456", // 6-digit BLIK code from user
}),
11});

Card Payment

1// Create payment session for cards
2const paymentSession = await medusa.payment.createPaymentSession({
3  provider_id: "p24-cards",
4  amount: 10000, // 100.00 PLN in grosze
5  currency_code: "PLN",
6  data: {
7    country: "PL", // Country code (defaults to "PL" if not provided)
8    language: "pl", // Language code (defaults to "pl" if not provided)
9  },
10  context: {
11    email: "customer@example.com",
12    billing_address: {
13      country_code: "PL",
14    },
15  },
16});
17
18// Redirect user to payment URL
19window.location.href = paymentSession.data.redirect_url;

General P24 Payment

1// Create payment session for general P24
2const paymentSession = await medusa.payment.createPaymentSession({
3  provider_id: "p24-general",
4  amount: 10000,
5  currency_code: "PLN",
6  data: {
7    country: "PL", // Country code (defaults to "PL" if not provided)
8    language: "pl", // Language code (defaults to "pl" if not provided)
9  },
10  context: {
11    email: "customer@example.com",
12  },
13});
14
15// Redirect user to P24 payment selection
16window.location.href = paymentSession.data.redirect_url;

Supported Payment Methods

The plugin currently supports the following Przelewy24 payment methods:

Payment Method	Provider ID
BLIK
Cards
General P24

Payment Flows

1. BLIK Payment Flow

Phase 1: Frontend creates payment session via
Phase 2: Frontend collects BLIK code (6 digits) from customer
Phase 3: Frontend calls internal API with BLIK code
Phase 4: Backend calls P24 BLIK API to charge the payment
Phase 5: Customer confirms payment on mobile device
Phase 6: P24 sends webhook notification confirming payment
Phase 7: Order is completed

Note: BLIK payments don't use redirect URLs. The entire flow happens through API calls.

2. Card Payment Flow

Customer is redirected to P24 card payment page
Customer enters card details
Payment is processed
Customer is redirected back to store
Webhook notification confirms payment

3. General P24 Flow

Customer is redirected to P24 payment selection
Customer chooses payment method (bank transfer, etc.)
Payment is processed through chosen method
Customer is redirected back to store
Webhook notification confirms payment

Webhook Configuration

Webhook URLs

The plugin provides webhook endpoints for each provider:

BLIK:
Cards:
General:

Return URL

Return URL:

Configure these URLs in your P24 merchant panel.

Note: The webhook URLs follow Medusa's pattern: where:

is the service's static identifier (e.g., , , )
is the package name ()

Extending the Plugin

To add support for additional Przelewy24 payment methods, create a new service in that extends the class:

1import P24Base from "../core/p24-base";
2import { PaymentOptions } from "../types";
3
4class P24NewMethodService extends P24Base {
5  static identifier = "p24-new-method";
6
7  get paymentCreateOptions(): PaymentOptions {
8    return {
9      method: "new_method",
10    };
11  }
12}
13
14export default P24NewMethodService;