SDK

Laravel Package

Seamless M-Pesa integration for Laravel applications with built-in STK Push support.

Installation

bash 
composer require paynexus/laravel-paynexus

Configuration

Add your PayNexus credentials to .env:

bash
PAYNEXUS_SECRET_KEY=sk_your_secret_key_here
PAYNEXUS_PUBLIC_KEY=pk_your_public_key_here
PAYNEXUS_BASE_URL=https://paynexus.co.ke
PAYNEXUS_WEBHOOK_SECRET=whsec_your_webhook_secret

Usage

php 
use PayNexus\Facades\PayNexus;

// Initiate payment
$result = PayNexus::initiatePayment([
    'amount' => 100,
    'phone' => '254712345678',
    'description' => 'Order #12345'
]);

if ($result['success']) {
    $checkoutRequestId = $result['data']['checkout_request_id'];
    // Redirect to status page or return response
}

// Get payment status
$status = PayNexus::getPaymentByCheckoutId($checkoutRequestId);

Publish & Migrate

Publish the config file and migrations:

bash 
php artisan vendor:publish --tag=paynexus-config
php artisan vendor:publish --tag=paynexus-migrations
php artisan migrate

Webhook Setup

Register the webhook URL in your PayNexus dashboard:

bash
https://yourapp.com/paynexus/webhook

The plugin automatically handles webhook events. Listen for events in your EventServiceProvider:

php 
use PayNexus\Events\PaymentCompleted;
use PayNexus\Events\PaymentFailed;

protected $listen = [
    PaymentCompleted::class => [
        \App\Listeners\HandlePaymentSuccess::class,
    ],
    PaymentFailed::class => [
        \App\Listeners\HandlePaymentFailure::class,
    ],
];

Key Features

  • Facade-based API - Simple, expressive syntax with PayNexus::method()
  • M-Pesa STK Push - Trigger mobile payments instantly
  • Webhook Handling - Automatic signature verification and event dispatching
  • Local Records - Automatic database sync with polymorphic relations
  • Invoice Management - Create, send, and track invoices
  • Receipt Management - Generate and resend receipts
  • Checkout Sessions - Hosted payment pages
  • Queue Support - Optional queued webhook processing

Available Methods

The PayNexus facade provides access to all API methods:

php 
// Payments
PayNexus::initiatePayment([...])
PayNexus::getPaymentByReference('PNX123')
PayNexus::getPaymentById(42)
PayNexus::getPaymentByCheckoutId('ws_CO_...')
PayNexus::listPayments(['status' => 'completed'])

// Invoices
PayNexus::createInvoice([...])
PayNexus::getInvoice(123)
PayNexus::listInvoices(['status' => 'pending'])
PayNexus::updateInvoice(123, [...])
PayNexus::deleteInvoice(123)
PayNexus::sendInvoice(123)

// Receipts
PayNexus::getReceipt(123)
PayNexus::listReceipts(['payment_id' => 456])
PayNexus::resendReceipt(123)

// Checkout Sessions
PayNexus::createCheckoutSession([...])

// Merchant
PayNexus::getMerchant()
PayNexus::getBusinesses()
PayNexus::getPaymentAccounts()

Local Models

Every payment, invoice, receipt, and checkout session is automatically synced to your database:

php 
use PayNexus\Models\PaynexusPayment;
use PayNexus\Models\PaynexusInvoice;
use PayNexus\Models\PaynexusReceipt;
use PayNexus\Models\PaynexusCheckoutSession;

// Find payment
$payment = PaynexusPayment::where('reference', 'PNX123')->first();

// Check status
$payment->isPending();
$payment->isCompleted();
$payment->isFailed();

// Link to your models (polymorphic)
$payment->update([
    'payable_type' => Order::class,
    'payable_id' => $order->id,
]);

// Invoice scopes
$pendingInvoices = PaynexusInvoice::pending()->get();
$paidInvoices = PaynexusInvoice::paid()->get();

// Checkout session scopes
$activeSessions = PaynexusCheckoutSession::active()->get();

Error Handling

The package provides specific exception types for different error scenarios:

php 
use PayNexus\Exceptions\PayNexusAuthException;
use PayNexus\Exceptions\PayNexusConnectionException;
use PayNexus\Exceptions\PayNexusApiException;

try {
    $result = PayNexus::initiatePayment([...]);
    
    if (!$result['success']) {
        return back()->with('error', $result['message']);
    }
} catch (PayNexusAuthException $e) {
    // Invalid API key
} catch (PayNexusConnectionException $e) {
    // Network error
} catch (PayNexusApiException $e) {
    // API error
}

Testing

Use Laravel's HTTP fake to test payment flows:

php 
use Illuminate\Support\Facades\Http;

Http::fake([
    'paynexus.co.ke/*' => Http::response([
        'success' => true,
        'data' => [
            'payment_id' => 123,
            'reference' => 'PNXTEST',
            'checkout_request_id' => 'ws_CO_test',
        ],
    ]),
]);

$result = PayNexus::initiatePayment([
    'amount' => 1000,
    'phone' => '254712345678',
]);

Requirements

  • PHP 8.2+
  • Laravel 11.x or 12.x
  • Composer 2.x

Support

For issues and questions: