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:
- Login to your PesaFlux Account
- Navigate to Linked Accounts and copy your API Key
- If you see "no data", go to Account Setup and link your Till, Paybill, or Bank Account
- 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
https://api.pesaflux.co.ke/v1/initiatestkHeaders
| Header | Description | Value |
|---|---|---|
| Content-Type | The Accept request HTTP header advertises which content types the client can understand. | application/json |
Parameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijbemailstringRequiredEmail that you use to login into PesaFlux AccountExample:example@gmail.comamountnumberRequiredAmount to request from your customer in KESExample:1msisdnstringRequiredPhone number to request money fromExample:254768783443 OR 0768783443referencestringOptionalA unique reference that will be used to identify the transactionExample:6527990
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 |
curl -X POST "https://api.pesaflux.co.ke/v1/initiatestk" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"amount": "30",
"msisdn": "254768783443",
"reference": "6527990"
}'<?php
$payload = [
'api_key' => 'nluhfjdgbmzfyjrwzsbqkwcsijb',
'email' => 'example@gmail.com',
'amount' => '30',
'msisdn' => '254768783443',
'reference' => '6527990'
];
$ch = curl_init('https://api.pesaflux.co.ke/v1/initiatestk');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const response = await fetch("https://api.pesaflux.co.ke/v1/initiatestk", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"amount": "30",
"msisdn": "254768783443",
"reference": "6527990"
}),
});
const data = await response.json();
console.log(data);import requests
payload = {
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"amount": "30",
"msisdn": "254768783443",
"reference": "6527990"
}
response = requests.post("https://api.pesaflux.co.ke/v1/initiatestk", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"amount": "30",
"msisdn": "254768783443",
"reference": "6527990"
}{
"success": "200",
"massage": "Request sent sucessfully.",
"transaction_request_id": "SOFTPID2809202423523970891"
}{
"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"
}{
"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"
}#Transaction Status
https://api.pesaflux.co.ke/v1/transactionstatusParameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijbemailstringRequiredEmail that you use to login into PesaFlux AccountExample:example@gmail.comtransaction_request_idstringRequiredTransaction id that you get after initiating stk pushExample:SOFTPID2809202423253425286
curl -X POST "https://api.pesaflux.co.ke/v1/transactionstatus" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"transaction_request_id": "SOFTPID2809202423253425286"
}'<?php
$payload = [
'api_key' => 'nluhfjdgbmzfyjrwzsbqkwcsijb',
'email' => 'example@gmail.com',
'transaction_request_id' => 'SOFTPID2809202423253425286'
];
$ch = curl_init('https://api.pesaflux.co.ke/v1/transactionstatus');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const response = await fetch("https://api.pesaflux.co.ke/v1/transactionstatus", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"transaction_request_id": "SOFTPID2809202423253425286"
}),
});
const data = await response.json();
console.log(data);import requests
payload = {
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"transaction_request_id": "SOFTPID2809202423253425286"
}
response = requests.post("https://api.pesaflux.co.ke/v1/transactionstatus", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"email": "example@gmail.com",
"transaction_request_id": "SOFTPID2809202423253425286"
}{
"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
https://api.fluxsms.co.ke/sendsmsstatus: "sent" went out, "scheduled" is waiting for a top-up.Headers
| Header | Description | Value |
|---|---|---|
| Content-Type | The Accept request HTTP header advertises which content types the client can understand. | application/json |
Parameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijbphonestringRequiredKenyan phone number (0712345678 or 254712345678)Example:0769290734messagestringRequiredSMS message content (max 160 characters per SMS)Example:Hello from FluxSMS!sender_idstringRequiredSender ID for the SMS (default: fluxsms)Example:fluxsms
curl -X POST "https://api.fluxsms.co.ke/sendsms" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phone": "0769290734",
"message": "Hello from FluxSMS API!",
"sender_id": "fluxsms"
}'<?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);
?>const response = await fetch("https://api.fluxsms.co.ke/sendsms", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phone": "0769290734",
"message": "Hello from FluxSMS API!",
"sender_id": "fluxsms"
}),
});
const data = await response.json();
console.log(data);import requests
payload = {
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phone": "0769290734",
"message": "Hello from FluxSMS API!",
"sender_id": "fluxsms"
}
response = requests.post("https://api.fluxsms.co.ke/sendsms", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phone": "0769290734",
"message": "Hello from FluxSMS API!",
"sender_id": "fluxsms"
}{
"response-code": 200,
"success": true,
"status": "sent",
"message_id": "953474467",
"phone": 254712345678,
"network": "Safaricom",
"units": 1
}{
"response-code": 200,
"success": true,
"status": "scheduled",
"message": "Insufficient SMS balance. Message queued and will be sent automatically after you top up (expires in 24 hours).",
"phone": "254712345678",
"scheduled_id": 86544
}#Send Bulk SMS
https://api.fluxsms.co.ke/bulksmsstatus: "sent" went out, "scheduled" is waiting for a top-up.Parameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijbphonesarrayRequiredArray of Kenyan phone numbersExample:["0769290734", "0712345678"]messagestringRequiredSMS message contentExample:Bulk SMS from FluxSMS!sender_idstringRequiredSender ID for the SMS (default: fluxsms)Example:fluxsms
curl -X POST "https://api.fluxsms.co.ke/bulksms" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phones": [
"0769290734",
"0712345678",
"0722345678"
],
"message": "Bulk SMS from FluxSMS API!",
"sender_id": "fluxsms"
}'<?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);
?>const response = await fetch("https://api.fluxsms.co.ke/bulksms", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phones": [
"0769290734",
"0712345678",
"0722345678"
],
"message": "Bulk SMS from FluxSMS API!",
"sender_id": "fluxsms"
}),
});
const data = await response.json();
console.log(data);import requests
payload = {
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phones": [
"0769290734",
"0712345678",
"0722345678"
],
"message": "Bulk SMS from FluxSMS API!",
"sender_id": "fluxsms"
}
response = requests.post("https://api.fluxsms.co.ke/bulksms", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"phones": ["0769290734", "0712345678", "0722345678"],
"message": "Bulk SMS from FluxSMS API!",
"sender_id": "fluxsms"
}{
"response-code": 200,
"success": true,
"total_sent": 2,
"total_requests": 2,
"scheduled": 0,
"responses": [
{
"response-code": 200,
"response-description": "Success",
"mobile": "254712345678",
"messageid": "953474467",
"clientsmsid": 365599,
"networkid": 1,
"units": 1,
"network": "Safaricom",
"status": "Sent"
},
{
"response-code": 200,
"response-description": "Success",
"mobile": "254722345678",
"messageid": "953474468",
"clientsmsid": 500073,
"networkid": 1,
"units": 1,
"network": "Safaricom",
"status": "Sent"
}
]
}{
"response-code": 200,
"success": true,
"status": "scheduled",
"message": "Insufficient SMS balance. Messages queued and will be sent automatically after you top up (expire in 24 hours).",
"scheduled": 2,
"failed": 0,
"details": "You can view queued messages in your SMS History."
}#SMS Status Check
https://api.fluxsms.co.ke/smsstatusParameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijbmessage_idstringRequiredMessage ID returned when SMS was sentExample:SMS_20241201_123456789
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 |
curl -X POST "https://api.fluxsms.co.ke/smsstatus" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"message_id": "SMS_20241201_123456789"
}'<?php
$payload = [
'api_key' => 'nluhfjdgbmzfyjrwzsbqkwcsijb',
'message_id' => 'SMS_20241201_123456789'
];
$ch = curl_init('https://api.fluxsms.co.ke/smsstatus');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const response = await fetch("https://api.fluxsms.co.ke/smsstatus", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"message_id": "SMS_20241201_123456789"
}),
});
const data = await response.json();
console.log(data);import requests
payload = {
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"message_id": "SMS_20241201_123456789"
}
response = requests.post("https://api.fluxsms.co.ke/smsstatus", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
"message_id": "SMS_20241201_123456789"
}{
"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 Balance Check
https://api.fluxsms.co.ke/check_sms_balanceParameters
api_keystringRequiredAPI key obtained from your PesaFlux AccountExample:nluhfjdgbmzfyjrwzsbqkwcsijb
curl -X POST "https://api.fluxsms.co.ke/check_sms_balance" \
-H "Content-Type: application/json" \
-d '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
}'<?php
$ch = curl_init('https://api.fluxsms.co.ke/check_sms_balance');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => '{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
}']);
echo curl_exec($ch);const response = await fetch("https://api.fluxsms.co.ke/check_sms_balance", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
}),
});
const data = await response.json();
console.log(data);import requests, json
payload = json.loads("""{
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
}""")
response = requests.post("https://api.fluxsms.co.ke/check_sms_balance", json=payload, timeout=30)
print(response.json()){
"api_key": "nluhfjdgbmzfyjrwzsbqkwcsijb",
}{
"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
- Login to your PesaFlux account at https://pesaflux.co.ke/user
- Navigate to Account Settings or API Settings
- Enter your webhook URL in the designated field
- Save your settings
- 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:
{
"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
ResponseCodeintegerTransaction response code (0 = success, other = error)ResponseDescriptionstringHuman-readable description of the transaction resultMerchantRequestIDstringUnique identifier for the merchant requestCheckoutRequestIDstringUnique identifier for the checkout requestTransactionIDstringPesaFlux transaction identifierTransactionAmountnumberAmount transacted in KESTransactionReceiptstringM-Pesa transaction receipt numberTransactionDatestringDate and time when transaction was completedTransactionReferencestringYour custom reference passed during STK initiationMsisdnstringPhone number that made the payment
PHP Webhook Handler Example
<?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
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:
- Login to your PesaFlux account
- Go to Account Setup
- Select your preferred bank or mobile money option
- Provide the required account details
- Verify your account information
- Start receiving payments directly
PesaFlux