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

ActiveLibrary[API Development](/categories/api)

emilkitua/clickpesa
===================

Laravel integration for ClickPesa API

31631PHP

Since Jun 27Pushed 10mo agoCompare

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

READMEChangelogDependenciesVersions (1)Used By (0)

```
# ClickPesa Laravel Integration

A simple Laravel package to integrate with the [ClickPesa](https://clickpesa.com) payment platform.

Supports:
- ✅ Token Authorization
- ✅ USSD Checkout
- ✅ Card Payment
- ✅ Payment Status Query
- ✅ Wallet Balance Retrieval

---

## 📦 Installation

```bash
composer require emilkitua/clickpesa
```

If you're installing from a local path or custom repository, configure it in your project's `composer.json`:

```
"repositories": [
  {
    "type": "path",
    "url": "./packages/EmilKitua/ClickPesa"
  }
]
```

Then run:

```
composer require emilkitua/clickpesa:dev-main
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Publish the config file:

```
php artisan vendor:publish --provider="EmilKitua\ClickPesa\ClickPesaServiceProvider"
```

Then add the following to your `.env`:

```
CLICKPESA_CLIENT_ID=your-client-id
CLICKPESA_CLIENT_SECRET=your-client-secret
CLICKPESA_BASE_URL=https://api.clickpesa.com
```

---

🧠 Usage
-------

[](#-usage)

Inject and use the `ClickPesa` service in your controller, job, or anywhere:

```
use EmilKitua\ClickPesa\ClickPesa;

public function pay(ClickPesa $clickPesa)
{
    // Initiate USSD Checkout
    $response = $clickPesa->initiateUSSD([
        'phone' => '255712345678',
        'amount' => 1000,
        'currency' => 'TZS',
        'reference' => 'ORDER123',
        'callback_url' => route('clickpesa.callback'),
    ]);

    return response()->json($response);
}
```

Other available methods:

```
$clickPesa->initiateUSSD([...]);

$clickPesa->initiateCardPayment([...]);

$clickPesa->queryStatus($transactionId);

$clickPesa->getBalance();
```

🔔 Webhook Handling ClickPesa supports callbacks for transaction updates.

Define a route:

```
Route::post('/webhooks/clickpesa', [ClickPesaWebhookController::class, 'handle']);
```

```
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class ClickPesaWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $data = $request->all();

        Log::info('ClickPesa Webhook:', $data);

        // Handle based on status, transaction_id, etc.
        // Update your local DB accordingly.

        return response()->json(['status' => 'received'], 200);
    }
}
```

🧪 Testing You can mock responses for testing without hitting the real API.

Example PHPUnit Mock:

```
use Illuminate\Support\Facades\Http;

public function testUssdCheckout()
{
    Http::fake([
        'https://api.clickpesa.com/oauth/token' => Http::response([
            'access_token' => 'test_token',
            'expires_in' => 3600
        ]),
        'https://api.clickpesa.com/ussd-checkout' => Http::response([
            'transaction_id' => 'TX123456',
            'status' => 'pending',
        ]),
    ]);

    $response = app(ClickPesa::class)->initiateUSSD([
        'phone' => '255712345678',
        'amount' => 500,
        'currency' => 'TZS',
        'reference' => 'TESTREF',
        'callback_url' => 'https://yourdomain.com/callback'
    ]);

    $this->assertEquals('TX123456', $response['transaction_id']);
}
```

---

🌐 Real ClickPesa API Endpoints

FeatureEndpointMethodToken Authentication`/oauth/token`POSTUSSD Checkout`/ussd-checkout`POSTCard Payment`/card-checkout`POSTPayment Status`/payments/{transaction_id}`GETWallet Balance`/wallet/balance`GETRefer to ClickPesa API docs for full request/response formats.

---

Database
--------

[](#database)

This package creates a table named `clickpesa_payments` to store payment transactions.

### Table Structure: `clickpesa_payments`

[](#table-structure-clickpesa_payments)

ColumnTypeDescriptionidbigint (PK)Auto-increment primary keyreference\_idstring, uniqueInternal reference ID for the paymentexternal\_idstring, nullableClickPesa transaction ID (from API response)payment\_methodenum ('ussd','card')Payment method usedphone\_numberstring, nullablePhone number used for USSD or card paymentscard\_number\_maskedstring, nullableMasked card number (only for card payments)amountdecimal(15,2)Payment amountcurrencystring (default 'TZS')Currency codestatusenumCurrent status: pending, processing, successful, failed, cancelledstatus\_detailstring, nullableAdditional status info or error messagesrequest\_payloadjson, nullableJSON payload sent to ClickPesa APIresponse\_payloadjson, nullableJSON response from ClickPesa APIpaid\_attimestamp, nullableWhen payment was completedcreated\_attimestampWhen request was createdupdated\_attimestampWhen record was last updatedThe table helps track payment requests, responses, and status updates.

---

Usage in Laravel app after installing your package
--------------------------------------------------

[](#usage-in-laravel-app-after-installing-your-package)

Just run:

```
php artisan migrate
```

Laravel will include and run your package migration along with the app’s migrations.

Optional: publish migration to app if the user wants to customize
-----------------------------------------------------------------

[](#optional-publish-migration-to-app-if-the-user-wants-to-customize)

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

---

Usage
-----

[](#usage)

When initiating a USSD or card payment, you can store the payment details automatically via the provided `TransactionService`:

```
use EmilKitua\ClickPesa\Models\ClickPesaPayment;
use EmilKitua\ClickPesa\Services\TransactionService;

// Example data for initiating payment
$data = [
    'reference_id' => 'ORDER12345',
    'payment_method' => 'ussd', // or 'card'
    'phone_number' => '255712345678',
    'amount' => 10000,
    'currency' => 'TZS',
    'request_payload' => $requestPayloadJson,  // API request data as JSON string or array
];

// Store payment request in DB
TransactionService::createPayment($data);
```

---

📁 Folder Structure
------------------

[](#-folder-structure)

```
ClickPesa/
├── src/
│   ├── ClickPesa.php
│   ├── ClickPesaServiceProvider.php
│   ├── Config/clickpesa.php
│   └── Http/Clients/ClickPesaClient.php
├── composer.json
└── README.md

```

---

✅ To Do
-------

[](#-to-do)

- \[✅\] Token Authentication
- \[✅\] USSD/Card Initiation
- \[✅\] Status Query
- \[✅\] Balance Retrieval
- \[✅\] Webhook suppory

---

📝 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

```

```

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance41

Moderate activity, may be stable

Popularity16

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/10583a2653ba3f1292c2343aac771fcee00591fa047362f6a05d9a56837add57?d=identicon)[emilkitua](/maintainers/emilkitua)

---

Top Contributors

[![emilkitua93](https://avatars.githubusercontent.com/u/264922883?v=4)](https://github.com/emilkitua93 "emilkitua93 (16 commits)")

### Embed Badge

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

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

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M475](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M270](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

263103.1M452](/packages/google-gax)

PHPackages © 2026

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