PHPackages                             kendenigerian/payzephyr - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. kendenigerian/payzephyr

ActiveLibrary[Payment Processing](/categories/payments)

kendenigerian/payzephyr
=======================

A unified payment abstraction layer for Laravel supporting multiple providers (Paystack, Flutterwave, Monnify, Stripe, PayPal, Square, OPay, Mollie, NOWPayments) with automatic fallback and webhooks.

v1.8.0(4mo ago)6292MITPHPPHP ^8.2CI passing

Since Dec 6Pushed 4mo agoCompare

[ Source](https://github.com/ken-de-nigerian/payzephyr)[ Packagist](https://packagist.org/packages/kendenigerian/payzephyr)[ Docs](https://github.com/ken-de-nigerian/payzephyr)[ RSS](/packages/kendenigerian-payzephyr/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (32)Used By (0)

PayZephyr
=========

[](#payzephyr)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9858dd1a8bf7c0ed60dd2ec5d6d6d809df42a2c639fd9ae01af0ccc82de570a1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b656e64656e6967657269616e2f7061797a65706879722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kendenigerian/payzephyr)[![Total Downloads](https://camo.githubusercontent.com/1a178dd54dcdba9929034fc24f0901bd8b5ea446d3552cb28de96dab3419a005/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b656e64656e6967657269616e2f7061797a65706879722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kendenigerian/payzephyr)[![Tests](https://github.com/ken-de-nigerian/payzephyr/actions/workflows/tests.yml/badge.svg)](https://github.com/ken-de-nigerian/payzephyr/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

**PayZephyr** is a Laravel package that makes accepting payments simple. Instead of writing different code for each payment provider (Paystack, Stripe, PayPal, etc.), you write code once and PayZephyr handles the rest.

**Features**

- **One API for all providers** - Switch between Paystack, Stripe, PayPal, and more without changing your code
- **Automatic fallback** - If one provider fails, PayZephyr automatically tries another
- **Built-in security** - Webhook signature validation, replay protection, and data sanitization
- **Production ready** - Comprehensive error handling, transaction logging, and extensive testing
- **Enterprise subscriptions** - Enhanced subscription management with automatic transaction logging and lifecycle events
- **Transaction logging** - All subscription operations automatically logged to database with full audit trail
- **Idempotency support** - Prevent duplicate subscriptions with automatic UUID generation or custom keys
- **Lifecycle events** - Webhook events for subscription created, renewed, cancelled, and payment failed
- **Business validation** - Built-in validation prevents duplicate subscriptions and validates plan eligibility
- **State management** - Comprehensive subscription status enum with state machine logic and transition validation
- **Query builder** - Advanced subscription filtering with fluent interface for complex queries

See [Provider Details](docs/providers.md) for currency and channel support.

---

Installation
------------

[](#installation)

New to PayZephyr? Check out our [Getting Started Guide](docs/GETTING_STARTED.md).

### Requirements

[](#requirements)

- PHP 8.2 or higher
- Laravel 10.x, 11.x, or 12.x
- Composer

### Quick Install

[](#quick-install)

```
# 1. Install the package
composer require kendenigerian/payzephyr

# 2. Run the install command (publishes config, migrations, and optionally runs migrations)
php artisan payzephyr:install

# 3. Configure your environment variables (see below)
```

**That's it!** You're ready to start accepting payments.

**Alternative:** Manual setup:

> ```
> php artisan vendor:publish --tag=payments-config
> php artisan vendor:publish --tag=payments-migrations
> php artisan migrate
> ```

---

Configuration
-------------

[](#configuration)

Add provider credentials to `.env`:

```
PAYMENTS_DEFAULT_PROVIDER=paystack
PAYSTACK_SECRET_KEY=sk_test_xxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxx
PAYSTACK_ENABLED=true
```

See [Configuration Guide](docs/DOCUMENTATION.md#installation--configuration) for all options.

---

Quick Start
-----------

[](#quick-start)

**What happens:** Customer clicks "Pay" → Redirected to payment page → Returns to your site → You verify payment

### Initialize Payment

[](#initialize-payment)

```
use KenDeNigerian\PayZephyr\Facades\Payment;

// Basic payment (amount in major currency unit: 100.00 = ₦100.00 for NGN)
return Payment::amount(100.00)
    ->email('customer@example.com')
    ->callback(route('payment.callback')) // Where to return after payment
    ->redirect(); // Sends customer to payment page

// With more options (including idempotency for retry safety)
return Payment::amount(500.00) // ₦500.00
    ->currency('NGN')
    ->email('customer@example.com')
    ->callback(route('payment.callback'))
    ->reference('ORDER_123') // Your order ID
    ->description('Premium subscription')
    ->metadata(['order_id' => 12345]) // Custom data
    ->idempotency('unique-key-123') // Prevents duplicate charges on retries
    ->with('paystack') // Optional: force specific provider
    ->redirect();
```

### Verify Payment

[](#verify-payment)

After customer returns from payment page:

```
public function callback(Request $request)
{
    // Get payment reference from URL
    $verification = Payment::verify($request->input('reference'));

    if ($verification->isSuccessful()) {
        // Payment succeeded - update your database
        Order::where('payment_reference', $verification->reference)
            ->update(['status' => 'paid']);
        return view('payment.success');
    }

    // Payment failed
    return view('payment.failed');
}
```

---

Webhooks
--------

[](#webhooks)

**Queue workers required.** Configure webhook URLs in provider dashboards:

- Paystack: `https://yourdomain.com/payments/webhook/paystack`
- Stripe: `https://yourdomain.com/payments/webhook/stripe`
- See [Webhook Guide](docs/webhooks.md) for all providers

### Setup

[](#setup)

```
// app/Providers/EventServiceProvider.php
protected $listen = [
    'payments.webhook.paystack' => [
        \App\Listeners\HandlePaystackWebhook::class,
    ],
];

// app/Listeners/HandlePaystackWebhook.php
public function handle(array $payload): void
{
    if ($payload['event'] === 'charge.success') {
        Order::where('payment_reference', $payload['data']['reference'])
            ->update(['status' => 'paid']);
    }
}
```

See [Webhook Guide](docs/webhooks.md) for complete setup.

---

Subscriptions
-------------

[](#subscriptions)

**Currently, only PaystackDriver supports subscriptions.** Support for other providers will be added in future releases.

PayZephyr provides enterprise-grade subscription management with automatic transaction logging, idempotency support, lifecycle events, business validation, and comprehensive state management. All subscription operations are automatically logged to the database for audit and analytics.

### Quick Example

[](#quick-example)

```
use KenDeNigerian\PayZephyr\Facades\Payment;
use KenDeNigerian\PayZephyr\DataObjects\SubscriptionPlanDTO;

// Create a subscription plan (using facade)
$planDTO = new SubscriptionPlanDTO(
    name: 'Monthly Premium',
    amount: 5000.00,  // ₦5,000.00
    interval: 'monthly',
    currency: 'NGN',
);

$plan = Payment::subscription()
    ->planData($planDTO)
    ->with('paystack')  // Currently only PaystackDriver supports subscriptions
    ->createPlan();

// Create a subscription with idempotency (prevents duplicates on retries)
$subscription = payment()->subscription()
    ->customer('customer@example.com')
    ->plan($plan['plan_code'])
    ->idempotency() // Auto-generates UUID, or pass custom key
    ->with('paystack')
    ->subscribe();  // Final action method (create() is also available as an alias)

// Query subscriptions using query builder
$activeSubscriptions = Payment::subscriptions()
    ->forCustomer('customer@example.com')
    ->active()
    ->from('paystack')
    ->get();

// Subscription automatically logged to subscription_transactions table
// Access logged subscription:
use KenDeNigerian\PayZephyr\Models\SubscriptionTransaction;
$logged = SubscriptionTransaction::where('subscription_code', $subscription->subscriptionCode)->first();

// Save subscription details to your own table
DB::table('subscriptions')->insert([
    'subscription_code' => $subscription->subscriptionCode,
    'email_token' => $subscription->emailToken,  // Important for cancel/enable
    'status' => $subscription->status,
]);
```

**Key Features:**

- **Automatic transaction logging** - All subscriptions logged to database automatically with full audit trail
- **Idempotency support** - Prevent duplicate subscriptions with automatic UUID generation or custom keys
- **Lifecycle events** - Webhook events for subscription created, renewed, cancelled, and payment failed
- **Business validation** - Built-in validation prevents duplicates and validates plan eligibility
- **State management** - Comprehensive subscription status enum with state machine logic and transition validation
- **Query builder** - Advanced subscription filtering with fluent interface: `Payment::subscriptions()->forCustomer()->active()->get()`

**📖 See [Subscriptions Guide](docs/SUBSCRIPTIONS.md) for complete documentation**

**👨‍💻 Developers**: Want to add subscription support for a new driver? See the [Developer Guide](docs/SUBSCRIPTIONS.md#developer-guide-adding-subscription-support-to-a-driver).

---

Transaction Logging
-------------------

[](#transaction-logging)

All payment and subscription transactions are automatically logged:

```
use KenDeNigerian\PayZephyr\Models\PaymentTransaction;
use KenDeNigerian\PayZephyr\Models\SubscriptionTransaction;

// Payment transactions
PaymentTransaction::where('reference', 'ORDER_123')->first();
PaymentTransaction::successful()->get();
PaymentTransaction::failed()->get();

// Subscription transactions (automatically logged on create/update/cancel)
SubscriptionTransaction::where('subscription_code', 'SUB_xyz')->first();
SubscriptionTransaction::active()->get();
SubscriptionTransaction::forCustomer('user@example.com')->get();
SubscriptionTransaction::forPlan('PLN_abc123')->get();
```

---

---

Testing
-------

[](#testing)

Use sandbox credentials for testing:

```
PAYSTACK_SECRET_KEY=sk_test_xxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxx
```

See [Testing Guide](docs/DOCUMENTATION.md#testing) for examples.

---

Advanced Usage
--------------

[](#advanced-usage)

```
// Fallback providers
Payment::amount(100.00)
    ->with(['paystack', 'stripe'])
    ->redirect();

// API-only mode (no redirect)
$response = Payment::amount(100.00)->charge();
return response()->json($response);

// Direct driver access
$driver = app(PaymentManager::class)->driver('paystack');
$driver->healthCheck();
```

See [Architecture Guide](docs/architecture.md) for advanced patterns.

---

Troubleshooting
---------------

[](#troubleshooting)

**Webhooks not processing?** Ensure queue workers are running:

```
php artisan queue:work
```

**Provider not found?** Check `.env`:

```
PAYSTACK_ENABLED=true
PAYSTACK_SECRET_KEY=sk_test_xxxxx
```

**Health check endpoint:** `GET /payments/health` - Monitor provider availability

See [Troubleshooting Guide](docs/DOCUMENTATION.md#troubleshooting) for more.

---

Documentation
-------------

[](#documentation)

- **[Getting Started](docs/GETTING_STARTED.md)** - Step-by-step tutorial
- **[Complete Guide](docs/DOCUMENTATION.md)** - Full documentation
- **[Webhooks](docs/webhooks.md)** - Webhook setup
- **[Providers](docs/providers.md)** - Provider details
- **[Architecture](docs/architecture.md)** - System design

---

Contributing
------------

[](#contributing)

Contributions welcome! See [Contributing Guide](docs/CONTRIBUTING.md).

---

Changelog
---------

[](#changelog)

See [CHANGELOG.md](docs/CHANGELOG.md) for version history.

**Latest: v1.8.0** - Major subscription enhancements with enterprise-grade features

**v1.8.0 Highlights**:

- **Subscription Transaction Logging** - Automatic logging of all subscription operations to database
- **Idempotency Support** - Prevent duplicate subscriptions with automatic UUID generation or custom keys
- **Lifecycle Events** - Comprehensive webhook events (SubscriptionCreated, SubscriptionRenewed, SubscriptionCancelled, SubscriptionPaymentFailed)
- **Business Validation** - Built-in validation prevents duplicate subscriptions and validates plan eligibility
- **State Management** - Subscription status enum with state machine logic and transition validation
- **Query Builder** - Advanced subscription filtering with fluent interface for complex queries
- **Lifecycle Hooks** - Optional interface for custom drivers to hook into subscription lifecycle events

See [Changelog](docs/CHANGELOG.md) for complete release notes.

---

License
-------

[](#license)

The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.

---

Support
-------

[](#support)

If PayZephyr helped your project:

- Star the repository on GitHub
- Share it with others
- Contribute code or documentation

---

**Built for the Laravel community by [Ken De Nigerian](https://github.com/ken-de-nigerian)**

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance76

Regular maintenance activity

Popularity15

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

31

Last Release

133d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f8903c5a95211f5879abc9431a6774ec6f3cd7a9d5ac2e947f7456b26f5eaae0?d=identicon)[ken-de-nigerian](/maintainers/ken-de-nigerian)

---

Top Contributors

[![ken-de-nigerian](https://avatars.githubusercontent.com/u/61892700?v=4)](https://github.com/ken-de-nigerian "ken-de-nigerian (123 commits)")

---

Tags

fintechflutterwavelaravelpaymentpaystacklaravelstripelaravel-packagepaymentpaymentspaypalmolliewebhookpayment gatewayfintechsquarepaystackflutterwavenowpaymentsmonnifyopay

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/kendenigerian-payzephyr/health.svg)

```
[![Health](https://phpackages.com/badges/kendenigerian-payzephyr/health.svg)](https://phpackages.com/packages/kendenigerian-payzephyr)
```

###  Alternatives

[musahmusah/laravel-multipayment-gateways

A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless

852.2k1](/packages/musahmusah-laravel-multipayment-gateways)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)