README

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: Paystack, Stripe, PayPal, Flutterwave, Square, Monnify, OPay, and Mollie.

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. If you need refund processing today, that's not built in yet (see the FAQ).

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 of the 8"| F[...]
    D & E & F --> G[Customer pays on\nthe provider's page]
    G --> H[Provider redirects back\nto 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.

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 database migrations it needs (for transaction logging), and offers to run them for you. See Installation if you'd rather do each step by hand.

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

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 6 of the 8 providers
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
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.

Changelog

See CHANGELOG.md for version history. v2.0.0 contains breaking changes: read the upgrade notes before updating a production app.

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

kendenigerian / payzephyr

Maintainers

Package info

Statistics

Security