Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
phone_number
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.
​
amount
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.
​
api_ref
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.
​
wallet_id
string
Alias ID of a specific KES wallet to receive the funds. If omitted, funds go to your default KES settlement wallet.
​
mobile_tarrif
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.
​
id
string
Payment session UUID.
​
invoice
object
Invoice created for this STK push.
​
customer
object
Customer record associated with this session.
​
created_at
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"
  }'

​
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.