Przelewy24

Przelewy24 Payments for Medusa

A comprehensive payment provider plugin that enables Przelewy24 payments on Medusa V2 projects.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
  • Configuration Options
  • Environment Variables
• Usage
• Client-Side Integration
• Supported Payment Methods
• Payment Flows
• Webhook Configuration
• Extending the Plugin
• Local Development and Customization
• License

Features

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

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

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

1
yarn add p24-medusa-plugin

Configuration

Add the provider to the Copy to clipboard@medusajs/payment module in your Copy to clipboardmedusa-config.ts file:

1234567891011121314151617181920
import { Modules } from "@medusajs/framework/utils";

module.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,

Configuration Options

Option Description Required Default Copy to clipboardmerchant_id P24 Merchant ID Yes - Copy to clipboardpos_id P24 POS ID Yes - Copy to clipboardapi_key P24 API Key Yes - Copy to clipboardcrc P24 CRC Key for signature verification Yes - Copy to clipboardsandbox Enable sandbox mode No Copy to clipboardfalse Copy to clipboardfrontend_url Frontend URL for customer redirects No Copy to clipboardhttp://localhost:3000 Copy to clipboardbackend_url Backend URL for webhook notifications No Copy to clipboardhttp://localhost:9000

Environment Variables

Create or update your Copy to clipboard.env file with the following variables:

123456789
# P24 Configuration
P24_MERCHANT_ID=your_merchant_id
P24_POS_ID=your_pos_id
P24_API_KEY=your_api_key
P24_CRC=your_crc_key

# URL Configuration
FRONTEND_URL=https://your-frontend-domain.com
BACKEND_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

12345678910111213141516
// Create payment session for BLIK
const paymentSession = await medusa.payment.createPaymentSession({
  provider_id: "p24-blik",
  amount: 10000, // 100.00 PLN in grosze
  currency_code: "PLN",
  data: {
    country: "PL", // Country code (defaults to "PL" if not provided)
    language: "pl", // Language code (defaults to "pl" if not provided)
  },
  context: {
    email: "customer@example.com",
  },
});

// Response includes session_id and token, but no redirect_url
console.log(paymentSession.data.session_id); // Use this for BLIK processing

Phase 2: Process BLIK Code

1234567891011
// Call internal API to process BLIK code
const 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
  }),
});

Card Payment

12345678910111213141516171819
// Create payment session for cards
const paymentSession = await medusa.payment.createPaymentSession({
  provider_id: "p24-cards",
  amount: 10000, // 100.00 PLN in grosze
  currency_code: "PLN",
  data: {
    country: "PL", // Country code (defaults to "PL" if not provided)
    language: "pl", // Language code (defaults to "pl" if not provided)
  },
  context: {
    email: "customer@example.com",
    billing_address: {
      country_code: "PL",
    },
  },
});

// Redirect user to payment URL
window.location.href = paymentSession.data.redirect_url;

General P24 Payment

12345678910111213141516
// Create payment session for general P24
const paymentSession = await medusa.payment.createPaymentSession({
  provider_id: "p24-general",
  amount: 10000,
  currency_code: "PLN",
  data: {
    country: "PL", // Country code (defaults to "PL" if not provided)
    language: "pl", // Language code (defaults to "pl" if not provided)
  },
  context: {
    email: "customer@example.com",
  },
});

// Redirect user to P24 payment selection
window.location.href = paymentSession.data.redirect_url;

Supported Payment Methods

The plugin currently supports the following Przelewy24 payment methods:

Payment Method Provider ID BLIK Copy to clipboardpp_p24-blik_p24-blik Cards Copy to clipboardpp_p24-cards_p24-cards General P24 Copy to clipboardpp_p24-provider_p24-general

Payment Flows

1. BLIK Payment Flow

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

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

2. Card Payment Flow

1. Customer is redirected to P24 card payment page
2. Customer enters card details
3. Payment is processed
4. Customer is redirected back to store
5. Webhook notification confirms payment

3. General P24 Flow

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

Webhook Configuration

Webhook URLs

The plugin provides webhook endpoints for each provider:

• BLIK: Copy to clipboard{backend_url}/hooks/payment/p24-blik_p24-medusa-plugin
• Cards: Copy to clipboard{backend_url}/hooks/payment/p24-cards_p24-medusa-plugin
• General: Copy to clipboard{backend_url}/hooks/payment/p24-provider_p24-medusa-plugin

Return URL

• Return URL: Copy to clipboard{frontend_url}

Configure these URLs in your P24 merchant panel.

Note: The webhook URLs follow Medusa's pattern: Copy to clipboard{identifier}_{provider} where:

• Copy to clipboardidentifier is the service's static identifier (e.g., Copy to clipboardp24-blik, Copy to clipboardp24-cards, Copy to clipboardp24-provider)
• Copy to clipboardprovider is the package name (Copy to clipboardp24-medusa-plugin)

Extending the Plugin

To add support for additional Przelewy24 payment methods, create a new service in Copy to clipboardsrc/providers/przelewy24/services that extends the Copy to clipboardP24Base class:

1234567891011121314
import P24Base from "../core/p24-base";
import { PaymentOptions } from "../types";

class P24NewMethodService extends P24Base {
  static identifier = "p24-new-method";

  get paymentCreateOptions(): PaymentOptions {
    return {
      method: "new_method",
    };
  }
}

export default P24NewMethodService;

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

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

Local development and customization

In case you want to customize and test the plugin locally, refer to the Medusa Plugin docs.

License

MIT License

Contributing

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