POST /api/v1/payment/mpesa-stk-push

Use this endpoint to send an M-Pesa STK push (Lipa na M-Pesa Express) prompt directly to a customer’s phone. When you call this endpoint, the customer receives a payment dialog on their device and approves the charge with their M-Pesa PIN. No redirect or frontend action is required. This endpoint requires your secret key and is intended for server-to-server calls only. If you need to trigger M-Pesa from a client-side context, use the collect payment endpoint with your public_key instead. Method: POST
URL: https://app.kulmipay.com/api/v1/payment/mpesa-stk-push/

Authentication

Authorization: Bearer <secret_key>

Request

string

required

Customer’s M-Pesa phone number in 254XXXXXXXXX format. The number must be a registered Safaricom line with an active M-Pesa account.

number

required

Amount to charge in KES. Decimal values are rounded up to the nearest whole shilling before the STK push is sent. Account and M-Pesa limits may apply.

string

Your reference for this transaction, up to 140 characters. Stored on the invoice and returned in webhook events. Defaults to "MPesa Express" if omitted.

string

Alias ID of a specific KES wallet to receive the funds. If omitted, funds go to your default KES settlement wallet.

string

default:"BUSINESS-PAYS"

Who bears the M-Pesa processing fee. BUSINESS-PAYS deducts the fee from your settlement; CUSTOMER-PAYS adds the fee on top of amount before sending the prompt. If your account has a default tariff set in Payment Settings, that value is used when this field is omitted.

Response

The response contains the payment session created for this request, including the invoice and customer details.

string

Payment session UUID.

object

Invoice created for this STK push.

Show invoice properties

string

Invoice alias ID. Use this with the payment status endpoint to check whether the customer completed payment.

string

Invoice state. Starts as PENDING while the customer is interacting with the STK prompt. Changes to COMPLETE on successful payment or FAILED if the customer declines or the request times out.

string

Amount charged, in KES, after tariff adjustment.

string

Always M-PESA for this endpoint.

string

Your reference as submitted in the request.

object

Customer record associated with this session.

Show customer properties

string

Internal customer alias.

string

The phone number the STK push was sent to.

string

Always M-PESA for STK push sessions.

string

ISO 8601 timestamp when the session was created.

Code examples

curl --request POST \
  --url https://app.kulmipay.com/api/v1/payment/mpesa-stk-push/ \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone_number": "254712345678",
    "amount": "1500.00",
    "api_ref": "order_20240416_001",
    "mobile_tarrif": "BUSINESS-PAYS"
  }'

import requests

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

data = response.json()
invoice_id = data["invoice"]["invoice_id"]

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

const data = await response.json();
const invoiceId = data.invoice.invoice_id;

Example response

{
  "id": "a3f7c819-4e2b-4d1a-9c3f-2b8e1d7a6f05",
  "invoice": {
    "invoice_id": "GQ7KZ2XPNM",
    "state": "PENDING",
    "value": "1500.00",
    "currency": "KES",
    "provider": "M-PESA",
    "account": "254712345678",
    "api_ref": "order_20240416_001",
    "mpesa_reference": null,
    "created_at": "2024-04-16T08:23:11.042Z"
  },
  "customer": {
    "customer_id": "CUST_XJ82KP",
    "phone_number": "254712345678",
    "provider": "M-PESA",
    "created_at": "2024-04-16T08:23:11.012Z"
  },
  "customer_comment": null,
  "refundable": false,
  "created_at": "2024-04-16T08:23:11.055Z",
  "updated_at": "2024-04-16T08:23:11.055Z"
}

The STK push prompt expires if the customer does not respond in time. Poll the payment status endpoint with the returned invoice.invoice_id to detect the final state, or subscribe to webhook events to receive a push notification when the payment completes.

Collections

Send Money

Wallet as a Service

Webhooks

Refunds

Bring Your M-Pesa Till/PayBill Number

POST /api/v1/payment/mpesa-stk-push

Authentication

Request

Response

Code examples

Example response

​Authentication

​Request

​Response

​Code examples

​Example response

Authentication

Request

Response

Code examples

Example response