ABA Editorial · Jan 11, 2026 · 12 min read
Safaricom's Daraja is the API gateway that connects your application to M-Pesa. This guide walks through the practical integration path: portal registration, sandbox setup, OAuth authentication, the STK Push payment flow, callback handling, and the transition from sandbox to production. Written for engineering teams building their first M-Pesa integration.
If you are building any product in Kenya that accepts or disburses money, you will eventually integrate with Safaricom's Daraja API. Daraja is the platform that exposes M-Pesa capabilities to third-party developers through RESTful endpoints: customer payments, business disbursements, balance queries, transaction status checks, and more. It replaced the older SOAP-based G2 API in 2017 and has become the standard integration path for Kenyan fintech. This guide walks through the practical steps to get from zero to a working sandbox integration, with pointers to the production go-live process. It is written for engineering teams approaching their first Daraja integration. If you are on your fifth, you do not need this guide.
The Daraja developer portal lives at developer.safaricom.co.ke. Start by creating an account, either as an individual developer or as a company. Individual developer accounts are sufficient for sandbox exploration and prototype building. Company accounts are required for production use. Registration is straightforward and does not require documentation at this stage.
Once registered, the portal gives you access to API documentation, a sandbox environment, and an app creation flow. You will use this portal as your primary working surface throughout integration.
Inside the portal, create a new app. Here you need to make a decision that has consequences later: which API products to assign to the app. Safaricom exposes several products including Lipa na M-Pesa Online (STK Push), Customer to Business (C2B), Business to Customer (B2C), Business to Business (B2B), Transaction Status Query, and Account Balance Query.
There is an important constraint that catches many first-time integrators. When you eventually go to production, you cannot use the same app for both C2B and B2C APIs. If you apply for a C2B shortcode or paybill, it will not be allowed to use the B2C API, and vice versa. The Lipa na M-Pesa Online API can share an app with C2B but not with B2C. Plan this split in advance rather than discovering it during production onboarding. Your development team should know from day one whether your product needs C2B, B2C, or both, and should create separate apps accordingly.
Once your sandbox app is created, the portal generates a Consumer Key and Consumer Secret. These are the credentials you will use for authentication in every API call.
Daraja uses OAuth 2.0 client credentials for authentication. Before you can call any business endpoint, you need to exchange your Consumer Key and Consumer Secret for a short-lived access token. The token endpoint is at /oauth/v1/generate?grant_type=client_credentials on the sandbox host sandbox.safaricom.co.ke.
The basic flow is: base64-encode the string "CONSUMER_KEY:CONSUMER_SECRET", set it as an HTTP Basic Authorization header, send a GET request to the token endpoint, and parse the JSON response to extract the access_token field. The token is valid for approximately one hour. Your integration should cache the token and refresh it before expiry rather than requesting a new one for every API call. Requesting tokens unnecessarily is a common cause of rate-limit issues.
STK Push, formally known as Lipa na M-Pesa Online, is the most commonly used Daraja endpoint. It lets your application trigger a payment prompt on a customer's phone without requiring the customer to enter your paybill or till number manually. The customer sees a prompt, enters their M-Pesa PIN, and the transaction completes.
The STK Push endpoint is /mpesa/stkpush/v1/processrequest. You send a POST request with your access token in the Authorization header and a JSON body containing the business shortcode, a base64-encoded password (constructed by concatenating the shortcode, a Daraja-issued passkey, and a timestamp, then base64-encoding the result), the timestamp, the transaction type (usually CustomerPayBillOnline), the amount, the paying phone number, the receiving shortcode, a callback URL that Daraja will notify when the transaction resolves, an account reference, and a transaction description.
The response is asynchronous. Your initial API call returns an acknowledgement indicating that the STK Push was accepted and is being processed. The actual transaction result arrives later, via the callback URL you provided. Your server needs to be able to receive this callback reliably, parse the result, and update your application state accordingly.
Callback handling is where many first-time integrations fail. Three rules will save you significant debugging time. First, your callback URL must be publicly accessible over HTTPS. Daraja cannot reach localhost or private IP ranges. During development, use a tunneling service like ngrok to expose your local callback handler. Second, your callback endpoint must return a 200 status code to Daraja even if your internal processing fails. If you return a non-200, Daraja treats the callback as undelivered and will not retry it reliably. Handle your own errors after acknowledging receipt. Third, your callback handler must be idempotent. Daraja may send the same callback more than once under certain conditions, and your code must not double-process a transaction.
If you cannot receive a callback for any reason, Daraja also provides a Transaction Status Query API that lets you poll for the result of a previously initiated transaction. Use this as a fallback, not as the primary mechanism.
Going from sandbox to production requires several additional steps. You need a live Safaricom business shortcode (a paybill or till number), which involves a separate application process with Safaricom's business onboarding team. You need to create a production app in the Daraja portal and obtain production Consumer Key and Consumer Secret credentials. You need to migrate any shortcode that was previously connected to the old SOAP API, which may require explicit requests to Safaricom's support team to delete the old registered URLs before the new API will work correctly. You need to implement proper error logging, transaction reconciliation, and finance-level reporting.
Do not underestimate the go-live timeline. From first sandbox success to production launch, six to eight weeks is typical for a well-prepared team. Longer is common for teams that discovered the C2B/B2C app constraint late in the process.
Daraja integration is well-documented but has enough operational gotchas that many teams benefit from bringing in a specialist consultant for their first go-live, particularly around the production onboarding process with Safaricom. ABA's Solutions & Services marketplace includes Daraja integration specialists, Kenyan payment infrastructure consultants, and fintech engineering firms with production M-Pesa experience.
Important notice: This guide is provided as general information and orientation only. It is not legal, regulatory, technical, or financial advice. API specifications, endpoint structures, authentication flows, and onboarding processes change regularly, and Safaricom's official documentation at developer.safaricom.co.ke should always be treated as the authoritative source. Before implementing a production integration, readers should consult the current official Daraja documentation and qualified integration professionals. Need verified guidance or hands-on support? ABA's Solutions & Services marketplace connects businesses with vetted professional services providers across Africa, including Daraja integration specialists and Kenyan payment infrastructure consultants. ABA and its contributors accept no liability for actions taken on the basis of this guide.