README

Przelewy24 payment gateway integration for Maho Commerce.

Accept payments through Przelewy24, one of Poland's most popular payment gateways.

Note: This module currently supports the gateway redirect flow only — the customer is redirected to Przelewy24's hosted payment page to choose their payment method. Direct card payments, BLIK, Google Pay, and Apple Pay are planned for future releases.

Features

• Gateway redirect — Customer selects their preferred payment method on Przelewy24's hosted payment page
• Full order lifecycle — Capture and refund (partial and full) from the Maho admin
• Webhook support — Real-time payment and refund notifications with SHA384 signature verification
• Cron safety net — Automatic polling of pending payments every 5 minutes in case webhooks fail
• Sandbox mode — Test integration with Przelewy24's sandbox environment
• Country restrictions — Allow payments from all or specific countries

Requirements

• PHP >= 8.3
• Maho Commerce >= 26.5.0
• A Przelewy24 merchant account

Installation

composer require mahocommerce/module-przelewy24

Clear the cache after installation:

php maho cache:flush

Configuration

Navigate to System > Configuration > Payment Methods in the Maho admin panel.

General Settings (Przelewy24 - General Settings)

Payment Method (Przelewy24 - Gateway Payment)

How It Works

1. Order placement — Customer selects Przelewy24 at checkout, order is created in pending_payment state
2. Registration — A transaction is registered with Przelewy24's API, returning a payment token
3. Redirect — Customer is redirected to Przelewy24's hosted payment page to complete payment
4. Webhook — Przelewy24 sends a signed notification to your store confirming payment
5. Verification — The module verifies the transaction with Przelewy24's API and captures the payment
6. Invoice — An invoice is automatically created and the order moves to processing

If the webhook fails to arrive, a cron job polls Przelewy24 every 5 minutes for pending orders (up to 24 hours old).

Webhooks

Configure the following webhook URL in your Przelewy24 merchant panel:

https://your-store.com/przelewy24/webhook/transaction

For refund notifications:

https://your-store.com/przelewy24/webhook/refund

Supported Currencies

All currencies supported by your Przelewy24 merchant account. Amounts are converted to grosze (1/100) for API communication.

Roadmap

• BLIK (inline 6-digit code entry at checkout)
• Direct card payments (Przelewy24 iframe)
• Google Pay
• Apple Pay

License

This module is licensed under the Open Software License v3.0.

Links

• Maho Commerce
• Przelewy24
• Przelewy24 API Documentation