M-Pesa STK Push - Kulmi Pay

M-Pesa STK Push (also called Lipa Na M-Pesa Express) lets you initiate a payment from your server. When you call the API, Safaricom sends a prompt to your customer’s phone asking them to enter their M-Pesa PIN. Once they confirm, the payment is processed and you receive a webhook notification. No redirect or hosted checkout page is required.

How it works

Send the STK push request

Call POST /api/v1/payment/mpesa-stk-push/ with the customer’s phone number and the amount to collect.

Customer receives a prompt

Safaricom sends a push notification to the customer’s phone with your business name and the payment amount.

Customer enters their PIN

The customer opens the prompt and enters their M-Pesa PIN to authorise the payment.

Webhook fires

Kulmi Pay sends a collection_event webhook to your configured endpoint with the invoice’s final state (COMPLETE or FAILED). You can also poll the payment status endpoint to check the result.

Send an STK push

curl -X POST https://app.kulmipay.com/api/v1/payment/mpesa-stk-push/ \
  -H "Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "254712345678",
    "amount": "1000.00",
    "api_ref": "ORDER-001",
    "mobile_tarrif": "BUSINESS-PAYS"
  }'

import requests

response = requests.post(
    "https://app.kulmipay.com/api/v1/payment/mpesa-stk-push/",
    headers={
        "Authorization": "Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "254712345678",
        "amount": "1000.00",
        "api_ref": "ORDER-001",
        "mobile_tarrif": "BUSINESS-PAYS",
    },
)
print(response.json())

const response = await fetch(
  "https://app.kulmipay.com/api/v1/payment/mpesa-stk-push/",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "254712345678",
      amount: "1000.00",
      api_ref: "ORDER-001",
      mobile_tarrif: "BUSINESS-PAYS",
    }),
  }
);

console.log(await response.json());

<?php

require_once __DIR__ . "/vendor/autoload.php";

use KulmiPay\KulmiPayPHP\Collection;

$collection = new Collection();
$collection->init([
    "token" => "ISSecretKey_live_xxxxxxxxxxxxxxxx",
]);

$response = $collection->mpesa_stk_push(
    "1000.00",
    "254712345678",
    "ORDER-001",
    null,
    "BUSINESS-PAYS"
);

echo $response->invoice->invoice_id;

Request fields

Field	Type	Required	Description
`phone_number`	string	Yes	Kenyan phone number in international format, e.g. `254712345678`.
`amount`	decimal string or number	Yes	Amount in KES. The backend rounds decimal values up to the nearest whole shilling before sending the STK push.
`api_ref`	string	No	Your internal reference for this payment, e.g. an order ID. Defaults to `MPesa Express` when omitted and is returned in the webhook payload.
`wallet_id`	string	No	The ID of a specific KES wallet to receive funds. Defaults to your primary settlement wallet.
`mobile_tarrif`	string	No	Who pays the transaction fee. `BUSINESS-PAYS` (default) or `CUSTOMER-PAYS`.

Success response

{
  "id": "a3f7c819-4e2b-4d1a-9c3f-2b8e1d7a6f05",
  "invoice": {
    "invoice_id": "INV-XXXXXXXX",
    "state": "PENDING",
    "provider": "M-PESA",
    "currency": "KES",
    "value": "1000.00",
    "api_ref": "ORDER-001",
    "account": "254712345678",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "customer": {
    "phone_number": "254712345678",
    "provider": "M-PESA"
  },
  "payment_link": null,
  "customer_comment": null,
  "refundable": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

The invoice.invoice_id field is the value you use to check payment status. Save it with your order record.

Sandbox URL

Use the sandbox host with the same path while testing:

https://sandbox.kulmipay.com/api/v1/payment/mpesa-stk-push/

After sending the request, poll POST /api/v1/payment/status/ with the invoice.invoice_id from the response to check whether the customer completed the payment. Alternatively, configure a webhook to receive automatic notifications.

​How it works

​Send an STK push

​Request fields

​Success response

​Sandbox URL

How it works

Send an STK push

Request fields

Success response

Sandbox URL