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

ActiveLibrary[Payment Processing](/categories/payments)

iamolayemi/laravel-paystack
===========================

A laravel package for working with paystack api

v1.0.1(2y ago)46502[2 PRs](https://github.com/iamolayemi/laravel-paystack/pulls)MITPHPPHP ^8.1|^8.2CI passing

Since Jun 5Pushed 10mo ago1 watchersCompare

[ Source](https://github.com/iamolayemi/laravel-paystack)[ Packagist](https://packagist.org/packages/iamolayemi/laravel-paystack)[ Docs](https://github.com/iamolayemi/laravel-paystack)[ RSS](/packages/iamolayemi-laravel-paystack/feed)WikiDiscussions master Synced today

READMEChangelog (2)Dependencies (6)Versions (5)Used By (0)

Laravel Paystack
================

[](#laravel-paystack)

[![Latest Version on Packagist](https://camo.githubusercontent.com/bbd4c6aeaf637246b5519deea8d672e02b2bb6add2f8c1dae5901bc2e5884414/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iamolayemi/laravel-paystack)[![Total Downloads](https://camo.githubusercontent.com/4399ceced65ec985693569bb6e93666cc69f0816bfc04946881100ff60caae68/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iamolayemi/laravel-paystack)[![Build Status](https://camo.githubusercontent.com/f3af55a5e92b9f3b6eee14e157cd7801fd66f169615079c2d8d9520806ff6227/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2f63692e796d6c3f6272616e63683d6d61696e)](https://github.com/iamolayemi/laravel-paystack/actions)[![Code Quality](https://camo.githubusercontent.com/f780a512819f3b1740d83ecd9363fb428da62985f4f81fd068315bd68631bef9/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/iamolayemi/laravel-paystack)[![Code Coverage](https://camo.githubusercontent.com/c0c9b0d0ade98dba192a843c009517ae73a125c710a00b7e51f96dd97942df0f/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f69616d6f6c6179656d692f6c61726176656c2d706179737461636b)](https://codecov.io/gh/iamolayemi/laravel-paystack)[![PHP Version](https://camo.githubusercontent.com/bf02a0fd90f21d5f75eea9690f56245401a50a9a0983c89c3850f5916863fc0d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://php.net)[![License](https://camo.githubusercontent.com/d3d25d4363374cb9b7b1b185d772cf06cc87e65d60698f6197e8fc5d22a43dcd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f69616d6f6c6179656d692f6c61726176656c2d706179737461636b2e7376673f7374796c653d666c61742d737175617265)](https://github.com/iamolayemi/laravel-paystack/blob/main/LICENSE.md)

A comprehensive Laravel package for seamless integration with the Paystack payment gateway. This package provides an expressive and convenient way to interact with the Paystack API within your Laravel application.

✨ Features
----------

[](#-features)

- 🚀 **Fluent API Interface** - Clean and intuitive method chaining
- 🛡️ **Comprehensive Error Handling** - Custom exception classes for different error types
- 🔒 **Security First** - Built-in validation and security checks
- 📊 **Full API Coverage** - Support for all Paystack API endpoints
- 🧪 **Extensive Testing** - High test coverage with mock support
- 📚 **Excellent Documentation** - Comprehensive guides and examples
- 🔧 **Developer Friendly** - Easy setup and configuration
- ⚡ **Performance Optimized** - Efficient HTTP client with retry logic
- 🌍 **Multi-Currency Support** - NGN, GHS, USD, and more
- 🔄 **Webhook Support** - Built-in webhook handling and verification

📋 Requirements
--------------

[](#-requirements)

- **PHP**: ^8.1|^8.2|^8.3
- **Laravel**: ^9.0|^10.0|^11.0
- **Composer**: ^2.0

🚀 Installation
--------------

[](#-installation)

You can install the package via Composer:

```
composer require iamolayemi/laravel-paystack
```

The package will automatically register itself if you're using Laravel's auto-discovery feature.

⚙️ Configuration
----------------

[](#️-configuration)

### Environment Variables

[](#environment-variables)

Add your Paystack credentials to your `.env` file:

```
PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_CALLBACK_URL=https://yourdomain.com/paystack/callback
PAYSTACK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
```

### Publishing Configuration (Optional)

[](#publishing-configuration-optional)

```
php artisan vendor:publish --provider="Iamolayemi\Paystack\PaystackServiceProvider"
```

📖 Quick Start
-------------

[](#-quick-start)

### Basic Usage

[](#basic-usage)

```
use Iamolayemi\Paystack\Facades\Paystack;

// Initialize a payment
$paymentData = [
    'amount' => 500000, // 5000 NGN in kobo
    'email' => 'customer@example.com',
    'reference' => 'PAY_' . uniqid(),
    'callback_url' => 'https://yourdomain.com/payment/callback',
];

$response = Paystack::transaction()
    ->initialize($paymentData)
    ->response();

if ($response['status']) {
    $authorizationUrl = $response['data']['authorization_url'];
    // Redirect user to $authorizationUrl
}
```

### Using Helper Function

[](#using-helper-function)

```
// Using the helper function
$response = paystack()->transaction()
    ->initialize($paymentData)
    ->response();
```

### Getting Specific Data

[](#getting-specific-data)

```
// Get only the authorization URL
$authorizationUrl = Paystack::transaction()
    ->initialize($paymentData)
    ->response('data.authorization_url');

// Or use the dedicated method
$authorizationUrl = Paystack::transaction()
    ->initialize($paymentData)
    ->authorizationURL();
```

### Verifying Transactions

[](#verifying-transactions)

```
// Verify a transaction
$reference = 'PAY_xxxxxxxxx';
$verification = Paystack::transaction()
    ->verify($reference)
    ->response();

if ($verification['status'] && $verification['data']['status'] === 'success') {
    // Payment was successful
    $amount = $verification['data']['amount'];
    $customerEmail = $verification['data']['customer']['email'];
}
```

🔧 Available Endpoints
---------------------

[](#-available-endpoints)

The package provides access to all Paystack API endpoints:

### Transactions

[](#transactions)

```
Paystack::transaction()->initialize($data);
Paystack::transaction()->verify($reference);
Paystack::transaction()->list($params);
Paystack::transaction()->fetch($id);
```

### Customers

[](#customers)

```
Paystack::customer()->create($data);
Paystack::customer()->list($params);
Paystack::customer()->fetch($emailOrCode);
Paystack::customer()->update($code, $data);
```

### Transfers

[](#transfers)

```
Paystack::transfer()->initiate($data);
Paystack::transfer()->finalize($data);
Paystack::transfer()->list($params);
Paystack::transfer()->fetch($code);
```

### Plans & Subscriptions

[](#plans--subscriptions)

```
Paystack::plan()->create($data);
Paystack::plan()->list($params);
Paystack::subscription()->create($data);
Paystack::subscription()->list($params);
```

### And Many More...

[](#and-many-more)

- **Banks**: List banks, resolve account numbers
- **Countries**: List countries and states
- **Invoices**: Create and manage invoices
- **Products**: Product management
- **Refunds**: Process refunds
- **Settlements**: Settlement management
- **Splits**: Split payment configuration
- **Sub-accounts**: Sub-account management

🛡️ Error Handling
-----------------

[](#️-error-handling)

The package provides comprehensive error handling with custom exception classes:

```
use Iamolayemi\Paystack\Exceptions\PaystackApiException;
use Iamolayemi\Paystack\Exceptions\PaystackValidationException;
use Iamolayemi\Paystack\Exceptions\PaystackConnectionException;

try {
    $response = Paystack::transaction()->initialize($data)->response();
} catch (PaystackValidationException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
} catch (PaystackApiException $e) {
    // Handle API errors
    $message = $e->getMessage();
    $endpoint = $e->getEndpoint();
} catch (PaystackConnectionException $e) {
    // Handle connection errors
    $url = $e->getUrl();
}
```

🧪 Testing
---------

[](#-testing)

### Running Tests

[](#running-tests)

```
# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test
vendor/bin/phpunit --filter=TransactionTest
```

### Mock Testing

[](#mock-testing)

```
use Illuminate\Support\Facades\Http;

Http::fake([
    'api.paystack.co/transaction/initialize' => Http::response([
        'status' => true,
        'message' => 'Authorization URL created',
        'data' => [
            'authorization_url' => 'https://checkout.paystack.com/0x234567',
            'reference' => 'TEST_REF_123',
        ],
    ], 200),
]);
```

📚 Documentation
---------------

[](#-documentation)

For detailed documentation, visit

### Additional Resources

[](#additional-resources)

- [Advanced Usage Guide](docs/src/guide/advanced-usage.md)
- [API Reference](docs/src/endpoints.md)
- [Testing Guide](docs/src/guide/testing.md)
- [Security Best Practices](docs/src/guide/security.md)

🔧 Development
-------------

[](#-development)

### Prerequisites

[](#prerequisites)

- **PHP**: ^8.1|^8.2|^8.3
- **Composer**: ^2.0
- **Node.js**: ^16.0 (for documentation)

### Quick Setup

[](#quick-setup)

```
# Clone the repository
git clone https://github.com/iamolayemi/laravel-paystack.git
cd laravel-paystack

# Install dependencies
composer install

# Run all checks to ensure everything is working
make ci
```

### Available Commands

[](#available-commands)

The project uses a comprehensive Makefile for development tasks:

```
# Show all available commands
make help

# Install dependencies
make install

# Development workflow
make dev-setup          # Complete development setup
make dev-install        # Install development dependencies
```

#### Testing Commands

[](#testing-commands)

```
# Run all tests
make test

# Run tests with coverage report
make test-coverage

# Run specific test file
vendor/bin/phpunit tests/Unit/TransactionEndpointTest.php

# Run tests with specific filter
vendor/bin/phpunit --filter=testTransactionInitialization
```

#### Code Quality Commands

[](#code-quality-commands)

```
# Run static analysis with PHPStan
make analyse

# Fix code style issues automatically
make fix

# Check code style without fixing
make fix-dry-run

# Run all code quality checks
make check
```

#### Security & Validation

[](#security--validation)

```
# Check for security vulnerabilities
make security-check

# Validate composer.json
make validate
```

#### CI/CD Commands

[](#cicd-commands)

```
# Run complete CI pipeline (test + analyse + style + security)
make ci

# Run all checks (test + analyse + style)
make check
```

#### Maintenance Commands

[](#maintenance-commands)

```
# Clean build artifacts
make clean

# Update dependencies
make update

# Update only composer.lock
make update-lock

# Build the package for production
make build
```

#### Documentation Commands

[](#documentation-commands)

```
# Generate documentation
make docs

# Build documentation (if using docs package)
cd docs && npm install && npm run build
```

#### Docker Commands (Optional)

[](#docker-commands-optional)

```
# Build Docker image
make docker-build

# Run tests in Docker
make docker-test

# Run shell in Docker container
make docker-shell
```

#### Release Commands

[](#release-commands)

```
# Release patch version (1.0.0 -> 1.0.1)
make release-patch

# Release minor version (1.0.0 -> 1.1.0)
make release-minor

# Release major version (1.0.0 -> 2.0.0)
make release-major
```

### Development Workflow

[](#development-workflow)

1. **Setup**: `make dev-setup`
2. **Make changes**: Edit code
3. **Test**: `make test`
4. **Check quality**: `make analyse`
5. **Fix style**: `make fix`
6. **Full validation**: `make ci`
7. **Commit**: `git commit -m "Your message"`
8. **Push**: `git push`

### Code Quality Standards

[](#code-quality-standards)

The project enforces high code quality standards:

- **PHPStan Level 8**: Strict static analysis
- **Laravel Pint**: PSR-12 coding standards
- **PHPUnit**: 100% test coverage target
- **Security Checker**: Vulnerability scanning

### Testing Strategy

[](#testing-strategy)

```
# Run all tests
make test

# Run with coverage (generates HTML report)
make test-coverage

# Run specific test suite
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Feature

# Run tests with verbose output
vendor/bin/phpunit --verbose

# Run tests with stop on failure
vendor/bin/phpunit --stop-on-failure
```

### Static Analysis

[](#static-analysis)

```
# Run PHPStan analysis
make analyse

# Run with specific level
vendor/bin/phpstan analyse --level=8

# Generate baseline (for ignoring existing errors)
vendor/bin/phpstan analyse --generate-baseline
```

### Code Style

[](#code-style)

```
# Fix all code style issues
make fix

# Check what would be fixed
make fix-dry-run

# Fix specific file
vendor/bin/pint src/Endpoints/Transaction.php
```

### Troubleshooting

[](#troubleshooting)

```
# If tests fail, try cleaning and reinstalling
make clean
composer install
make test

# If PHPStan fails, check configuration
vendor/bin/phpstan analyse --debug

# If style check fails, auto-fix
make fix
```

### IDE Setup

[](#ide-setup)

For the best development experience:

1. **PHPStorm/IntelliJ**: Enable PHPStan integration
2. **VS Code**: Install PHP extensions
3. **EditorConfig**: Project includes `.editorconfig`
4. **PHP CS Fixer**: Configuration in `.php-cs-fixer.php`

### Pre-commit Hooks

[](#pre-commit-hooks)

Consider setting up pre-commit hooks:

```
# Create pre-commit hook
cat > .git/hooks/pre-commit