What is the Daraja API? Safaricom M-Pesa Integration Guide

If you have ever paid for goods through Lipa Na M-Pesa, received a salary into your phone, or topped up your Netflix subscription with mobile money, you have used a service powered by the Daraja API. Daraja is Safaricom’s official public API for M-Pesa — the gateway that lets developers and businesses move money in and out of the largest mobile money network in the world. In this guide we explain exactly what the Daraja API is, what each of its endpoints does, how to integrate it, and the practical pitfalls that catch most teams the first time.

M-Pesa processes more than US$314 billion in transaction value annually across East Africa (Safaricom FY 2024 results), and Daraja is how every modern Kenyan e-commerce site, SaaS platform, fintech and SME plugs into that flow. Whether you are a developer building a new payment journey or a founder evaluating the work involved, this article has you covered.

What is the Daraja API?

The Daraja API is a RESTful HTTPS interface published by Safaricom that exposes M-Pesa functionality to third-party applications. The name “Daraja” is Swahili for “bridge” — the API bridges your application to Safaricom’s core M-Pesa infrastructure. Through Daraja you can:

• Receive payments from customers (Lipa Na M-Pesa Online / STK Push, C2B PayBill and Till numbers).
• Send payments to customers, suppliers or employees (B2C — salaries, refunds, payouts).
• Send payments between business accounts (B2B).
• Check account balance and transaction status programmatically.
• Reverse transactions within a limited window.
• Process QR code payments.

Daraja replaced the older G2 SOAP API in 2017 and has become the standard way to integrate with M-Pesa Kenya. Sister Daraja portals now also serve M-Pesa in Tanzania, Mozambique, DRC and Ghana, although each has its own credentials.

How the Daraja API authentication works

Daraja uses OAuth 2.0 client-credentials. Every request must include a Bearer token, which you obtain by exchanging your Consumer Key and Consumer Secret at:

GET https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic base64(consumerKey:consumerSecret)

The response gives you an access_token valid for 3,600 seconds (1 hour). Cache it server-side; do not regenerate on every call. Use https://sandbox.safaricom.co.ke for testing and the production host once approved.

The five Daraja endpoints you actually need

1. M-Pesa Express (STK Push) — the customer-facing payment prompt

STK Push (also called Lipa Na M-Pesa Online) is the most common integration. You send a request, and Safaricom triggers a payment prompt directly on the customer’s phone. They enter their PIN, and the funds move to your PayBill or Till.

POST https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "BusinessShortCode": 174379,
  "Password": "<base64(shortcode+passkey+timestamp)>",
  "Timestamp": "20260615120000",
  "TransactionType": "CustomerPayBillOnline",
  "Amount": 1500,
  "PartyA": 254712345678,
  "PartyB": 174379,
  "PhoneNumber": 254712345678,
  "CallBackURL": "https://yourapp.com/mpesa/callback",
  "AccountReference": "INV-1042",
  "TransactionDesc": "Payment for invoice 1042"
}

The customer prompt arrives within 5–10 seconds. They have 60 seconds to enter their PIN. Daraja then POSTs the result to your CallBackURL within another 10–30 seconds, with a ResultCode of 0 for success or a non-zero error code.

2. C2B (Customer to Business)

C2B lets customers pay your PayBill or Till independently — from the M-Pesa menu, not triggered by your app. You register validation and confirmation URLs once, and Daraja calls them every time a customer sends money to your shortcode. Use this for paying invoices, school fees, or topping up wallets.

3. B2C (Business to Customer)

B2C is for payouts: salaries, supplier payments, betting winnings, insurance claims. You initiate the payment from your application, Safaricom moves the funds, and you receive a callback with the result. Requires a separate Business Shortcode and initiator credentials.

4. Transaction Status

Used to confirm the state of a transaction (settled, pending, reversed). Critical when a callback was missed due to a server outage — do not rely on callbacks alone; reconcile with Transaction Status nightly.

5. Account Balance

Returns the live balance of your PayBill or Till. Useful for paying out from a float without going negative.

The integration journey: sandbox to production

1. Register at developer.safaricom.co.ke and create a sandbox app. You get a Consumer Key, Consumer Secret and a test PayBill (174379).
2. Build against the sandbox. Implement STK Push, your callback handler, and idempotent storage of CheckoutRequestID + MpesaReceiptNumber.
3. Apply for a production shortcode. You need a registered business (Certificate of Incorporation, KRA PIN, board resolution), a bank account for settlement, and signed Safaricom terms.
4. Go-live testing. Safaricom’s integration team runs you through end-to-end tests, including failure paths.
5. Whitelist your production callback URL with Safaricom — it must be HTTPS and publicly accessible.

End-to-end go-live typically takes 2–6 weeks depending on Safaricom’s queue and how clean your paperwork is.

Common pitfalls and how to avoid them

• Token expiry. The access token lives one hour. Cache it; refresh proactively at 55 minutes.
• Wrong password encoding. The Password field is base64 of (Shortcode + Passkey + Timestamp). Many failed integrations boil down to encoding bugs here.
• Timestamps in the wrong format. Use YYYYMMDDHHMMSS in Africa/Nairobi time. UTC drift causes silent rejections.
• Treating callbacks as guaranteed. Safaricom retries failed callbacks but not forever — build a nightly reconciliation job that calls Transaction Status for anything pending.
• Logging PINs or full MSISDNs. Mask them; Kenya’s Data Protection Act 2019 considers MSISDNs personal data and the ODPC can fine you for poor handling.

Daraja API for non-developers

You don’t have to integrate Daraja yourself. If you sell on Shopify, WooCommerce, or run a SaaS that needs M-Pesa, there are gateway providers (Pesapal, Flutterwave, IntaSend, HelloDuty) that wrap Daraja behind a simpler API or a no-code dashboard. They handle the shortcode application, token refresh, callbacks and reconciliation — you get a checkout button or a single REST endpoint.

At HelloDuty we connect M-Pesa to the rest of the customer-engagement stack: when a customer pays an invoice, we can automatically send an SMS receipt and trigger a WhatsApp follow-up — see how to send bulk SMS in Kenya effectively and WhatsApp integration for better customer experience. We also cover the broader picture in the comprehensive guide to building USSD applications for feature-phone payments.

Frequently asked questions

Is the Daraja API free?

Yes, the API itself is free. You pay Safaricom’s normal M-Pesa transaction fees — settlement is governed by your PayBill or Till tariff, not by per-API-call charges.

What is the difference between STK Push and C2B?

STK Push is initiated by your application — Safaricom prompts the customer to pay. C2B is initiated by the customer from the M-Pesa menu — your application reacts to a confirmation callback. Most checkout journeys use STK Push for the lower friction.

How long does it take to get a production PayBill?

Typically 2–6 weeks from clean paperwork to live access, including Safaricom’s integration testing. Companies in regulated sectors (banking, insurance, betting) take longer.

Can I integrate Daraja without writing code?

Yes — use a gateway like Pesapal, IntaSend, Flutterwave or HelloDuty. They publish drop-in checkout buttons and webhooks, abstracting away token refresh, callbacks and reconciliation.

Does Daraja work outside Kenya?

Safaricom’s Daraja is Kenya-only. M-Pesa Tanzania, Mozambique, DRC and Ghana run their own developer portals with similar but separate APIs. If you operate across markets, choose a provider that wraps all of them behind a single API.

Wrapping up

The Daraja API is the bridge between your application and the largest mobile money network in Africa. With around an hour of focused engineering you can run sandbox STK Push end-to-end; with a few more weeks you can be live in production with a production PayBill. If you want the result without the boilerplate, HelloDuty packages M-Pesa, SMS, WhatsApp Business and AI voice into a single platform that your team can run from a dashboard.

Talk to us if you want to take M-Pesa payments alongside your customer-engagement channels — we will scope your integration in a 20-minute call.