README

At Intelfric, we harness the power of artificial intelligence to build smart, adaptable, and future-ready solutions for organizations and individuals. Our team of AI specialists, software engineers, and researchers provides end-to-end services from research and prototyping to full-scale deployment and long-term support.

We specialize in delivering cloud-based SaaS platforms, including AI-powered CRM, HRM, inventory management systems, and fully customized enterprise solutions. By merging emerging technologies with practical, real-world applications, we ensure our clients stay ahead in an ever-evolving digital landscape.

What sets Intelfric apart is our commitment to ethical, secure, and responsible AI. Every solution is designed with transparency, fairness, and data privacy at its core. For us, innovation is not just about technology it’s about creating purposeful tools that align with our clients’ values and visions.

ClickPesa Laravel Package

A Laravel package for integrating with the ClickPesa API, providing easy access to authorization, payments, payouts, and BillPay functionalities.

Installation

You can install the package via Composer:

composer require intelfric-technologies/clickpesa-laravel

After installing the package, publish its configuration file:

php artisan vendor:publish --provider="ClickPesa\\Laravel\\ClickPesaServiceProvider" --tag="clickpesa-config"

This will create a clickpesa.php file in your config directory.

Configuration

Add the following environment variables to your .env file:

CLICKPESA_API_KEY=your_clickpesa_api_key
CLICKPESA_CLIENT_ID=your_clickpesa_client_id
CLICKPESA_BASE_URL=https://api.clickpesa.com/ # Optional, default is provided
CLICKPESA_TOKEN_CACHE_LIFETIME=3500 # Optional, default is 3500 seconds (58 minutes)

# Webhook Configuration (Optional)
CLICKPESA_WEBHOOK_SECRET=your_webhook_secret
CLICKPESA_WEBHOOK_ENABLED=true
CLICKPESA_WEBHOOK_PATH=clickpesa/webhook

Usage

The package provides a ClickPesa facade for easy access to the API client. You can also resolve the ClickPesaClient directly from the service container.

Authorization

The authorization token is automatically managed by the ClickPesaClient. It will generate and refresh the token as needed. You typically won't need to interact with this directly.

use ClickPesa\Laravel\Facades\ClickPesa;

// The token is handled internally, but you can force a refresh if needed
try {
    $response = ClickPesa::authorization()->generateToken();
    // This will return the token details, but it's usually not necessary to call directly.
    // The client automatically fetches and caches it.
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Payments

Preview USSD-PUSH request

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your USSD-PUSH preview data
    ];
    $response = ClickPesa::payments()->previewUssdPush($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Initiate USSD-PUSH request

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your USSD-PUSH initiation data
    ];
    $response = ClickPesa::payments()->initiateUssdPush($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Preview Card Payment

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your card payment preview data
    ];
    $response = ClickPesa::payments()->previewCardPayment($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Initiate Card Payment

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your card payment initiation data
    ];
    $response = ClickPesa::payments()->initiateCardPayment($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Query Payment Status

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $transactionId = 'your_transaction_id';
    $response = ClickPesa::payments()->queryPaymentStatus($transactionId);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Query All Payments

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $query = [
        'from' => '2023-01-01',
        'to' => '2023-12-31',
        'page' => 1,
        'limit' => 10
    ];
    $response = ClickPesa::payments()->queryAllPayments($query);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Payouts

Preview Mobile Money Payout

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your mobile money payout preview data
    ];
    $response = ClickPesa::payouts()->previewMobileMoneyPayout($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Create Mobile Money Payout

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your mobile money payout creation data
    ];
    $response = ClickPesa::payouts()->createMobileMoneyPayout($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Preview Bank Payout

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your bank payout preview data
    ];
    $response = ClickPesa::payouts()->previewBankPayout($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Create Bank Payout

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your bank payout creation data
    ];
    $response = ClickPesa::payouts()->createBankPayout($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Query Payout Status

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $transactionId = 'your_payout_transaction_id';
    $response = ClickPesa::payouts()->queryPayoutStatus($transactionId);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Query All Payouts

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $query = [
        'from' => '2023-01-01',
        'to' => '2023-12-31',
        'page' => 1,
        'limit' => 10
    ];
    $response = ClickPesa::payouts()->queryAllPayouts($query);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Retrieve Banks List

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $response = ClickPesa::payouts()->retrieveBanksList();
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

BillPay

Create Order Control Number

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your order control number creation data
    ];
    $response = ClickPesa::billpay()->createOrderControlNumber($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Create Customer Control Number

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        // ... your customer control number creation data
    ];
    $response = ClickPesa::billpay()->createCustomerControlNumber($data);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Query BillPay Number Details

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $controlNumber = 'your_control_number';
    $response = ClickPesa::billpay()->queryBillPayNumberDetails($controlNumber);
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Checkout Link

Generate Checkout Link

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        'amount' => 50000,
        'currency' => 'TZS',
        'reference' => 'ORDER-001',
        'description' => 'Payment for Order #001',
        'redirect_url' => 'https://yourdomain.com/payment/success',
        'cancel_url' => 'https://yourdomain.com/payment/cancel',
    ];
    $response = ClickPesa::checkoutLink()->generate($data);
    
    // Returns checkout link URL
    $checkoutUrl = $response['checkout_url'];
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Payout Link

Generate Payout Link

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $data = [
        'amount' => 25000,
        'currency' => 'TZS',
        'reference' => 'PAYOUT-001',
        'description' => 'Payout for service',
        'recipient_name' => 'John Doe',
    ];
    $response = ClickPesa::payoutLink()->generate($data);
    
    // Returns payout link URL
    $payoutUrl = $response['payout_url'];
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Account

Retrieve Account Balance

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $response = ClickPesa::account()->getBalance();
    
    // Returns account balance details
    $balance = $response['balance'];
    $currency = $response['currency'];
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Retrieve Account Statement

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $query = [
        'from' => '2023-01-01',
        'to' => '2023-12-31',
        'page' => 1,
        'limit' => 50
    ];
    $response = ClickPesa::account()->getStatement($query);
    
    // Returns account transactions
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Exchange Rates

Retrieve Exchange Rates

use ClickPesa\Laravel\Facades\ClickPesa;

try {
    $response = ClickPesa::exchangeRates()->get();
    
    // Returns current exchange rates
    print_r($response);
} catch (\ClickPesa\Laravel\Exceptions\ClickPesaException $e) {
    echo "Error: " . $e->getMessage();
}

Webhooks

ClickPesa sends webhooks to notify your application about payment events. The package provides built-in webhook handling.

Setup Webhooks

1. Add your webhook secret to .env:

   CLICKPESA_WEBHOOK_SECRET=your_webhook_secret_from_clickpesa

2. Register your webhook URL with ClickPesa:

   https://yourdomain.com/clickpesa/webhook
   

Available Events

The package dispatches the following Laravel events:

• ClickPesa\Laravel\Events\PaymentReceived - When a payment is received/completed
• ClickPesa\Laravel\Events\PayoutCompleted - When a payout is processed/completed
• ClickPesa\Laravel\Events\BillPayReceived - When a BillPay payment is received

Listening to Webhook Events

Create a listener:

<?php

namespace App\Listeners;

use ClickPesa\Laravel\Events\PaymentReceived;

class HandlePaymentReceived
{
    public function handle(PaymentReceived $event): void
    {
        $transactionId = $event->getTransactionId();
        $amount = $event->getAmount();
        $status = $event->getStatus();
        
        // Update your database, send notifications, etc.
    }
}

Register the listener in EventServiceProvider:

use ClickPesa\Laravel\Events\PaymentReceived;
use App\Listeners\HandlePaymentReceived;

protected $listen = [
    PaymentReceived::class => [
        HandlePaymentReceived::class,
    ],
];

For detailed webhook documentation, see WEBHOOKS.md.

Error Handling

All API calls are wrapped in try-catch blocks to catch ClickPesa\Laravel\Exceptions\ClickPesaException.

Testing

Run the test suite:

composer test

Run tests with coverage:

composer test:coverage

Run static analysis:

composer analyse

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.