README

Requirement

Requires Composer Requires PHP 8.2+

Paystack PHP SDK

A robust, fluent and object-oriented PHP SDK for the Paystack API, designed for ease of use and extensibility.

Introduction
Key Features
Installation
Quick Start
API Reference
Extending the SDK
Contributing
License

Introduction

The SDK provides a comprehensive and intuitive way to interact with the Paystack API. Designed with developer experience in mind, it offers a fluent, object-oriented interface to various Paystack endpoints, making payment integration seamless and efficient for your PHP applications.

This SDK supports a wide array of Paystack services, including:

Transactions: Initialize, verify, list, fetch, charge authorizations, refunds, and more.
Customers: Manage customer records, including creation, updates, and identity validation.
Transfers: Facilitate single and bulk transfers to bank accounts and mobile money wallets.
Subscriptions: Handle recurring payments by managing plans and customer subscriptions.
Dedicated Accounts (Virtual Accounts): Create and manage unique bank accounts for customers.
Transaction Splits: Automatically divide payments among multiple recipients.
Terminals: Interact with physical Paystack POS devices.
Disputes: Manage and resolve chargebacks effectively.
Miscellaneous: Access general data like lists of banks, countries, and states.

Key Features

Fluent API: Enjoy a clean and readable codebase with chained method calls (e.g., client()->transaction()->initialize(...)).
Object-Oriented Design: Paystack API endpoints are encapsulated into dedicated classes for better organization and maintainability.
PSR-18 HTTP Client Support: Leverage any PSR-18 compatible HTTP client for flexible and robust request handling.
Strong Typing: Benefits from PHP's type hints for enhanced code quality and improved IDE support.
Extensible Architecture: Designed for easy extension, allowing you to add custom transporters or build new API modules.

Installation

The easiest way to install the Paystack PHP SDK is via Composer:

composer require musheabdulhakim/paystack

Quick Start

To get started, initialize the Paystack client with your secret key. You can then immediately begin interacting with any available Paystack API endpoint.

Simple Initialization

<?php

require 'vendor/autoload.php';

use MusheAbdulHakim\Paystack\Paystack;

// Replace with your actual Paystack secret key
$secretKey = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Initialize the Paystack client
$client = Paystack::client($secretKey);

// Example: Initialize a new transaction
try {
    $response = $client->transaction()->initialize([
        'amount' => 500000, // Amount in kobo (e.g., NGN 5000.00)
        'email' => 'customer@example.com',
        'callback_url' => '[https://yourwebsite.com/verify-payment](https://yourwebsite.com/verify-payment)',
    ]);

    echo "Transaction initialized successfully! Authorization URL: " . $response['authorization_url'] . "\n";
} catch (\Exception $e) {
    echo "Error initializing transaction: " . $e->getMessage() . "\n";
}

// Example: List all customers
try {
    $customers = $client->customer()->list(['perPage' => 5]);
    echo "Customers:\n";
    print_r($customers);
} catch (\Exception $e) {
    echo "Error listing customers: " . $e->getMessage() . "\n";
}

?>

Advanced Initialization with Factory

For more granular control over the underlying HTTP client, base URI, or default headers, use the Paystack::factory() method. This is useful for advanced scenarios like proxying requests, custom logging, or integrating with a specific PSR-18 client implementation (e.g., Guzzle).

<?php

require 'vendor/autoload.php';

use MusheAbdulHakim\Paystack\Paystack;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;

// Replace with your actual Paystack secret key
$secretKey = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Example of a dummy PSR-18 HTTP Client (replace with a real implementation like Guzzle)
class MyCustomHttpClient implements ClientInterface {
    public function sendRequest(\Psr\Http\Message\RequestInterface $request): \Psr\Http\Message\ResponseInterface {
        // Dummy response for demonstration
        return new \GuzzleHttp\Psr7\Response(200, [], '{"status": true, "message": "Custom client response"}');
    }
}

// Example of a dummy PSR-17 Request Factory
class MyCustomRequestFactory implements RequestFactoryInterface {
    public function createRequest(string $method, \Psr\Http\Message\UriInterface|string $uri): \Psr\Http\Message\RequestInterface {
        return new \GuzzleHttp\Psr7\Request($method, $uri);
    }
}

// Example of a dummy PSR-17 Stream Factory
class MyCustomStreamFactory implements StreamFactoryInterface {
    public function createStream(string $content = ''): \Psr\Http\Message\StreamInterface {
        return \GuzzleHttp\Psr7\Utils::streamFor($content);
    }
}

$client = Paystack::factory()
    ->withSecretKey($secretKey)
    ->withBaseUri('[https://api.paystack.com/](https://api.paystack.com/)') // Set a custom base URI
    ->withHeaders([ // Add default headers to all requests
        'X-Custom-Header' => 'My-App-Identifier',
        'User-Agent' => 'MyCustomPaystackClient/1.0',
    ])
    ->withQueryParameters(['perPage' => 50]) // Add default query parameters
    ->withHttpClient(new MyCustomHttpClient()) // Provide your custom HTTP client
    ->withRequestFactory(new MyCustomRequestFactory()) // Provide your custom request factory
    ->withStreamFactory(new MyCustomStreamFactory()) // Provide your custom stream factory
    ->make();

// Now, all requests made through $client will use your custom configurations.
try {
    $response = $client->miscellaneous()->banks(['country' => 'nigeria']);
    echo "Nigerian Banks (via custom client):\n";
    print_r($response);
} catch (\Exception $e) {
    echo "Error fetching banks: " . $e->getMessage() . "\n";
}

?>

API Reference

The SDK is structured with dedicated classes for each major Paystack API resource, providing clear and organized access to their respective methods. Click on the links below to view detailed documentation and sample code for each class.

Apple Pay: Manage Apple Pay domains (register, list, unregister).
Bulk Charges: Initiate, list, fetch, pause, and resume bulk charge operations.
Charges: Directly charge customers, handle authentication steps (PIN, OTP, etc.), and check pending charge status.
Customers: Create, list, fetch, update, validate customer details, and manage risk actions.
Disputes: List, fetch, update, resolve disputes, and upload/manage evidence.
Integration: Fetch and update payment session timeout settings.
Miscellaneous: Retrieve lists of banks, countries, and states.
Payment Pages: Create, list, fetch, update payment pages, check slug availability, and add products.
Payment Requests: Create, list, fetch, verify, notify, finalize, update, and archive payment requests (invoices).
Plans: Create, list, fetch, and update subscription plans.
Products: Create, list, fetch, and update products.
Refunds: Create, list, and fetch details of refunds for transactions.
Settlements: List settlements and retrieve transactions associated with them.
Subaccounts: Create, list, fetch, and update subaccounts for splitting payments.
Subscriptions: Create, list, fetch, enable, disable subscriptions, and generate/send management links.
Terminals: Send events to terminals, check event status, get terminal presence, list, fetch, update, commission, and decommission devices.
Transactions: Initialize, verify, list, fetch transactions, charge authorizations, view timelines, get totals, export data, and perform partial debits.
Transaction Splits: Create, list, fetch, update transaction splits, and manage subaccounts within a split.
Transfers: Initiate single and bulk transfers, finalize transfers with OTP, list, fetch, and verify status.
Transfer Control: Retrieve account balance and ledger, and manage OTP settings for transfers.
Transfer Recipients: Create single and bulk transfer recipients, list, fetch, update, and delete them.
Verifications: Resolve bank accounts, validate bank accounts, and resolve card BINs.
Virtual Accounts: Create, assign, list, fetch, requery, deactivate virtual accounts, manage split transactions, and retrieve bank providers.

Extending the SDK

The SDK is built with extensibility at its core. If you need to customize how HTTP requests are sent (e.g., for specific logging, advanced error handling, or integrating with a custom HTTP client not directly supported by PSR-18), you can implement your own Transporter and provide it to the Factory. This allows you to tailor the SDK's behavior to your exact needs.

You can also easily add new API modules if Paystack introduces new endpoints not yet covered by the SDK, or if you wish to group specific functionalities into your own custom classes.

Contributing

We welcome contributions to the Paystack PHP SDK! Whether it's bug reports, feature requests, or pull requests, your input is valuable. Please refer to the CONTRIBUTING.md file (if available) for guidelines on how to contribute.

License

This Paystack PHP SDK is open-sourced software licensed under the MIT license.

musheabdulhakim / paystack

Maintainers

Details