kahsaygt/mpesa-sdk-php

A PHP SDK for M-PESA API integration

dev-main 2025-05-09 19:54 UTC

This package is auto-updated.

Last update: 2025-07-09 20:12:58 UTC


README

Easily integrate M-PESA APIs into your PHP or Laravel applications using the kahsaygt/mpesa-sdk-php package.๐ŸŒŸ

Features โœจ

  • ๐Ÿ”‘ Easy Authentication: Generate access tokens effortlessly.
  • ๐Ÿ“ฒ STK Push (NI Push): Initiate customer-to-business payments with USSD prompts.
  • ๐Ÿช C2B Support: Register URLs and handle customer payments.
  • ๐Ÿ’ธ B2C Payouts: Process business-to-customer disbursements.
  • ๐Ÿงฉ Modular Design: Well-structured and extensible codebase.
  • ๐Ÿšจ Error Handling: Robust, developer-friendly error management.

Installation ๐Ÿ“ฆ

Install the SDK via Composer:

composer require kahsaygt/mpesa-sdk-php:dev-main

Using a Custom Repository ๐ŸŒ

Since this package is hosted on GitHub, add the repository to your composer.json:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/kahsay-GT/mpesa-sdk-php.git"
    }
],
"require": {
    "kahsaygt/mpesa-sdk-php": "dev-main"
},


"minimum-stability": "dev"

Then run:

composer update

Laravel (Optional)

If using Laravel, publish the configuration file (if supported by your SDK):

php artisan vendor:publish --tag=mpesa-config

Requirements โœ…

  • ๐Ÿ˜ PHP 7.4 or higher
  • ๐ŸŒ cURL extension enabled
  • ๐Ÿ“ฅ Composer

Usage ๐Ÿ› ๏ธ

This SDK provides a Client class for API interactions and service classes for each M-PESA API endpoint. Below are usage examples for authentication and various API operations.

1. Authentication ๐Ÿ”

All API requests require an access token. Use Authentication.php to authenticate a Client instance:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php'; // Adjust path as needed

use Mpesa\Sdk\Client;

$client = getClient();
authenticate($client, __DIR__ . '/logs/auth.log');

// The client is now ready for API requests

2. STK Push (Lipa Na M-PESA Online) ๐Ÿ“ฑ

Initiate an STK Push payment request using StkPushService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/StkPushService.php';

use Ramsey\Uuid\Uuid;

$service = new StkPushService();
$service->run();

3. Account Balance Query ๐Ÿ“Š

Check your account balance using AccountBalanceService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/AccountBalanceService.php';

$service = new AccountBalanceService();
$service->run();

4. B2C Payout ๐Ÿ’ธ

Initiate a B2C payout using B2CPayOutService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/B2CPayOutService.php';

$service = new B2CPayOutService();
$service->run();

5. C2B URL Registration ๐ŸŒ

Register C2B callback URLs using C2BRegisterService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/C2BRegisterService.php';

$service = new C2BRegisterService();
$service->run();

6. Transaction Status Query ๐Ÿ”

Query transaction status using TransactionStatusService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/TransactionStatusService.php';

$service = new TransactionStatusService();
$service->run();

7. Transaction Reversal ๐Ÿ”„

Reverse a transaction using TransactionReversalService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/TransactionReversalService.php';

$service = new TransactionReversalService();
$service->run();

8. B2C Simulation ๐Ÿงช

Simulate a B2C transaction using SimulateTransactionService:

require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/Authentication.php';
require __DIR__ . '/SimulateTransactionService.php';

$service = new SimulateTransactionService();
$service->run();

Configuration in pure PHP โš™๏ธ

The Authentication.php file centralizes configuration. Customize it with:

$config = [
    'base_url' => 'https://apisandbox.safaricom.et/mpesa/',
    'consumer_key' => 'your_consumer_key',
    'consumer_secret' => 'your_consumer_secret',
];
$securityCredential = 'your_security_credential';

Configuration in Laravel โš™๏ธ

Configuration is managed via config/mpesa.php in Laravel projects. After publishing the config file with php artisan vendor:publish --tag=mpesa-config, customize it with your credentials. Use environment variables in your .env file:

APP_ENV=development #production
DEV_MPESA_BASE_URL=https://apisandbox.safaricom.et/
DEV_MPESA_CONSUMER_KEY=your_consumer_key
DEV_MPESA_CONSUMER_SECRET=your_consumer_secret
DEV_SECURITY_CREDENTIAL=your_security_credential

PROD_MPESA_BASE_URL=https://apisandbox.safaricom.et/
PROD_MPESA_CONSUMER_KEY=your_consumer_key
PROD_MPESA_CONSUMER_SECRET=your_consumer_secret
PROD_SECURITY_CREDENTIAL=your_security_credential

---

## Laravel Integration โš™๏ธ

In a Laravel controller:

```php
<?php

namespace App\Http\Controllers;

use Mpesa\Sdk\Authentication as MpesaAuth;
use Mpesa\Sdk\Client;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

class MpesaController extends Controller
{
    private function getClient(): Client
    {
        $env = env('APP_ENV', 'development');
        $config = config("mpesa.{$env}", [
            'base_url' => 'https://apisandbox.safaricom.et/mpesa/',
            'consumer_key' => 'YOUR_CONSUMER_KEY',
            'consumer_secret' => 'YOUR_CONSUMER_SECRET',
        ]);
        return new Client(array_merge($config, [
            'timeout' => 1, 'retries' => 5, 'retry_delay' => 10,
        ]));
    }

    private function authenticate(Client $client): string
    {
        $auth = new MpesaAuth($client);
        $token = $auth->generateToken();
        Log::info("M-Pesa Auth Success", ['token' => $token->accessToken]);
        return $token->accessToken;
    }

    private function getAccessToken(): string
    {
        return Cache::remember('mpesa_access_token', 3599, fn() => $this->authenticate($this->getClient()));
    }

    public function testSdk()
    {
        try {
            return response()->json(['token' => $this->getAccessToken()]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}

Api Route

Route::get('/test-mpesa', [MpesaController::class, 'testSdk']);

Route::prefix('mpesa')->group(function () {
    Route::get('/auth', [MpesaController::class, 'getToken']);
    Route::post('/balance', [MpesaController::class, 'checkBalance']);
    Route::post('/b2c/payout', [MpesaController::class, 'b2cPayout']);
    Route::post('/c2b/register', [MpesaController::class, 'c2bRegister']);
    Route::post('/c2b/simulate', [MpesaController::class, 'simulateTransaction']);
    Route::post('/stk/push', [MpesaController::class, 'stkPush']);
    Route::post('/reverse', [MpesaController::class, 'reverseTransaction']);
    Route::post('/status', [MpesaController::class, 'transactionStatus']);
});

Notes ๐Ÿ“

  • Service Classes: Each service class (e.g., StkPushService) encapsulates an API operation. Copy the full implementations from your project files.

  • Logging: Logs are written to the logs/ directory. Ensure it exists and is writable.

  • UUID: Some examples use ramsey/uuid. Install it with:

    composer require ramsey/uuid
  • Sandbox vs Production: Update base_url in Authentication.php for production use:

    'base_url' => 'https://apisandbox.safaricom.et/mpesa'

Instructions

  1. Open your README.md file in your project.
  2. Copy the entire content above.
  3. Paste it into your README.md, replacing the existing content.
  4. Save the file.

Testing Examples

This package uses Php for testing. To run the tests, use the following command:

   php  examples/Authentication.php
   php  examples/StkPush.php
   php  examples/C2BRegister.php
   php  examples/C2BValidate.php
   php  examples/C2BConfirm.php
   php  examples/SimulateTransaction.php
   php  examples/B2CPayOut.php
   php  examples/TransactionStatus.php
   php  examples/AccountBalance.php
   php  examples/TransactionReversal.php
   .

Customization

  • Paths: Adjust require paths based on where you place Authentication.php and service files.
  • Credentials: Replace placeholders (your_consumer_key, your_security_credential) with your actual values.
  • Extra Sections: Need "Contributing," "License," or "Troubleshooting" sections? Let me know, and Iโ€™ll expand it!

Support ๐Ÿ“ง