PHPackages                             dawilly/laravel-clickpesa - 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. dawilly/laravel-clickpesa

ActiveLibrary[Payment Processing](/categories/payments)

dawilly/laravel-clickpesa
=========================

A Laravel package for integrating with the ClickPesa payment gateway.

v1.0.0(5mo ago)21MITPHPPHP ^8.0

Since Jan 11Pushed 4mo agoCompare

[ Source](https://github.com/dawillygene/clickpesa-laravel)[ Packagist](https://packagist.org/packages/dawilly/laravel-clickpesa)[ RSS](/packages/dawilly-laravel-clickpesa/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Laravel Clickpesa Payment Integration
=====================================

[](#laravel-clickpesa-payment-integration)

A comprehensive Laravel package for integrating Clickpesa payment gateway and disbursement services. Support for USSD Push payments, card payments, mobile money payouts, and bank transfers.

Features
--------

[](#features)

- ✅ **Payments**: USSD Push, Card Payments
- ✅ **Disbursements**: Mobile Money Payouts, Bank Transfers (ACH/RTGS)
- ✅ **Authentication**: JWT token management with auto-refresh
- ✅ **Payment Status**: Query and track payment status
- ✅ **Payout Status**: Track disbursement transactions
- ✅ **Sandbox & Live**: Full support for both environments
- ✅ **Error Handling**: Comprehensive error documentation
- ✅ **Facades**: Clean, Laravel-style API

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

[](#installation)

```
composer require dawilly/laravel-clickpesa
```

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

[](#configuration)

### Publishing Package Assets

[](#publishing-package-assets)

The package provides the following publishable assets:

#### 1. Publish Configuration File

[](#1-publish-configuration-file)

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

Publishes `config/clickpesa.php` to your application's config directory.

#### 2. Publish Database Migrations

[](#2-publish-database-migrations)

```
php artisan vendor:publish --tag=clickpesa-migrations
```

Publishes database migrations to your `database/migrations/` directory.

#### 3. Publish All Assets

[](#3-publish-all-assets)

```
php artisan vendor:publish --provider="Dawilly\\Dawilly\\ClickpesaServiceProvider"
```

Publishes all package assets (config + migrations) at once.

### Running Migrations

[](#running-migrations)

After publishing the migrations, run:

```
php artisan migrate
```

This creates the `clickpesa_transactions` and `clickpesa_webhooks` tables in your database.

### Environment Configuration

[](#environment-configuration)

Add to your `.env`:

```
CLICKPESA_API_KEY=your_api_key
CLICKPESA_CLIENT_ID=your_client_id
CLICKPESA_ENVIRONMENT=sandbox
CLICKPESA_CALLBACK_URL=https://yourdomain.com/clickpesa/callback
CLICKPESA_CURRENCY=TZS
```

Usage
-----

[](#usage)

### 1. Payment Operations

[](#1-payment-operations)

#### USSD Push Payments

[](#ussd-push-payments)

```
use Dawilly\Dawilly\Facades\Clickpesa;

// Preview available payment methods
$preview = Clickpesa::previewUssdPushRequest([
    'amount' => '10000',
    'currency' => 'TZS',
    'orderReference' => 'ORDER-123',
    'phoneNumber' => '255712345678',
    'fetchSenderDetails' => true
]);

// Response:
// {
//   "activeMethods": [
//     {
//       "name": "TIGO-PESA",
//       "status": "AVAILABLE",
//       "fee": 500,
//       "message": "Service available"
//     }
//   ],
//   "sender": {
//     "accountName": "John Doe",
//     "accountNumber": "255712345678",
//     "accountProvider": "TIGO-PESA"
//   }
// }

// Initiate the payment
$payment = Clickpesa::initiateUssdPushRequest([
    'amount' => '10000',
    'currency' => 'TZS',
    'orderReference' => 'ORDER-123',
    'phoneNumber' => '255712345678'
]);

// Response:
// {
//   "id": "txn_abc123xyz",
//   "status": "PROCESSING",
//   "channel": "TIGO-PESA",
//   "orderReference": "ORDER-123",
//   "collectedAmount": "10000",
//   "collectedCurrency": "TZS",
//   "createdAt": "2023-11-07T05:31:56Z",
//   "clientId": "your-client-id"
// }
```

#### Card Payments

[](#card-payments)

```
// Preview card payment availability
$preview = Clickpesa::previewCardPayment([
    'amount' => '100',
    'currency' => 'USD',
    'orderReference' => 'CARD-001'
]);

// Initiate card payment (returns payment link)
$cardPayment = Clickpesa::initiateCardPayment([
    'amount' => '100',
    'currency' => 'USD',
    'orderReference' => 'CARD-001',
    'customer' => [
        'id' => 'existing-customer-id'
        // OR for new customers:
        // 'firstName' => 'John',
        // 'lastName' => 'Doe',
        // 'email' => 'john@example.com',
        // 'phoneNumber' => '255712345678'
    ]
]);

// Response:
// {
//   "cardPaymentLink": "https://pay.clickpesa.com/card/abc123xyz",
//   "clientId": "your-client-id"
// }

// Redirect customer to the payment link
// Redirect::away($cardPayment['cardPaymentLink']);
```

#### Query Payment Status

[](#query-payment-status)

```
// Check payment status by order reference
$status = Clickpesa::queryPaymentStatus('ORDER-123');

// Response:
// [
//   {
//     "id": "txn_abc123xyz",
//     "status": "SUCCESS",
//     "paymentReference": "PAY-XYZ-789",
//     "orderReference": "ORDER-123",
//     "collectedAmount": 10000,
//     "collectedCurrency": "TZS",
//     "message": "Payment completed successfully",
//     "updatedAt": "2023-11-07T05:31:56Z",
//     "createdAt": "2023-11-07T05:31:56Z",
//     "customer": {
//       "customerName": "John Doe",
//       "customerPhoneNumber": "255712345678",
//       "customerEmail": "john@example.com"
//     },
//     "clientId": "your-client-id"
//   }
// ]
```

### 2. Disbursement Operations

[](#2-disbursement-operations)

#### Mobile Money Payouts

[](#mobile-money-payouts)

```
use Dawilly\Dawilly\Facades\Disbursement;
use Dawilly\Dawilly\Facades\Clickpesa;

// Ensure authentication token is generated
Clickpesa::generateToken();

// Preview mobile money payout
$preview = Disbursement::previewMobileMoneyPayout([
    'amount' => 10000,
    'phoneNumber' => '255712345678',
    'currency' => 'TZS',
    'orderReference' => 'PAYOUT-001'
]);

// Response:
// {
//   "amount": 10500.00,
//   "balance": 50000,
//   "channelProvider": "TIGO PESA",
//   "fee": 500,
//   "exchanged": false,
//   "order": {
//     "amount": 10000,
//     "currency": "TZS",
//     "id": "PAYOUT-001"
//   },
//   "payoutFeeBearer": "merchant",
//   "receiver": {
//     "accountName": "Jane Doe",
//     "accountNumber": "255712345678",
//     "accountCurrency": "TZS",
//     "amount": 10000
//   }
// }

// Execute mobile money payout
$payout = Disbursement::createMobileMoneyPayout([
    'amount' => 10000,
    'phoneNumber' => '255712345678',
    'currency' => 'TZS',
    'orderReference' => 'PAYOUT-001'
]);

// Response:
// {
//   "id": "payout_abc123xyz",
//   "createdAt": "2023-11-07T05:31:56Z",
//   "updatedAt": "2023-11-07T05:31:56Z",
//   "orderReference": "PAYOUT-001",
//   "amount": "10500.00",
//   "currency": "TZS",
//   "fee": "500.00",
//   "exchanged": false,
//   "status": "AUTHORIZED",
//   "channel": "MOBILE MONEY",
//   "channelProvider": "TIGO PESA",
//   "beneficiary": {
//     "accountNumber": "255712345678",
//     "accountName": "Jane Doe",
//     "amount": "10000.00"
//   },
//   "clientId": "your-client-id"
// }
```

#### Bank Payouts

[](#bank-payouts)

```
// Preview bank payout
$preview = Disbursement::previewBankPayout([
    'amount' => 20000,
    'accountNumber' => '123456789',
    'currency' => 'TZS',
    'orderReference' => 'BANK-001',
    'bic' => 'EQTZTZTZ',
    'transferType' => 'ACH'
]);

// Response:
// {
//   "amount": 22360.00,
//   "balance": 50000,
//   "channelProvider": "Equity Bank Tanzania Limited",
//   "fee": 2360,
//   "exchanged": false,
//   "order": {
//     "amount": 20000,
//     "currency": "TZS",
//     "id": "BANK-001"
//   },
//   "payoutFeeBearer": "merchant",
//   "receiver": {
//     "accountNumber": "123456789",
//     "accountCurrency": "TZS",
//     "amount": 20000
//   },
//   "transferType": "ACH"
// }

// Execute bank payout
$bankPayout = Disbursement::createBankPayout([
    'amount' => 20000,
    'accountNumber' => '123456789',
    'accountName' => 'John Doe',
    'currency' => 'TZS',
    'orderReference' => 'BANK-001',
    'bic' => 'EQTZTZTZ',
    'transferType' => 'ACH'  // or 'RTGS'
]);

// Response:
// {
//   "id": "payout_xyz789abc",
//   "createdAt": "2023-11-07T05:31:56Z",
//   "updatedAt": "2023-11-07T05:31:56Z",
//   "orderReference": "BANK-001",
//   "amount": "22360.00",
//   "currency": "TZS",
//   "fee": "2360.00",
//   "exchanged": false,
//   "status": "AUTHORIZED",
//   "channel": "BANK TRANSFER",
//   "channelProvider": "Equity Bank Tanzania Limited",
//   "transferType": "ACH",
//   "beneficiary": {
//     "accountNumber": "123456789",
//     "accountName": "John Doe",
//     "amount": "20000.00"
//   },
//   "clientId": "your-client-id"
// }
```

#### Query Payout Status

[](#query-payout-status)

```
// Check payout status by order reference
$payoutStatus = Disbursement::queryPayoutStatus('PAYOUT-001');

// Response:
// [
//   {
//     "id": "payout_abc123xyz",
//     "status": "SUCCESS",
//     "orderReference": "PAYOUT-001",
//     "amount": "10500.00",
//     "currency": "TZS",
//     "fee": "500.00",
//     "channel": "MOBILE MONEY",
//     "channelProvider": "TIGO PESA",
//     "createdAt": "2023-11-07T05:31:56Z",
//     "updatedAt": "2023-11-07T05:31:56Z",
//     "beneficiary": {
//       "accountNumber": "255712345678",
//       "accountName": "Jane Doe"
//     },
//     "clientId": "your-client-id"
//   }
// ]
```

Payment Callback
----------------

[](#payment-callback)

The package provides a callback endpoint at `/clickpesa/callback`. Configure this URL in your Clickpesa dashboard.

The callback dispatches a `PaymentReceived` event:

```
use Dawilly\Dawilly\Events\PaymentReceived;
use Illuminate\Support\Facades\Event;

Event::listen(PaymentReceived::class, function (PaymentReceived $event) {
    $paymentData = $event->paymentData;

    // Update your order status
    // Send confirmation email
    // Log transaction
});
```

Status Values
-------------

[](#status-values)

### Payment Status

[](#payment-status)

- `PROCESSING` - Payment initiated, awaiting customer confirmation
- `SUCCESS` - Payment completed successfully
- `FAILED` - Payment failed
- `SETTLED` - Payment settled

### Payout Status

[](#payout-status)

- `AUTHORIZED` - Payout authorized, processing
- `SUCCESS` - Payout completed successfully
- `REVERSED` - Payout was reversed

Error Handling
--------------

[](#error-handling)

All methods return consistent error responses:

```
$response = Clickpesa::initiateUssdPushRequest([...]);

if (isset($response['success']) && $response['success'] === false) {
    // Handle error
    $message = $response['message'];
    $details = $response['response'] ?? null;

    // Log error
    Log::error('Clickpesa Error', $response);
}
```

### Common Error Messages

[](#common-error-messages)

- `Unauthorized` - Invalid or expired token
- `Invalid request parameters` - Missing or invalid parameters
- `Order reference already used` - Order reference must be unique
- `Invalid Order Reference, should only contain alphanumeric characters` - Order ref format invalid
- `Account has no payment collection methods` - No payment methods configured
- `Invalid bank BIC code` - Invalid bank BIC provided

Testing
-------

[](#testing)

```
./vendor/bin/phpunit
```

Or with Laravel:

```
php artisan test
```

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

[](#requirements)

- PHP ^8.0
- Laravel ^9.0|^10.0|^11.0
- GuzzleHTTP ^7.0
- Orchestra Testbench ^7.0|^8.0|^9.0 (for development)

License
-------

[](#license)

MIT License. See LICENSE file for details.

Author
------

[](#author)

Dawilly gene

Support
-------

[](#support)

For issues or feature requests, please visit the [GitHub repository](https://github.com/dawillygene/clickpesa-laravel).

Refer to [Clickpesa API Documentation](https://docs.clickpesa.com) for more details on the API specifications.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance74

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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

174d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/26033748?v=4)[ZeroMeters](/maintainers/dawilly)[@Dawilly](https://github.com/Dawilly)

---

Top Contributors

[![dawillygene](https://avatars.githubusercontent.com/u/121281452?v=4)](https://github.com/dawillygene "dawillygene (19 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/dawilly-laravel-clickpesa/health.svg)

```
[![Health](https://phpackages.com/badges/dawilly-laravel-clickpesa/health.svg)](https://phpackages.com/packages/dawilly-laravel-clickpesa)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[illuminate/http

The Illuminate Http package.

11937.9M6.9k](/packages/illuminate-http)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4851.0k](/packages/sebdesign-laravel-viva-payments)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.0k](/packages/simplestats-io-laravel-client)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1235.9k20](/packages/fleetbase-core-api)

PHPackages © 2026

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