Download the PHP package kuzry/laravel-przelewy24 without Composer

Laravel Przelewy24

A Laravel package for seamless integration with Przelewy24 payment gateway. Przelewy24 is one of the leading online payment providers in Poland, offering a wide range of payment methods including credit cards, bank transfers, BLIK, and more.

This package allows you to quickly implement secure online payments in your Laravel application using the official Przelewy24 API.

Features

• 🚀 Easy Integration - Quick setup with minimal configuration
• ⚛️ React Hooks - Ready-to-use hooks for frontend payment handling
• 🏪 Multiple POS Support - Handle multiple Point of Sales configurations
• 🔄 Automatic Data Sharing - Seamless integration with Inertia.js
• 🔒 Secure - Built-in signature verification and transaction validation
• 📝 TypeScript Support - Full type definitions for frontend integration

Requirements

• PHP: 8.3 or higher
• Laravel: 11.x or higher

Installation

1. Install the package

2. Publish a configuration file

Default values from the configuration file can be overridden directly when calling the package's methods.

3. Configure environment variables

Add the following variables to your .env file. You can obtain these credentials from your Przelewy24 merchant panel:

Note: Always use a sandbox environment for development and testing. Switch to production only when you're ready to accept real payments.

4. Frontend Framework Setup

4.1 React

Update your vite.config.js:

Update your tsconfig.json:

Quick start

Payment Flow Overview

The integration follows a standard payment flow:

1. Register Transaction - Create a payment session with Przelewy24
2. Redirect Customer - Send the customer to Przelewy24 payment gateway
3. Receive Notification - Handle the webhook callback after payment from Przelewy24
4. Verify Transaction - Confirm the payment with Przelewy24 API

Transaction Registration

The transactionRegister method initiates a new payment transaction with Przelewy24. It creates a payment session and returns the data needed to redirect the customer to the payment gateway.

Important security note: Never trust data directly from the request for critical fields like amount, currency or sessionId. Always retrieve these values from your database or calculate them server-side to prevent payment manipulation.

Register the route in your routes/web.php:

Note: The route name must match the url_transaction_register option in your config/przelewy24.php file. This allows the package to generate proper callback URLs.

Payment Status Webhook

After the customer completes the payment, Przelewy24 will send a notification to your webhook endpoint. This is where you verify and confirm the transaction.

Register the webhook route in your routes/api.php:

Note: The route name must match the url_status option in your config/przelewy24.php file. This allows the package to generate proper callback URLs.

Frontend Integration

Automatic Data Sharing

If you're using Inertia.js, the package can automatically share Przelewy24 configuration data with all your frontend components. The przelewy24 prop will be available globally in every Inertia page without any additional setup.

To enable this feature, set the following option in your config/przelewy24.php:

This is handled automatically by the package's Service Provider. No additional setup required!

Manual Data Sharing

If auto_register_frontend_data is disabled, you need to manually pass the data in your controllers:

React Integration

The package provides a ready-to-use React hook (usePrzelewy24) for handling payment initialization and redirection directly from your frontend. This hook simplifies the integration process, allowing you to start a transaction in just a few lines of code.

Hook API

The usePrzelewy24() hook returns an object with the following structure:

Basic Usage

Here's a simple example of implementing a payment button in your shopping cart:

By default, the hook automatically redirects the user to the Przelewy24 payment gateway on success.

Advanced Usage with Custom Callbacks

You can customize the behavior by providing onSuccess and onError callbacks:

Security

Best Practices

• Always validate amounts and currencies server-side
• Use HTTPS in production
• Implement proper error handling
• Log all payment transactions
• Never expose your CRC or Report Key

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Krzysztof Kuzara

License

The MIT License (MIT). Please see License File for more information.