README

AstraPay PHP SDK

AstraPay is a lightweight PHP SDK that simplifies integrating Safaricom M-Pesa STK Push, C2B (Customer to Business), and B2C (Business to Customer) APIs into your web applications. Built and maintained by Astra Softwares, this SDK allows you to initiate secure mobile payments and disbursements with ease.

📦 Installation

Install via Composer:

composer require astrasoftwares/astrapay

Requires PHP >= 7.4

⚙️ Configuration

Initialize the client with your credentials. Depending on the service you are using (STK, C2B, or B2C), different keys are required.

require 'vendor/autoload.php';

use Astrapay\AstraMpesa;

$config = [
    'consumerKey'    => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
    'shortcode'      => '174379', // Paybill or Till Number
    'passkey'        => 'YOUR_PASSKEY', // Required for STK Push
    'callbackUrl'    => 'https://yourdomain.com/callback', // Global callback for STK
    'env'            => 'sandbox', // 'sandbox' or 'live'
    
    // Required only for B2C
    'initiatorName'      => 'YOUR_INITIATOR_NAME',
    'securityCredential' => 'YOUR_ENCRYPTED_CREDENTIAL' 
];

$client = new AstraMpesa($config);

🚀 Usage Examples

1. STK Push (M-Pesa Express)

Initiate a payment prompt on the customer's phone.

// Simple usage
$response = $client->pay('254712345678', 100); 

// Advanced usage with custom reference and description
$response = $client->pay(
    '254712345678', 
    100, 
    'Invoice #102', // Account Reference
    'School Fees'   // Transaction Description
);

print_r($response);

2. C2B (Customer to Business)

Handle payments sent directly to your Paybill/Till via the SIM toolkit.

Step A: Register URLs (Run Once) You must tell Safaricom where to send validation and confirmation data.

$client->registerC2BUrls(
    'https://yourdomain.com/mpesa/validation',
    'https://yourdomain.com/mpesa/confirmation'
);

Step B: Simulate C2B (Sandbox Only) Since you cannot use real money in Sandbox, use this to test your confirmation URLs.

$client->simulateC2B(
    '254708374149', 
    1000, 
    'INV/001' // BillRefNumber
);

3. B2C (Business to Customer)

Send money from your business account to a user (e.g., Salaries, Refunds).

$response = $client->b2cPayment(
    '254712345678', 
    500, 
    'BusinessPayment', // Options: SalaryPayment, BusinessPayment, PromotionPayment
    'Refund for Order #20', // Remarks
    'https://yourdomain.com/b2c/timeout', // Queue Timeout URL
    'https://yourdomain.com/b2c/result'   // Result URL
);

print_r($response);

🔐 How to Get M-Pesa API Credentials

To integrate with M-Pesa, you’ll need to create a Safaricom Daraja developer account:

1. Register on Daraja Portal ➔ https://developer.safaricom.co.ke
2. Create an App

• Log in and click “My Apps” → “Add a New App”
• Ensure you check the boxes for:
• Lipa na M-Pesa Sandbox (for STK)
• M-Pesa Sandbox (for C2B/B2C)

1. Get your Credentials:

• Consumer Key & Secret: Found in your App dashboard.
• Passkey: Generated via the "Simulate" tab in Daraja or sent via email in production.
• Security Credential (B2C Only): This is an encrypted password. In Sandbox, Safaricom provides a test credential. In Production, you must generate it using the M-Pesa Public Certificate.

🧲 Sample Test Numbers (Sandbox)

Use the sandbox environment for development/testing. When moving to production (env => 'live'), ensure your Shortcode is active and approved by Safaricom.

📖 Documentation

• Python SDK
• JavaScript SDK

🤝 Contribute

Pull requests are welcome! If you find a bug or want a feature added, open an issue or submit a PR.

🧑‍💻 Author

Built with ❤️ by Ishmael Bett 📧 info.astrasoft@gmail.com

📄 License

This project is licensed under the MIT License.