initial commit

Author: ApeliDev

.env.example

@@ -0,0 +1,83 @@
+# Application Environment
+APP_ENV=development  # Options: development, staging, production
+
+# Debug Mode (true for development, false for production)
+APP_DEBUG=false
+
+# Logging Configuration
+LOG_LEVEL=debug  # Options: debug, info, warning, error
+LOG_PATH=./logs
+
+# M-Pesa API Version
+MPESA_API_VERSION=v1
+
+# M-Pesa API Credentials
+MPESA_CONSUMER_KEY=consumer_key_here
+MPESA_CONSUMER_SECRET=consumer_secret_here
+MPESA_PASSKEY=passkey  # For STK Push
+MPESA_SHORTCODE=yshortcode  # Business Short Code
+
+MPESA_INITIATOR_PASSWORD=your_initiator_password
+MPESA_CERTIFICATE_PATH=path/to/certificate.pem
+
+# M-Pesa API Endpoints
+# Sandbox URLs (for development and testing)
+MPESA_BASE_URL_SANDBOX=https://sandbox.safaricom.co.ke
+MPESA_OAUTH_TOKEN_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/oauth/v1/generate
+MPESA_STK_PUSH_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/stkpush/v1/processrequest
+MPESA_STK_QUERY_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/stkpushquery/v1/query
+MPESA_C2B_REGISTER_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/c2b/v1/registerurl
+MPESA_C2B_SIMULATE_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/c2b/v1/simulate
+MPESA_B2C_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/b2c/v1/paymentrequest
+MPESA_B2B_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/b2b/v1/paymentrequest
+MPESA_TRANSACTION_STATUS_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/transactionstatus/v1/query
+MPESA_ACCOUNT_BALANCE_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/accountbalance/v1/query
+MPESA_REVERSAL_URL_SANDBOX=${MPESA_BASE_URL_SANDBOX}/mpesa/reversal/v1/request
+
+# Production URLs (for live environment)
+MPESA_BASE_URL_PRODUCTION=https://api.safaricom.co.ke
+MPESA_OAUTH_TOKEN_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/oauth/v1/generate
+MPESA_STK_PUSH_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/stkpush/v1/processrequest
+MPESA_STK_QUERY_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/stkpushquery/v1/query
+MPESA_C2B_REGISTER_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/c2b/v1/registerurl
+MPESA_C2B_SIMULATE_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/c2b/v1/simulate
+MPESA_B2C_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/b2c/v1/paymentrequest
+MPESA_B2B_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/b2b/v1/paymentrequest
+MPESA_TRANSACTION_STATUS_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/transactionstatus/v1/query
+MPESA_ACCOUNT_BALANCE_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/accountbalance/v1/query
+MPESA_REVERSAL_URL_PRODUCTION=${MPESA_BASE_URL_PRODUCTION}/mpesa/reversal/v1/request
+
+
+# Callback URLs 
+MPESA_STK_CALLBACK_URL=https://example.com/api/callbacks/stk
+MPESA_C2B_CONFIRMATION_URL=https://example.com/api/callbacks/c2b/confirmation
+MPESA_C2B_VALIDATION_URL=https://example.com/api/callbacks/c2b/validation
+MPESA_B2C_RESULT_URL=https://example.com/api/callbacks/b2c/result
+MPESA_B2C_TIMEOUT_URL=https://example.com/api/callbacks/b2c/timeout
+MPESA_B2B_RESULT_URL=https://example.com/api/callbacks/b2b/result
+MPESA_B2B_TIMEOUT_URL=https://example.com/api/callbacks/b2b/timeout
+MPESA_ACCOUNT_BALANCE_RESULT_URL=https://example.com/api/callbacks/accountbalance/result
+MPESA_ACCOUNT_BALANCE_TIMEOUT_URL=https://example.com/api/callbacks/accountbalance/timeout
+MPESA_REVERSAL_RESULT_URL=https://example.com/api/reversal/result
+MPESA_REVERSAL_TIMEOUT_URL=https://example.com/api/reversal/timeout
+MPESA_TRANSACTION_STATUS_RESULT_URL=https://example.com/api/status/result
+MPESA_TRANSACTION_STATUS_TIMEOUT_URL=https://example.com/api/status/timeout
+
+
+# Transaction Type Identifiers
+MPESA_COMMAND_ID_B2C_SALARY=SalaryPayment
+MPESA_COMMAND_ID_B2C_PAYMENT=BusinessPayment
+MPESA_COMMAND_ID_B2C_PROMOTION=PromotionPayment
+
+# Security Settings
+MPESA_INITIATOR_NAME=your_initiator_name  # For B2C, B2B, Transaction Status, etc.
+MPESA_SECURITY_CREDENTIAL=your_encrypted_security_credential  # Base64 encoded
+
+# Timeout settings (in seconds)
+HTTP_TIMEOUT=30
+
+# Cache settings
+CACHE_ENABLED=true
+CACHE_DRIVER=file  # Options: file, redis, memcached
+CACHE_PREFIX=mpesa_
+CACHE_TTL=3600  # Token caching time in seconds

LICENSE

@@ -0,0 +1,205 @@
+# M-Pesa PHP Library
+
+This library provides a simple and flexible way to integrate M-Pesa API services into your PHP application. It supports STK Push, C2B, B2C, transaction status queries, and reversals.
+
+---
+
+## Features
+- **STK Push**: Initiate Lipa Na M-Pesa Online payments.
+- **C2B**: Handle customer-to-business transactions.
+- **B2C**: Process business-to-customer payments.
+- **Transaction Status**: Query the status of transactions.
+- **Reversal**: Reverse transactions.
+
+---
+
+## Installation
+
+Install the library via Composer:
+
+```bash
+composer require apelimpesa/mpesa
+```
+
+---
+
+## Configuration
+
+### Step 1: Copy the Example Environment File
+
+The library includes an `.env.example` file with all required configuration variables. Copy this file to your project root as `.env`:
+
+```bash
+cp vendor/apelimpesa/mpesa/.env.example .env
+```
+
+### Step 2: Configure Your Environment Variables
+
+Edit the `.env` file with your M-Pesa API credentials and settings:
+
+```ini
+# ==============================================
+# M-PESA API CONFIGURATION
+# ==============================================
+
+# Application Environment (development/production)
+APP_ENV=development
+
+# M-Pesa API Credentials
+MPESA_CONSUMER_KEY=your_consumer_key
+MPESA_CONSUMER_SECRET=your_consumer_secret
+MPESA_SHORTCODE=your_shortcode
+MPESA_PASSKEY=your_passkey
+
+# Security Credentials
+MPESA_INITIATOR_NAME=your_initiator_name
+MPESA_INITIATOR_PASSWORD=your_initiator_password
+MPESA_CERTIFICATE_PATH=path/to/your/cert.pem
+
+# ==============================================
+# CALLBACK URLS
+# ==============================================
+
+# C2B URLs
+MPESA_C2B_VALIDATION_URL=https://yourdomain.com/api/c2b/validate
+MPESA_C2B_CONFIRMATION_URL=https://yourdomain.com/api/c2b/confirm
+
+# B2C URLs
+MPESA_B2C_RESULT_URL=https://yourdomain.com/api/b2c/result
+MPESA_B2C_TIMEOUT_URL=https://yourdomain.com/api/b2c/timeout
+
+# Transaction Status URLs
+MPESA_TRANSACTION_STATUS_RESULT_URL=https://yourdomain.com/api/status/result
+MPESA_TRANSACTION_STATUS_TIMEOUT_URL=https://yourdomain.com/api/status/timeout
+
+# Reversal URLs
+MPESA_REVERSAL_RESULT_URL=https://yourdomain.com/api/reversal/result
+MPESA_REVERSAL_TIMEOUT_URL=https://yourdomain.com/api/reversal/timeout
+```
+
+### Step 3: Required Variables
+
+| Variable                     | Description                                      | Required For          |
+|------------------------------|--------------------------------------------------|-----------------------|
+| `APP_ENV`                    | Application environment (`development`/`production`) | All operations        |
+| `MPESA_CONSUMER_KEY`         | Your M-Pesa API consumer key                    | All operations        |
+| `MPESA_CONSUMER_SECRET`      | Your M-Pesa API consumer secret                 | All operations        |
+| `MPESA_SHORTCODE`            | Your business shortcode                         | All operations        |
+| `MPESA_PASSKEY`              | Your Lipa Na M-Pesa Online passkey              | STK Push              |
+| `MPESA_INITIATOR_NAME`       | B2C/B2B transaction initiator name              | B2C/B2B               |
+| `MPESA_INITIATOR_PASSWORD`   | Encrypted initiator password                    | B2C/B2B               |
+| `MPESA_CERTIFICATE_PATH`     | Path to your M-Pesa certificate (if required)   | Optional for security |
+
+---
+
+## Usage
+
+### Step 1: Load Environment Variables
+
+Ensure your application loads the `.env` file. For non-Laravel projects, use `vlucas/phpdotenv`:
+
+```php
+require_once __DIR__.'/vendor/autoload.php';
+
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
+$dotenv->load();
+```
+
+### Step 2: Initialize the Library
+
+Create an instance of the M-Pesa service:
+
+```php
+use ApeliMpesa\Mpesa\Mpesa;
+
+$mpesa = new Mpesa([
+    'consumer_key' => getenv('MPESA_CONSUMER_KEY'),
+    'consumer_secret' => getenv('MPESA_CONSUMER_SECRET'),
+    'shortcode' => getenv('MPESA_SHORTCODE'),
+    'passkey' => getenv('MPESA_PASSKEY'),
+    'environment' => getenv('APP_ENV'), // 'development' or 'production'
+]);
+```
+
+### Step 3: Perform Transactions
+
+#### 1. STK Push (Lipa Na M-Pesa Online)
+
+```php
+$response = $mpesa->stkPush([
+    'amount' => 100,
+    'phone' => '+254712345678',
+    'reference' => 'Order123',
+    'description' => 'Payment for Order123',
+    'callback_url' => 'https://yourdomain.com/api/stk/callback',
+]);
+
+if ($response->isSuccessful()) {
+    echo "STK Push initiated successfully. CheckoutRequestID: " . $response->getCheckoutRequestID();
+} else {
+    echo "Error: " . $response->getErrorMessage();
+}
+```
+
+#### 2. Query Transaction Status
+
+```php
+$response = $mpesa->queryTransactionStatus('CheckoutRequestID123');
+
+if ($response->isSuccessful()) {
+    echo "Transaction completed successfully.";
+} else {
+    echo "Error: " . $response->getErrorMessage();
+}
+```
+
+#### 3. Reverse a Transaction
+
+```php
+$response = $mpesa->reverseTransaction([
+    'transaction_id' => 'TransactionID123',
+    'amount' => 100,
+    'receiver' => '600000',
+    'receiver_type' => 'Paybill',
+    'callback_url' => 'https://yourdomain.com/api/reversal/callback',
+]);
+
+if ($response->isSuccessful()) {
+    echo "Transaction reversed successfully.";
+} else {
+    echo "Error: " . $response->getErrorMessage();
+}
+```
+
+---
+
+## Testing with Sandbox
+
+When `APP_ENV=development`, the library uses M-Pesa's sandbox environment. No real money is transferred during testing.
+
+For production, set:
+
+```ini
+APP_ENV=production
+```
+
+---
+
+## Security Notes
+
+- Use different credentials for development and production environments.
+- Keep your `.env` file secure and avoid committing it to version control.
+
+---
+
+## Requirements
+
+- PHP 7.4 or higher
+- Composer
+- cURL extension enabled
+
+---
+
+## License
+
+This library is open-source and available under the [MIT License](LICENSE).

README.md

@@ -0,0 +1,93 @@
+{
+    "name": "apelimpesa/mpesa-php",
+    "description": "A comprehensive PHP library for integrating with the M-Pesa API",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "mpesa",
+        "safaricom",
+        "payment",
+        "api",
+        "mobile-money",
+        "kenya",
+        "africa"
+    ],
+    "authors": [
+        {
+            "name": "Livingstone Apeli",
+            "email": "[email protected]",
+            "homepage": "https://apelisolutions.com",
+            "role": "Software Developer"
+        }
+        
+    ],
+    "support": {
+        "email": "[email protected]",
+        "issues": "https://github.com/ApeliDev/mpesa-php/issues",
+        "source": "https://github.com/ApeliDev/mpesa-php",
+        "docs": "https://ApeliDev.github.io/mpesa-php"
+    },
+    "funding": [
+        {
+            "type": "github",
+            "url": "https://github.com/sponsors/ApeliDev"
+        },
+        {
+            "type": "patreon",
+            "url": "https://www.patreon.com/ApeliDev"
+        }
+    ],
+    "minimum-stability": "stable",
+    "prefer-stable": true,
+    "require": {
+        "php": ">=7.4",
+        "guzzlehttp/guzzle": "^7.0",
+        "monolog/monolog": "^2.9",
+        "nesbot/carbon": "^2.0",
+        "vlucas/phpdotenv": "^5.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5",
+        "mockery/mockery": "^1.4",
+        "squizlabs/php_codesniffer": "^3.6",
+        "phpstan/phpstan": "^1.0",
+        "friendsofphp/php-cs-fixer": "^3.0",
+        "phpmd/phpmd": "^2.10"
+    },
+    "autoload": {
+        "psr-4": {
+            "ApeliMpesa\\Mpesa\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "ApeliMpesa\\Mpesa\\Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "test": "phpunit",
+        "check-style": "phpcs -p --standard=PSR12 src tests",
+        "fix-style": "phpcbf -p --standard=PSR12 src tests",
+        "analyse": "phpstan analyse --level=7 src",
+        "md": "phpmd src text cleancode,codesize,controversial,design,naming,unusedcode",
+        "cs-fix": "php-cs-fixer fix --using-cache=no",
+        "check-all": [
+            "@check-style",
+            "@analyse",
+            "@md",
+            "@test"
+        ]
+    },
+    "config": {
+        "sort-packages": true,
+        "optimize-autoloader": true,
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true
+        }
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-main": "1.0-dev"
+        }
+    }
+}