M-PESA Daraja API Complete Guide (2026): endpoints, auth, errors

Daraja is Safaricom's official REST API for M-PESA. You register at developer.safaricom.co.ke, get a Consumer Key and Consumer Secret, exchange them for an OAuth token, and then call the endpoint catalogue: STK Push (checkout), C2B (paybill / till receipts), B2C (payouts), Account Balance, and Transaction Status. Safaricom processed KShs 41.68 trillion in M-PESA volume in FY26 across 40.99 million customers (Source: Safaricom PLC Annual Report FY2026), so Daraja is the plumbing under every modern Kenyan payment integration.

This is the complete reference. For the shorter integration walkthrough that predates this guide, see the original Daraja API integration guide (still current for the Shopify / WooCommerce plugin path).

What Daraja actually is

Daraja (Swahili for "bridge") is a set of REST endpoints hosted by Safaricom that expose M-PESA operations to developers. Daraja 2.0 launched in 2018 as the modern replacement for the older SOAP-based G2 gateway. Every endpoint returns JSON, uses OAuth 2.0 bearer tokens, and follows an asynchronous callback pattern: you POST a request, Safaricom returns a synchronous acknowledgement, then the customer-facing action completes and Safaricom POSTs the final result to a callback URL you own.

Sandbox versus production

Authentication: OAuth token exchange

Every Daraja call needs a Bearer token in the Authorization header. You get that token by making a Basic-Auth GET against the OAuth endpoint with your Consumer Key and Consumer Secret as the username and password. The token is valid for 3599 seconds (about 1 hour). Cache it.

Sandbox: https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials

Production: https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials

Node.js OAuth token exchange

// Node.js 20+, native fetch
const consumerKey = process.env.MPESA_CONSUMER_KEY;
const consumerSecret = process.env.MPESA_CONSUMER_SECRET;
const auth = Buffer.from(`${consumerKey}:${consumerSecret}`).toString('base64');

const res = await fetch(
  'https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',
  { headers: { Authorization: `Basic ${auth}` } }
);
const { access_token, expires_in } = await res.json();
// Cache access_token for (expires_in - 60) seconds.

Python OAuth token exchange

import base64, requests, os
key = os.environ['MPESA_CONSUMER_KEY']
secret = os.environ['MPESA_CONSUMER_SECRET']
auth = base64.b64encode(f"{key}:{secret}".encode()).decode()

r = requests.get(
    'https://sandbox.safaricom.co.ke/oauth/v1/generate',
    params={'grant_type': 'client_credentials'},
    headers={'Authorization': f'Basic {auth}'},
    timeout=10,
)
token = r.json()['access_token']

PHP OAuth token exchange

<?php
$auth = base64_encode(getenv('MPESA_CONSUMER_KEY') . ':' . getenv('MPESA_CONSUMER_SECRET'));
$ch = curl_init('https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Basic ' . $auth]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
$token = $response['access_token'];

The endpoint catalogue

For per-endpoint walkthroughs see the sibling guides in this cluster:

• STK Push integration 2026
• C2B integration 2026
• B2C integration 2026

Rate limits

Safaricom does not publish exact numbers, but the following limits are consistent across production integrations in 2026:

• OAuth token: approximately 300 requests per minute per Consumer Key.
• STK Push: approximately 100 requests per minute per short code.
• C2B Register URL: single-shot per short code, not rate-limited (call once at deploy).
• B2C: throttled to your paid-out daily limit; a busy PSP hits it before rate limits bite.
• Callback traffic (inbound to you): no explicit limit from Safaricom; size for your own peak.

IP whitelisting and callback security

Callbacks are the security-critical path in Daraja. Safaricom will POST payment results to a URL you own; a naive endpoint that accepts any POST as authoritative can be spoofed by an attacker sending fake "successful payment" JSON. Recommended controls:

1. HTTPS with a valid certificate. Safaricom rejects HTTP callbacks in production. Let's Encrypt is fine; self-signed is not.
2. Whitelist Safaricom source IPs. Safaricom's callback traffic comes from a small set of IPs in their AS37061 range. Restrict inbound at your firewall or your reverse-proxy layer.
3. Validate the payload structure and correlate the CheckoutRequestID.Every callback carries a request ID you generated on the outbound POST. If the ID does not match a pending request in your database, drop the callback.
4. Rate-limit and log every callback. Even legitimate callbacks can be replayed by Safaricom on network glitches; make your handler idempotent.

Common errors and fixes

Going live checklist

1. Build and load-test on sandbox against the test short code and test PIN.
2. Prepare production callback URLs (HTTPS, publicly reachable, HTTP 200 in under 5 seconds).
3. Submit the Go-Live request at developer.safaricom.co.ke with your paybill / till, callback URLs and settlement bank.
4. Once Safaricom issues production Consumer Key and Consumer Secret, replace the sandbox environment variables.
5. Run one KES 10 end-to-end payment on production to confirm callbacks land and settle.
6. Roll out to real traffic; monitor callback latency and STK success rate as your first two SLOs.

Related reading

• M-PESA for Business hub
• Daraja API integration (original guide)
• STK Push integration
• C2B integration
• B2C integration
• M-PESA payment gateways compared
• M-PESA charges 2026
• Kenya mobile money statistics 2026

FAQ

Verified 1 September 2026. Volume and customer figures from Safaricom PLC Annual Report FY2026. Endpoint paths and OAuth flow verified against the current Safaricom Daraja portal at developer.safaricom.co.ke.