M-Pesa API STK Push Documentation

Overview

This is your guide for integrating the M-Pesa STK Push API. It outlines endpoints, required parameters, and example requests for smooth integration. Please go through the documentation carefully to understand how our web service works. Basic JSON and HTTP knowledge is required to simulate or integrate the API

Getting Started

Before you can send STK Push requests, you need to:

  • Register an account with us in the developer portal.
  • Obtain your API key, Username, & Email.
  • Whitelist your IPs if necessary.

🔗 Endpoint

Send a POST request to the following endpoint to initiate STK Push:

POST https://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest

📝 Parameters

These are the required parameters you need to include in the JSON request body:

Parameter Type Description Example
api_key String Your API key obtained in your portal. Sd4#k[HFS
username String Your Account username. admin
email String Your registered Email. example@gmail.com
phone String Your customer phone number in format 07XXXXXXXX. 0712345678
amount Intenger Amount to push. 100

💻 Example Request

Here's an example of how to structure your STK Push request:


          https://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest
          Content-Type: application/json
          
          {
            "api_key": "Sd4#k[HFS",
            "username": "admin",
            "email": "example@gmail.com",
            "phone": "0712345678",
            "amount": 100
        }

✅ Success Response

If the STK Push request is successful, you will receive a response similar to:


                {
                    "status":"0",
                    "transaction_id":"B0smi_Id2025032121054940609",
                    "Phone_Num":"254712345678",
                    "message":"Transaction initiated successfully."
                  }

⚠️ Error Response

In case of errors (e.g., invalid phone number), you might receive:


          {
              "status": "error",
              "message": "Failed to initiate payment, please retry and use correct MPESA number."
          }

🔍 Query Transaction Endpoint

To query the status of a transaction, send a POST request to:

POST https://api.bosmi.org/bsmpay/stkpushquery/v3/query

📝 Parameters

Required fields in your JSON body:

Parameter Type Description Example
api_key String Your API key. Sd4#k[HFS
username String Your portal email. admin
transaction_id String The transaction ID received from initial STK push. B0smi_Id2025032121054940609

💻 Example Query Request


POST https://api.bosmi.org/bsmpay/stkpushquery/v3/query
Content-Type: application/json

{
  "api_key": "Sd4#k[HFS",
  "email": "example@gmail.com",
  "transaction_id": "B0smi_Id2025032121054940609"
}

✅ Success Response


{
    "status" => 0
    "B0smi_Id" => B0smi_Id2025110317475720811
    "amount" => 1
    "phone" => 254759446172
    "mpesa_receipt" => TK3GE944U2
    "message" => Transaction completed successfully.
}

⚠️ Error Response


{
  "status": "error",
  "message": "Transaction is being processed or failed."
}

📦 Sample Code

Python (STK Push)


import requests

url = "https://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest"
payload = {
    "api_key": "YOUR_API_KEY",
    "username": "YOUR_USERNAME",
    "email": "your@email.com",
    "phone": "0712345678",
    "amount": 100
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Python (Query Transaction)


import requests

url = "https://api.bosmi.org/bsmpay/stkpushquery/v3/query"
payload = {
    "api_key": "YOUR_API_KEY",
    "email": "your@email.com",
    "transaction_id": "BOSMI_TRANSACTION_ID"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

PHP (STK Push)


 'YOUR_API_KEY',
    'username' => 'YOUR_USERNAME',
    'email' => 'your@email.com',
    'phone' => '0712345678',
    'amount' => 100
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
} else {
    echo $response;
}
curl_close($ch);
?>

PHP (Query Transaction)


 'BOSMI_TRANSACTION_ID',
    'api_key' => 'YOUR_API_KEY',
    'email' => 'your@email.com'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
} else {
    $decoded = json_decode($response, true);
    echo "
";
    print_r($decoded);
    echo "
";
}
curl_close($ch);
?>

cURL Example (STK Push)


curl -X POST https://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest \
-H "Content-Type: application/json" \
-d '{
  "api_key": "YOUR_API_KEY",
  "username": "YOUR_USERNAME",
  "email": "your@email.com",
  "phone": "0712345678",
  "amount": 100
}'