Download the PHP package aqsaahsan301/laravel-payments without Composer

Gateway-agnostic payment and subscription billing for Laravel.

Installation

You can install the package via Composer:

You may publish all of the package's resources at once:

Or, you may publish each resource individually:

Publishing the Configuration File

Why gateway-agnostic

Laravel Cashier is excellent, but it's Stripe-only by design — it owns a subscriptions table, a Billable Eloquent trait, and a whole persistence layer built around Stripe's model. For clients who need a local gateway instead (Billplz, ToyyibPay, Curlec/Razorpay — common where FPX, GrabPay, or TnG matter), that coupling means starting over.

This package takes a different shape:

• A base contract shaped around what every gateway can do. PaymentGateway has just charge() (a one-time payment) and handleWebhook(). It's deliberately not shaped around Stripe's subscription model — plenty of real gateways (FPX, Billplz, ToyyibPay, DuitNow QR) are one-time/invoice-only with no subscription concept at all, and a contract that assumed subscriptions would make them impossible to implement honestly.
• Subscriptions are a separate, optional contract. Drivers whose gateway actually supports recurring billing (Stripe, presumably Curlec/Razorpay) additionally implement SupportsSubscriptions — checkout(), cancelSubscription(), currentPlan(). Host app code checks $gateway instanceof SupportsSubscriptions (or resolves SupportsSubscriptions from the container directly) before offering recurring-billing UI, rather than assuming every driver has it.
• PaymentManager resolves the configured driver the same way Laravel's own MailManager/QueueManager do. Set PAYMENT_GATEWAY=stripe in .env; swapping to a different driver later is a config change plus a new driver class, not a rewrite.
• No database, no Eloquent models, no opinion on your schema. The package is completely stateless. charge()/checkout() take and return plain identifiers (strings) that you persist however you like. Inbound webhooks come back out as this package's own Laravel events — PaymentSucceeded, PaymentFailed, SubscriptionCancelled, SubscriptionUpdated — carrying plain data, not gateway SDK objects. You listen for those and update your own tables. This is what makes the package reusable across projects with completely different schemas (a User is billable in one app, an Organization in another — the package doesn't care).

Design principle: Interface Segregation (SOLID)

The PaymentGateway / SupportsSubscriptions split (shipped in v1.1.0) is a direct application of the Interface Segregation Principle — "no client should be forced to depend on methods it does not use." Before the split, PaymentGateway carried checkout(), cancelSubscription(), and currentPlan() as required methods, which meant a one-time/invoice-only gateway (FPX, Billplz, ToyyibPay) had no honest way to implement it — it would have to either throw NotSupportedException from three methods or fake a subscription concept it doesn't have. Both are ISP violations: the interface was shaped around one client's needs (Stripe) and imposed on every implementer.

Splitting the fat interface into a lean base contract (charge(), handleWebhook() — what every gateway can do) plus a segregated, opt-in contract (SupportsSubscriptions — what only some gateways can do) means:

• A driver only implements what its gateway actually supports. No dead methods, no throw stubs.
• Consumers depend on the narrowest interface that satisfies them — code that only ever charges type-hints PaymentGateway; code that needs recurring billing type-hints SupportsSubscriptions and gets a clear container-resolution error if the active driver doesn't implement it, instead of a runtime "method does not exist" surprise.
• Adding a gateway with a different capability shape (say, one that supports refunds but not subscriptions) is a new optional interface, not a widening of the base contract that breaks every other driver.

Configuration

Map your app's plan slugs to each gateway's own price/plan ids in config/laravel-payments.php:

The package registers its webhook route automatically at laravel-payments/webhook (or wherever webhook_path points). Exclude it from CSRF verification in your host app's bootstrap/app.php — the gateway calls it directly and can't supply a token:

Then point your gateway's dashboard (Stripe's webhook settings, for example) at https://your-app.test/laravel-payments/webhook, and copy the signing secret it gives you into STRIPE_WEBHOOK_SECRET.

Usage

A one-time payment (every gateway supports this)

Starting a subscription checkout (only for drivers that support it)

Type-hinting SupportsSubscriptions (rather than PaymentGateway) means the container throws immediately with a clear message if PAYMENT_GATEWAY is ever pointed at a driver that doesn't support subscriptions — instead of failing later with a "method does not exist" error. If your app needs to conditionally show recurring-billing UI only when it's available, resolve PaymentGateway and check instanceof SupportsSubscriptions instead of hard-depending on it.

Both charge() and checkout() return a URL to redirect the browser to — for hosted-checkout gateways like Stripe, that has to be a real top-level navigation (redirect()->away(...) in a controller, or window.location.href = ... from an SPA/Inertia frontend), not an XHR-driven route visit, since the response goes off-site.

Reacting to webhook events

Available events: PaymentSucceeded, PaymentFailed, SubscriptionCancelled, SubscriptionUpdated. Each carries plain scalars (providerCustomerId, providerSubscriptionId, amounts, currency, status) plus a raw array with the full webhook payload for anything not modeled explicitly.

Checking the current plan / cancelling

Adding a new driver

Every driver is a class implementing Aqsaahsan301\LaravelPayments\Contracts\PaymentGateway (and SupportsSubscriptions too, only if the gateway genuinely has recurring billing) — StripeDriver (src/Drivers/StripeDriver.php) is the reference implementation to copy the shape of. To add, say, a Billplz driver (one-time/invoice-only, no subscriptions):

1. Write the driver. src/Drivers/BillplzDriver.php implements PaymentGateway. It's the only class allowed to import anything from Billplz's SDK/API client — everything else in the package (and in host apps) depends on the contract, never on your driver directly. Implement charge() and handleWebhook(); skip SupportsSubscriptions entirely if the gateway has no subscription concept — that's the whole point of the split.
2. Translate provider events into this package's own events. In your handleWebhook(), map Billplz's webhook payload fields onto PaymentSucceeded/PaymentFailed (and SubscriptionCancelled/SubscriptionUpdated too, if you implemented SupportsSubscriptions) and dispatch those — don't invent new event classes per driver, or host app listeners have to know which gateway is active, defeating the point.
3. Register it. Either add a createBillplzDriver() method to PaymentManager (the built-in, Laravel Manager-style way — see createStripeDriver()), or call $manager->extendDriver('billplz', BillplzDriver::class) from your own service provider if you're shipping the driver as a separate package.
4. Test it the same way StripeDriverTest/StripeWebhookEventsTest do: install a fake HTTP client for your provider's SDK (or bind a mock client in the container) so tests never hit the network, then assert on charge()'s returned ChargeResult, on which events handleWebhook() dispatches for which payloads, and that an invalid signature is rejected.
5. Nothing in PaymentGateway, SupportsSubscriptions, PaymentManager, the routes file, the events, or any host app code should need to change. If it does, that's a sign the new driver needs something the contract doesn't offer yet — widen the contract, not a driver-specific escape hatch.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Payments! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Aqsa Ahsan
• All Contributors

License

Laravel Payments is open-sourced software licensed under the MIT license.