PayZephyr

What is PayZephyr?

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('customer@example.com')->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: Flutterwave, Mollie, Monnify, OPay, Paddle, PayPal, Paystack, Razorpay, Square, and Stripe.

When a payment goes wrong, you get the whole story

Every payment library can tell you a charge succeeded. PayZephyr can tell you what happened on the way there - including the parts that left no other trace.

Say a customer's payment came through, eventually. Your transactions table says provider: stripe, status: success. True, and complete, and it tells you nothing about the fact that Paystack was tried first, failed its health check, and was skipped - because that attempt never existed anywhere durable. Turn tracing on and it does:

14:22:07.104 • payment.initiated          chain: paystack, stripe
14:22:07.106 • provider.skipped           paystack - failed_health_check
14:22:07.241 → provider.request.sent      stripe   POST /v1/checkout/sessions
14:22:08.402 ← provider.response.received stripe   HTTP 200   1161ms
14:22:08.404 • payment.completed          stripe

One append-only row per step, keyed by the reference you already have, redacted before it is written, and readable from the command line:

php artisan payzephyr:trace PZ_1758000000_ab12cd

This is the part that is genuinely hard to add afterwards. Normalizing providers behind one API is table stakes - several packages do it. Reconstructing why a payment took the path it took, across a fallback chain, with per-attempt correlation IDs and millisecond gaps, is the thing you cannot bolt on once the decisions have already been made and forgotten.

It is off by default, costs nothing when off, and can be turned off again on the next request with no deploy. It covers charges, verifications, refunds, subscriptions and inbound webhooks; the few edges that remain are listed in Tracing.

Is this for you?

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.

How it fits together

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.

Pick a provider, get everything

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 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.

Quick Start

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:install

payzephyr: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=true

3. Start a payment:

use KenDeNigerian\PayZephyr\Facades\Payment;

Route::get('/checkout', function () {
    return Payment::amount(500.00)
        ->email('customer@example.com')
        ->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.

Documentation

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

1. Installation: every way to install PayZephyr, explained
2. Configuration: what every config option does and when to change it
3. Your First Payment: a complete, working example built step by step
4. Understanding Payment Flow: what actually happens between "customer clicks pay" and "money in your account"
5. Payment Verification: confirming a payment actually succeeded, correctly

Core features

6. Subscriptions: recurring billing, supported on most bundled providers
7. Refunds: full and partial refunds, supported on every bundled provider
8. Tracing: the step-by-step record of why a payment took the path it took
9. Webhooks: why they exist and how to handle them
10. Events: every event PayZephyr fires and how to listen for it
11. Testing: testing code that charges money, without charging money
12. Error Handling: what can go wrong and how PayZephyr tells you
13. Security: webhook verification, replay protection, and what PayZephyr does not protect you from
14. Queues: why a queue worker is required, not optional

Going further

15. Multiple Providers: per-provider setup, currencies, and feature support
16. Custom Drivers: adding a provider PayZephyr doesn't support yet
17. Extending a Driver: add refunds and subscriptions to a custom driver
18. Advanced Usage: direct driver access, health checks, idempotency patterns

Shipping it

19. Production Checklist: what to double-check before going live
20. Deployment: migrations, environment variables, monitoring
21. Upgrade Guide: moving between major versions

When things go wrong

22. Troubleshooting: common problems, their causes, and their fixes
23. FAQ

Reference

24. API Reference: every public method, documented
25. Architecture: how the package is put together internally
26. Contributing

The full table of contents, if you'd rather browse than read linearly, is in docs/INDEX.md.

Changelog

The latest release is the one on the Packagist badge above; CHANGELOG.md has the full history. Every major version's breaking changes, and what to do about each, are in the Upgrade Guide.

License

MIT. See LICENSE.

Support

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