Download the PHP package paynexus/laravel-paynexus without Composer

✨ Features

• 🚀 Easy Integration - Simple facade-based API for quick setup
• 💳 M-Pesa STK Push - Seamless mobile payment initiation
• 🔄 Real-time Tracking - Poll for payment completion or use webhooks
• 📊 Local Records - Automatic database synchronization
• 🔔 Webhook Events - Laravel events for payment state changes
• 🔒 Secure - HMAC signature verification for webhooks
• 🎯 Polymorphic Relations - Link payments to any model (Order, Invoice, etc.)
• ✅ Phone Validation - Built-in phone number normalization

⚠️ Plugin vs Platform

This plugin is for external Laravel applications (e.g., ecommerce stores, SaaS apps) that want to accept payments through PayNexus.

Note: If you're looking for the PayNexus platform source code, that's a separate repository. This plugin is the client SDK for merchants integrating with PayNexus.

📑 Table of Contents

• How It Works
• Installation
• Configuration
• Quick Start
• API Reference
  • Merchant
  • Businesses
  • Payment Accounts
  • Initiate Payment
  • Payment Status
  • Poll for Completion
  • List Payments
  • Phone Validation
  • Webhooks
• Webhook Integration
• Events
• Local Payment Records
• Ecommerce Integration Guide
  • Order Checkout Flow
  • Cart Checkout Controller
  • Payment Status Page (Livewire)
  • Handling Webhooks in Your App
  • Subscription Integration
  • Manual Payment Verification
• Error Handling
• Testing
• JavaScript Polling
• Custom Webhook Handler
• Configuration Reference
• Getting API Keys
• Support
• Troubleshooting
• License

🔄 How It Works

Payment Flow:

1. Initiate — Your app calls PayNexus::initiatePayment(...). A payment record is created both on PayNexus and in your local paynexus_payments table.
2. STK Push — PayNexus sends an M-Pesa STK Push to the customer's phone.
3. Customer pays — The customer enters their PIN on their phone.
4. Callback — M-Pesa sends a callback to PayNexus. PayNexus updates its record and fires a webhook to your app.
5. Webhook received — This plugin receives the webhook, updates the local paynexus_payments record, and dispatches a Laravel event (PaymentCompleted or PaymentFailed).
6. Your listener — Your EventServiceProvider listener marks the order as paid, sends a receipt, etc.

Both records always match. If the webhook is missed, you can call PayNexus::pollStatus(...) or PayNexus::getPaymentByCheckoutId(...) to sync manually.

📦 Installation

Install the package via Composer:

The service provider and facade are auto-discovered by Laravel.

Publish Config and Migration

⚙️ Configuration

Add these to your .env file:

🔑 Where to Get Credentials

🔓 Public Key Allowed Operations

Public keys (pk_) can perform the following read-only operations:

Merchant Information

• GET /api/merchant - Get merchant information
• GET /api/merchant/businesses - List merchant businesses
• GET /api/merchant/payment-accounts - List payment accounts

Payment Read Operations

• GET /api/payments/{reference} - Get payment status by reference
• GET /api/payments/{id}/status-by-id - Get payment status by ID
• POST /api/payments/status-by-checkout-id - Get payment status by checkout ID
• GET /api/payments - List all payments

M-Pesa Operations

• GET /api/mpesa/health - M-Pesa service health check
• POST /api/mpesa/validate-phone - Validate phone number
• POST /api/mpesa/payment/status - Check M-Pesa transaction status

Webhook Read Operations

• GET /api/webhooks - List registered webhooks

API Key Read Operations

• GET /api/api-keys - List API keys

Invoice Read Operations

• GET /api/invoices - List invoices
• GET /api/invoices/{invoice} - View invoice details

Receipt Read Operations

• GET /api/receipts - List receipts
• GET /api/receipts/{receipt} - View receipt details

🔒 Public Key Blocked Operations

Public keys (pk_) are blocked from these write operations at the middleware level:

Payment Write Operations

• POST /api/payments/initiate - Initiate payments
• POST /api/mpesa/payment/initiate - Initiate STK push payment

Webhook Management

• POST /api/webhooks/register - Register webhooks
• PUT /api/webhooks/{id} - Update webhooks
• DELETE /api/webhooks/{id} - Delete webhooks

API Key Management

• POST /api/api-keys - Create API keys
• PUT /api/api-keys/{id} - Update API keys
• DELETE /api/api-keys/{id} - Delete API keys

Invoice Management

• POST /api/invoices - Create invoices
• PUT /api/invoices/{invoice} - Update invoices
• DELETE /api/invoices/{invoice} - Delete invoices
• POST /api/invoices/{invoice}/send - Send invoices

Receipt Management

• POST /api/receipts/{receipt}/resend - Resend receipts

🚀 Quick Start

📚 API Reference

👤 Merchant

🏢 Businesses

💳 Payment Accounts

💰 Initiate Payment

Two endpoints are available:

Idempotency Protection:

To prevent duplicate payments, you can provide an idempotency key:

If a payment with the same idempotency_key already exists, the existing payment details will be returned instead of creating a new one. This is especially useful for handling network retries and preventing duplicate charges.

Benefits of idempotency:

• Prevents duplicate payments on network retries
• Safe to retry payment initiation without side effects
• Atomic database transactions ensure consistency
• Existing payment returned if key matches

Response:

Both methods also create a local paynexus_payments record automatically.

📊 Payment Status

⏱️ Poll for Completion

Blocks until the payment reaches a terminal state or times out:

📋 List Payments

✅ Phone Validation

🔗 Webhooks

🔔 Webhook Integration

The plugin automatically registers a POST route at /paynexus/webhook (configurable via PAYNEXUS_WEBHOOK_PATH).

Queue Support for Webhooks

For production environments, you can enable queue processing for webhooks to improve reliability:

When enabled, webhooks are dispatched to a queue job (ProcessPayNexusWebhook) with configurable retry behavior:

Benefits of queue processing:

• Asynchronous processing prevents webhook timeouts
• Automatic retries with exponential backoff
• Better handling of high-volume webhook traffic
• Dead-letter queue support for failed webhooks

Handling Webhook Failures:

When a webhook job exhausts its retry attempts, a WebhookProcessingFailed event is dispatched. You can listen for this event:

PayNexus sends this payload when a payment completes:

The webhook controller:

1. Verifies the X-PayNexus-Signature header (HMAC-SHA256 of the JSON body using your webhook secret).
2. Checks X-PayNexus-Timestamp for replay protection (rejects payloads older than 5 minutes by default).
3. Finds or creates the matching paynexus_payments record.
4. Updates the local record's status.
5. Dispatches a Laravel event (PaymentCompleted or PaymentFailed).

Setup in PayNexus dashboard:

1. Go to Webhooks in your PayNexus merchant panel.
2. Add a webhook pointing to https://yourapp.com/paynexus/webhook.
3. Copy the generated secret and set PAYNEXUS_WEBHOOK_SECRET in your .env.

🎯 Events

Register listeners in your EventServiceProvider:

📦 Local Payment Records

Every payment initiated through the plugin creates a row in the paynexus_payments table.

🔍 Payment Verification

The plugin tracks verification data from the payment provider:

👤 Manual Confirmation

For payments that need manual review:

🔗 Polymorphic Relationship

Link payments to any of your models:

🛒 Ecommerce Integration Guide

📦 Order Checkout Flow

Here is a complete end-to-end checkout flow for an ecommerce store.

Step 1: Order Model Setup

Step 2: Orders Migration

🛍️ Cart Checkout Controller

Routes:

⚡ Payment Status Page (Livewire)

If you use Livewire, here is a component that polls automatically:

🎧 Handling Webhooks in Your App

🔄 Subscription Integration

For subscription-based applications:

Subscription Model:

Subscription Payment Controller:

� Manual Payment Verification

For payments that require manual admin review:

⚠️ Error Handling

The plugin provides specific exceptions for different error scenarios:

🧪 Testing

Mocking HTTP Requests

🌐 JavaScript Polling

For client-side payment status polling:

� Custom Webhook Handler

If you need custom webhook handling beyond the built-in controller:

Register your custom webhook route:

�� Configuration Reference

Advanced Configuration Options

Queue Webhooks:

Retry Configuration:

Custom Webhook Path:

Custom Polling Settings:

HTTP Client Settings:

Custom Log Channel:

Then in config/logging.php:

🔑 Getting API Keys

To use this plugin, you need API keys from the PayNexus platform:

1. Register at paynexus.co.ke to create an account
2. Choose a subscription plan that fits your needs
3. Navigate to the merchant panel after registration
4. Create a business in your merchant dashboard
5. Add a payment account (e.g., M-Pesa till number) to your business
6. Navigate to API Keys and select the appropriate API key for the specific payment account you created
   • Secret Key (sk_): For initiating payments and write operations. Keep this server-side only.
   • Public Key (pk_): For read operations like checking payment status. Safe to use in client-side code.
7. Configure webhook in PayNexus dashboard pointing to https://yourapp.com/paynexus/webhook
8. Copy the webhook secret and set PAYNEXUS_WEBHOOK_SECRET in your .env

💬 Support

• Documentation: README.md
• Issues: GitHub Issues
• Email: [email protected]
• Platform: paynexus.co.ke

🔧 Troubleshooting

"PayNexus secret key is required"

• Set PAYNEXUS_SECRET_KEY (or PAYNEXUS_API_KEY for backwards compatibility) in your .env.
• Run php artisan config:clear after changing environment variables.

"Unable to reach PayNexus API"

• Check your internet connection.
• Verify PAYNEXUS_BASE_URL is correct (https://paynexus.co.ke, no trailing /api).
• Test connectivity: curl -H "X-API-Key: sk_..." https://paynexus.co.ke/api/merchant

"Invalid PayNexus webhook signature"

• Ensure PAYNEXUS_WEBHOOK_SECRET matches the secret shown in PayNexus when you created the webhook.
• The webhook URL must be publicly accessible (PayNexus needs to reach it).

Payment stays "pending"

• The customer may not have confirmed the STK push on their phone.
• Call PayNexus::checkMpesaStatus($checkoutRequestId) to query M-Pesa directly.
• Check that your PayNexus callback URL is correctly configured in the M-Pesa Daraja portal.

Local record not updating

• Ensure your webhook endpoint is correctly registered with PayNexus.
• Check storage/logs/laravel.log for [PayNexus Webhook] entries.
• Verify your .env has PAYNEXUS_WEBHOOK_SECRET set correctly.
• You can manually sync by calling PayNexus::getPaymentByCheckoutId(...).

📄 License

MIT — see LICENSE.