DEV Community

stanleygichana5-lab
stanleygichana5-lab

Posted on Edited on

How to Architect M-Pesa Daraja 2.0 STK Push & Callback Verification in Next.js 15 (TypeScript)

Integrating M-Pesa Daraja 2.0 STK Push into a modern Next.js 15 App Router application often breaks in production due to three common mistakes: expired OAuth tokens, unverified callback payloads, and duplicate webhook processing.

Here is the clean, production-safe architecture pattern to handle Daraja 2.0 reliably in TypeScript.


1. Cache Your Daraja OAuth Access Token

Requesting a fresh OAuth token from Safaricom on every single STK Push adds latency and risks rate-limiting. Store the token in memory (or Redis) with a 55-minute TTL before its 3600-second expiry:

let cachedToken: { token: string; expiresAt: number } | null = null;

export async function getDarajaAccessToken(): Promise<string> {
  if (cachedToken && Date.now() < cachedToken.expiresAt) {
    return cachedToken.token;
  }

  const credentials = Buffer.from(
    `${process.env.MPESA_CONSUMER_KEY}:${process.env.MPESA_CONSUMER_SECRET}`
  ).toString("base64");

  const res = await fetch(
    "https://safaricom.co.ke",
    {
      headers: { Authorization: `Basic ${credentials}` },
      cache: "no-store",
    }
  );

  const data = await res.json();
  cachedToken = {
    token: data.access_token,
    expiresAt: Date.now() + 55 * 60 * 1000, // 55 mins
  };

  return cachedToken.token;
}
Enter fullscreen mode Exit fullscreen mode

2. Validate & Normalize Kenyan Phone Numbers (2547XXXXXXXX / 2541XXXXXXXX)

Always sanitize user input before generating the Base64 password (BusinessShortCode + Passkey + Timestamp):

export function formatKenyanPhone(phone: string): string {
  const cleaned = phone.replace(/\D/g, "");
  if (cleaned.startsWith("0")) return `254${cleaned.slice(1)}`;
  if (cleaned.startsWith("254")) return cleaned;
  throw new Error("Invalid Kenyan phone number format");
}
Enter fullscreen mode Exit fullscreen mode

3. Idempotent Callback Route Handler (app/api/mpesa/callback/route.ts)

Safaricom's servers will retry callbacks if your endpoint takes too long to respond. Always verify ResultCode === 0, extract MpesaReceiptNumber from CallbackMetadata.Item, check if the receipt already exists in your database, and immediately return { ResultCode: 0, ResultDesc: "Accepted" }.


âš¡ Skip the Boilerplate Setup

If you want the complete, plug-and-play Next.js 15 M-Pesa Daraja 2.0 API Boilerplate & STK Push UI Component (including full TypeScript types, error states, and checkout UI), you can grab it here:

Top comments (1)

Collapse
 
fintechrailsdigest profile image
Fintech Rails Digest •

the 55-minute token cache is worth a comment: daraja tokens come back with a 3599-second expiry, so refreshing five minutes early is right, but the cache also needs to survive a cold start, otherwise every serverless warm-up hits safaricom's token endpoint anyway. on the callback side, checking ResultCode === 0 alone isn't quite enough; dedupe on MpesaReceiptNumber before crediting the order, because the retries the article mentions can deliver the same successful transaction twice.