kahsaygt / mpesa-sdk-php
A PHP SDK for M-PESA API integration
Requires
- php: ^7.4|^8.0
- ext-curl: *
- guzzlehttp/guzzle: ^7.0
- ramsey/uuid: ^4.7
Requires (Dev)
- phpunit/phpunit: ^9.0
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
inAuthentication.php
for production use:'base_url' => 'https://apisandbox.safaricom.et/mpesa'
Instructions
- Open your
README.md
file in your project. - Copy the entire content above.
- Paste it into your
README.md
, replacing the existing content. - 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 placeAuthentication.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 ๐ง
- For issues or questions, open an issue on GitHub or contact kahsay21a@gmail.com
- Reach out on Telegram: @KahsayG21 ๐ฉ