How to Properly Handle M-Pesa STK Push Timeouts and Disconnections Without Losing Transaction State

The STK Push gets all the attention because it is what users interact with directly, a prompt appears on their phone, they enter their PIN, money moves. But a large class of business problems requires the reverse: your system needs to push money out to a customer's phone without any action on their end. Refunds, loan disbursements, withdrawal payouts, salary payments, promotional cashbacks, marketplace seller payments, all of these are B2C problems.The Daraja Business to Customer (B2C) API handles exactly this. You call the endpoint with a phone number and an amount, Safaricom processes the transaction, and the money lands in the recipient's M-Pesa wallet. No STK prompt. No customer action required.<ad-spot></ad-spot>This guide covers the full B2C integration in Node.js, from understanding what makes B2C different from STK Push, through generating the SecurityCredential that trips most developers up, to parsing the async callback correctly. If you have already read our <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/how-to-integrate-m-pesa-stk-push-using-daraja-30-a-complete-guide-for-kenya">STK Push guide</a> and <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/how-to-integrate-m-pesa-c2b-payments-with-daraja-30-nodejs-guide">C2B guide, </a>the patterns here will feel familiar.<h2>How B2C Is Different From STK Push</h2>Before touching any code, it is worth being precise about what B2C does and does not do, because the assumptions people carry from STK Push cause the most common B2C mistakes.STK Push is customer-initiated in the sense that the customer must actively approve the transaction by entering their PIN. Your system triggers the prompt, but the money does not move until the customer responds.B2C is business-initiated. Your system sends the request, Safaricom validates it, and the money moves. The recipient gets a notification SMS but takes no action. This means:<ul><li>You need a B2C-specific shortcode — a standard Paybill or Till number does not work. You need to apply specifically for a B2C shortcode through Safaricom.</li><li>You need an Initiator — an API operator account created on the M-Pesa business portal with the correct role assigned.</li><li>You need a SecurityCredential — an encrypted version of the Initiator's password, generated using Safaricom's public key certificate. This is the step that blocks most developers.</li><li>B2C is asynchronous. Unlike STK Push where you wait for the callback, B2C has two callback URLs: a <code>ResultURL</code> for successful responses and a <code>QueueTimeOutURL</code> for when the transaction takes too long. Both must be live HTTPS endpoints when going to production.</li></ul><h2>Prerequisites</h2>Before writing a single line of code, confirm you have all of the following:A B2C shortcode — this is different from your standard Paybill or Till number. Log into the M-Pesa Business portal at business.safaricom.co.ke. Under your organisation's shortcodes, check whether a B2C shortcode is available. If not, you need to apply to Safaricom's M-Pesa Business team.An Initiator account with the correct role — on the M-Pesa Business portal, create an API operator account (not a web operator). Assign it the Org Business Manager role and the B2C Org API Initiator role. The username assigned during creation is your <code>InitiatorName</code>. The password set is the plaintext password you will encrypt into a <code>SecurityCredential</code>.<ad-spot></ad-spot>A Daraja app with B2C enabled — on <a target="_blank" rel="noopener noreferrer nofollow" href="https://developer.safaricom.co.ke">developer.safaricom.co.ke</a>, create or use an existing app and ensure B2C is among the enabled APIs. Note your Consumer Key and Consumer Secret.Public HTTPS callback URLs — for sandbox testing, tools like <a target="_blank" rel="noopener noreferrer nofollow" href="https://ngrok.com">ngrok</a> work. For production, these must be real HTTPS endpoints. Do not use ngrok or any tunneling tool in production.<h2>Generating the SecurityCredential</h2>This is the step where most B2C integrations stall. The SecurityCredential is not your Initiator password in plaintext, it is your Initiator password encrypted with Safaricom's M-Pesa public key certificate, then Base64 encoded.Safaricom provides two certificates:<ul><li>Sandbox: downloadable from developer.safaricom.co.ke under Test Credentials</li><li>Production: downloadable from the same portal under your production app</li></ul>Here is how to generate the SecurityCredential in Node.js:<pre><code class="language-javascript">const crypto = require('crypto');
const fs = require('fs');

function generateSecurityCredential(initiatorPassword, certificatePath) {
 // Read the certificate file
 const certificate = fs.readFileSync(certificatePath);
 
 // Encrypt the password using the certificate's public key
 const encrypted = crypto.publicEncrypt(
 {
 key: certificate,
 padding: crypto.constants.RSA_PKCS1_PADDING,
 },
 Buffer.from(initiatorPassword)
 );
 
 // Return as Base64 string
 return encrypted.toString('base64');
}

// Usage
const securityCredential = generateSecurityCredential(
 'your_initiator_password',
 './sandbox_cert.cer' // or './production_cert.cer' for live
);

console.log(securityCredential);
// Copy this value into your .env file as MPESA_SECURITY_CREDENTIAL
</code></pre>Important: Generate this once and store it. Do not regenerate it on every request, the certificate changes rarely and regenerating unnecessarily adds latency. Store the generated credential in your environment variables.<ad-spot></ad-spot>Also important: The Initiator password on the M-Pesa Business portal expires periodically, typically every 90 days. When it expires, your B2C requests will fail with "The Initiator Information Is Invalid." Set a calendar reminder to renew the password before expiry and regenerate the SecurityCredential immediately after.Store credentials in a <code>.env</code> file:<pre><code>MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_B2C_SHORTCODE=600XXX
MPESA_INITIATOR_NAME=your_initiator_name
MPESA_SECURITY_CREDENTIAL=your_generated_base64_credential
MPESA_RESULT_URL=https://yourdomain.com/api/mpesa/b2c/result
MPESA_TIMEOUT_URL=https://yourdomain.com/api/mpesa/b2c/timeout
</code></pre><h2>Project Setup</h2><pre><code class="language-bash">mkdir daraja-b2c &amp;&amp; cd daraja-b2c
npm init -y
npm install express axios dotenv
touch index.js .env
</code></pre><h2>Step 1: Generate an Access Token</h2>Every Daraja API call requires a Bearer token obtained by authenticating with your Consumer Key and Consumer Secret. This is identical to the STK Push and C2B guides.<pre><code class="language-javascript">// auth.js
const axios = require('axios');

async function getAccessToken() {
 const consumerKey = process.env.MPESA_CONSUMER_KEY;
 const consumerSecret = process.env.MPESA_CONSUMER_SECRET;
 
 const auth = Buffer.from(`${consumerKey}:${consumerSecret}`).toString('base64');
 
 // Sandbox URL — change to api.safaricom.co.ke for production
 const url = 'https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials';
 
 const response = await axios.get(url, {
 headers: {
 Authorization: `Basic ${auth}`,
 },
 });
 
 return response.data.access_token;
}

module.exports = { getAccessToken };
</code></pre><h2>Step 2: The B2C Request</h2>The B2C API endpoint is:<ul><li>Sandbox: <code>https://sandbox.safaricom.co.ke/mpesa/b2c/v3/paymentrequest</code></li><li>Production: <code>https://api.safaricom.co.ke/mpesa/b2c/v3/paymentrequest</code></li></ul><pre><code class="language-javascript">// b2c.js
const axios = require('axios');
const { getAccessToken } = require('./auth');

async function sendB2CPayment({
 phone,
 amount,
 commandID = 'BusinessPayment',
 remarks = 'Payment',
 occasion = '',
}) {
 const token = await getAccessToken();
 
 // Normalise phone number to 254XXXXXXXXX format
 const normalisedPhone = phone.replace(/^0/, '254').replace(/^\+/, '');
 
 const payload = {
 InitiatorName: process.env.MPESA_INITIATOR_NAME,
 SecurityCredential: process.env.MPESA_SECURITY_CREDENTIAL,
 CommandID: commandID,
 Amount: amount,
 PartyA: process.env.MPESA_B2C_SHORTCODE,
 PartyB: normalisedPhone,
 Remarks: remarks,
 QueueTimeOutURL: process.env.MPESA_TIMEOUT_URL,
 ResultURL: process.env.MPESA_RESULT_URL,
 Occasion: occasion,
 };
 
 const response = await axios.post(
 'https://sandbox.safaricom.co.ke/mpesa/b2c/v3/paymentrequest',
 payload,
 {
 headers: {
 Authorization: `Bearer ${token}`,
 'Content-Type': 'application/json',
 },
 }
 );
 
 return response.data;
}

module.exports = { sendB2CPayment };
</code></pre><h2>Understanding CommandID</h2>The <code>CommandID</code> field tells Safaricom what type of B2C payment this is. There are three valid values:<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1">CommandID</th><th colspan="1" rowspan="1">Use case</th></tr><tr><td colspan="1" rowspan="1"><code>BusinessPayment</code></td><td colspan="1" rowspan="1">General payments — refunds, withdrawals, marketplace seller payouts, any ad-hoc payment</td></tr><tr><td colspan="1" rowspan="1"><code>SalaryPayment</code></td><td colspan="1" rowspan="1">Employee salary disbursements</td></tr><tr><td colspan="1" rowspan="1"><code>PromotionPayment</code></td><td colspan="1" rowspan="1">Cashbacks, loyalty rewards, promotional disbursements</td></tr></tbody></table>Use <code>BusinessPayment</code> for the majority of use cases unless your specific deployment is salary or promotion related. The CommandID affects how the transaction is reported in M-Pesa statements and how Safaricom classifies your usage pattern.<h2>Step 3: Handling the Callbacks</h2>B2C is fully asynchronous. The initial API response tells you Safaricom has accepted the request. The actual result (success or failure ) arrives later at your <code>ResultURL</code> or <code>QueueTimeOutURL</code>. You must handle both.<ad-spot></ad-spot><h3>The Result Callback (Success or Failure)</h3><pre><code class="language-javascript">// routes/b2cCallback.js
const express = require('express');
const router = express.Router();

router.post('/result', express.json(), (req, res) =&gt; {
 // Always respond to Safaricom immediately — before any async processing
 res.json({ ResultCode: 0, ResultDesc: 'Success' });
 
 const result = req.body?.Result;
 
 if (!result) {
 console.error('B2C callback: empty result body');
 return;
 }
 
 const {
 ResultCode,
 ResultDesc,
 OriginatorConversationID,
 ConversationID,
 TransactionID,
 ResultParameters,
 } = result;
 
 if (ResultCode !== 0) {
 // Transaction failed
 console.error(`B2C failed [${OriginatorConversationID}]: ${ResultDesc}`);
 // Update your database — mark this payout as failed
 // Trigger retry logic if appropriate
 return;
 }
 
 // Transaction succeeded — extract result parameters
 const params = {};
 ResultParameters?.ResultParameter?.forEach(({ Key, Value }) =&gt; {
 params[Key] = Value;
 });
 
 console.log('B2C success:', {
 transactionID: TransactionID,
 conversationID: ConversationID,
 originatorConversationID: OriginatorConversationID,
 transactionAmount: params.TransactionAmount,
 transactionReceipt: params.TransactionReceipt,
 receiverPartyPublicName: params.ReceiverPartyPublicName,
 transactionCompletedDateTime: params.TransactionCompletedDateTime,
 b2CUtilityAccountAvailableFunds: params.B2CUtilityAccountAvailableFunds,
 b2CWorkingAccountAvailableFunds: params.B2CWorkingAccountAvailableFunds,
 });
 
 // Update your database — mark payout as complete
 // Store TransactionReceipt as your reference
});

module.exports = router;
</code></pre><h3>The Timeout Callback</h3>This fires when the transaction has been queued but Safaricom has not processed it within the timeout window. This does not necessarily mean the transaction failed, it may still process later.<pre><code class="language-javascript">router.post('/timeout', express.json(), (req, res) =&gt; {
 res.json({ ResultCode: 0, ResultDesc: 'Accepted' });
 
 const result = req.body?.Result;
 const { OriginatorConversationID, ConversationID } = result || {};
 
 console.warn(`B2C timeout [${OriginatorConversationID}]`);
 
 // Do NOT immediately mark the payout as failed
 // Use the Transaction Status API to check the outcome later
 // Schedule a status check after 5-10 minutes
});
</code></pre><h2>Step 4: The Full Express Server</h2><pre><code class="language-javascript">// index.js
require('dotenv').config();
const express = require('express');
const { sendB2CPayment } = require('./b2c');
const b2cCallbackRouter = require('./routes/b2cCallback');

const app = express();
app.use(express.json());

// Callback routes — must match your MPESA_RESULT_URL and MPESA_TIMEOUT_URL
app.use('/api/mpesa/b2c', b2cCallbackRouter);

// Trigger a B2C payment (protect this route in production — never expose it publicly)
app.post('/api/pay', async (req, res) =&gt; {
 const { phone, amount, remarks } = req.body;
 
 try {
 const result = await sendB2CPayment({
 phone,
 amount,
 commandID: 'BusinessPayment',
 remarks: remarks || 'Payment',
 });
 
 res.json({
 success: true,
 conversationID: result.ConversationID,
 originatorConversationID: result.OriginatorConversationID,
 responseDescription: result.ResponseDescription,
 });
 } catch (error) {
 console.error('B2C initiation failed:', error.response?.data || error.message);
 res.status(500).json({
 success: false,
 error: error.response?.data || error.message,
 });
 }
});

app.listen(3000, () =&gt; console.log('Server running on port 3000'));
</code></pre><h2>Idempotency and the OriginatorConversationID</h2>The <code>OriginatorConversationID</code> is Safaricom's reference for your request. When your callback arrives, this is how you match it to the payout record in your database.The critical pattern: store the OriginatorConversationID in your database at the moment you initiate the B2C request, before waiting for the callback. This way, when the callback arrives ( potentially minutes later ) you have a clean record to update.<pre><code class="language-javascript">// At initiation time
const result = await sendB2CPayment({ phone, amount });

await db.payouts.create({
 originatorConversationID: result.OriginatorConversationID,
 conversationID: result.ConversationID,
 phone,
 amount,
 status: 'pending',
 initiatedAt: new Date(),
});

// In your callback handler
const payout = await db.payouts.findOne({
 where: { originatorConversationID: result.OriginatorConversationID }
});

await payout.update({
 status: ResultCode === 0 ? 'completed' : 'failed',
 transactionID: result.TransactionID,
 completedAt: new Date(),
});
</code></pre>Never process a callback without first confirming the <code>OriginatorConversationID</code> exists in your database. Unknown IDs should be logged and investigated, they may indicate replay attacks.<h2>Common Errors and What They Mean</h2>"The Initiator Information Is Invalid" Your SecurityCredential does not match the Initiator. Either you used the wrong password to generate it, used the sandbox certificate for a production request (or vice versa), or the Initiator password has expired on the M-Pesa Business portal. Renew the password and regenerate the SecurityCredential."Invalid Access Token" The Bearer token has expired (tokens last 1 hour). Implement token caching with automatic refresh rather than fetching a new token on every request.<ad-spot></ad-spot>"The request requires authentication" (HTTP 401) Your Consumer Key or Consumer Secret is wrong, or you are using sandbox credentials against the production endpoint."System internal error" (or empty response) Usually a Safaricom-side issue. Implement exponential backoff retry logic for the initiation request. Do not retry blindly, check your database first to avoid duplicate payouts.No callback received Your <code>ResultURL</code> is not publicly accessible. In sandbox, ensure your ngrok tunnel is running and the URL in your <code>.env</code> matches exactly. In production, ensure your HTTPS certificate is valid and the route is live.<h2>Going to Production Checklist</h2><ul><li>Apply for and receive a production B2C shortcode from Safaricom</li><li>Create the Initiator account on the production M-Pesa Business portal with the correct roles</li><li>Download the production certificate from the Daraja portal and regenerate SecurityCredential</li><li>Replace sandbox URLs with production URLs (<code>api.safaricom.co.ke</code>)</li><li>Replace <code>.env</code> values with production Consumer Key and Secret</li><li>Ensure <code>ResultURL</code> and <code>QueueTimeOutURL</code> are live HTTPS endpoints, not localhost, not ngrok</li><li>Whitelist your server IP with Safaricom (required for production)</li><li>Test with a small amount (Ksh 1) before enabling full amounts</li><li>Set a reminder to renew the Initiator password before its 90-day expiry</li><li>Implement Transaction Status API calls for timeout scenarios</li></ul><h2>What Comes Next in This Series</h2>This guide completes the core M-Pesa payment flows for most applications. The next guide in the series covers the Transaction Status API — how to query the outcome of any B2C, C2B, or STK Push transaction after the fact. This is essential for recovering from timeout scenarios and for building reconciliation tooling.Read the rest of the Daraja series: <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/how-to-integrate-m-pesa-stk-push-using-daraja-30-a-complete-guide-for-kenya">STK Push guide </a>| <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/how-to-integrate-m-pesa-c2b-payments-with-daraja-30-nodejs-guide">C2B guide</a> | Transaction Status (coming soon)Questions about your B2C integration? Drop them in the comments, we read every one.

How to Send Money from Your M-Pesa Business Account to Any Phone Using the Daraja B2C API

If you are building a product in Kenya that accepts payments, M-Pesa integration is not optional, it is table stakes. Over 100 million transactions move through M-Pesa every day, and 25% of them now flow through APIs built by developers like you on Safaricom's Daraja platform.This guide covers the most common and most useful integration: the STK Push, the prompt that appears on a customer's phone asking them to enter their M-Pesa PIN to complete a payment. By the end, you will have a working Node.js backend that authenticates with Daraja 3.0, initiates an STK Push, and handles the callback when the transaction completes or fails.This guide uses the sandbox environment throughout. The same code works in production with your live credentials, you just swap the URLs and keys.<h2>What You Need Before Starting</h2>A Daraja developer account. Register at <a target="_blank" rel="noopener noreferrer nofollow" href="https://developer.safaricom.co.ke">developer.safaricom.co.ke</a>. The process is now fully self-service, one of Daraja 3.0's most welcome improvements. No paperwork, no back-and-forth with a sales team.A sandbox app. After logging in, create a new app from your dashboard. You will receive a Consumer Key and Consumer Secret, treat these like passwords, never expose them in client-side code or commit them to a public repository.<ad-spot></ad-spot>Your sandbox credentials. From the APIs section of the developer portal, navigate to M-Pesa Express. You will find your sandbox Business Shortcode and Passkey. Save both, you will need them to generate the payment password.Node.js 20 or later. If you followed our <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/how-to-set-up-a-web-development-environment-in-kenya-2026-edition">developer environment setup guide,</a> you are already set.A way to expose your local server to the internet. The Daraja API sends transaction results to a callback URL on your server. During development, your server is on localhost which Safaricom cannot reach. The easiest solution is <a target="_blank" rel="noopener noreferrer nofollow" href="https://ngrok.com">ngrok</a>, it creates a public tunnel to your local machine. Install it and run <code>ngrok http 3000</code> (or whatever port you use) before testing.<h2>Project Setup</h2>Create your project folder and initialise it:<pre><code class="language-bash">mkdir mpesa-integration
cd mpesa-integration
npm init -y</code></pre>Install the dependencies:<pre><code class="language-bash">npm install express axios dotenv
npm install --save-dev nodemon</code></pre>Update <code>package.json</code> to add a dev script:<pre><code class="language-json">{
 "scripts": {
 "dev": "nodemon server.js",
 "start": "node server.js"
 }
}</code></pre>Create a <code>.env</code> file in the root of your project:<pre><code class="language-bash"># Daraja Sandbox Credentials
CONSUMER_KEY=your_consumer_key_here
CONSUMER_SECRET=your_consumer_secret_here
BUSINESS_SHORTCODE=174379
PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
CALLBACK_URL=https://your-ngrok-url.ngrok.io/callback

# Server
PORT=3000</code></pre><blockquote>The <code>BUSINESS_SHORTCODE</code> and <code>PASSKEY</code> values above are Safaricom's official sandbox test credentials. Use them for testing — replace with your live credentials before going to production.</blockquote>Create a <code>.gitignore</code> file immediately, before your first commit:<pre><code>node_modules/
.env</code></pre><h2>Step 1: Generate an Access Token</h2>Every Daraja API call requires a fresh OAuth access token. Tokens expire after 3,600 seconds (one hour). The cleanest approach is a middleware function that generates a token before each payment request.Create <code>middleware/auth.js</code>:<pre><code class="language-javascript">const axios = require("axios");

const generateToken = async (req, res, next) =&gt; {
 const consumerKey = process.env.CONSUMER_KEY;
 const consumerSecret = process.env.CONSUMER_SECRET;

 // Encode credentials as Base64
 const auth = Buffer.from(`${consumerKey}:${consumerSecret}`).toString("base64");

 try {
 const response = await axios.get(
 "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials",
 {
 headers: {
 Authorization: `Basic ${auth}`,
 },
 }
 );

 // Attach the token to the request object for the next handler
 req.access_token = response.data.access_token;
 next();
 } catch (error) {
 console.error("Token generation failed:", error.message);
 res.status(500).json({ error: "Failed to generate access token" });
 }
};

module.exports = generateToken;</code></pre><blockquote>For production: Cache the access token and only regenerate it when it is close to expiry, rather than making an OAuth call before every single transaction. This reduces latency and avoids hitting Safaricom's rate limits under load.</blockquote><h2>Step 2: Build the STK Push Utility</h2>The STK Push requires a password — a Base64-encoded combination of your Business Shortcode, your Passkey, and the current timestamp in <code>yyyyMMddHHmmss</code> format. This password proves to Safaricom that the request is genuinely from you.Create <code>utils/mpesa.js</code>:<pre><code class="language-javascript">const axios = require("axios");

/**
 * Generate the timestamp in the format required by Daraja: yyyyMMddHHmmss
 */
const getTimestamp = () =&gt; {
 const now = new Date();

 const year = now.getFullYear();
 const month = String(now.getMonth() + 1).padStart(2, "0");
 const day = String(now.getDate()).padStart(2, "0");
 const hours = String(now.getHours()).padStart(2, "0");
 const minutes = String(now.getMinutes()).padStart(2, "0");
 const seconds = String(now.getSeconds()).padStart(2, "0");

 return `${year}${month}${day}${hours}${minutes}${seconds}`;
};

/**
 * Generate the Base64 password required by STK Push
 * Formula: Base64(BusinessShortCode + Passkey + Timestamp)
 */
const generatePassword = (timestamp) =&gt; {
 const shortcode = process.env.BUSINESS_SHORTCODE;
 const passkey = process.env.PASSKEY;

 return Buffer.from(`${shortcode}${passkey}${timestamp}`).toString("base64");
};

/**
 * Format a phone number to the 2547XXXXXXXX format Daraja requires.
 * Accepts: 07XXXXXXXX, 7XXXXXXXX, +2547XXXXXXXX, 2547XXXXXXXX
 */
const formatPhoneNumber = (phone) =&gt; {
 // Remove any spaces or dashes
 const cleaned = phone.toString().replace(/[\s-]/g, "");

 if (cleaned.startsWith("254")) return cleaned;
 if (cleaned.startsWith("0")) return `254${cleaned.slice(1)}`;
 if (cleaned.startsWith("+254")) return cleaned.slice(1);
 if (cleaned.startsWith("7") || cleaned.startsWith("1")) return `254${cleaned}`;

 throw new Error(`Invalid phone number format: ${phone}`);
};

/**
 * Initiate an STK Push request
 * @param {string} phone - Customer phone number (any common Kenyan format)
 * @param {number} amount - Amount in KES (must be a whole number)
 * @param {string} accountReference - Your order ID or reference
 * @param {string} description - Short description of the transaction
 * @param {string} accessToken - OAuth token from the auth middleware
 */
const initiateSTKPush = async (phone, amount, accountReference, description, accessToken) =&gt; {
 const timestamp = getTimestamp();
 const password = generatePassword(timestamp);
 const formattedPhone = formatPhoneNumber(phone);
 const shortcode = process.env.BUSINESS_SHORTCODE;
 const callbackUrl = process.env.CALLBACK_URL;

 const payload = {
 BusinessShortCode: shortcode,
 Password: password,
 Timestamp: timestamp,
 TransactionType: "CustomerPayBillOnline",
 Amount: Math.round(amount), // Must be a whole number — no decimals
 PartyA: formattedPhone, // Customer's phone number
 PartyB: shortcode, // Your business shortcode
 PhoneNumber: formattedPhone,
 CallBackURL: callbackUrl,
 AccountReference: accountReference,
 TransactionDesc: description,
 };

 const response = await axios.post(
 "https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest",
 payload,
 {
 headers: {
 Authorization: `Bearer ${accessToken}`,
 "Content-Type": "application/json",
 },
 }
 );

 return response.data;
};

module.exports = { initiateSTKPush, formatPhoneNumber };</code></pre><h2>Step 3: Create the Express Server</h2>Create <code>server.js</code>:<pre><code class="language-javascript">require("dotenv").config();
const express = require("express");
const generateToken = require("./middleware/auth");
const { initiateSTKPush } = require("./utils/mpesa");

const app = express();
app.use(express.json());

/**
 * POST /stkpush
 * Initiates an M-Pesa STK Push to a customer's phone.
 *
 * Request body:
 * {
 * "phone": "0712345678",
 * "amount": 100,
 * "orderId": "ORDER-001"
 * }
 */
app.post("/stkpush", generateToken, async (req, res) =&gt; {
 const { phone, amount, orderId } = req.body;

 // Basic validation
 if (!phone || !amount || !orderId) {
 return res.status(400).json({
 error: "phone, amount, and orderId are required",
 });
 }

 if (amount &lt; 1) {
 return res.status(400).json({
 error: "Amount must be at least KES 1",
 });
 }

 try {
 const result = await initiateSTKPush(
 phone,
 amount,
 orderId,
 `Payment for order ${orderId}`,
 req.access_token
 );

 // MerchantRequestID and CheckoutRequestID identify this specific STK push
 // Save these to your database so you can match the callback to this request
 console.log("STK Push initiated:", result);

 res.status(200).json({
 message: "STK Push sent. Customer should receive a prompt shortly.",
 merchantRequestId: result.MerchantRequestID,
 checkoutRequestId: result.CheckoutRequestID,
 });
 } catch (error) {
 console.error("STK Push failed:", error.response?.data || error.message);
 res.status(500).json({
 error: "Failed to initiate payment",
 details: error.response?.data,
 });
 }
});

/**
 * POST /callback
 * Safaricom calls this endpoint with the transaction result.
 * This is where you confirm payment and update your database.
 */
app.post("/callback", (req, res) =&gt; {
 const callbackData = req.body;

 // Always respond with 200 immediately — Safaricom expects a quick acknowledgement
 res.status(200).json({ ResultCode: 0, ResultDesc: "Accepted" });

 // Now process the callback data
 const { Body } = callbackData;

 if (!Body?.stkCallback) {
 console.error("Unexpected callback structure:", callbackData);
 return;
 }

 const { ResultCode, ResultDesc, MerchantRequestID, CheckoutRequestID, CallbackMetadata } =
 Body.stkCallback;

 if (ResultCode === 0) {
 // Payment was successful
 // Extract transaction details from CallbackMetadata
 const metadata = {};
 CallbackMetadata.Item.forEach((item) =&gt; {
 metadata[item.Name] = item.Value;
 });

 console.log("Payment successful:", {
 merchantRequestId: MerchantRequestID,
 checkoutRequestId: CheckoutRequestID,
 amount: metadata.Amount,
 mpesaReceiptNumber: metadata.MpesaReceiptNumber, // The M-Pesa transaction ID
 transactionDate: metadata.TransactionDate,
 phoneNumber: metadata.PhoneNumber,
 });

 // TODO: Update your database here
 // Match using CheckoutRequestID to find the pending order
 // Mark the order as paid
 // Send confirmation to the customer

 } else {
 // Payment failed or was cancelled
 console.log("Payment failed:", {
 merchantRequestId: MerchantRequestID,
 checkoutRequestId: CheckoutRequestID,
 resultCode: ResultCode,
 resultDesc: ResultDesc, // Human-readable reason
 });

 // TODO: Update your database — mark the order as failed or pending
 // Common ResultCodes:
 // 1032 - Request cancelled by user
 // 1037 - DS timeout (user did not respond)
 // 2001 - Wrong PIN
 }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () =&gt; {
 console.log(`Server running on port ${PORT}`);
});</code></pre><ad-spot></ad-spot><h2>Step 4: Test It</h2>Start your server:<pre><code class="language-bash">npm run dev</code></pre>Start ngrok in a separate terminal:<pre><code class="language-bash">ngrok http 3000</code></pre>Copy the <code>https://</code> URL ngrok gives you, it looks like <code>https://a1b2c3d4.ngrok.io</code>. Update your <code>.env</code> file:<pre><code>CALLBACK_URL=https://a1b2c3d4.ngrok.io/callback</code></pre>Restart your server after updating <code>.env</code>.Trigger a test payment using curl:<pre><code class="language-bash">curl -X POST http://localhost:3000/stkpush \
 -H "Content-Type: application/json" \
 -d '{
 "phone": "0712345678",
 "amount": 1,
 "orderId": "TEST-001"
 }'</code></pre>If everything is configured correctly, you will get a response like:<pre><code class="language-json">{
 "message": "STK Push sent. Customer should receive a prompt shortly.",
 "merchantRequestId": "29115-34620561-1",
 "checkoutRequestId": "ws_CO_191220191020363925"
}</code></pre>In the sandbox, you do not receive an actual phone prompt. Instead, use Safaricom's Simulator in the developer portal to simulate a successful or failed payment. The simulator will send a callback to your ngrok URL, and you should see the transaction details logged in your terminal.<h2>Understanding the Callback Structure</h2>This is what a successful callback from Safaricom looks like:<pre><code class="language-json">{
 "Body": {
 "stkCallback": {
 "MerchantRequestID": "29115-34620561-1",
 "CheckoutRequestID": "ws_CO_191220191020363925",
 "ResultCode": 0,
 "ResultDesc": "The service request is processed successfully.",
 "CallbackMetadata": {
 "Item": [
 { "Name": "Amount", "Value": 1.00 },
 { "Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV" },
 { "Name": "TransactionDate", "Value": 20191219102115 },
 { "Name": "PhoneNumber", "Value": 254712345678 }
 ]
 }
 }
 }
}</code></pre>And a failed callback (user cancelled):<pre><code class="language-json">{
 "Body": {
 "stkCallback": {
 "MerchantRequestID": "29115-34620561-1",
 "CheckoutRequestID": "ws_CO_191220191020363925",
 "ResultCode": 1032,
 "ResultDesc": "Request cancelled by user."
 }
 }
}</code></pre>Note that failed callbacks do not include <code>CallbackMetadata</code>. Always check <code>ResultCode</code> before trying to read metadata.<h2>Common Errors and How to Fix Them</h2><code>400.002.02</code> — Bad Request: Invalid PhoneNumberYour phone number is not in the <code>2547XXXXXXXX</code> format. Use the <code>formatPhoneNumber</code> utility above.<code>400.002.02</code> — Bad Request: Invalid Amount. The amount must be a whole number. M-Pesa does not support decimal amounts. Use <code>Math.round(amount)</code>.<code>500.001.1001</code> — Internal Server Error. Usually means your password is wrong. Double-check that you are concatenating <code>shortcode + passkey + timestamp</code> in that exact order before Base64 encoding.Callback not arriving. Check that your ngrok URL is running and matches what is in <code>CALLBACK_URL</code> exactly. ngrok URLs change every time you restart ngrok unless you have a paid plan, always update your <code>.env</code> after restarting ngrok.<code>errorCode: 404.001.04</code> — App not found. Your Consumer Key and Consumer Secret do not match a valid app in the sandbox. Double-check your <code>.env</code> file.<h2>Going to Production</h2>When you are ready to go live, three things change:1. Replace sandbox URLs with production URLs:<pre><code class="language-javascript">// Sandbox
"https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"
"https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest"

// Production
"https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"
"https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest"</code></pre>2. Replace your sandbox credentials with live credentials — your live Consumer Key, Consumer Secret, Shortcode, and Passkey from the Daraja portal.3. Use a real HTTPS callback URL — ngrok is for development only. Your production callback endpoint must be on a real server with a valid SSL certificate. Safaricom will reject HTTP callback URLs in production.<ad-spot></ad-spot><h2>What to Build Next</h2>With STK Push working, the natural next integrations are:C2B (Customer to Business) — for accepting payments via Paybill without triggering an STK Push. Useful for cases where customers initiate the payment from their M-Pesa menu directly.B2C (Business to Customer) — for sending money to customers. Used for refunds, payouts, and disbursements. Requires additional approval from Safaricom.Transaction Status API — for checking the status of a payment that never received a callback. Network issues can occasionally drop callbacks, this API lets you query the status of any transaction by its <code>CheckoutRequestID</code>.Ratiba API — Daraja 3.0's newest addition, announced in early 2026. Enables scheduled and recurring payments, standing orders and subscription billing. Documentation is still rolling out on the developer portal.<h2>A Note on Number Masking</h2>As we covered in our <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.techinkenya.com/articles/m-pesa-is-hiding-your-phone-number-from-merchants-here-is-everything-that-c">M-Pesa number masking piece</a>, the CBK recently approved Safaricom to mask customer phone numbers from merchant-facing SMS confirmations. What remains unconfirmed is whether the <code>PhoneNumber</code> field in the Daraja callback payload will also be masked in the future.For now, the callback still returns the full customer phone number. Watch the Daraja changelog and the developer forum closely, if this changes, any logic that uses the callback phone number as a customer identifier will need to be updated.Built something with Daraja? Hit a specific error that is not covered here? Drop a comment below or reach us at hello@techinkenya.com. We update our guides when the API changes.

How to Properly Handle M-Pesa STK Push Timeouts and Disconnections Without Losing Transaction State

How to Send Money from Your M-Pesa Business Account to Any Phone Using the Daraja B2C API

How to Integrate M-Pesa STK Push Using Daraja 3.0 — A Complete Guide for Kenyan Developers