Download the PHP package gusmanwidodo/laravel-billing without Composer

Laravel Billing

Generic, multi-purpose billing & invoicing for Laravel. Attach invoices to any model (user, organization, tenant, project — anything), store money safely as integer minor units (no floating-point errors), build invoices with line items, tax, and discounts, and record payments. Payment-gateway agnostic by design.

Why

• Multi-purpose: invoices are polymorphic — bill a User, an Organization, a Tenant, a Project, or nothing at all.
• Money done right: all amounts are integer minor units (cents) plus a currency code, so 0.1 + 0.2 is exactly 0.30 — never a float rounding bug.
• Computed totals: subtotal, tax, and total are derived from line items and persisted; recompute any time.
• Gateway-agnostic: the package records payments; it does not talk to Stripe, Midtrans, etc. Bring your own gateway and call recordPayment().

Requirements

• PHP ^8.3
• Laravel 12

Installation

Quick start

All prices are integer minor units in the invoice currency (e.g. 5000 = $50.00). Use the Money helper to convert:

Billing any model

Add the HasInvoices trait to whatever you bill:

The invoice's billable is a polymorphic relation, so the same package bills users, orgs, tenants, or anything else — no per-type tables.

Totals

For each line item:

For the invoice:

All integer arithmetic. Call Billing::recompute($invoice) after changing items.

Payments

amount_paid is always the sum of recorded payments; status is derived (partially_paid / paid). Payments must match the invoice currency and be positive.

Void

Status

Status is free-form — your app owns the workflow. Convenience constants are provided, and the package sets partially_paid / paid automatically as payments come in (and void when you void):

Money & currencies

• Amounts are stored as bigInteger minor units; never floats.
• Money::fromMajor(10.50, 'USD') → 1050. Pass decimals: for zero-decimal currencies (e.g. JPY): Money::fromMajor(1000, 'JPY', decimals: 0).
• Money supports add, subtract, multiply, percentage, format, and refuses cross-currency arithmetic.

Config

config/billing.php:

Testing

Payment providers (v0.2)

Billing is gateway-agnostic: it defines a PaymentProvider contract and a provider registry. A built-in manual provider handles offline (cash / transfer) payments; real gateways (Stripe, Midtrans, ...) implement the same interface and register themselves — typically from their own package.

The flow

For manual payments there is no webhook — confirm in-app when you see the money:

Writing a provider

Implement Gusmanwidodo\Billing\Payments\PaymentProvider and register it:

Register it from your service provider:

Set the default provider via config('billing.default_provider') or BILLING_PROVIDER.

Security

Webhook signature verification is part of the contract — handleWebhook() refuses to act on a webhook whose verifyWebhook() returns false, so a forged or tampered payload never records a payment. Settlement is idempotent: replaying the same success event records exactly one payment.

Subscriptions (v0.3)

Recurring billing via plans (price + interval) and subscriptions (a billable subscribed to a plan). The package computes each cycle; your app's scheduler triggers invoice generation.

Generating cycle invoices

The package does not run its own scheduler — you call generateDueInvoices() from yours (e.g. in routes/console.php or a scheduled command):

Pair it with a payment provider to charge each generated invoice automatically (e.g. in an after step, call Billing::charge($invoice, provider: 'stripe')).

Lifecycle

Statuses: trialing, active, paused, canceled, expired. A subscription canceled at period end stays active and onGracePeriod() until ends_at.

Intervals

interval is day / week / month / year, times interval_count. Month and year advancement is overflow-safe (Jan 31 + 1 month → Feb 28). Proration is out of scope in v0.3.

Invoice PDF (v0.4)

Render invoices to HTML or PDF. HTML rendering is always available; PDF uses dompdf, which is an optional dependency — install it only if you need PDF:

If dompdf is not installed, toPdf() throws a clear error telling you to install it. Check availability with InvoicePdf::available().

Customizing the template

Publish the Blade template and edit it:

Set a vendor name/address and paper size in config/billing.php:

Official provider packages

• gusmanwidodo/laravel-billing-midtrans — Midtrans (Snap) provider: charge, SHA512 webhook verification, refund.
• gusmanwidodo/laravel-billing-stripe — Stripe provider: Checkout charge, Stripe-Signature verification (+replay), refund.

Metered / usage-based billing (v0.5)

A plan can be metered (type: 'metered') — its amount is the price per unit, and each cycle bills the aggregated usage recorded that period.

Zero-usage cycles produce a zero-total invoice. Usage is aggregated only over unbilled records, so each cycle bills exactly what was used since the last.

Proration — mid-cycle plan change (v0.5)

Swap a subscription to a new plan mid-cycle with day-based proration:

The proration is day-based over the current period: for R remaining days out of T total, the charge is round(newAmount * R/T) and the credit is round(oldAmount * R/T). The subscription then continues on the new plan (its next full charge is at the existing period end). You can swap between licensed and metered plans.

Roadmap

• Tiered / volume pricing.

License

MIT © Gusman Widodo. See LICENSE.