Getting Started

Welcome to the comprehensive PesaFlux API documentation. This guide will help you understand how to integrate our payment and SMS services into your applications. Our APIs are designed to be developer-friendly with clear documentation and practical examples.

PesaFlux offers multiple services:

  • Mpesa Integration: STK Push payments and transaction status checking
  • FluxSMS: Single and bulk SMS sending capabilities
  • Wallet Services: Fund management and instant withdrawals
  • Webhooks: Real-time notifications for your applications

To get started with our API integration, you need an API Key. To obtain one:

  1. Login to your PesaFlux Account
  2. Navigate to Linked Accounts and copy your API Key
  3. If you see "no data", go to Account Setup and link your Till, Paybill, or Bank Account
  4. You'll then be redirected to Linked Accounts where you can get your API Key

Mpesa API Integration

PesaFlux Mpesa API enables you to collect payments on your website or mobile app through M-Pesa STK Push. The money is automatically sent to your M-Pesa till number, paybill number, or bank account that you have connected to your PesaFlux account.

Initiate STK Push

POST
https://api.pesaflux.co.ke/v1/initiatestk

Headers

Header Description Value
Content-Type The Accept request HTTP header advertises which content types the client can understand. application/json

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb
email string Required Email that you use to login into PesaFlux Account example@gmail.com
amount number Required Amount to request from your customer in KES 1
msisdn string Required Phone number to request money from 254768783443 OR 0768783443
reference string Optional A unique reference that will be used to identify the transaction 6527990

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "amount": "30",
    "msisdn": "254768783443",
    "reference": "6527990"
}

Success Response

200 OK - Success Response
{
    "success": "200",
    "massage": "Request sent sucessfully.",
    "transaction_request_id": "SOFTPID2809202423523970891"
}

Callback Response (Success)

Webhook Success Payload
{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "dab3-4cb9-9110-99918efd35e39105683",
    "CheckoutRequestID": "ws_CO_28092024222014167769290734",
    "TransactionID": "SOFTPID2809202422201241148",
    "TransactionAmount": 2,
    "TransactionReceipt": "SIS88JC7AM",
    "TransactionDate": "20240928222012",
    "TransactionReference": "8803416",
    "Msisdn": "254769290734"
}

Error Response

Error Response Example
{
    "ResponseCode": 1032,
    "ResponseDescription": "Request cancelled by user",
    "MerchantRequestID": "c687-4e11-bbe3-3e2fd41c9911951313",
    "CheckoutRequestID": "ws_CO_28092024232536273769290734",
    "TransactionID": "SOFTPID2809202423253425286",
    "TransactionAmount": 640,
    "TransactionDate": "20240928232534",
    "TransactionReference": "1",
    "Msisdn": "254769290734"
}

Error Response Codes

ResponseCode ResponseDescription
0 Success. Request accepted for processing
1 The balance is insufficient for the transaction.
1032 Request cancelled by user
1037 DS timeout user cannot be reached
1025 An error occurred while sending a push request
9999 An error occurred while sending a push request.
2001 The initiator information is invalid.
1019 Transaction has expired
1001 Unable to lock subscriber, a transaction is already in process for the current subscriber

Transaction Status

POST
https://api.pesaflux.co.ke/v1/transactionstatus

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb
email string Required Email that you use to login into PesaFlux Account example@gmail.com
transaction_request_id string Required Transaction id that you get after initiating stk push SOFTPID2809202423253425286

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "email": "example@gmail.com",
    "transaction_request_id": "SOFTPID2809202423253425286"
}

Response

Transaction Status Response
{
    "ResultCode": "200",
    "ResultDesc": "Success. Request accepted for processing",
    "TransactionID": "SOFTPID2809202423523970891",
    "TransactionStatus": "Completed",
    "TransactionCode": "0",
    "TransactionReceipt": "SIS48OB9N4",
    "TransactionAmount": "10",
    "Msisdn": "254768783443",
    "TransactionDate": "202423491281280",
    "TransactionReference": "8803416"
}

FluxSMS API

FluxSMS API allows you to send single and bulk SMS messages to Kenyan phone numbers. Our SMS service is reliable, fast, and cost-effective for all your messaging needs.

Send Single SMS

POST
https://api.fluxsms.co.ke/sendsms

Headers

Header Description Value
Content-Type The Accept request HTTP header advertises which content types the client can understand. application/json

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb
phone string Required Kenyan phone number (0712345678 or 254712345678) 0769290734
message string Required SMS message content (max 160 characters per SMS) Hello from FluxSMS!
sender_id string Required Sender ID for the SMS (default: fluxsms) fluxsms

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "phone": "0769290734",
    "message": "Hello from FluxSMS API!",
    "sender_id": "fluxsms"
}

PHP Example

PHP - Single SMS
<?php
function sendSMS($phone, $message, $sender_id = 'fluxsms') {
    $endpoint = "https://api.fluxsms.co.ke/sendsms";
    
    $payload = [
        "api_key" => "YOUR_API_KEY",
        "phone" => $phone,
        "message" => $message,
        "sender_id" => $sender_id
    ];
    
    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = sendSMS("0769290734", "Hello from FluxSMS!", "fluxsms");
echo json_encode($result);
?>

Success Response

200 OK - SMS Sent Successfully
{
    "response-code": 200,
    "response-description": "SMS sent successfully",
    "message_id": "SMS_20241201_123456789",
    "phone": "0769290734",
    "message": "Hello from FluxSMS!",
    "sender_id": "fluxsms",
    "cost": 1,
    "status": "sent"
}

Send Bulk SMS

POST
https://api.fluxsms.co.ke/bulksms

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb
phones array Required Array of Kenyan phone numbers ["0769290734", "0712345678"]
message string Required SMS message content Bulk SMS from FluxSMS!
sender_id string Required Sender ID for the SMS (default: fluxsms) fluxsms

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "phones": ["0769290734", "0712345678", "0722345678"],
    "message": "Bulk SMS from FluxSMS API!",
    "sender_id": "fluxsms"
}

PHP Example

PHP - Bulk SMS
<?php
function sendBulkSMS($phones, $message, $sender_id = 'fluxsms') {
    $endpoint = "https://api.fluxsms.co.ke/bulksms";
    
    $payload = [
        "api_key" => "YOUR_API_KEY",
        "phones" => $phones,
        "message" => $message,
        "sender_id" => $sender_id
    ];
    
    $ch = curl_init($endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$phones = ["0769290734", "0712345678", "0722345678"];
$result = sendBulkSMS($phones, "Bulk SMS from FluxSMS!", "fluxsms");
echo json_encode($result);
?>

Success Response

200 OK - Bulk SMS Sent Successfully

   {
    "responses": [
        {
            "response-code": 200,
            "response-description": "Success",
            "mobile": "0769290734",
            "messageid": "2058323784",
            "clientsmsid": 365599,
            "networkid": 1
        },
        {
            "response-code": 200,
            "response-description": "Success",
            "mobile": "0112076941",
            "messageid": "2058323785",
            "clientsmsid": 500073,
            "networkid": 1
        }
    ],
    "success": true,
    "sent": 2
}

SMS Status Check

POST
https://api.fluxsms.co.ke/smsstatus

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb
message_id string Required Message ID returned when SMS was sent SMS_20241201_123456789

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    "message_id": "SMS_20241201_123456789"
}

Response

SMS Status Response
{
    "response-code": 200,
    "message-id": "2057725612",
    "response-description": "Success",
    "delivery-status": 32,
    "delivery-description": "DeliveredToTerminal",
    "delivery-tat": "0.17 sec",
    "delivery-networkid": 1,
    "delivery-time": "2025-07-12 22:02:46"
}

SMS Status Values

Status Description
pending SMS is queued for sending
sent SMS has been sent to the network
delivered SMS has been delivered to the recipient
failed SMS delivery failed
unknown Delivery status is unknown

SMS Balance Check

POST
https://api.fluxsms.co.ke/check_sms_balanace

Parameters

Parameter Type Required Description Sample Value
api_key string Required API key obtained from your PesaFlux Account nluhfjdgbmzfyjrwzsbqkwcsijb

Request Example

JSON Request Body
{
    "api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
    
}

Response

SMS Status Response
{
    "success": true,
    "sms_balance": 53721
}

WebHooks

WebHooks allow your application to receive real-time notifications when transactions are completed. This eliminates the need to continuously poll our API for transaction status updates.

Setting Up WebHooks

  1. Login to your PesaFlux account at https://pesaflux.co.ke/user
  2. Navigate to Account Settings or API Settings
  3. Enter your webhook URL in the designated field
  4. Save your settings
  5. Test your webhook endpoint to ensure it can receive POST requests

Webhook Payload Structure

When a transaction is completed, PesaFlux will send a POST request to your webhook URL with the following payload:

Webhook Payload Example
{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "dab3-4cb9-9110-99918efd35e39105683",
    "CheckoutRequestID": "ws_CO_28092024222014167769290734",
    "TransactionID": "SOFTPID2809202422201241148",
    "TransactionAmount": 100,
    "TransactionReceipt": "SIS88JC7AM",
    "TransactionDate": "20240928222012",
    "TransactionReference": "ORDER_12345",
    "Msisdn": "254769290734"
}

Webhook Parameters

Parameter Type Description
ResponseCode integer Transaction response code (0 = success, other = error)
ResponseDescription string Human-readable description of the transaction result
MerchantRequestID string Unique identifier for the merchant request
CheckoutRequestID string Unique identifier for the checkout request
TransactionID string PesaFlux transaction identifier
TransactionAmount number Amount transacted in KES
TransactionReceipt string M-Pesa transaction receipt number
TransactionDate string Date and time when transaction was completed
TransactionReference string Your custom reference passed during STK initiation
Msisdn string Phone number that made the payment

PHP Webhook Handler Example

PHP Webhook Handler
<?php
// webhook.php - Handle PesaFlux webhook notifications

// Get the raw POST data
$json = file_get_contents('php://input');
$data = json_decode($json, true);

// Log the webhook data for debugging
error_log("PesaFlux Webhook: " . $json);

// Validate the webhook data
if (!$data || !isset($data['TransactionID'])) {
    http_response_code(400);
    echo "Invalid webhook data";
    exit;
}

// Extract transaction details
$responseCode = $data['ResponseCode'];
$transactionId = $data['TransactionID'];
$amount = $data['TransactionAmount'];
$receipt = $data['TransactionReceipt'];
$phone = $data['Msisdn'];
$reference = $data['TransactionReference'];

// Process the transaction based on response code
if ($responseCode == 0) {
    // Transaction successful
    processSuccessfulPayment($transactionId, $amount, $receipt, $phone, $reference);
    
    // Send success response
    http_response_code(200);
    echo json_encode(['status' => 'success', 'message' => 'Webhook processed']);
    
} else {
    // Transaction failed
    processFailedPayment($transactionId, $responseCode, $data['ResponseDescription']);
    
    // Send success response (acknowledge receipt)
    http_response_code(200);
    echo json_encode(['status' => 'received', 'message' => 'Failed transaction logged']);
}

function processSuccessfulPayment($transactionId, $amount, $receipt, $phone, $reference) {
    // Your business logic here
    // Example: Update database, send confirmation email, etc.
    
    // Database connection (replace with your details)
    $pdo = new PDO('mysql:host=localhost;dbname=your_db', 'username', 'password');
    
    // Update payment status in database
    $stmt = $pdo->prepare("
        UPDATE payments 
        SET status = 'completed', 
            transaction_receipt = ?, 
            completed_at = NOW() 
        WHERE transaction_id = ?
    ");
    $stmt->execute([$receipt, $transactionId]);
    
    // Send confirmation email/SMS to customer
    sendConfirmation($phone, $amount, $receipt);
}

function processFailedPayment($transactionId, $responseCode, $description) {
    // Log failed transaction
    $pdo = new PDO('mysql:host=localhost;dbname=your_db', 'username', 'password');
    
    $stmt = $pdo->prepare("
        UPDATE payments 
        SET status = 'failed', 
            failure_reason = ?, 
            failed_at = NOW() 
        WHERE transaction_id = ?
    ");
    $stmt->execute([$description, $transactionId]);
}

function sendConfirmation($phone, $amount, $receipt) {
    // Send SMS confirmation using FluxSMS API
    $message = "Payment of KES {$amount} received successfully. Receipt: {$receipt}. Thank you!";
    
    // Use FluxSMS API to send confirmation
    // Implementation depends on your SMS setup
}
?>

Webhook Security Best Practices

  • Validate webhook data: Always validate incoming webhook data before processing
  • Use HTTPS: Ensure your webhook endpoint uses HTTPS for secure communication
  • Implement idempotency: Handle duplicate webhook calls gracefully
  • Log webhook data: Keep logs of all webhook calls for debugging and audit purposes
  • Respond quickly: Return HTTP 200 status code within 10 seconds
  • Handle failures: Implement proper error handling and retry mechanisms

Testing Your Webhook

You can test your webhook endpoint using tools like:

  • Postman: Send test POST requests to your webhook URL
  • ngrok: Expose your local development server for testing
  • Webhook.site: Create temporary webhook URLs for testing
Test Webhook with cURL
curl -X POST https://your-domain.com/webhook.php \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseCode": 0,
    "ResponseDescription": "Success. Request accepted for processing",
    "MerchantRequestID": "test-merchant-id",
    "CheckoutRequestID": "test-checkout-id",
    "TransactionID": "TEST_TRANSACTION_123",
    "TransactionAmount": 100,
    "TransactionReceipt": "TEST_RECEIPT",
    "TransactionDate": "20241201120000",
    "TransactionReference": "TEST_REF_123",
    "Msisdn": "254712345678"
  }'

Supported Banks

PesaFlux supports direct deposits to major Kenyan banks. You can link your bank account to receive payments directly from M-Pesa transactions.

Major Banks

  • Kenya Commercial Bank (KCB)
  • Equity Bank
  • Cooperative Bank
  • Standard Chartered Bank
  • Absa Bank Kenya
  • NCBA Bank

Other Supported Banks

  • Diamond Trust Bank (DTB)
  • Diamond Trust Bank (DTB)
  • I&M Bank
  • Stanbic Bank
  • Family Bank
  • Prime Bank
  • Gulf African Bank

Mobile Money

  • M-Pesa (Safaricom)
  • Airtel Money
  • T-Kash (Telkom)
  • Till Numbers
  • Paybill Numbers
  • Buy Goods & Services

Account Setup

To link your bank account or mobile money:

  1. Login to your PesaFlux account
  2. Go to Account Setup
  3. Select your preferred bank or mobile money option
  4. Provide the required account details
  5. Verify your account information
  6. Start receiving payments directly
Link Account Now
Note: Processing times may vary depending on the bank or mobile money provider. Most transactions are processed instantly, while bank transfers may take 1-3 business days.