Core M-Pesa API concepts
These terms describe how your system and the payment side talk to each other. Get them clear before writing code, because most integration problems come from treating one of them as another.
- Request: the message your server sends to start an action, such as asking a customer to pay a set amount in KES. A successful response to a request usually means it was accepted for processing, not that the customer has paid.
- Callback or postback: a message sent to a URL on your server once the outcome is known. Safaricom documentation uses the word callback. With Payment Gateway Kenya, postbacks send transaction status to the merchant. They are not a customer notification service, so your own system decides what to tell the customer.
- Status: the state of a transaction at a point in time, for example pending, successful or failed. Your order should only move to paid when a final successful status is recorded against it.
- Idempotency: the rule that repeating the same request or receiving the same postback twice has the same effect as doing it once. In practice you attach a unique reference to each order and check it before acting, so a retry never creates a second charge or a second fulfilment.
- Reference: your own order or invoice identifier, stored alongside the transaction identifier returned to you. Matching the two is the basis of reconciliation.
M-PESA Express, PayBill and Till: three different transaction types
Safaricom documentation describes M-PESA Express (Lipa na M-PESA Online) as a prompt-style request started by the business. Your system sends the request, and the customer receives a prompt on their phone to confirm the payment. Many people in the market call this 'STK Push', a term used in Safaricom documentation.
PayBill and Till are separate transaction types. In both, the customer starts the payment from their own M-Pesa menu, using a business number and, for PayBill, an account reference. Because the customer starts it, your system learns about the payment from the incoming message rather than from a request you sent.
| Type | Who starts the payment | What your system relies on |
|---|---|---|
| M-PESA Express (Lipa na M-PESA Online) | The business, by sending a request | Your request reference, then the callback or postback with the outcome |
| PayBill | The customer, from their M-Pesa menu | The business number and the account reference the customer enters |
| Till | The customer, from their M-Pesa menu | The till number and the incoming payment record |
Whether you should build on Daraja yourself or connect through a gateway depends on your team and your volume. We compare the two in Daraja vs a payment gateway.
Illustrative flow: from request to confirmed order
The example below shows where request, postback, status and idempotency fit in one pay-in. It is a concept sketch only. Field names, endpoints and formats for Payment Gateway Kenya are shared with merchants during integration.
// 1. Merchant server sends a pay-in request
POST /payins
Idempotency-Key: order-10482
{
"reference": "order-10482",
"amount": 2500,
"currency": "KES",
"method": "mpesa",
"phone": "2547XXXXXXXX",
"postback_url": "https://shop.example/payments/postback"
}
// 2. Response: request accepted, not yet paid
{ "reference": "order-10482", "status": "pending" }
// 3. Postback to merchant with the outcome
{ "reference": "order-10482", "status": "successful" }
// 4. Merchant server logic
if (alreadyProcessed(reference)) return 200; // idempotency check
if (status === "successful") markOrderPaid(reference);
return 200;Illustrative flow only. This is not the Payment Gateway Kenya API or the Safaricom Daraja API, and the endpoints and field names are placeholders. Ask our team for the actual integration documentation.
-
Send the request with your reference
Use a unique order reference and send it again unchanged on any retry, so a repeated request is recognised as the same one.
-
Treat 'pending' as pending
An accepted request is not a payment. Hold the order until a final status arrives.
-
Handle the postback safely
Check whether the reference has already been processed before updating anything, then record the status and reply to confirm receipt.
-
Tell the customer yourself
Postbacks go to your server, not to the customer. Show the result on your page or send your own confirmation.
Keep pay-ins, payouts and settlement separate
Payment Gateway Kenya offers two connection routes into the same gateway: API (H2H) for teams that want to build their own checkout, and a Hosted Payment Page for teams that prefer less development work. H2H is not a white-label product. Pricing is custom, so talk to sales about your setup.
M-Pesa API: frequently asked questions
Short answers to the questions developers and merchants ask most often when planning an M-Pesa integration.
What is an M-Pesa API?
It is the set of messages a business system uses to start M-Pesa payments and receive their outcomes. In practice that means sending requests, receiving callbacks or postbacks, and tracking each transaction's status.
Is 'STK Push' the same as M-PESA Express?
'STK Push' is a market term found in Safaricom documentation for the prompt-style request. Safaricom's documentation names the service M-PESA Express (Lipa na M-PESA Online), which is started by the business.
How are PayBill and Till different from M-PESA Express?
PayBill and Till are separate transaction types where the customer starts the payment from their own M-Pesa menu. With M-PESA Express, the business starts the request and the customer confirms it on their phone.
Does a Payment Gateway Kenya postback notify my customer?
No. Postbacks send transaction status to the merchant and are not a customer notification service. Your system receives the status and decides how to inform the customer.
Why does idempotency matter for M-Pesa payments?
Networks retry and messages can arrive more than once. Using a unique reference and checking it before acting means a repeated request or postback never leads to a double charge or a duplicate order.
Do I have to use the API, or is there a simpler option?
Payment Gateway Kenya offers API (H2H) and a Hosted Payment Page. They are two routes into the same gateway, so you can choose based on how much development work your team wants to take on.
When are merchant settlements sent?
Merchant settlements are sent on the same day (T+0). This describes when settlement is sent, not when funds are credited to your account.
How much does the M-Pesa integration cost?
Pricing is custom. Talk to sales about your business and setup to get a quote.