M-Pesa Daraja API Integration with Next.js: A Production Guide

const REQUIRED = [
  'MPESA_CONSUMER_KEY',
  'MPESA_CONSUMER_SECRET',
  'MPESA_SHORTCODE',
  'MPESA_PASSKEY',
  'MPESA_CALLBACK_URL',
] as const

for (const key of REQUIRED) {
  if (!process.env[key]) throw new Error(`Missing environment variable: ${key}`)
}

export const mpesaConfig = {
  baseUrl:
    process.env.MPESA_ENV === 'production'
      ? 'https://api.safaricom.co.ke'
      : 'https://sandbox.safaricom.co.ke',
  consumerKey: process.env.MPESA_CONSUMER_KEY!,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET!,
  shortcode: process.env.MPESA_SHORTCODE!,
  passkey: process.env.MPESA_PASSKEY!,
  callbackUrl: process.env.MPESA_CALLBACK_URL!,
  // CustomerPayBillOnline for a paybill, CustomerBuyGoodsOnline for a till.
  transactionType: process.env.MPESA_TILL
    ? 'CustomerBuyGoodsOnline'
    : 'CustomerPayBillOnline',
} as const

import { mpesaConfig } from './config'

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

export async function getAccessToken(): Promise<string> {
  if (cached && Date.now() < cached.expiresAt) return cached.token

  const credentials = Buffer.from(
    `${mpesaConfig.consumerKey}:${mpesaConfig.consumerSecret}`
  ).toString('base64')

  const response = await fetch(
    `${mpesaConfig.baseUrl}/oauth/v1/generate?grant_type=client_credentials`,
    {
      headers: { Authorization: `Basic ${credentials}` },
      cache: 'no-store',
    }
  )

  if (!response.ok) {
    throw new Error(`Daraja auth failed: ${response.status} ${await response.text()}`)
  }

  const data = (await response.json()) as { access_token: string; expires_in: string }

  cached = {
    token: data.access_token,
    // Expire a minute early so a token can never die mid-flight.
    expiresAt: Date.now() + (Number(data.expires_in) - 60) * 1000,
  }

  return cached.token
}

/**
 * Accepts 0712345678, +254712345678, 254712345678, 712345678 and the 01xx
 * range, and returns the 2547XXXXXXXX / 2541XXXXXXXX form Daraja requires.
 */
export function normalizePhone(input: string): string {
  const digits = input.replace(/\D/g, '')

  if (/^254[17]\d{8}$/.test(digits)) return digits
  if (/^0[17]\d{8}$/.test(digits)) return `254${digits.slice(1)}`
  if (/^[17]\d{8}$/.test(digits)) return `254${digits}`

  throw new Error(`Not a valid Kenyan mobile number: ${input}`)
}

import { mpesaConfig } from './config'
import { getAccessToken } from './token'
import { normalizePhone } from './phone'

function stamp() {
  const now = new Date()
  const pad = (n: number) => String(n).padStart(2, '0')
  const timestamp =
    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
    `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`

  const password = Buffer.from(
    `${mpesaConfig.shortcode}${mpesaConfig.passkey}${timestamp}`
  ).toString('base64')

  return { timestamp, password }
}

export interface StkPushResult {
  merchantRequestId: string
  checkoutRequestId: string
  customerMessage: string
}

export async function initiateStkPush(params: {
  phone: string
  amount: number
  accountReference: string
  description: string
}): Promise<StkPushResult> {
  const { timestamp, password } = stamp()
  const token = await getAccessToken()
  const phone = normalizePhone(params.phone)

  const response = await fetch(
    `${mpesaConfig.baseUrl}/mpesa/stkpush/v1/processrequest`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      cache: 'no-store',
      body: JSON.stringify({
        BusinessShortCode: mpesaConfig.shortcode,
        Password: password,
        Timestamp: timestamp,
        TransactionType: mpesaConfig.transactionType,
        // Daraja rejects decimals. Round up rather than truncating so you
        // never undercharge.
        Amount: Math.ceil(params.amount),
        PartyA: phone,
        PartyB: mpesaConfig.shortcode,
        PhoneNumber: phone,
        CallBackURL: mpesaConfig.callbackUrl,
        AccountReference: params.accountReference.slice(0, 12),
        TransactionDesc: params.description.slice(0, 13),
      }),
    }
  )

  const data = await response.json()

  if (data.ResponseCode !== '0') {
    throw new Error(
      `STK Push rejected: ${data.errorMessage ?? data.ResponseDescription ?? 'unknown'}`
    )
  }

  return {
    merchantRequestId: data.MerchantRequestID,
    checkoutRequestId: data.CheckoutRequestID,
    customerMessage: data.CustomerMessage,
  }
}

import { NextResponse } from 'next/server'
import { z } from 'zod'

import { initiateStkPush } from '@/lib/mpesa/stk'
import { db } from '@/lib/db'

const schema = z.object({
  phone: z.string().min(9),
  amount: z.number().positive().max(150_000),
  orderId: z.string().uuid(),
})

export async function POST(request: Request) {
  const parsed = schema.safeParse(await request.json())
  if (!parsed.success) {
    return NextResponse.json({ error: 'Invalid request' }, { status: 400 })
  }

  const { phone, amount, orderId } = parsed.data

  try {
    const result = await initiateStkPush({
      phone,
      amount,
      accountReference: orderId.slice(0, 12),
      description: 'Order payment',
    })

    // Write the pending row BEFORE returning. The callback can arrive before
    // this response reaches the browser, and it needs a row to update.
    await db.payment.create({
      data: {
        orderId,
        amount,
        phone,
        status: 'PENDING',
        checkoutRequestId: result.checkoutRequestId,
        merchantRequestId: result.merchantRequestId,
      },
    })

    return NextResponse.json({
      checkoutRequestId: result.checkoutRequestId,
      message: result.customerMessage,
    })
  } catch (error) {
    console.error('STK Push failed', { orderId, error })
    return NextResponse.json({ error: 'Could not reach M-Pesa' }, { status: 502 })
  }
}

import { NextResponse } from 'next/server'

interface CallbackItem {
  Name: string
  Value?: string | number
}

export async function POST(request: Request) {
  const payload = await request.json()
  const callback = payload?.Body?.stkCallback

  // Always acknowledge. A non-200 makes Safaricom retry, and a retry storm
  // is much worse than a payload you decided to ignore.
  if (!callback) return NextResponse.json({ ResultCode: 0, ResultDesc: 'Accepted' })

  const { CheckoutRequestID, ResultCode, ResultDesc } = callback

  const items: CallbackItem[] = callback.CallbackMetadata?.Item ?? []
  const field = (name: string) => items.find((item) => item.Name === name)?.Value

  await recordCallback({
    checkoutRequestId: CheckoutRequestID,
    success: ResultCode === 0,
    resultCode: ResultCode,
    resultDesc: ResultDesc,
    receipt: field('MpesaReceiptNumber') as string | undefined,
    amount: field('Amount') as number | undefined,
    phone: field('PhoneNumber') as number | undefined,
  })

  return NextResponse.json({ ResultCode: 0, ResultDesc: 'Accepted' })
}

'use client'

import { useEffect, useState } from 'react'

type Status = 'pending' | 'paid' | 'failed' | 'timeout'

export function usePaymentStatus(checkoutRequestId: string | null) {
  const [status, setStatus] = useState<Status>('pending')

  useEffect(() => {
    if (!checkoutRequestId) return

    const startedAt = Date.now()
    const interval = setInterval(async () => {
      // M-Pesa prompts expire after about 60 seconds; give it 90 and stop.
      if (Date.now() - startedAt > 90_000) {
        setStatus('timeout')
        clearInterval(interval)
        return
      }

      const response = await fetch(`/api/payments/mpesa/${checkoutRequestId}`)
      const { status: next } = await response.json()

      if (next !== 'pending') {
        setStatus(next)
        clearInterval(interval)
      }
    }, 3000)

    return () => clearInterval(interval)
  }, [checkoutRequestId])

  return status
}