PHPackages                             nimblephp/payments - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. nimblephp/payments

ActiveLibrary[Payment Processing](/categories/payments)

nimblephp/payments
==================

Payments for NimblePHP

0629PHP

Since Apr 13Pushed 3mo agoCompare

[ Source](https://github.com/NimbleMVC/Payments)[ Packagist](https://packagist.org/packages/nimblephp/payments)[ RSS](/packages/nimblephp-payments/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

nimblephp/payments
==================

[](#nimblephppayments)

Moduł płatności dla NimblePHP.

Aktualny zakres
---------------

[](#aktualny-zakres)

Na ten moment moduł wspiera:

- modułowy storage transakcji `module_payment_transaction`
- wspólny flow transakcji modułu z persystencją statusów i payloadów
- wybór systemu płatności przez `NimblePHP\Payments\Payments`
- system `przelewy24`
- provider adapter dla Przelewy24 nad niskopoziomowym gatewayem
- provider-specific DTO dla rejestracji i weryfikacji transakcji
- provider-specific response DTO dla odpowiedzi API
- obsługę callbacków / webhooków operatora
- mapowanie statusów operatora na wspólny status modułu
- budowanie URL checkoutu dla Przelewy24

To nie jest jeszcze w pełni generyczna warstwa dla wielu operatorów. Obecne DTO odzwierciedlają payloady Przelewy24 i są trzymane w:

`src/Provider/Przelewy24/DTO/`

Wymagania
---------

[](#wymagania)

- PHP `>=8.4`
- `ext-curl`
- `nimblephp/framework ^0.4.3`
- `nimblephp/migrations ^0.3.2`
- `brick/money ^0.12.2`

Instalacja
----------

[](#instalacja)

```
composer require nimblephp/payments
```

Po instalacji moduł powinien zostać uwzględniony w aktualizacji projektu, tak aby wykonały się jego migracje.

Migracje modułu
---------------

[](#migracje-modułu)

Moduł trzyma własne migracje w katalogu:

`migrations/`

Hook `NimblePHP\Payments\Module::onUpdate()` uruchamia je przez `nimblephp/migrations` z grupą:

`nimblephp-payments`

Obecne migracje:

- tworzą tabelę `module_payment_transaction`
- rozszerzają storage o `provider_status` i `webhook_payload`
- dodają indeksy po najważniejszych polach wyszukiwania
- używają aktualnych klas kolumn z `krzysztofzylka/database-manager/src/Columns`

Przy kolejnych zmianach schematu należy dodawać nowe pliki migracji, zamiast rozbudowywać `Module::onUpdate()` o ręczne `CreateTable` / `ALTER TABLE`.

Główne klasy
------------

[](#główne-klasy)

### Entry point

[](#entry-point)

- `NimblePHP\Payments\Payments`
- `NimblePHP\Payments\Module`

### Enum systemów

[](#enum-systemów)

- `NimblePHP\Payments\Enum\PaymentSystemEnum`
- `NimblePHP\Payments\Enum\PaymentTransactionStatusEnum`

### Wspólna transakcja modułu

[](#wspólna-transakcja-modułu)

- `NimblePHP\Payments\DTO\PaymentTransactionDTO`
- `NimblePHP\Payments\DTO\PaymentFlowResultDTO`
- `NimblePHP\Payments\DTO\ProviderTransactionUpdateDTO`
- `NimblePHP\Payments\Model\PaymentTransactionModel`
- `NimblePHP\Payments\Service\PaymentTransactionFlowService`
- `NimblePHP\Payments\Contracts\PaymentProviderAdapterInterface`

### Przelewy24

[](#przelewy24)

- `NimblePHP\Payments\Provider\Przelewy24\Przelewy24Adapter`
- `NimblePHP\Payments\Provider\Przelewy24\Przelewy24Gateway`
- `NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24ConfigDTO`
- `NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24RegisterTransactionDTO`
- `NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24RegisterTransactionResponseDTO`
- `NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24VerifyTransactionDTO`
- `NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24VerifyTransactionResponseDTO`

Konfiguracja Przelewy24
-----------------------

[](#konfiguracja-przelewy24)

Biblioteka czyta konfigurację z `NimblePHP\Framework\Config`.

Obsługiwane klucze:

- `PRZELEWY24_MERCHANT_ID`
- `PRZELEWY24_MECHANT_ID` - fallback dla starszej literówki
- `PRZELEWY24_POS_ID`
- `PRZELEWY24_API_KEY`
- `PRZELEWY24_CRC`
- `PRZELEWY24_API` - `production` albo `sandbox`

Przykład użycia
---------------

[](#przykład-użycia)

```
use NimblePHP\Payments\DTO\PaymentTransactionDTO;
use NimblePHP\Payments\Enum\PaymentSystemEnum;
use NimblePHP\Payments\Payments;
use NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24RegisterTransactionDTO;
use NimblePHP\Payments\Provider\Przelewy24\DTO\Przelewy24VerifyTransactionDTO;

$payments = new Payments('przelewy24');
$flow = $payments->flow();

$transaction = new PaymentTransactionDTO();
$transaction->provider = PaymentSystemEnum::przelewy24;
$transaction->amount = 12345;
$transaction->objectType = 'order';
$transaction->objectId = 123;

$register = new Przelewy24RegisterTransactionDTO();
$register->sessionId = 'session-123';
$register->amount = 12345;
$register->description = 'Order #123';
$register->email = 'john@example.com';
$register->urlReturn = 'https://example.com/order/123';
$register->urlStatus = 'https://example.com/payment/callback';

$registered = $flow->registerTransaction($transaction, $register);
$checkoutUrl = $registered->checkoutUrl;

$flow->handleWebhook([
    'data' => [
        'sessionId' => 'session-123',
        'orderId' => 10001,
        'status' => 2,
    ],
]);

$verify = new Przelewy24VerifyTransactionDTO();
$verify->sessionId = 'session-123';
$verify->orderId = 10001;
$verify->amount = 12345;
$verify->currency = 'PLN';

$flow->verifyTransaction($registered->transactionId, $verify);
```

Architektura
------------

[](#architektura)

- `Payments` wybiera provider na podstawie stringa albo `PaymentSystemEnum`
- `Payments` udostępnia zarówno niski poziom (`gateway()`), jak i wspólny flow modułu (`flow()`)
- `GatewayInterface` trzyma wspólny kontrakt dla providerów
- `PaymentProviderAdapterInterface` oddziela flow modułu od logiki konkretnego operatora
- `Module::onUpdate()` uruchamia migracje modułu z katalogu `migrations/`
- implementacje providerów są w `src/Provider/`
- adapter operatora mapuje statusy i webhooki do wspólnego formatu modułu
- `PaymentTransactionFlowService` odpowiada za zapis rekordu, update statusów i przechowanie payloadów
- DTO są provider-specific, dopóki nie pojawi się realna potrzeba wspólnej warstwy dla wielu operatorów
- storage transakcji jest wspólny dla modułu i nie jest nazwany per provider
- migracje używają aktualnych klas kolumn zamiast deprecated helperów `addIdColumn()` / `addDateCreatedColumn()` / `addDateModifyColumn()`

Tabela `module_payment_transaction`
-----------------------------------

[](#tabela-module_payment_transaction)

Aktualny wspólny storage modułu zawiera między innymi:

- `provider`
- `provider_session_id`
- `provider_order_id`
- `provider_transaction_id`
- `provider_token`
- `provider_status`
- `account_id`
- `object_type`
- `object_id`
- `amount`
- `currency`
- `status`
- `request_payload`
- `register_response_payload`
- `verify_response_payload`
- `webhook_payload`
- `metadata`
- `date_completed`
- `date_failed`
- `date_created`
- `date_modify`

Callbacki i statusy
-------------------

[](#callbacki-i-statusy)

- callback / webhook operatora nie kończy flow sam z siebie — aktualizuje transakcję do stanu pośredniego i zapisuje surowy payload,
- finalne potwierdzenie płatności powinno następować po `verifyTransaction(...)`,
- moduł przechowuje jednocześnie wspólny `status` oraz surowy `provider_status`,
- adapter operatora odpowiada za mapowanie statusów zewnętrznych do `PaymentTransactionStatusEnum`.

###  Health Score

23

—

LowBetter than 25% of packages

Maintenance54

Moderate activity, may be stable

Popularity18

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/b71301619d71d2798d3a84f23de616ac1f1c185ab72e4f03e925cff169b03a0d?d=identicon)[krzysztofzylka](/maintainers/krzysztofzylka)

---

Top Contributors

[![krzysztofzylka](https://avatars.githubusercontent.com/u/41385342?v=4)](https://github.com/krzysztofzylka "krzysztofzylka (1 commits)")

### Embed Badge

![Health badge](/badges/nimblephp-payments/health.svg)

```
[![Health](https://phpackages.com/badges/nimblephp-payments/health.svg)](https://phpackages.com/packages/nimblephp-payments)
```

###  Alternatives

[pagseguro/php

Biblioteca de integração com o PagSeguro

23260.3k6](/packages/pagseguro-php)[dinkbit/conekta-cashier

Dinkbit Cashier nos da una interface para cobrar subscripciones con Conketa en Laravel.

365.4k](/packages/dinkbit-conekta-cashier)[msilabs/bkash

bKash Payment Gateway API for Laravel Framework.

181.4k](/packages/msilabs-bkash)[binkode/laravel-paystack

A description for laravel-paystack.

112.1k](/packages/binkode-laravel-paystack)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)