PHPackages                             paynecta/paynecta-laravel-sdk - 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. [API Development](/categories/api)
4. /
5. paynecta/paynecta-laravel-sdk

ActiveLibrary[API Development](/categories/api)

paynecta/paynecta-laravel-sdk
=============================

Official Laravel SDK for Paynecta Payment API - Simplify M-Pesa, Bank, and Wallet payment integrations in Kenya

v1.0.4(7mo ago)223↓100%1MITPHPPHP ^8.2|^8.3

Since Oct 13Pushed 6mo agoCompare

[ Source](https://github.com/Paynecta/paynecta-laravel-sdk)[ Packagist](https://packagist.org/packages/paynecta/paynecta-laravel-sdk)[ RSS](/packages/paynecta-paynecta-laravel-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (5)Used By (0)

Paynecta Laravel SDK
====================

[](#paynecta-laravel-sdk)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7ed2636b77fa12e55a4b9eda31a83b80b4a31fd138a56c39d63f0c4912bc00fd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061796e656374612f7061796e656374612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/paynecta/paynecta-laravel-sdk)[![Total Downloads](https://camo.githubusercontent.com/aad267545b643143c9f2db2f3bc7dd0d7e4aac249c33281f9148f84d31933700/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7061796e656374612f7061796e656374612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/paynecta/paynecta-laravel-sdk)[![License](https://camo.githubusercontent.com/2a7adaf330702f3903b09368922efdb3351ef7ee918708fd999ec8a1b593dfdf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7061796e656374612f7061796e656374612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/paynecta/paynecta-laravel-sdk)

Official Laravel SDK for [Paynecta Payment API](https://paynecta.co.ke) - Simplify M-Pesa, Bank, and Wallet payment integrations in Kenya.

Features
--------

[](#features)

- 🚀 **Easy Integration** - Get started in minutes with simple configuration
- 💳 **M-Pesa STK Push** - Trigger payment prompts directly on customer phones
- 💰 **Payment Links** - Create and manage shareable payment pages
- 🏦 **Bank Integration** - Access all available banks and their paybill numbers
- 🔔 **Real-time Webhooks** - Instant notifications for payment events
- 🛡️ **Secure Authentication** - API key and email-based authentication
- 📝 **Comprehensive Logging** - Debug with detailed request/response logs
- ⚡ **Exception Handling** - Graceful error handling with specific exceptions
- 🎯 **Laravel Events** - Native Laravel event system for webhooks

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

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x or 11.x
- Guzzle HTTP Client 7.x

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

[](#installation)

Install the package via Composer:

```
composer require paynecta/paynecta-laravel-sdk
```

### Publish Configuration

[](#publish-configuration)

Publish the configuration file to customize settings:

```
php artisan vendor:publish --tag=paynecta-config
```

This will create a `config/paynecta.php` file in your Laravel application.

### Environment Configuration

[](#environment-configuration)

Add your Paynecta credentials to your `.env` file:

```
PAYNECTA_API_KEY=your_api_key_here
PAYNECTA_EMAIL=your-email@example.com
PAYNECTA_LOGGING=false
```

> **⚠️ Security Note:** Never commit your API credentials to version control. Always use environment variables.

Getting Your API Credentials
----------------------------

[](#getting-your-api-credentials)

1. Log in to your [Paynecta Dashboard](https://paynecta.co.ke)
2. Navigate to `/api` section
3. Click "Create New API Key"
4. Copy your API key immediately (it's shown only once!)
5. Store it securely in your `.env` file

Quick Start
-----------

[](#quick-start)

### Verify Authentication

[](#verify-authentication)

Test your credentials and retrieve user information:

```
use Paynecta\LaravelSdk\Facades\Paynecta;

try {
    $user = Paynecta::verifyAuth();

    echo "Authentication successful!";
    echo "User: " . $user['data']['email'];

} catch (\Paynecta\LaravelSdk\Exceptions\AuthenticationException $e) {
    echo "Authentication failed: " . $e->getMessage();
}
```

Usage Guide
-----------

[](#usage-guide)

### 1. Payment Links

[](#1-payment-links)

```
use Paynecta\LaravelSdk\Facades\Paynecta;

// Get all payment links
$links = Paynecta::paymentLinks()->getAll();

// Get specific link
$link = Paynecta::paymentLinks()->get('ABC123');

// Get only invoices
$invoices = Paynecta::paymentLinks()->getInvoices();

// Search links
$results = Paynecta::paymentLinks()->search('subscription');

// Count total links
$count = Paynecta::paymentLinks()->count();
```

### 2. Initialize Payments (M-Pesa STK Push)

[](#2-initialize-payments-m-pesa-stk-push)

```
use Paynecta\LaravelSdk\Facades\Paynecta;

// Initialize payment
$payment = Paynecta::payments()->initialize(
    'ABC123',           // Payment link code
    '254700000000',     // Mobile number
    100                 // Amount in KES (1-250,000)
);

// With validation
$payment = Paynecta::payments()->initializeWithValidation(
    'ABC123',
    '0700000000',       // Accepts 07XX format
    500
);

// Get transaction reference
$reference = Paynecta::payments()->getTransactionReference($payment);
echo "Transaction Reference: {$reference}";
```

### 3. Query Payment Status

[](#3-query-payment-status)

```
use Paynecta\LaravelSdk\Facades\Paynecta;

// Query status
$status = Paynecta::payments()->queryStatus('ABCP20240803123456ABCD');

// Check status
if (Paynecta::payments()->isCompleted($status)) {
    $receipt = Paynecta::payments()->getMpesaReceiptNumber($status);
    echo "Payment completed! Receipt: {$receipt}";
}

if (Paynecta::payments()->isFailed($status)) {
    $reason = Paynecta::payments()->getFailureReason($status);
    echo "Payment failed: {$reason}";
}

// Poll until complete (checks every 2 seconds, max 30 attempts)
$finalStatus = Paynecta::payments()->pollStatus($reference, 30, 2);
```

### 4. Currency Rates

[](#4-currency-rates)

```
use Paynecta\LaravelSdk\Facades\Paynecta;

// Get all currency rates (160+ currencies)
$rates = Paynecta::currencyRates()->getAll();

// Get specific currency rate
$usdRate = Paynecta::currencyRates()->get('USD');

// Convert currency
$converted = Paynecta::currencyRates()->convert(100, 'USD', 'KES');

// Convert with specific date
$converted = Paynecta::currencyRates()->convert(100, 'USD', 'KES', '2025-10-01');

// Get historical rates
$history = Paynecta::currencyRates()->getHistory('KES', 'USD', '2025-10-01', '2025-10-13');

// Helper methods
$rate = Paynecta::currencyRates()->getRate($usdRate);
$amount = Paynecta::currencyRates()->getConvertedAmount($converted);
$allRates = Paynecta::currencyRates()->getRates($rates);
```

### 5. Banks

[](#5-banks)

```
use Paynecta\LaravelSdk\Facades\Paynecta;

// Get all banks
$banks = Paynecta::banks()->getAll();

// Get specific bank
$bank = Paynecta::banks()->get('jR3kL9');

// Search banks
$results = Paynecta::banks()->search('equity');

// Find by name
$kcb = Paynecta::banks()->findByName('KCB Bank');

// Find by paybill
$bank = Paynecta::banks()->findByPaybill('247247');

// For dropdowns (returns bank_id => bank_name)
$options = Paynecta::banks()->getForDropdown();

// Simple list (returns bank_name => paybill_number)
$list = Paynecta::banks()->getAllAsList();

// Grouped by first letter
$grouped = Paynecta::banks()->getGroupedByLetter();
```

### 6. Webhooks

[](#6-webhooks)

#### Setup Webhook URL

[](#setup-webhook-url)

Your webhook URL will be automatically registered at:

```
https://yourdomain.com/paynecta/webhook

```

Add to your dashboard at:

#### Whitelist Webhook Route (Important!)

[](#whitelist-webhook-route-important)

Add to `app/Http/Middleware/VerifyCsrfToken.php`:

```
protected $except = [
    'paynecta/webhook',
];
```

#### Listen to Webhook Events

[](#listen-to-webhook-events)

Create event listeners:

```
php artisan make:listener HandlePaymentCompleted
```

In `app/Listeners/HandlePaymentCompleted.php`:

```