Download the PHP package myckhel/laravel-paystack without Composer

Laravel Paystack

Laravel wrapper for the Paystack API, built for direct use in controllers, services, and queued jobs.

Features

• Covers a broad set of Paystack endpoints (transactions, customers, transfers, plans, subscriptions, disputes, refunds, and more).
• Optional built-in HTTP routes for quick API proxying from your Laravel app.
• Built-in webhook route with signature validation and event dispatching.
• Compatible with Laravel 10, 11, 12, and 13.

Installation

Laravel package auto-discovery will register the service provider and facade alias automatically.

Configuration

Publish config:

Set your credentials in .env:

Default config (config/paystack.php):

Quick Usage

Call support classes directly:

Developer Integration Scenarios

Here are common design patterns for using this package across different parts of a Laravel application.

1. Controllers (Checkout & Verification)

Controllers should initiate payments and handle callback verification. When an API call fails, the package automatically calls Laravel's abort(), throwing a Symfony\Component\HttpKernel\Exception\HttpException which is caught by Laravel's global exception handler.

2. Service Classes (Business Logic Isolation)

For larger applications, abstract Paystack calls into a service layer to keep controllers clean. This is especially useful for managing complex customer profiles, plans, or subscriptions.

3. Queued Jobs (Background Processing)

When interacting with the Paystack API inside queued jobs (e.g. processing bulk transfers or validating statuses in the background), network errors or rate limits (429 Too Many Requests) can occur.

You should design your jobs to handle these failures gracefully and support retries:

4. Error Handling

Because the package uses Laravel's HTTP client under the hood, any failed response (status codes 4xx and 5xx) automatically throws a Symfony\Component\HttpKernel\Exception\HttpException via abort($res->status(), ...).

You can catch this in your application code for fine-grained error handling:

Available Support Classes

• ApplePay
• BulkCharge
• Charge
• ControlPanel
• Customer
• DedicatedVirtualAccount
• Dispute
• Invoice
• Miscellaneous
• Order
• Page
• Plan
• Product
• Recipient
• Refund
• Settlement
• Split
• SubAccount
• Subscription
• Terminal
• Transaction
• Transfer
• TransferControl
• Verification
• VirtualTerminal

See class methods in src/Support/*.

Built-In Routes

The package registers route definitions from src/routes.php. By default, API routes are disabled through the paystack_route_disabled middleware.

To enable built-in routes, remove paystack_route_disabled from paystack.route.middleware in config/paystack.php.

Default route prefix is api, so endpoints resolve like:

• POST /api/transaction/initialize
• GET /api/transaction/verify/{reference}
• POST /api/customer

Webhooks

Webhook endpoint:

• POST /api/hooks (route is registered as Route::any, but Paystack should call it with POST)

Incoming webhook requests are validated by the validate_paystack_hook middleware using your PAYSTACK_SECRET_KEY.

Each valid incoming webhook dispatches the Binkode\Paystack\Events\Hook event.

Create a listener:

Example listener:

Testing

Useful Links

• Paystack API Docs
• Postman Collection
• Package Demo App

Contributing

Please read CONTRIBUTING.md.

Security

If you discover any security-related issues, email [email protected] instead of opening a public issue.

License

Released under the MIT License.