PHPackages                             kommandhub/paystack - 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. kommandhub/paystack

ActiveLibrary[Payment Processing](/categories/payments)

kommandhub/paystack
===================

A framework-agnostic PHP library for integrating Paystack payments using SOLID principles and PSR standards.

1.1.0(3mo ago)0341MITPHPPHP >=8.1CI passing

Since Mar 15Pushed 3mo agoCompare

[ Source](https://github.com/KommandHub/paystack)[ Packagist](https://packagist.org/packages/kommandhub/paystack)[ RSS](/packages/kommandhub-paystack/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (3)Dependencies (23)Versions (5)Used By (1)

 [![Paystack logo](./paystack.png "Paystack")](./paystack.png)

Paystack PHP Library
====================

[](#paystack-php-library)

[![PHP Composer](https://github.com/KommandHub/paystack/actions/workflows/tests.yml/badge.svg)](https://github.com/KommandHub/paystack/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/f1df4a2ac36ac75ac170a463554464867dfc9b141301f81d99750f5f208a1e2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f6d6d616e646875622f706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kommandhub/paystack)[![Total Downloads](https://camo.githubusercontent.com/e6e6a11941c3f8396093b124f6b58780fc2b49c29c6678a0d5ad3aed5ed1d1f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f6d6d616e646875622f706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kommandhub/paystack)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)

A framework-agnostic PHP library for integrating [Paystack](https://paystack.com) payments using SOLID principles and PSR standards. It provides a clean, object-oriented interface to the Paystack API and works in any PHP environment.

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Initialization](#initialization)
    - [Using Guzzle and Nyholm PSR-7](#using-guzzle-and-nyholm-psr-7)
    - [Bringing Your Own HTTP Client](#bringing-your-own-http-client)
- [Response Structure](#response-structure)
- [Error Handling](#error-handling)
- [Resources](#resources)
    - [Transactions](#transactions)
    - [Customers](#customers)
    - [Transfers](#transfers)
    - [Subscriptions](#subscriptions)
    - [Plans](#plans)
    - [Splits](#splits)
    - [Subaccounts](#subaccounts)
    - [Refunds](#refunds)
    - [Verification](#verification)
    - [Settlements](#settlements)
    - [Miscellaneous](#miscellaneous)
- [Webhook Handling](#webhook-handling)
- [Testing](#testing)
- [Development (Docker)](#development-docker)
- [Code Quality](#code-quality)
- [Contributing](#contributing)
- [License](#license)

---

Requirements
------------

[](#requirements)

- PHP **8.1** or higher
- A PSR-18 HTTP client (e.g. `guzzlehttp/guzzle`, `symfony/http-client`)
- PSR-17 HTTP factory (e.g. `nyholm/psr7`, `guzzlehttp/psr7`)

Installation
------------

[](#installation)

```
composer require kommandhub/paystack
```

If you don't already have a PSR-18 client and PSR-17 factory, install popular ones:

```
composer require guzzlehttp/guzzle nyholm/psr7
```

---

Quick Start
-----------

[](#quick-start)

```
use Kommandhub\Paystack\Paystack;
use GuzzleHttp\Client;
use Nyholm\Psr7\Factory\Psr17Factory;

$factory  = new Psr17Factory();
$paystack = new Paystack(
    secretKey:      'sk_live_your_secret_key',
    client:         new Client(),
    requestFactory: $factory,
    streamFactory:  $factory
);

// Initialize a transaction
$response = $paystack->transactions()->initialize([
    'email'  => 'customer@example.com',
    'amount' => 500000, // amount in kobo (NGN 5,000)
]);

header('Location: ' . $response['data']['authorization_url']);
exit;
```

---

Initialization
--------------

[](#initialization)

### Using Guzzle and Nyholm PSR-7

[](#using-guzzle-and-nyholm-psr-7)

```
use Kommandhub\Paystack\Paystack;
use GuzzleHttp\Client;
use Nyholm\Psr7\Factory\Psr17Factory;

$factory  = new Psr17Factory();

$paystack = new Paystack(
    secretKey:      'sk_live_your_secret_key',
    client:         new Client(),
    requestFactory: $factory,
    streamFactory:  $factory
);
```

### Bringing Your Own HTTP Client

[](#bringing-your-own-http-client)

Implement `Kommandhub\Paystack\Contracts\HttpClientInterface` to wrap any HTTP layer you prefer, then pass it directly:

```
use Kommandhub\Paystack\Paystack;
use App\Http\MyCustomHttpClient;

$paystack = new Paystack(
    secretKey:  'sk_live_your_secret_key',
    httpClient: new MyCustomHttpClient()
);
```

---

Response Structure
------------------

[](#response-structure)

Every resource method returns an associative array that mirrors the Paystack API JSON response:

```
[
    'status'  => true,           // bool – whether the request succeeded
    'message' => 'Authorized',   // string – human-readable status message
    'data'    => [ ... ],        // array – the actual payload (varies by endpoint)
]
```

Always check `$response['status']` before consuming `$response['data']`.

---

Error Handling
--------------

[](#error-handling)

All resource methods throw `Kommandhub\Paystack\Exceptions\PaystackException` on HTTP or API errors. Wrap calls in a try/catch block:

```
use Kommandhub\Paystack\Exceptions\PaystackException;

try {
    $response = $paystack->transactions()->verify('invalid_ref');
} catch (PaystackException $e) {
    // Log or display $e->getMessage()
    echo 'Paystack error: ' . $e->getMessage();
}
```

---

Resources
---------

[](#resources)

### Transactions

[](#transactions)

Handle payment initialization, verification, and retrieval.

```
// Initialize a transaction
$response = $paystack->transactions()->initialize([
    'email'        => 'customer@example.com',
    'amount'       => 500000,                         // in kobo
    'callback_url' => 'https://your-site.com/callback',
]);

$authorizationUrl = $response['data']['authorization_url'];

// Verify a transaction
$response = $paystack->transactions()->verify('transaction_reference');

// List transactions (supports query params: perPage, page, customer, status, etc.)
$response = $paystack->transactions()->list(['perPage' => 20, 'page' => 1]);

// Fetch a single transaction by ID
$response = $paystack->transactions()->fetch('12345678');
```

---

### Customers

[](#customers)

Manage your customer database.

```
// Create a customer
$response = $paystack->customers()->create([
    'email'      => 'customer@example.com',
    'first_name' => 'John',
    'last_name'  => 'Doe',
    'phone'      => '+2348012345678',
]);

// List customers (supports query params: perPage, page, etc.)
$response = $paystack->customers()->list(['perPage' => 50]);

// Fetch a customer by email or customer code
$response = $paystack->customers()->fetch('customer@example.com');
$response = $paystack->customers()->fetch('CUS_xxxxxxxxxx');

// Update a customer
$response = $paystack->customers()->update('CUS_xxxxxxxxxx', [
    'first_name' => 'Jane',
]);
```

---

### Transfers

[](#transfers)

Send money to customers or vendors.

```
// Create a transfer recipient
$response = $paystack->transfers()->recipient([
    'type'           => 'nuban',
    'name'           => 'John Doe',
    'account_number' => '0001234567',
    'bank_code'      => '058',
    'currency'       => 'NGN',
]);

$recipientCode = $response['data']['recipient_code'];

// Initiate a transfer
$response = $paystack->transfers()->initiate([
    'source'    => 'balance',
    'amount'    => 50000,
    'recipient' => $recipientCode,
    'reason'    => 'Payment for services',
]);

// List transfers (supports query params: perPage, page, customer, etc.)
$response = $paystack->transfers()->list(['perPage' => 20]);

// Fetch a single transfer by ID or transfer code
$response = $paystack->transfers()->fetch('TRF_xxxxxxxxxx');

// Verify a transfer by reference
$response = $paystack->transfers()->verify('transfer_reference');
```

---

### Subscriptions

[](#subscriptions)

Manage recurring payments.

```
// Create a subscription
$response = $paystack->subscriptions()->create([
    'customer'   => 'CUS_xxxxxxxxxx',
    'plan'       => 'PLN_xxxxxxxxxx',
    'start_date' => '2026-01-01T00:00:00.000Z', // optional
]);

// List subscriptions (supports query params: perPage, page, customer, plan)
$response = $paystack->subscriptions()->list(['plan' => 'PLN_xxxxxxxxxx']);

// Fetch a subscription by ID or subscription code
$response = $paystack->subscriptions()->fetch('SUB_xxxxxxxxxx');

// Enable a subscription
$response = $paystack->subscriptions()->enable([
    'code'  => 'SUB_xxxxxxxxxx',
    'token' => 'email_token',
]);

// Disable a subscription
$response = $paystack->subscriptions()->disable([
    'code'  => 'SUB_xxxxxxxxxx',
    'token' => 'email_token',
]);

// Generate a self-service management link for the customer
$response = $paystack->subscriptions()->manageLink('SUB_xxxxxxxxxx');
$managementUrl = $response['data']['link'];

// Email the management link directly to the customer
$response = $paystack->subscriptions()->sendManageLink('SUB_xxxxxxxxxx');
```

---

### Plans

[](#plans)

Create and manage payment plans for subscriptions.

```
// Create a plan
$response = $paystack->plans()->create([
    'name'     => 'Monthly Premium',
    'amount'   => 500000,   // in kobo
    'interval' => 'monthly', // daily | weekly | monthly | annually
]);

// List plans (supports query params: perPage, page, status, interval, amount)
$response = $paystack->plans()->list(['interval' => 'monthly']);

// Fetch a plan by ID or plan code
$response = $paystack->plans()->fetch('PLN_xxxxxxxxxx');

// Update a plan
$response = $paystack->plans()->update('PLN_xxxxxxxxxx', [
    'name'   => 'Monthly Premium Plus',
    'amount' => 750000,
]);
```

---

### Splits

[](#splits)

Split payments between multiple subaccounts.

```
// Create a split
$response = $paystack->splits()->create([
    'name'         => 'Revenue Split',
    'type'         => 'percentage',  // percentage | flat
    'currency'     => 'NGN',
    'subaccounts'  => [
        ['subaccount' => 'ACCT_xxxxxxxxxx', 'share' => 20],
    ],
    'bearer_type'  => 'subaccount',  // subaccount | account | all-proportional | all
    'bearer_subaccount' => 'ACCT_xxxxxxxxxx',
]);

// List splits (supports query params: name, active, sort_by, perPage, page, from, to)
$response = $paystack->splits()->list(['active' => true]);

// Fetch a split by ID
$response = $paystack->splits()->fetch('SPL_xxxxxxxxxx');

// Update a split
$response = $paystack->splits()->update('SPL_xxxxxxxxxx', [
    'name'   => 'Updated Revenue Split',
    'active' => true,
]);

// Add or update a subaccount in a split
$response = $paystack->splits()->addSubaccount('SPL_xxxxxxxxxx', [
    'subaccount' => 'ACCT_yyyyyyyyyy',
    'share'      => 30,
]);

// Remove a subaccount from a split
$response = $paystack->splits()->removeSubaccount('SPL_xxxxxxxxxx', [
    'subaccount' => 'ACCT_yyyyyyyyyy',
]);
```

---

### Subaccounts

[](#subaccounts)

Manage subaccounts for split payments and marketplace settlements.

```
// Create a subaccount
$response = $paystack->subaccounts()->create([
    'business_name'    => 'Acme Stores',
    'settlement_bank'  => '058',
    'account_number'   => '0001234567',
    'percentage_charge' => 18.2,
]);

// List subaccounts (supports query params: perPage, page, from, to)
$response = $paystack->subaccounts()->list(['perPage' => 50]);

// Fetch a subaccount by ID or subaccount code
$response = $paystack->subaccounts()->fetch('ACCT_xxxxxxxxxx');

// Update a subaccount
$response = $paystack->subaccounts()->update('ACCT_xxxxxxxxxx', [
    'percentage_charge' => 20.0,
    'description'       => 'Updated description',
]);
```

---

### Refunds

[](#refunds)

Process full or partial refunds for transactions.

```
// Create a refund (omit 'amount' for a full refund)
$response = $paystack->refunds()->create([
    'transaction' => 'transaction_reference',
    'amount'      => 50000, // optional – partial refund in kobo
]);

// List refunds (supports query params: reference, currency, from, to, perPage, page)
$response = $paystack->refunds()->list(['reference' => 'transaction_reference']);

// Fetch a refund by reference
$response = $paystack->refunds()->fetch('refund_reference');
```

---

### Verification

[](#verification)

Verify customer account and card information.

```
// Resolve a bank account number
$response = $paystack->verification()->resolveAccount('0001234567', '058');
$accountName = $response['data']['account_name'];

// Resolve a card BIN (first 6 digits)
$response = $paystack->verification()->resolveCardBin('539983');
$cardInfo  = $response['data']; // bank, card_type, brand, etc.
```

---

### Settlements

[](#settlements)

Retrieve settlement reports and their associated transactions.

```
// List settlements (supports query params: perPage, page, status, subaccount, from, to)
$response = $paystack->settlements()->list(['from' => '2026-01-01']);

// Fetch transactions for a specific settlement
$response = $paystack->settlements()->transactions('settlement_id', ['perPage' => 100]);
```

---

### Miscellaneous

[](#miscellaneous)

Access supporting reference data from the Paystack API.

```
// List supported banks (supports query params: country, use_cursor, perPage, etc.)
$response = $paystack->miscellaneous()->listBanks(['country' => 'nigeria']);

// List supported countries
$response = $paystack->miscellaneous()->listCountries();

// List states for Address Verification Service (AVS)
$response = $paystack->miscellaneous()->listStates('US');
```

---

Webhook Handling
----------------

[](#webhook-handling)

Paystack sends webhook events to your endpoint for asynchronous notifications. Always validate the signature before processing:

```
// webhook.php

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYSTACK_SIGNATURE'] ?? '';
$secret    = 'sk_live_your_secret_key';

if (hash_hmac('sha512', $payload, $secret) !== $signature) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);

match ($event['event']) {
    'charge.success'      => handleChargeSuccess($event['data']),
    'transfer.success'    => handleTransferSuccess($event['data']),
    'subscription.create' => handleSubscriptionCreate($event['data']),
    default               => null,
};

http_response_code(200);
```

> **Tip:** Respond with HTTP `200` as quickly as possible and process webhook payloads asynchronously (e.g. via a queue) to avoid timeouts.

---

Testing
-------

[](#testing)

```
composer test
```

---

Development (Docker)
--------------------

[](#development-docker)

This project includes a Docker environment for easy development.

### Requirements

[](#requirements-1)

- Docker
- Docker Compose

### Getting Started

[](#getting-started)

CommandDescription`make build`Build and start the container`make shell`Open a shell inside container`make test`Run the test suite`make lint`Run static analysis (PHPStan)`make format`Fix code style (PHP CS Fixer)`make down`Stop and remove containersOr use `docker-compose` directly:

```
docker-compose up -d
docker-compose exec app sh
```

---

Code Quality
------------

[](#code-quality)

ToolCommandPurpose[PHPStan](https://phpstan.org)`composer lint`Static analysis[PHP CS Fixer](https://cs.symfony.com)`composer format`Code style enforcementPlease ensure both pass before submitting a pull request.

---

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see the [License File](LICENSE) for more information.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance82

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~3 days

Total

3

Last Release

94d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0f1debdb2d793fd382ffc606ad8ed6433c9e8b70a9eda51a58227625a2ba412b?d=identicon)[kommandhub](/maintainers/kommandhub)

---

Top Contributors

[![KommandHub](https://avatars.githubusercontent.com/u/225087266?v=4)](https://github.com/KommandHub "KommandHub (15 commits)")

---

Tags

laravellaravel-frameworklaravel-packagepaymentpayment-integrationpaystackphpphplibrarypaymentgatewayNigeriapaystackafrica

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/kommandhub-paystack/health.svg)

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

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60315.4M74](/packages/mollie-mollie-api-php)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[aporat/store-receipt-validator

PHP receipt validator for Apple App Store and Amazon Appstore

6513.9M11](/packages/aporat-store-receipt-validator)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)

PHPackages © 2026

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