M-Pesa is woven into how Kenyans pay for goods, services, school fees, utilities and loans. For businesses, the difference between accepting M-Pesa manually and integrating it properly is large: integrated payments are confirmed instantly, matched to the right account automatically and reconciled without anyone reading SMS messages.
This article explains how that integration works through Safaricom’s Daraja API platform. It covers the main APIs, how they fit together and the design decisions that separate reliable integrations from fragile ones.
What is Daraja?
Daraja is Safaricom’s developer platform for M-Pesa. It provides web APIs that let a business’s systems request payments, receive payment notifications, send money and query transactions, all programmatically.
To use Daraja, a business needs:
- an M-Pesa shortcode (a paybill or till number) registered to the business;
- a Daraja account, where developers create an app and receive a consumer key and consumer secret;
- for Lipa na M-Pesa Online (STK Push), a passkey associated with the shortcode;
- for APIs that move money out of the shortcode, an initiator user with appropriate permissions.
Daraja provides a sandbox with test credentials for development. Production access is granted through a go-live process on the portal.
Authentication
Every Daraja API call is authorised with an access token. Your server requests the token from the OAuth endpoint using the consumer key and secret, and the token is valid for about an hour. A well-built integration caches the token and refreshes it before it expires, rather than requesting a new one for every call.
The consumer key and secret must stay on your server. They should never be placed in a mobile app or website code where users could extract them.
STK Push (Lipa na M-Pesa Online)
STK Push is what most people mean by “M-Pesa checkout”. Your system asks Safaricom to send a payment prompt to the customer’s phone; the customer enters their M-Pesa PIN; and the result is sent back to your system.
The request includes the shortcode, the amount, the customer’s phone number, an account reference, a callback URL and a password generated from the shortcode, passkey and a timestamp:
Timestamp = YYYYMMDDHHmmss (for example 20261119143005)
Password = Base64( Shortcode + Passkey + Timestamp )
Two things are easy to misunderstand.
- The immediate response is not the payment result. A successful response only means the request was accepted for processing. The customer has not paid yet.
- The real result arrives at your callback URL. Safaricom posts the outcome to your callback. A result code of
0means the payment succeeded, and the payload includes the M-Pesa receipt number, amount and phone number. Other result codes indicate failures such as the customer cancelling the prompt or the request timing out.
If no callback arrives within a reasonable time, your system can use the STK Push query API to check the status of the request.
C2B: payments to your paybill or till
With C2B (customer to business), the customer starts the payment from their own phone, for example by paying a paybill with an account number. Your system needs to know about these payments as they happen.
You register two URLs against your shortcode:
- a confirmation URL, which receives details of every completed payment, including the transaction ID, amount and the account reference (bill reference) the customer entered;
- a validation URL (optional, and enabled on request), which lets your system accept or reject a payment before it completes, for example when the account number does not exist.
C2B is ideal for schools, utilities, SACCOs, landlords and any business where customers pay against an account number.
B2C: paying customers, staff and beneficiaries
B2C (business to customer) lets your system send money from your shortcode to M-Pesa users: customer refunds, loan disbursements, salary or allowance payments, agent commissions or beneficiary payments.
B2C requests are made by an initiator whose credential is encrypted with Safaricom’s public certificate. Like most Daraja APIs that move money, B2C is asynchronous. Your system receives an acknowledgement immediately and the final result later at a result URL, with a separate timeout URL for requests that could not be processed in time.
Other useful APIs
- Transaction status lets you query the status of a specific transaction.
- Account balance retrieves the balance of your shortcode.
- Reversal reverses a transaction where your business process allows it.
These are also asynchronous, returning results to the URLs you specify.
Designing reliable callbacks
Callbacks are where most M-Pesa integrations succeed or fail. Good practice includes:
- Use public HTTPS endpoints. Safaricom must be able to reach your callback URLs over HTTPS.
- Respond quickly. Acknowledge the callback straight away and process it in the background, so slow processing does not cause timeouts.
- Store the raw payload. Keep the original callback data for audit and troubleshooting.
- Make processing idempotent. Use the M-Pesa receipt number or transaction ID as a unique key, so a duplicate callback never credits an account twice.
- Never trust the client. Release goods or services only when your server has received and validated the payment result, not because a browser or app says the customer paid.
- Validate amounts and references. Check that the amount and account reference match what you expected.
- Restrict access where possible and log every request.
Reconciliation
Integration makes reconciliation largely automatic, but you still need a process for exceptions:
- payments with a wrong or missing account reference;
- overpayments and partial payments;
- callbacks that never arrived;
- reversals.
A robust system places these in an exception queue for review and regularly compares recorded transactions against M-Pesa statements to confirm nothing has been missed.
Common mistakes
- Treating the STK Push acknowledgement as a successful payment.
- Requesting a new access token for every API call, or letting tokens expire mid-process.
- Using callback URLs that are not publicly reachable over HTTPS.
- Generating timestamps in the wrong format or time zone.
- Formatting phone numbers incorrectly. Daraja expects the international format, such as
2547XXXXXXXX. - Not handling duplicate callbacks.
- Exposing API credentials in front-end code.
Going live
After building and testing in the sandbox, the business completes Safaricom’s go-live process on the Daraja portal using the shortcode’s administrator credentials, then switches to production credentials and the production passkey. Monitoring callbacks closely in the first days of live operation catches configuration issues early.
Bringing it together
A complete M-Pesa integration usually combines several of these APIs: STK Push for checkout, C2B for paybill payments, B2C for refunds or disbursements and transaction status for exceptions. All of it is tied into your ERP, POS or billing system so that every payment updates the right record automatically.
GetSharp builds M-Pesa integrations for websites, apps, POS, ERP and billing systems. Learn more about our M-Pesa integration service or talk to our team.