README

A comprehensive PHP package for integrating with Safaricom's M-Pesa DARAJA API. This package provides a simple, elegant interface for all M-Pesa API endpoints including STK Push, B2C, B2B, C2B, and more.

Features

Complete API Coverage - All M-Pesa API endpoints supported
Easy to Use - Simple, intuitive interface
Well Documented - Comprehensive documentation for each endpoint
Framework Agnostic - Works with any PHP project
Laravel Support - Dedicated Laravel package available
Sandbox & Production - Easy switching between environments
Automatic Token Management - Handles authentication automatically
Callback Handling - Built-in support for M-Pesa callbacks

Requirements

PHP 7.0 or higher
cURL extension enabled
OpenSSL extension enabled

Installation

This package supports both Composer and manual installation.

Using Composer (Recommended)

composer require yourdudeken/mpesa

Manual Installation

Download the source code as a zip file
Extract to your project directory
Include the autoloader in your code:

<?php
require "{PATHTOTHISLIBFOLDER}/src/autoload.php";

use Yourdudeken\Mpesa\Init as Mpesa;

Laravel Users

For Laravel-specific implementation with facades and service providers, check out:
Laravel M-Pesa Package

Quick Start

Basic Usage

<?php
require "vendor/autoload.php";

use Yourdudeken\Mpesa\Init as Mpesa;

// Initialize with default config
$mpesa = new Mpesa();

// Or pass custom configuration
$mpesa = new Mpesa([
    'consumer_key' => 'your_consumer_key',
    'consumer_secret' => 'your_consumer_secret',
    'is_sandbox' => true
]);

try {
    // Initiate STK Push
    $response = $mpesa->STKPush([
        'amount' => 100,
        'phoneNumber' => '254722000000',
        'accountReference' => 'INV-001',
        'transactionDesc' => 'Payment for invoice'
    ]);
    
    echo json_encode($response);
} catch(\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Configuration

The package comes with a structured configuration file for easy setup.

Configuration File Location

src/config/mpesa.php

Key Configuration Options

return [
    // API Environment
    'apiUrl' => 'https://sandbox.safaricom.co.ke/',
    'is_sandbox' => true,
    
    // Credentials
    'apps' => [
        'default' => [
            'consumer_key' => 'your_consumer_key',
            'consumer_secret' => 'your_consumer_secret',
        ],
    ],
    
    // STK Push Configuration
    'lnmo' => [
        'short_code' => '174379',
        'passkey' => 'your_passkey',
        'callback' => 'https://yourdomain.com/callback',
    ],
    
    // B2C Configuration
    'b2c' => [
        'initiator_name' => 'testapi',
        'security_credential' => 'your_credential',
        'short_code' => '600000',
        'result_url' => 'https://yourdomain.com/result',
        'timeout_url' => 'https://yourdomain.com/timeout',
    ],
    
    // Additional configurations for B2B, C2B, etc.
];

Environment Setup

Sandbox (Testing)
- Set is_sandbox to true
- Use sandbox credentials from Safaricom Developer Portal
- API URL: https://sandbox.safaricom.co.ke/
Production (Live)
- Set is_sandbox to false
- Use production credentials
- API URL: https://api.safaricom.co.ke/

Available Methods

STK Push (Lipa na M-Pesa Online)

Initiate payment requests to customer phones:

$mpesa->STKPush([
    'amount' => 100,
    'phoneNumber' => '254722000000',
    'accountReference' => 'ORDER-123',
    'transactionDesc' => 'Payment for order'
]);

STK Status Query

Check the status of an STK Push request:

$mpesa->STKStatus([
    'checkoutRequestID' => 'ws_CO_191220191020363925'
]);

B2C (Business to Customer)

Send money to customer accounts:

$mpesa->B2C([
    'amount' => 100,
    'partyB' => '254722000000',
    'remarks' => 'Salary payment',
    'occasion' => 'Monthly salary'
]);

B2B (Business to Business)

Transfer funds between business accounts:

$mpesa->B2B([
    'amount' => 1000,
    'partyB' => '600000',
    'accountReference' => 'INV-001',
    'remarks' => 'Payment for supplies'
]);

B2Pochi (Business to Pochi)

Send money to customer Pochi savings accounts:

$mpesa->B2Pochi([
    'amount' => 100,
    'partyB' => '254722000000',
    'remarks' => 'Savings deposit'
]);

C2B Register

$mpesa->C2BRegister([
    'validationURL' => 'https://yourdomain.com/validate',
    'confirmationURL' => 'https://yourdomain.com/confirm',
    'responseType' => 'Completed'
]);

C2B Simulate

Simulate C2B payments (sandbox only):

$mpesa->C2BSimulate([
    'amount' => 100,
    'msisdn' => '254722000000',
    'billRefNumber' => 'INV-001'
]);

Account Balance

Query account balance:

$mpesa->accountBalance([
    'remarks' => 'Balance query'
]);

Transaction Status

Check transaction status:

$mpesa->transactionStatus([
    'transactionID' => 'NLJ7RT61SV',
    'remarks' => 'Status check'
]);

Reversal

Reverse erroneous transactions:

$mpesa->reversal([
    'transactionID' => 'NLJ7RT61SV',
    'amount' => 100,
    'receiverParty' => '600000',
    'remarks' => 'Reversing duplicate payment'
]);

API Documentation

Comprehensive documentation for each API endpoint is available in the docs folder:

1. Lipa na M-Pesa Online (STK Push)

Initiate payment requests directly to customer phones. Customers authorize payments by entering their M-Pesa PIN.

Use Cases: E-commerce checkout, bill payments, donations, subscriptions

2. Lipa na M-Pesa Online Query

Query the status of STK Push requests to verify payment completion.

Use Cases: Payment verification, transaction reconciliation

3. C2B (Customer to Business)

Receive real-time notifications when customers make payments to your Till or Paybill number.

Use Cases: Payment notifications, automatic reconciliation, real-time payment processing

4. B2C (Business to Customer)

Send money from your business account to customer M-Pesa accounts.

Use Cases: Salary payments, refunds, promotions, rewards, withdrawals

5. B2B (Business to Business)

Transfer funds between business accounts (PayBill to PayBill or Till to Till).

Use Cases: Supplier payments, business settlements, inter-branch transfers

6. B2Pochi (Business to Pochi)

Send money directly to customer Pochi savings accounts.

Use Cases: Savings programs, rewards, targeted savings deposits

7. Transaction Status

Query the status of any M-Pesa transaction for verification and reconciliation.

Use Cases: Dispute resolution, transaction verification, reconciliation

8. Reversal

Reverse erroneous M-Pesa transactions.

Use Cases: Correcting payment errors, duplicate payment reversals, refunds

9. Account Balance

Query your business account balance on demand.

Use Cases: Balance monitoring, pre-transaction validation, financial reporting

Code Examples

Complete STK Push Example

<?php
require "vendor/autoload.php";

use Yourdudeken\Mpesa\Init as Mpesa;

$mpesa = new Mpesa();

try {
    // Initiate payment
    $response = $mpesa->STKPush([
        'amount' => 100,
        'phoneNumber' => '254722000000',
        'accountReference' => 'ORDER-12345',
        'transactionDesc' => 'Payment for order #12345',
        'callBackURL' => 'https://yourdomain.com/mpesa/callback'
    ]);
    
    // Store the CheckoutRequestID for status queries
    $checkoutRequestID = $response->CheckoutRequestID;
    
    // Return response to user
    header('Content-Type: application/json');
    echo json_encode([
        'success' => true,
        'message' => 'Payment request sent. Please check your phone.',
        'checkoutRequestID' => $checkoutRequestID
    ]);
    
} catch(\Exception $e) {
    header('Content-Type: application/json');
    http_response_code(500);
    echo json_encode([
        'success' => false,
        'message' => 'Payment request failed: ' . $e->getMessage()
    ]);
}

Handling STK Push Callback

<?php
require "vendor/autoload.php";

// Get callback data
$callbackData = file_get_contents('php://input');
$callback = json_decode($callbackData, true);

// Extract result
$resultCode = $callback['Body']['stkCallback']['ResultCode'];

if ($resultCode == 0) {
    // Payment successful
    $metadata = $callback['Body']['stkCallback']['CallbackMetadata']['Item'];
    
    $amount = null;
    $mpesaReceiptNumber = null;
    $phoneNumber = null;
    
    foreach ($metadata as $item) {
        if ($item['Name'] == 'Amount') {
            $amount = $item['Value'];
        }
        if ($item['Name'] == 'MpesaReceiptNumber') {
            $mpesaReceiptNumber = $item['Value'];
        }
        if ($item['Name'] == 'PhoneNumber') {
            $phoneNumber = $item['Value'];
        }
    }
    
    // Update your database
    // Mark order as paid, send confirmation, etc.
    
    error_log("Payment successful: $mpesaReceiptNumber - Amount: $amount");
    
} else {
    // Payment failed
    $resultDesc = $callback['Body']['stkCallback']['ResultDesc'];
    error_log("Payment failed: $resultDesc");
}

// Always respond to Safaricom
header('Content-Type: application/json');
echo json_encode(['ResultCode' => 0, 'ResultDesc' => 'Success']);

B2C Payment Example

<?php
require "vendor/autoload.php";

use Yourdudeken\Mpesa\Init as Mpesa;

$mpesa = new Mpesa();

try {
    $response = $mpesa->B2C([
        'amount' => 500,
        'partyB' => '254722000000',
        'remarks' => 'December salary payment',
        'occasion' => 'Salary',
        'commandID' => 'SalaryPayment',
        'resultURL' => 'https://yourdomain.com/mpesa/b2c/result',
        'queueTimeOutURL' => 'https://yourdomain.com/mpesa/b2c/timeout'
    ]);
    
    echo json_encode($response);
    
} catch(\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Testing

The package includes comprehensive unit tests. Run tests using:

vendor/bin/phpunit

Troubleshooting

Common Issues

Issue: "Invalid Access Token"
Solution: Check your consumer key and secret. Ensure they match your environment (sandbox/production).

Issue: "STK DS timeout"
Solution: Some SIM cards don't support STK Push. This is a Safaricom limitation.

Issue: Callback not received
Solution: Ensure your callback URL is publicly accessible via HTTPS. Use tools like ngrok for local testing.

Issue: "Insufficient permissions"
Solution: Verify your initiator credentials have the required permissions for the operation.

Security Best Practices

Never commit credentials - Use environment variables for sensitive data
Use HTTPS - All callback URLs must use HTTPS in production
Validate callbacks - Verify callbacks are from Safaricom (IP whitelisting)
Implement idempotency - Handle duplicate callback notifications
Secure your endpoints - Protect callback URLs from unauthorized access
Log everything - Maintain audit trails of all transactions
Handle errors gracefully - Don't expose sensitive error details to users

Support

Need help with integration?

Email: kenmwendwamuthengi@gmail.com
Telegram: @yourdudeken
Documentation: docs folder
Issues: GitHub Issues

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Changelog

Latest Updates

Added B2Pochi payment method support
Comprehensive documentation for all endpoints
Improved error handling
Enhanced callback processing examples
Updated configuration structure

Inspiration

This package was inspired by the excellent work from @SmoDav on the SmoDav/mpesa project.

Contributors

Special thanks to all contributors who have helped improve this package:

_{Kennedy Muthengi}

License

The M-Pesa Package is open-sourced software licensed under the MIT license.

Made with love in Kenya

yourdudeken / mpesa

Maintainers

Details