PayNexus Laravel Plugin

Accept payments through PayNexus on your Laravel website. Supports M-Pesa STK Push, embeddable payment pages, webhooks, and optional Filament admin panel integration.

Installation

composer require paynexus/laravel-paynexus

Core Installation (Without Filament)

1. Install the package:

   composer require paynexus/laravel-paynexus
   

2. Publish the configuration:

   php artisan vendor:publish --tag=paynexus-config
   

3. Set your API credentials in .env:

   PAYNEXUS_API_KEY=pk_your_api_key_here
   PAYNEXUS_SECRET_KEY=sk_your_secret_key_here
   PAYNEXUS_WEBHOOK_SECRET=whsec_your_webhook_secret
   PAYNEXUS_BASE_URL=https://www.paynexus.co.ke
   PAYNEXUS_CURRENCY=KES
   

4. Publish migrations (optional):

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

Filament Integration (Optional)

If you use Filament and want admin panel integration:

1. Install Filament (if not already installed):

   composer require filament/filament
   

2. Enable Filament integration in your .env:

   PAYNEXUS_FILAMENT_ENABLED=true
   

3. Register the plugin in your PanelProvider:

   // In your Filament PanelProvider
   ->plugins([
       \PayNexus\Filament\PayNexusPlugin::make(),
   ])
   

This adds:

• Payments Resource — View and manage payments in your admin panel
• Revenue Widget — Dashboard chart showing payment trends
• Payment Stats Widget — Quick overview stats

Configuration Options

Basic Configuration

Filament Configuration

Quick Start

Initiate an M-Pesa Payment

use PayNexus\Facades\PayNexus;

$result = PayNexus::pay([
    'amount' => 1000,
    'phone' => '254746990866',
    'description' => 'Order #12345',
    'reference' => 'ORD-12345',
    'callback_url' => route('paynexus.webhook'), // optional override
]);

if ($result['success']) {
    // STK push sent — $result['checkout_request_id']
}

Check Payment Status

$status = PayNexus::status($checkoutRequestId);
// $status['status'] => 'completed', 'pending', 'failed'

Embedded Payment Page

Generate a hosted payment page URL:

$url = PayNexus::paymentPage([
    'amount' => 500,
    'title' => 'Premium Subscription',
    'description' => 'Monthly plan',
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
    'success_url' => route('payment.success'),
    'cancel_url' => route('payment.cancel'),
]);

return redirect($url);

Webhooks

The package registers a webhook route at /paynexus/webhook automatically. Implement listeners for payment events:

// In EventServiceProvider
use PayNexus\Events\PaymentCompleted;
use PayNexus\Events\PaymentFailed;

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

Blade Components

<!-- Payment Button -->
<x-paynexus::pay-button
    :amount="1000"
    phone="254746990866"
    description="Order Payment"
    reference="ORD-123"
    class="bg-blue-500 text-white px-6 py-3 rounded-lg"
>
    Pay KES 1,000
</x-paynexus::pay-button>

Filament Integration (Optional)

If your project uses Filament, the package provides optional resources and widgets:

// In your Filament PanelProvider
->plugins([
    \PayNexus\Filament\PayNexusPlugin::make(),
])

This adds:

• Payments Resource — View and manage payments in your admin panel
• Revenue Widget — Dashboard chart showing payment trends
• Payment Stats Widget — Quick overview stats

API Reference

PayNexus::pay(array $data): array

Initiate an M-Pesa STK Push payment.

PayNexus::status(string $checkoutRequestId): array

Check payment status by checkout request ID.

PayNexus::paymentPage(array $data): string

Generate a hosted payment page URL.

PayNexus::transactions(array $filters): array

List transactions with optional filters.

Events

Troubleshooting

Common Issues

1. "PayNexus configuration key 'api_key' is required"

   • Ensure you've set PAYNEXUS_API_KEY in your .env file
   • Run php artisan config:clear after updating environment variables

2. "Connection error: Unable to reach PayNexus API"

   • Check your internet connection
   • Verify PAYNEXUS_BASE_URL is correct
   • Ensure your API keys are valid

3. Filament resources not showing

   • Set PAYNEXUS_FILAMENT_ENABLED=true in your .env
   • Ensure you've registered the plugin in your PanelProvider
   • Clear caches: php artisan config:clear && php artisan filament:cache

4. Webhook signature verification failing

   • Ensure PAYNEXUS_WEBHOOK_SECRET matches your PayNexus dashboard settings
   • Check that your webhook URL is accessible from the internet

Debug Mode

To enable debug logging, set a log channel:

PAYNEXUS_LOG_CHANNEL=paynexus

Then configure the channel in config/logging.php.

Upgrade Guide

From v1.x to v2.x

1. Refund functionality removed - If you were using refund methods, they are no longer available
2. Filament integration is now opt-in - You must explicitly enable it in configuration
3. Better error handling - Error messages are now more descriptive
4. Configuration validation - Invalid configurations will throw exceptions during registration

License

MIT