Przelewy24 payments medusa

Name: Przelewy24 payments medusa
Author: Sawka-tech

Плагин платёжной интеграции Przelewy24 (P24) для Medusa с поддержкой BLIK, карт и общего протокола P24. Форк @gmisoftware/przelewy24-payments-medusa с исправлениями расчётов по платежам, канала BLIK и provider-id. Подробнее в FORK.md.

npm install @sawka-tech/przelewy24-payments-medusa

Категория

Создано

Регионы

Сервис

Версия

0.1.3-sawka.7

Последнее обновление

1 месяц назад

Ежемесячные загрузки

NPM Github

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

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

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

Примечание

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

Installation

yarn add @gmisoftware/przelewy24-payments-medusa

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 (/ 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	-

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 (use the same names as medusa-config.ts)
8MEDUSA_STORE_URL=https://your-frontend-domain.com
9MEDUSA_BACKEND_URL=https://your-backend-domain.com   # public HTTPS — P24 webhooks hit this host
10P24_IS_SANDBOX=false

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

1// Create payment session for BLIK
2const paymentSession = await medusa.payment.createPaymentSession({
3  provider_id: "pp_p24-blik_przelewy24",
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// Store API (publishable key + cart context)
2const blikResponse = await fetch("/store/payments/blik/charge", {
method: "POST",
headers: {
  "Content-Type": "application/json",
  "x-publishable-api-key": publishableKey,
},
body: JSON.stringify({
  token: paymentSession.data.token,
  blikCode: "123456",
  payment_session_id: paymentSession.id,
}),
13});

Legacy route remains as a deprecated wrapper.

Card Payment 2.0 (white-label iframe)

Per P24 Card Payment 2.0 docs:

1// 1) Create payment session — returns tokenization fields (no transaction register yet)
2const { payment_session } = await medusa.store.cart.createPaymentSession(cartId, {
3  provider_id: "pp_p24-cards_przelewy24",
4});
5
6const { merchant_id, session_id, card_tokenization_sign } =
7  payment_session.data;
8
9// 2) Load P24 Card 2.0 SDK and render iframe
10// https://{sandbox|secure}.przelewy24.pl/js/cardTokenizationIframe.min.js
11// new Przelewy24CardTokenization(merchant_id, session_id, card_tokenization_sign)
12//   .render("form", "#container", { lang: "pl", ... })
13// On Pay: .tokenize("temporary") → listen for postMessage success with data.refId
14
15// 3) Register with refId, then run P24 whitelabel charge script in the browser
16const cardResponse = await fetch("/store/payments/card/charge", {
17  method: "POST",
18  headers: {
19    "Content-Type": "application/json",
20    "x-publishable-api-key": publishableKey,
21  },
22  body: JSON.stringify({
23    ref_id: refIdFromTokenization,
24    payment_session_id: payment_session.id,
25  }),
26});
27
28const { token, chargeScriptUrl } = await cardResponse.json();
29// 4) Load chargeScriptUrl and run Przelewy24CardWhileLabelHandler (3DS in merchant modal)
30// 5) Poll POST /store/carts/{cartId}/complete until type === "order"
31// 6) Capture happens via P24 webhook to urlStatus (not via a separate confirm API)

Visa Mobile (redirect with pre-selected method)

1// 1) Create payment session — returns redirect_url with method 198 pre-selected
2const { payment_session } = await medusa.store.cart.createPaymentSession(cartId, {
3  provider_id: "pp_p24-visa-mobile_przelewy24",
4});
5
6// 2) Redirect customer to P24 Visa Mobile flow
7window.location.href = payment_session.data.redirect_url;
8
9// 3) Customer completes payment on P24 hosted page
10// 4) Return to frontend_url / return_url
11// 5) Capture happens via P24 webhook to urlStatus (not via a separate confirm API)

Transaction status (poll timeout fallback)

1await fetch("/store/payments/transaction/status", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  session_id: payment_session.data.session_id,
  provider_id: payment_session.provider_id,
}),
8});

General P24 Payment

1// Create payment session for general P24
2const paymentSession = await medusa.payment.createPaymentSession({
3  provider_id: "pp_p24-provider_przelewy24",
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

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 → verify + capture →

BLIK does not use redirect URLs.

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 → verify + capture

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)

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: → → .

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.

yarn build && yalc publish --push

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;