Przelewy24 PHP library

PHP wrapper for Przelewy24.

If you are using Laravel, check out mnastalski/przelewy24-laravel.

Przelewy24's API documentation is available at https://developers.przelewy24.pl/.

Requirements

PHP >=8.1

For lower PHP versions, check the 0.x versions.

Installation

composer require mnastalski/przelewy24-php

Usage

Creating an instance

use Przelewy24\Przelewy24;

$przelewy24 = new Przelewy24(
    merchantId: 12345,
    reportsKey: 'f0ae...',
    crc: 'aef0...',
    isLive: false,
);

Setting isLive to false will use the sandbox environment. Set it to true to use production/live mode.

Testing the connection

You may use the following method to test if the connection to Przelewy24's API using provided credentials is working:

$test = $przelewy24->tests()->testAccess();

var_dump($test->data());

bool(true)

Creating a transaction

$transaction = $przelewy24->transactions()->register(
    // Required parameters:
    sessionId: 'unique order identifier from your application',
    amount: 125,
    description: 'transaction description',
    email: 'buyer email address',
    urlReturn: 'url to return to after transaction',

    // Optional parameters:
    urlStatus: 'url to which the transaction status webhook will be sent',

    // client: 'Mateusz Nastalski',
    // currency: \Przelewy24\Enums\Currency::EUR,
    // language: Language::ENGLISH,
    // ...
);

Note that amount is passed as an integer, so if the actual amount is 1.25 PLN you will need to pass 125 as value.

For the complete list of available parameters check the signature of TransactionRequests::register().

Return the transaction's token:

$transaction->token();

Return the URL to the payment gateway:

$transaction->gatewayUrl();

Listening for transaction registration status webhook

To parse the webhook's payload, pass the whole request's POST data as an array to handleWebhook():

// $requestData = $request->request->all();
// $requestData = $request->post();
// $requestData = json_decode(file_get_contents('php://input'), true);

$webhook = $przelewy24->handleWebhook($requestData);

handleWebhook() returns TransactionStatusNotification::class, which has a bunch of useful methods you can use to check the transaction's data, as well as verify the webhook's signature:

$webhook->amount();
$webhook->currency();
$webhook->orderId();
...
$webhook->isSignValid(...);

If you would like to make sure the incoming request's IP address belongs to Przelewy24 then a list of valid IPs is available in the \Przelewy24\Constants\IpAddresses::V4 constant. A helper method that accepts a string with an IP address and returns a boolean is also available: \Przelewy24\Constants\IpAddresses::isValid($ip).

Verifying a transaction

$przelewy24->transactions()->verify(
    sessionId: 'unique order identifier from your application',
    orderId: $webhook->orderId(),
    amount: 125,
);

Similarly to registering a transaction, the amount is passed as an integer.

Refunding transactions

$refund = $przelewy24->transactions()->refund(
    requestId: 'unique request identifier from your application',
    refundsId: 'unique refunds identifier from your application',
    refunds: [
        new RefundItem(
            orderId: $webhook->orderId(),
            sessionId: 'unique order identifier from your application',
            amount: 2100,
            description: 'item #1',
        ),
        new RefundItem(
            orderId: $webhook->orderId(),
            sessionId: 'unique order identifier from your application',
            amount: 125,
            description: 'item #2',
        ),
    ],
    urlStatus: 'url to which the refund status webhook will be sent',
);

Return the refunds' item list:

$refund->refunds();

Listening for transaction refund status webhook

To parse the webhook's payload, pass the whole request's POST data as an array to handleRefundWebhook():

// $requestData = $request->request->all();
// $requestData = $request->post();
// $requestData = json_decode(file_get_contents('php://input'), true);

$webhook = $przelewy24->handleRefundWebhook($requestData);

Error handling

Should Przelewy24's API return an erroneous response, an ApiResponseException::class (which extends Przelewy24Exception::class) will be thrown. You can therefore use a try/catch block to handle any errors:

use Przelewy24\Exceptions\Przelewy24Exception;

try {
    $przelewy24->transactions()->verify([
        // ...
    ]);
} catch (Przelewy24Exception $e) {
    // Handle the error...
}