Accept M-Pesa Payments with STK Push

What you'll build

A Node.js/Express backend that accepts M-Pesa mobile money payments via Safaricom's Daraja API. M-Pesa is the dominant mobile money platform in Kenya, Tanzania, and across East Africa, processing billions of dollars in transactions annually. STK Push (also called Lipa Na M-Pesa Online) is the server-initiated payment flow — your backend triggers a payment prompt directly on the customer's phone. After they enter their M-Pesa PIN, Safaricom sends a callback to your server confirming the result.

By the end of this tutorial:

• Your server authenticates with Safaricom's Daraja API using OAuth2 client credentials
• POST /pay triggers an STK Push prompt on the customer's phone
• POST /mpesa/callback receives and validates the payment result
• GET /payments/:id lets you check the status of any payment
• All secrets are stored securely in environment variables

Prerequisites

• Node.js 18+ installed
• A Safaricom Developer account (free)
• ngrok or another HTTPS tunnel for local callback testing
• BlocWeave installed in VS Code

How M-Pesa STK Push works

1. Your server requests an OAuth2 access token from Safaricom
2. Your server sends an STK Push request with the customer's phone number and amount
3. Safaricom pushes a payment prompt to the customer's phone
4. The customer enters their M-Pesa PIN to authorize the payment
5. Safaricom sends a callback to your server with the payment result

Get your API key

1. Go to developer.safaricom.co.ke and create an account
2. Create a new app — enable Lipa Na M-Pesa Sandbox
3. Copy your Consumer Key and Consumer Secret from the app dashboard
4. Note the test shortcode and passkey from the sandbox documentation

Add these to your .env:

MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_passkey_from_sandbox_docs
MPESA_CALLBACK_URL=https://your-domain.com/mpesa/callback
PORT=3000

Initialize the project

mkdir mpesa-app && cd mpesa-app
npm init -y
npm install express dotenv axios
npm install -D typescript @types/express @types/node tsx
npx tsc --init

Add to package.json scripts:

"dev": "tsx watch src/index.ts"

Build the payment endpoint

Handle the webhook

Safaricom sends the payment result as a POST to your callback URL. The callback payload is deeply nested — the actual data lives inside Body.stkCallback. You must always return HTTP 200 quickly, even if the payment failed, otherwise Safaricom will keep retrying the callback.

Callback payload example

A successful payment callback looks like this:

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_191220191020363925",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 100 },
          { "Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV" },
          { "Name": "TransactionDate", "Value": 20191219102115 },
          { "Name": "PhoneNumber", "Value": 254708374149 }
        ]
      }
    }
  }
}

Test it

Start the server and expose it via ngrok:

npm run dev
# In another terminal:
ngrok http 3000

Update MPESA_CALLBACK_URL in .env with the ngrok HTTPS URL (e.g., https://abc123.ngrok-free.app/mpesa/callback), then restart the server.

Trigger a test payment using the Safaricom sandbox test credentials:

# Use the sandbox test number 254708374149
curl -X POST http://localhost:3000/pay \
  -H "Content-Type: application/json" \
  -d '{"phone": "254708374149", "amount": 100}'

You should get back a response like:

{
  "checkoutRequestId": "ws_CO_21062026120000123456",
  "merchantRequestId": "12345-67890123-1",
  "responseDescription": "Success. Request accepted for processing"
}

In the sandbox, the STK Push prompt is simulated — the callback will fire automatically after a few seconds. Check the payment status:

curl http://localhost:3000/payments/ws_CO_21062026120000123456

Common errors

Handling phone number formats

Kenyan customers enter phone numbers in many formats. Normalize them before calling the API:

• 0712345678 becomes 254712345678 (replace leading 0 with 254)
• +254712345678 becomes 254712345678 (strip the +)
• 254712345678 is already correct
• Reject numbers that don't start with 2547 after normalization

Project structure after this tutorial

src/
  mpesa.ts          # Daraja API auth + STK Push logic
  index.ts          # Express app, routes, callback handler
.env                # MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, etc.
package.json