iamolayemi / laravel-paystack
A laravel package for working with paystack api
Requires
- php: ^8.1|^8.2
- guzzlehttp/guzzle: ^7.3
- illuminate/support: ^9.0|^10.0
Requires (Dev)
- laravel/pint: ^1.10
- nunomaduro/collision: 6.0|^7.0
- orchestra/testbench: ^7.0|^8.0
- phpunit/phpunit: ^9.0|^10.0
This package is auto-updated.
Last update: 2025-06-28 23:58:40 UTC
README
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
- ๐ 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
- PHP: ^8.1|^8.2|^8.3
- Laravel: ^9.0|^10.0|^11.0
- Composer: ^2.0
๐ 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
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)
php artisan vendor:publish --provider="Iamolayemi\Paystack\PaystackServiceProvider"
๐ Quick Start
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 the helper function $response = paystack()->transaction() ->initialize($paymentData) ->response();
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
// 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
The package provides access to all Paystack API endpoints:
Transactions
Paystack::transaction()->initialize($data); Paystack::transaction()->verify($reference); Paystack::transaction()->list($params); Paystack::transaction()->fetch($id);
Customers
Paystack::customer()->create($data); Paystack::customer()->list($params); Paystack::customer()->fetch($emailOrCode); Paystack::customer()->update($code, $data);
Transfers
Paystack::transfer()->initiate($data); Paystack::transfer()->finalize($data); Paystack::transfer()->list($params); Paystack::transfer()->fetch($code);
Plans & Subscriptions
Paystack::plan()->create($data); Paystack::plan()->list($params); Paystack::subscription()->create($data); Paystack::subscription()->list($params);
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
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
Running Tests
# Run all tests composer test # Run with coverage composer test-coverage # Run specific test vendor/bin/phpunit --filter=TransactionTest
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
For detailed documentation, visit https://laravel-paystack.netlify.app
Additional Resources
๐ง Development
Prerequisites
- PHP: ^8.1|^8.2|^8.3
- Composer: ^2.0
- Node.js: ^16.0 (for documentation)
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
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
# 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
# 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
# Check for security vulnerabilities make security-check # Validate composer.json make validate
CI/CD Commands
# Run complete CI pipeline (test + analyse + style + security) make ci # Run all checks (test + analyse + style) make check
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
# Generate documentation make docs # Build documentation (if using docs package) cd docs && npm install && npm run build
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 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
- Setup:
make dev-setup
- Make changes: Edit code
- Test:
make test
- Check quality:
make analyse
- Fix style:
make fix
- Full validation:
make ci
- Commit:
git commit -m "Your message"
- Push:
git push
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
# 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
# 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
# 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
# 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
For the best development experience:
- PHPStorm/IntelliJ: Enable PHPStan integration
- VS Code: Install PHP extensions
- EditorConfig: Project includes
.editorconfig
- PHP CS Fixer: Configuration in
.php-cs-fixer.php
Pre-commit Hooks
Consider setting up pre-commit hooks:
# Create pre-commit hook cat > .git/hooks/pre-commit << 'EOF' #!/bin/sh make ci EOF chmod +x .git/hooks/pre-commit
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
- Fork the repository
- Clone your fork
- Install dependencies:
composer install
- Run tests:
make test
- Make your changes
- Ensure all tests pass:
make ci
- Submit a pull request
๐ Bug Reports
If you discover any bugs, please create an issue on GitHub.
๐ Security
If you discover any security-related issues, please email olatayo.olayemi.peter@gmail.com instead of using the issue tracker.
๐ License
The MIT License (MIT). Please see License File for more information.
๐ Credits
- Olayemi Olatayo - Original author
- All Contributors - Community contributors
- Paystack - Payment gateway provider