Download the PHP package emeroid/laravel-billing-core without Composer

Laravel Billing Core

Laravel Billing Core is a robust, driver-based, multi-gateway billing package for Laravel. It provides a simple, fluent API to manage one-time payments, subscriptions, plan swapping, and dunning logic for your SaaS application.

Stop rebuilding billing logic for every project — this package is the plug-and-play foundation you need.

🚀 Features

• Driver-Based: Switch gateways just by changing your .env.
• Multi-Gateway: Out-of-the-box support for Paystack and PayPal.
• Subscription Management: A complete subscription lifecycle (subscribe, cancel, swapPlan).
• Grace Periods: Automatically handles “cancel on end of billing period”.
• Plan Swapping: Fluent API to upgrade or downgrade users.
• Dunning: Listens for invoice.payment_failed webhooks to set past_due status.
• Event-Based: Fires events like SubscriptionStarted, SubscriptionCancelled, etc.
• Billable Trait: A powerful interface you can add to your User model.

🧩 Installation

1. Configuration

Publish the Config File

This creates config/billing.php.

Publish the Migrations

This adds the plans, subscriptions, and transactions tables.

Run the Migrations

Update Your .env File

Add the Billable Trait

💳 Usage

2. Creating Plans

Before creating subscriptions, define your plans in the plans table — typically via a seeder:

3. One-Time Payments

4. Subscriptions

5. Handling Callbacks

After payment, users are redirected to your site. The built-in CallbackController handles:

• Verifying the transaction via Billing::verifyTransaction(...)
• Creating the Subscription record
• Firing events (TransactionSuccessful, SubscriptionStarted)
• Redirecting to success/failure URLs (defined in config/billing.php)

All of this happens automatically.

6. Handling Webhooks

Add these URLs to your gateway dashboards:

The package automatically handles:

• charge.success → verifies payments
• subscription.create → creates subscriptions
• subscription.disable → triggers SubscriptionCancelled

• Dunning events:

  • invoice.payment_failed (Paystack)
  • BILLING.SUBSCRIPTION.PAYMENT.FAILED (PayPal)

7. The Billable Trait API

8. Events

Listen for billing events in your EventServiceProvider:

Emeroid Billing Package Customization

This document explains how to configure the Emeroid Billing package to correctly identify the billable entity when the customer’s payment gateway email does not directly match the billable model’s email field.

In many SaaS applications, a subscription belongs to a Team or Organization, even though the User making the payment uses their personal email.

1. Custom Billable Lookup Strategy

By default, the AbstractDriver attempts to locate the Billable Model (e.g., Team) by matching the email directly on that model.

If your Billable Model does not store the customer’s email, you must implement a custom lookup strategy.

Implementation: The BillableLookup Class

Create a lookup class that identifies the Billable Model (Team) through an associated User.

This method must have the exact signature:

Example: app/Lookups/BillableLookup.php

2. Configuration

Register the custom lookup method inside config/billing.php under your gateway settings:

3. How the Driver Uses the Strategy

The Emeroid\Billing\Drivers\AbstractDriver is designed to check for your custom lookup first:

Conclusion

This customization ensures reliable billing behavior even when your architecture involves multi-layer ownership structures (e.g., users owning teams). The billing package will correctly identify the billable entity through your defined strategy, preventing mismatches and failed invoice processing.

🧪 Testing

🤝 Contributing

Please see CONTRIBUTING.md for details.

🔒 Security

If you discover any security-related issues, please email 📧 [email protected] instead of using the issue tracker.

📄 License

Licensed under the MIT License (MIT). See the License File for more information.

❤️ Sponsorship

This project is free and open-source. If it helps you build your business, please consider supporting its development.

Sponsor @emeroid on GitHub.