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:

POSThttps://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest

Parameters

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

Example Request

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

Copyhttps://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:

Copy{
  "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:

Copy{
  "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:

POSThttps://api.bosmi.org/bsmpay/stkpushquery/v3/query

Parameters

Required fields in your JSON body:

Example Query Request

CopyPOST 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

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

Error Response

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

Sample Code

Python (STK Push)

Copyimport 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)

Copyimport 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)

Copy<?php
$endpoint = 'https://api.bosmi.org/bsmpay/stkpushquery/v3/processrequest';
$data = [
    'api_key' => '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)

Copy<?php
$url = 'https://api.bosmi.org/bsmpay/stkpushquery/v3/query';
$data = [
    'transaction_id' => '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 "<pre>";
    print_r($decoded);
    echo "</pre>";
}
curl_close($ch);
?>

cURL Example (STK Push)

Copycurl -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
}'