PHPackages                             felixmuhoro/laravel-mpesa-invoices - 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. felixmuhoro/laravel-mpesa-invoices

ActiveLibrary[Payment Processing](/categories/payments)

felixmuhoro/laravel-mpesa-invoices
==================================

Auto-generates professional PDF invoices for M-Pesa payments and stores/emails them

v1.0.0(1mo ago)00MITPHPPHP ^8.1

Since Jun 4Pushed 1mo agoCompare

[ Source](https://github.com/felixmuhoro/laravel-mpesa-invoices)[ Packagist](https://packagist.org/packages/felixmuhoro/laravel-mpesa-invoices)[ Docs](https://github.com/felixmuhoro/laravel-mpesa-invoices)[ RSS](/packages/felixmuhoro-laravel-mpesa-invoices/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (2)Versions (2)Used By (0)

laravel-mpesa-invoices
======================

[](#laravel-mpesa-invoices)

Auto-generates professional PDF invoices for M-Pesa payments and stores/emails them.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10 / 11 / 12 / 13
- `felixmuhoro/laravel-mpesa: ^1.2`
- `barryvdh/laravel-dompdf: ^2.0`

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

[](#installation)

```
composer require felixmuhoro/laravel-mpesa-invoices
```

Publish the config file:

```
php artisan vendor:publish --tag=mpesa-invoices-config
```

Run migrations:

```
php artisan migrate
```

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

[](#configuration)

Set the following in your `.env`:

```
INVOICE_BUSINESS_NAME="Acme Kenya Ltd"
INVOICE_BUSINESS_ADDRESS="P.O. Box 12345-00100, Nairobi, Kenya"
INVOICE_BUSINESS_PHONE="+254 700 123 456"
INVOICE_BUSINESS_EMAIL="billing@acme.co.ke"
INVOICE_BUSINESS_WEBSITE="https://acme.co.ke"
INVOICE_KRA_PIN="P051234567X"
INVOICE_VAT_NUMBER="V000123456Z"   # optional

INVOICE_TAX_RATE=16                # VAT percentage (Kenyan standard)
INVOICE_TAX_ENABLED=true
INVOICE_CURRENCY=KES

INVOICE_AUTO_EMAIL=false           # auto-email on PaymentSuccessful event
INVOICE_STORAGE_DISK=local
INVOICE_STORAGE_PATH=invoices
```

Usage
-----

[](#usage)

### Basic — from a payment array

[](#basic--from-a-payment-array)

```
use FelixMuhoro\MpesaInvoices\Invoice;

$invoice = Invoice::fromPayment([
    'mpesa_receipt'  => 'QHX1234567',
    'amount'         => 1500.00,
    'phone'          => '0712345678',
    'customer_name'  => 'Jane Doe',
    'customer_email' => 'jane@example.com',
    'description'    => 'Premium Subscription',
]);

// Download as PDF response
return $invoice->download();

// Get HTML string
$html = $invoice->toHtml();

// Store PDF to disk + create DB record
$record = $invoice->store();

// Send email (with PDF attachment)
$invoice->send('jane@example.com');
```

### Via Facade

[](#via-facade)

```
use FelixMuhoro\MpesaInvoices\Facades\MpesaInvoice;

$invoice = MpesaInvoice::createFromPayment($paymentArray, store: true);
$record  = MpesaInvoice::findByReceipt('QHX1234567');
$record  = MpesaInvoice::findByNumber('INV-202401-0001');
```

### With multiple line items

[](#with-multiple-line-items)

```
$invoice = Invoice::fromPayment([
    'mpesa_receipt' => 'ZZZ9876543',
    'phone'         => '0722222222',
    'customer_name' => 'John Kamau',
    'items' => [
        ['description' => 'Product A', 'quantity' => 2, 'unit_price' => 500, 'amount' => 1000],
        ['description' => 'Delivery',  'quantity' => 1, 'unit_price' => 200, 'amount' =>  200],
    ],
]);
```

### Auto-generate on payment events

[](#auto-generate-on-payment-events)

Register the listener in `EventServiceProvider`:

```
use FelixMuhoro\MpesaInvoices\Listeners\GenerateInvoiceOnPayment;

protected $listen = [
    \YourApp\Events\PaymentSuccessful::class => [
        GenerateInvoiceOnPayment::class,
    ],
];
```

Your event must expose either:

- a `$payment` property (array/object), or
- a `toPaymentArray()` method, or
- be itself castable to the expected keys.

### HasInvoices trait

[](#hasinvoices-trait)

Add the trait to any Eloquent model (e.g. `Order`, `User`):

```
use FelixMuhoro\MpesaInvoices\Concerns\HasInvoices;

class Order extends Model
{
    use HasInvoices;
}

// Usage:
$order->invoices();       // MorphMany
$order->latestInvoice();  // ?InvoiceRecord
```

When storing, link to the model:

```
$invoice->store($order);
```

### HTTP Routes

[](#http-routes)

Two routes are registered automatically (protected by `auth` middleware):

MethodURLActionGET`/invoices/{invoiceNumber}/download`Stream PDF downloadPOST`/invoices/{invoiceNumber}/email`Re-send by emailPOST body for email: `{ "email": "override@example.com" }` (optional).

Invoice Number Format
---------------------

[](#invoice-number-format)

```
INV-202401-0001
^^^  ^^^^^^  ^^^^
|    |        |-- 4-digit sequence (resets per month)
|    |--- YYYYMM
|--- prefix (configurable)

```

KRA / VAT Compliance
--------------------

[](#kra--vat-compliance)

The PDF template includes:

- Business KRA PIN
- VAT Registration Number (when set)
- Tax line item breakdown (VAT 16%)
- Official KRA-compliant disclaimer

Publishing Views
----------------

[](#publishing-views)

To customise the invoice template:

```
php artisan vendor:publish --tag=mpesa-invoices-views
```

The Blade template will be copied to `resources/views/vendor/mpesa-invoices/`.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT — Felix Muhoro

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

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

Unknown

Total

1

Last Release

50d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f4e43995a8ec026a33d25263c30f437674d6d8481092cb3acd64e96e4ba3f4e4?d=identicon)[felixmuhoro](/maintainers/felixmuhoro)

---

Tags

laravelmpesakenyasafaricom

### Embed Badge

![Health badge](/badges/felixmuhoro-laravel-mpesa-invoices/health.svg)

```
[![Health](https://phpackages.com/badges/felixmuhoro-laravel-mpesa-invoices/health.svg)](https://phpackages.com/packages/felixmuhoro-laravel-mpesa-invoices)
```

PHPackages © 2026

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