The Complete Developer Guide to M-Pesa POS Integration

Who is this guide for?

Software developers, technical leads, and system architects building or maintaining POS systems that accept M-Pesa payments in Kenya. Assumes working knowledge of Node.js/JavaScript, REST APIs, and basic understanding of payment processing.

Important: SSL/TLS Requirements

Self-signed certificates are not accepted by Safaricom. Use a certificate from a trusted CA. Free options like Let's Encrypt work perfectly. During development, use a tunneling service like ngrok to expose your local server over HTTPS.

const axios = require('axios')
const Buffer = require('buffer').Buffer

// Token cache
let cachedToken = null
let tokenExpiry = 0

const CONSUMER_KEY = process.env.MPESA_CONSUMER_KEY
const CONSUMER_SECRET = process.env.MPESA_CONSUMER_SECRET
const BASE_URL = process.env.MPESA_ENV === 'production'
  ? 'https://api.safaricom.co.ke'
  : 'https://sandbox.safaricom.co.ke'

async function getAccessToken() {
  // Return cached token if still valid (5-min buffer)
  if (cachedToken && Date.now() < tokenExpiry - 300000) {
    return cachedToken
  }

  const credentials = Buffer.from(
    `${CONSUMER_KEY}:${CONSUMER_SECRET}`
  ).toString('base64')

  const response = await axios.get(
    `${BASE_URL}/oauth/v1/generate?grant_type=client_credentials`,
    {
      headers: {
        Authorization: `Basic ${credentials}`
      }
    }
  )

  cachedToken = response.data.access_token
  tokenExpiry = Date.now() + (3599 * 1000)

  return cachedToken
}

module.exports = { getAccessToken }

function generatePassword(shortcode, passkey) {
  const timestamp = new Date()
    .toISOString()
    .replace(/[-T:.Z]/g, '')
    .slice(0, 14)

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

  return { password, timestamp }
}

const { getAccessToken } = require('./auth')
const axios = require('axios')

const SHORTCODE = process.env.MPESA_SHORTCODE
const PASSKEY = process.env.MPESA_PASSKEY
const CALLBACK_URL = process.env.MPESA_CALLBACK_URL
const BASE_URL = process.env.MPESA_BASE_URL

async function initiateSTKPush(phoneNumber, amount, orderId) {
  const token = await getAccessToken()
  const { password, timestamp } = generatePassword(SHORTCODE, PASSKEY)

  const payload = {
    BusinessShortCode: SHORTCODE,
    Password: password,
    Timestamp: timestamp,
    TransactionType: 'CustomerPayBillOnline',
    Amount: Math.round(amount), // Must be whole number
    PartyA: formatPhone(phoneNumber),
    PartyB: SHORTCODE,
    PhoneNumber: formatPhone(phoneNumber),
    CallBackURL: `${CALLBACK_URL}/api/mpesa/stk-callback`,
    AccountReference: orderId,
    TransactionDesc: `Payment for ${orderId}`
  }

  try {
    const response = await axios.post(
      `${BASE_URL}/mpesa/stkpush/v1/processrequest`,
      payload,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    )

    // Store CheckoutRequestID for status queries
    const { MerchantRequestID, CheckoutRequestID } = response.data

    await saveTransaction({
      orderId,
      checkoutRequestId: CheckoutRequestID,
      merchantRequestId: MerchantRequestID,
      phoneNumber: formatPhone(phoneNumber),
      amount: Math.round(amount),
      status: 'pending',
      createdAt: new Date()
    })

    return {
      success: true,
      checkoutRequestId: CheckoutRequestID,
      merchantRequestId: MerchantRequestID
    }
  } catch (error) {
    console.error('STK Push failed:', error.response?.data || error.message)
    return {
      success: false,
      error: error.response?.data?.errorMessage || 'STK Push request failed'
    }
  }
}

// Format phone number to 2547XXXXXXXX format
function formatPhone(phone) {
  let cleaned = phone.replace(/\D/g, '')
  if (cleaned.startsWith('0')) cleaned = '254' + cleaned.slice(1)
  if (cleaned.startsWith('+')) cleaned = cleaned.slice(1)
  if (!cleaned.startsWith('254')) cleaned = '254' + cleaned
  return cleaned
}

{ // ResultCode 0 = Success
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_191220191020363925",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 1500 },
          { "Name": "MpesaReceiptNumber", "Value": "SFH7TQ4OLE" },
          { "Name": "TransactionDate", "Value": 20260225143025 },
          { "Name": "PhoneNumber", "Value": 254712345678 }
        ]
      }
    }
  }
}

{ // ResultCode != 0 = Failure
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_191220191020363925",
      "ResultCode": 1032,
      "ResultDesc": "Request cancelled by user"
      // Note: No CallbackMetadata on failure
    }
  }
}

const express = require('express')
const router = express.Router()

// POST /api/mpesa/stk-callback
router.post('/stk-callback', async (req, res) => {
  // ALWAYS respond 200 immediately to prevent Safaricom retries
  res.status(200).json({ ResultCode: 0, ResultDesc: 'Accepted' })

  try {
    const callback = req.body.Body.stkCallback
    const { CheckoutRequestID, ResultCode, ResultDesc } = callback

    if (ResultCode === 0) {
      // Payment successful - extract metadata
      const metadata = callback.CallbackMetadata.Item
      const getValue = (name) =>
        metadata.find(i => i.Name === name)?.Value

      const paymentData = {
        amount: getValue('Amount'),
        receiptNumber: getValue('MpesaReceiptNumber'),
        transactionDate: getValue('TransactionDate'),
        phoneNumber: getValue('PhoneNumber')
      }

      // Update transaction in database
      await updateTransaction(CheckoutRequestID, {
        status: 'completed',
        mpesaReceiptNumber: paymentData.receiptNumber,
        completedAt: new Date(),
        ...paymentData
      })

      // Notify POS terminal via WebSocket or SSE
      await notifyPOS(CheckoutRequestID, {
        status: 'paid',
        receiptNumber: paymentData.receiptNumber
      })

    } else {
      // Payment failed
      await updateTransaction(CheckoutRequestID, {
        status: 'failed',
        resultCode: ResultCode,
        resultDesc: ResultDesc,
        failedAt: new Date()
      })

      await notifyPOS(CheckoutRequestID, {
        status: 'failed',
        reason: ResultDesc
      })
    }
  } catch (error) {
    console.error('Callback processing error:', error)
    // Do NOT re-throw - we already sent 200
  }
})

async function querySTKStatus(checkoutRequestId) {
  const token = await getAccessToken()
  const { password, timestamp } = generatePassword(SHORTCODE, PASSKEY)

  const response = await axios.post(
    `${BASE_URL}/mpesa/stkpushquery/v1/query`,
    {
      BusinessShortCode: SHORTCODE,
      Password: password,
      Timestamp: timestamp,
      CheckoutRequestID: checkoutRequestId
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  )

  return response.data
  // ResultCode 0 = success, 1032 = cancelled, 1037 = timeout
}

async function registerC2BUrls() {
  const token = await getAccessToken()

  const response = await axios.post(
    `${BASE_URL}/mpesa/c2b/v1/registerurl`,
    {
      ShortCode: SHORTCODE,
      ResponseType: 'Completed', // or "Cancelled" to reject by default
      ConfirmationURL: `${CALLBACK_URL}/api/mpesa/c2b-confirm`,
      ValidationURL: `${CALLBACK_URL}/api/mpesa/c2b-validate`
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  )

  console.log('C2B URLs registered:', response.data)
  return response.data
}

// Validation handler - accept or reject payment
router.post('/c2b-validate', async (req, res) => {
  const { BillRefNumber, TransAmount, MSISDN } = req.body

  // Check if order exists and amount matches
  const order = await findOrder(BillRefNumber)

  if (!order) {
    return res.json({
      ResultCode: 1,
      ResultDesc: 'Order not found'
    })
  }

  if (parseFloat(TransAmount) < order.totalAmount) {
    return res.json({
      ResultCode: 1,
      ResultDesc: 'Insufficient amount'
    })
  }

  // Accept payment
  res.json({ ResultCode: 0, ResultDesc: 'Accepted' })
})

// Confirmation handler - payment completed
router.post('/c2b-confirm', async (req, res) => {
  res.status(200).json({ ResultCode: 0 })

  const {
    TransID, TransAmount, BillRefNumber,
    MSISDN, TransTime
  } = req.body

  await recordC2BPayment({
    transactionId: TransID,
    amount: parseFloat(TransAmount),
    accountReference: BillRefNumber,
    phoneNumber: MSISDN,
    transactionTime: TransTime,
    status: 'completed'
  })

  // Try to match with open POS order
  const order = await findOrder(BillRefNumber)
  if (order) {
    await markOrderPaid(order.id, TransID)
    await notifyPOS(order.id, { status: 'paid', via: 'c2b' })
  }
})

B2C requires separate approval

B2C uses different credentials from STK Push. You need an Initiator Name and Security Credential, which are obtained through a separate approval process with Safaricom. Apply early in your development timeline.

const crypto = require('crypto')
const fs = require('fs')

function generateSecurityCredential(initiatorPassword) {
  // Use sandbox cert for testing, production cert for live
  const certPath = process.env.MPESA_ENV === 'production'
    ? './certs/ProductionCertificate.cer'
    : './certs/SandboxCertificate.cer'

  const cert = fs.readFileSync(certPath, 'utf8')
  const buffer = Buffer.from(initiatorPassword)

  const encrypted = crypto.publicEncrypt(
    {
      key: cert,
      padding: crypto.constants.RSA_PKCS1_PADDING
    },
    buffer
  )

  return encrypted.toString('base64')
}

async function processRefund(phoneNumber, amount, originalTransactionId) {
  const token = await getAccessToken()

  const securityCredential = generateSecurityCredential(
    process.env.MPESA_INITIATOR_PASSWORD
  )

  const payload = {
    InitiatorName: process.env.MPESA_INITIATOR_NAME,
    SecurityCredential: securityCredential,
    CommandID: 'BusinessPayment',
    Amount: Math.round(amount),
    PartyA: SHORTCODE,
    PartyB: formatPhone(phoneNumber),
    Remarks: `Refund for ${originalTransactionId}`,
    QueueTimeOutURL: `${CALLBACK_URL}/api/mpesa/b2c-timeout`,
    ResultURL: `${CALLBACK_URL}/api/mpesa/b2c-result`,
    Occasion: 'POS Refund'
  }

  try {
    const response = await axios.post(
      `${BASE_URL}/mpesa/b2c/v1/paymentrequest`,
      payload,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    )

    await saveRefund({
      conversationId: response.data.ConversationID,
      originatorConversationId: response.data.OriginatorConversationID,
      originalTransactionId,
      phoneNumber: formatPhone(phoneNumber),
      amount: Math.round(amount),
      status: 'pending'
    })

    return { success: true, conversationId: response.data.ConversationID }
  } catch (error) {
    console.error('B2C refund failed:', error.response?.data)
    return { success: false, error: error.response?.data?.errorMessage }
  }
}

async function checkTransactionStatus(transactionId) {
  const token = await getAccessToken()
  const securityCredential = generateSecurityCredential(
    process.env.MPESA_INITIATOR_PASSWORD
  )

  const response = await axios.post(
    `${BASE_URL}/mpesa/transactionstatus/v1/query`,
    {
      Initiator: process.env.MPESA_INITIATOR_NAME,
      SecurityCredential: securityCredential,
      CommandID: 'TransactionStatusQuery',
      TransactionID: transactionId,
      PartyA: SHORTCODE,
      IdentifierType: '4', // 4 = shortcode
      ResultURL: `${CALLBACK_URL}/api/mpesa/status-result`,
      QueueTimeOutURL: `${CALLBACK_URL}/api/mpesa/status-timeout`,
      Remarks: 'POS status check',
      Occasion: 'StatusQuery'
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  )

  return response.data
}

async function reverseTransaction(transactionId, amount) {
  const token = await getAccessToken()
  const securityCredential = generateSecurityCredential(
    process.env.MPESA_INITIATOR_PASSWORD
  )

  const response = await axios.post(
    `${BASE_URL}/mpesa/reversal/v1/request`,
    {
      Initiator: process.env.MPESA_INITIATOR_NAME,
      SecurityCredential: securityCredential,
      CommandID: 'TransactionReversal',
      TransactionID: transactionId,
      Amount: amount,
      ReceiverParty: SHORTCODE,
      RecieverIdentifierType: '11', // 11 = reversal
      ResultURL: `${CALLBACK_URL}/api/mpesa/reversal-result`,
      QueueTimeOutURL: `${CALLBACK_URL}/api/mpesa/reversal-timeout`,
      Remarks: 'POS transaction reversal',
      Occasion: 'Reversal'
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  )

  return response.data
}

async function safeInitiateSTKPush(phoneNumber, amount, orderId) {
  // Check 1: Does this order already have a payment?
  const existing = await findTransaction({ orderId })
  if (existing && ['pending', 'completed'].includes(existing.status)) {
    return {
      success: false,
      error: 'Payment already in progress for this order'
    }
  }

  // Check 2: Cooldown per phone number
  const recentTx = await findRecentTransaction({
    phoneNumber: formatPhone(phoneNumber),
    createdAfter: new Date(Date.now() - 60000) // 60 seconds
  })

  if (recentTx) {
    return {
      success: false,
      error: 'Please wait before retrying. A recent payment was sent to this number.'
    }
  }

  // Safe to proceed
  return initiateSTKPush(phoneNumber, amount, orderId)
}

async function withRetry(fn, maxRetries = 3, baseDelay = 1000) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn()
    } catch (error) {
      const isRetryable =
        error.response?.status >= 500 ||
        error.response?.status === 429 ||
        error.code === 'ECONNRESET'

      if (!isRetryable || attempt === maxRetries - 1) {
        throw error
      }

      const delay = baseDelay * Math.pow(2, attempt)
      const jitter = Math.random() * 1000
      await new Promise(r => setTimeout(r, delay + jitter))
    }
  }
}

// Usage
const result = await withRetry(
  () => initiateSTKPush(phone, amount, orderId),
  3, // max 3 retries
  2000 // start at 2 second delay
)

// Send a mock callback to test your handler locally
async function sendMockCallback(checkoutRequestId, success = true) {
  const payload = success
    ? {
        Body: {
          stkCallback: {
            MerchantRequestID: 'test-merchant-001',
            CheckoutRequestID: checkoutRequestId,
            ResultCode: 0,
            ResultDesc: 'The service request is processed successfully.',
            CallbackMetadata: {
              Item: [
                { Name: 'Amount', Value: 1500 },
                { Name: 'MpesaReceiptNumber', Value: 'TEST123456' },
                { Name: 'TransactionDate', Value: 20260225143025 },
                { Name: 'PhoneNumber', Value: 254708374149 }
              ]
            }
          }
        }
      }
    : {
        Body: {
          stkCallback: {
            MerchantRequestID: 'test-merchant-001',
            CheckoutRequestID: checkoutRequestId,
            ResultCode: 1032,
            ResultDesc: 'Request cancelled by user'
          }
        }
      }

  await axios.post('http://localhost:3000/api/mpesa/stk-callback', payload)
}

Q: How long does it take to get Daraja API production credentials?

A: After submitting your go-live request on the Safaricom Developer Portal, production credentials typically take 3-5 business days. Ensure your application is fully tested in sandbox, your callback URLs are live and accessible over HTTPS, and all required business documents are uploaded.

Q: What is the difference between STK Push and C2B for POS systems?

A: STK Push (Lipa Na M-Pesa Online) is merchant-initiated: the POS sends a payment prompt to the customer phone. C2B is customer-initiated: the customer manually enters the Till or Paybill number. STK Push is faster for in-store POS checkout (10-15 seconds vs 30-60 seconds) and reduces human error since the amount is pre-filled.

Q: Can I use the Daraja sandbox for automated testing?

A: Yes. The Daraja sandbox supports automated testing with test credentials and simulated phone numbers. You can simulate successful payments, failed payments, and timeouts. Use the sandbox base URL https://sandbox.safaricom.co.ke and the test credentials from your Safaricom Developer Portal dashboard.

Q: How do I handle M-Pesa callback timeouts in my POS?

A: Implement a polling fallback using the Transaction Status API. After initiating STK Push, wait 30 seconds for the callback. If no callback arrives, query the transaction status. Retry up to 3 times with exponential backoff (30s, 60s, 120s). Always store the CheckoutRequestID so you can query later.

Q: What SSL certificate do I need for M-Pesa callbacks?

A: Safaricom requires a valid SSL/TLS certificate from a trusted Certificate Authority (CA) for all callback URLs. Self-signed certificates are not accepted. Free certificates from Let's Encrypt work perfectly. The certificate must cover the exact domain used in your callback URL.

Q: How do I prevent double charges with M-Pesa STK Push?

A: Use idempotency keys. Generate a unique identifier for each POS transaction and include it as the AccountReference in your STK Push request. Before initiating a new STK Push, check if a pending or completed transaction exists for that identifier. Also implement a cooldown period (e.g., 60 seconds) per phone number to prevent accidental duplicate triggers.

Q: What are the M-Pesa API rate limits?

A: Daraja API rate limits are per-app and depend on your production tier. Default production limits are approximately 40 transactions per second for STK Push. If you need higher throughput, contact Safaricom to request a rate limit increase. Always implement retry logic with exponential backoff for 429 (rate limit) responses.

Q: Can I process M-Pesa refunds programmatically?

A: Yes, use the B2C API (Business to Customer) to send refunds back to the customer M-Pesa account. You need the Initiator Name, Security Credential, and the original transaction details. Note that B2C requires separate approval from Safaricom and has different credentials from STK Push.

Q: How do I handle the "Request cancelled by user" error?

A: ResultCode 1032 means the customer dismissed the STK Push prompt without entering their PIN. In your POS, show a friendly message like "Payment was cancelled. Would you like to try again?" and allow the cashier to re-initiate the STK Push. Do not automatically retry without customer consent.

Q: What IP addresses should I whitelist for M-Pesa callbacks?

A: Safaricom publishes their callback IP ranges in the Daraja API documentation. As of 2025, the primary ranges include 196.201.214.0/24 and 196.201.214.200/28. Always verify the current list from Safaricom official documentation as these may change. Implement IP whitelisting at both application and firewall levels.

Q: How do I test M-Pesa integration without a real phone number?

A: Use the Daraja sandbox environment with the test phone number 254708374149. This number simulates a successful STK Push flow. For testing failures, you can use specific test scenarios documented in the Safaricom Developer Portal. No real money is involved in sandbox transactions.

Q: Does EliteTeQ POS handle all M-Pesa integration complexity?

A: Yes. EliteTeQ POS provides a pre-built M-Pesa integration that handles STK Push, C2B confirmation, callback processing, transaction status queries, error handling, and automatic reconciliation. You do not need to write any code or manage API credentials. The system is production-ready out of the box.

Skip the integration work. Get M-Pesa payments working today.

EliteTeQ POS includes a production-ready M-Pesa integration with STK Push, C2B, reconciliation, and KRA eTIMS compliance. Book a free demo: Book a Free Demo