Magochi API Documentation - Complete API Reference

POST

/mpesa/stk-push

Auth Required

STK Push

Initiate M-Pesa STK Push (Lipa Na M-Pesa Online). Supports both Paybill and Till.

Scopes: payment:create

Rate Limit: 20 per minute

Request/Response Examples

Initiate M-Pesa STK push.

JSON

{
    "phone": "254712345678",
    "amount": 5000,
    "reference_type": "reservation",
    "reference_id": 456,
    "account_reference": "RES-2025-0001",
    "branch_id": 1
}

STK push initiated successfully.

JSON

{
    "status": "success",
    "data": {
        "merchant_request_id": "HOTEL202501151030001234",
        "checkout_request_id": "MPSabc123xyz789",
        "response_code": "0",
        "response_description": "Success. Request accepted for processing"
    },
    "code": 200
}

Code Examples

PHP - M-Pesa STK Push

PHP example for M-Pesa STK Push

<?php
$token = "YOUR_JWT_TOKEN_HERE";

$stkData = [
    "phone" => "254712345678",
    "amount" => 5000,
    "reference_type" => "reservation",
    "reference_id" => 456,
    "account_reference" => "RES-2025-0001",
    "branch_id" => 1
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://hotel.webninjaafrica.com/api/mpesa/stk-push",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($stkData),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $token,
        "X-API-Key: YOUR_API_KEY",
        "Content-Type: application/json"
    ]
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

if ($result["status"] === "success") {
    echo "STK push sent. Checkout ID: " . $result["data"]["checkout_request_id"];
}

curl_close($curl);
?>

Python - M-Pesa STK Push

Python example for M-Pesa STK Push

import requests

token = "YOUR_JWT_TOKEN_HERE"
api_key = "YOUR_API_KEY_HERE"
url = "https://hotel.webninjaafrica.com/api/mpesa/stk-push"

stk_data = {
    "phone": "254712345678",
    "amount": 5000,
    "reference_type": "reservation",
    "reference_id": 456,
    "account_reference": "RES-2025-0001",
    "branch_id": 1
}

headers = {
    "Authorization": f"Bearer {token}",
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(url, json=stk_data, headers=headers)
data = response.json()

if data["status"] == "success":
    print("STK push sent. Checkout ID: " + data["data"]["checkout_request_id"])
else:
    print("Error: " + data["message"])

cURL - M-Pesa STK Push

cURL example for M-Pesa STK push

curl -X POST https://hotel.webninjaafrica.com/api/mpesa/stk-push \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "254712345678",
    "amount": 5000,
    "reference_type": "reservation",
    "reference_id": 456,
    "account_reference": "RES-2025-0001",
    "branch_id": 1
  }'