If you've ever had to accept payments in a Laravel app, you've probably run into this problem: every payment provider (Stripe, PayPal, Paystack, and the rest) has its own SDK, its own way of creating a charge, its own webhook format, and its own quirks. Wire your app up to one provider, and you're locked into rewriting a chunk of it if you ever need to add a second, or switch.
PayZephyr solves that by giving you one API that works the same way no matter which provider is behind it. You write:
Payment::amount(100.00)->email('[email protected]')->redirect();and PayZephyr handles the fact that, underneath, this might be talking to Paystack today and Stripe tomorrow. You don't write provider-specific code, and you don't have to think about it again until you actually need to: for example, if a provider goes down and you want to fail over to another one automatically, which PayZephyr also does for you.
Currently supported providers: Paystack, Stripe, PayPal, Flutterwave, Square, Monnify, OPay, and Mollie.
PayZephyr is a good fit if:
- You're building a Laravel app that needs to accept one-time payments, recurring subscriptions, or both.
- You want to support more than one payment provider (or might in the future) without duplicating your checkout logic.
- You want webhook signature verification, replay-attack protection, and transaction logging handled for you instead of hand-rolled per provider.
It's not trying to be a full accounting or invoicing system; it's a payment abstraction layer. Refunds are supported (see Refunds), but full accounting/ledger reconciliation is out of scope.
flowchart LR
A[Your Controller] -->|Payment::amount...->redirect| B[PayZephyr]
B --> C{Which provider?}
C -->|paystack| D[Paystack API]
C -->|stripe| E[Stripe API]
C -->|"...or any other provider"| F[...]
D & E & F --> G["Customer pays on<br/>the provider's page"]
G --> H["Provider redirects back<br/>to your callback URL"]
G -.->|webhook, in parallel| I[Your queue worker]
H --> J[Payment::verify]
I --> K[WebhookReceived event]
Two things happen when a customer pays: they get redirected back to your app (so you can show a "thank you" page), and the provider sends your app a webhook in the background (so your database stays correct even if the customer closes their browser before the redirect completes). PayZephyr handles both paths: the Understanding Payment Flow chapter walks through exactly what happens at each step.
The point of PayZephyr is that choosing a provider is the only decision you make. Everything else is already built.
Switch from Paystack to Stripe and you change one line in .env. Your checkout code does not
change. Neither does your webhook handling, your retry safety, or your database schema.
The same is true for a provider PayZephyr does not ship with. Write a driver, and it inherits all of this without you implementing any of it:
| You get, automatically | Meaning |
|---|---|
| Automatic fallback | Provider down? The next one takes over. |
| Double-charge protection | The safety rules that stop a customer paying twice apply to your driver too. |
| Retry safety | A request that timed out is never quietly retried somewhere else. |
| Webhook verification | Signature checking and replay protection. |
| Transaction logging | Every payment recorded, in the same tables. |
| Events | The same events fire, so your listeners keep working. |
| Health checks | Cached, so a slow provider does not slow every charge. |
| Secret-safe logging | Keys and tokens stripped before anything is written. |
You write what is genuinely specific to your provider: how to build its request, and how to read its response. That is the part nobody else can write for you.
Adding refunds or subscriptions later is opt-in, one interface at a time. A provider that cannot do refunds is not a broken driver, and PayZephyr says so clearly rather than failing strangely.
See Custom Drivers to build one, then Extending a Driver to add refunds and subscriptions.
This gets you from zero to a working payment in about five minutes. For the full walkthrough with explanations of why each step matters, see Your First Payment.
1. Install the package and run the setup command:
composer require kendenigerian/payzephyr
php artisan payzephyr:installpayzephyr:install copies PayZephyr's configuration file into your app (so you can edit it), copies the core database migrations it always needs (for transaction logging), asks whether you also want Subscriptions and/or Refunds, and offers to run the migrations for you. See Installation for exactly which tables are core vs. optional, and how to select features non-interactively with --all/--features=. A matching php artisan payzephyr:uninstall removes what PayZephyr installed - see Uninstalling PayZephyr.
2. Add your provider's credentials to .env. Paystack is enabled by default. Grab your test keys from your Paystack dashboard:
PAYSTACK_SECRET_KEY=sk_test_xxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxx
PAYSTACK_ENABLED=true3. Start a payment:
use KenDeNigerian\PayZephyr\Facades\Payment;
Route::get('/checkout', function () {
return Payment::amount(500.00)
->email('[email protected]')
->callback(route('payment.callback'))
->redirect();
});4. Verify it when the customer comes back:
use KenDeNigerian\PayZephyr\Facades\Payment;
Route::get('/payment/callback', function (\Illuminate\Http\Request $request) {
$verification = Payment::verify($request->query('reference'));
if ($verification->isSuccessful()) {
return 'Payment succeeded! Reference: '.$verification->reference;
}
return 'Payment did not go through.';
})->name('payment.callback');That's a working payment flow. It's also incomplete on its own: webhooks are what make it reliable (a customer closing their browser tab shouldn't mean you never find out they paid). Read on.
The chapters below are written to be read roughly in order if you're new to PayZephyr; each one builds on the last. If you already know what you're looking for, jump straight there.
Getting started
- Installation: every way to install PayZephyr, explained
- Configuration: what every config option does and when to change it
- Your First Payment: a complete, working example built step by step
- Understanding Payment Flow: what actually happens between "customer clicks pay" and "money in your account"
- Payment Verification: confirming a payment actually succeeded, correctly
Core features
- Subscriptions: recurring billing, supported on most bundled providers
- Refunds: full and partial refunds, supported on every bundled provider
- Webhooks: why they exist and how to handle them
- Events: every event PayZephyr fires and how to listen for it
- Testing: testing code that charges money, without charging money
- Error Handling: what can go wrong and how PayZephyr tells you
- Security: webhook verification, replay protection, and what PayZephyr does not protect you from
- Queues: why a queue worker is required, not optional
Going further
- Multiple Providers: per-provider setup, currencies, and feature support
- Custom Drivers: adding a provider PayZephyr doesn't support yet
- Extending a Driver: add refunds and subscriptions to a custom driver
- Advanced Usage: direct driver access, health checks, idempotency patterns
Shipping it
- Production Checklist: what to double-check before going live
- Deployment: migrations, environment variables, monitoring
- Upgrade Guide: moving between major versions
When things go wrong
- Troubleshooting: common problems, their causes, and their fixes
- FAQ
Reference
- API Reference: every public method, documented
- Architecture: how the package is put together internally
- Contributing
The full table of contents, if you'd rather browse than read linearly, is in docs/INDEX.md.
The current release is v3.0.0. See CHANGELOG.md for the full version history.
v3.0.0 contains one breaking change. If you bind your own implementation of
WebhookEventRepositoryInterface, it now needs a forget() method. If you don't (and most
apps don't), upgrading needs no code changes from you. The Upgrade Guide
walks through it.
MIT. See LICENSE.
If PayZephyr is useful to you, starring the repository helps other people find it. Contributions (code, documentation, bug reports) are welcome; see Contributing.
Built for the Laravel community by Ken De Nigerian