Setup — M-Pesa Tracker

Setup Guide

Get your M-Pesa transactions flowing into the tracker automatically. Two things to configure: the iOS Shortcut and your API keys.

iOS Shortcut — Auto-capture M-Pesa SMS

This Shortcut runs automatically every time you receive an SMS from MPESA. It reads the message body and POSTs it to your tracker in the background — no manual action needed.

Open the Shortcuts app and tap Automation

Tap the + button (top right) to create a new automation.

Choose trigger: Message

Scroll down and select Message as the trigger.
Set From to: MPESA
Toggle "Run Immediately" ON (so it fires without asking).

Add action: Get Contents of Shortcut Input

Tap Add Action, search for "Shortcut Input", and add Get Contents of Shortcut Input. This captures the incoming message object.

Add action: Get Body of Message

Search for "Body" and add Get Body of [Message]. Use the Shortcut Input result from the previous step as the input. This extracts the raw SMS text.

Add action: Get Contents of URL (HTTP request)

Search for "URL" and add Get Contents of URL.

Configure it as follows:

https://mpesa.smartshamba.io/api/sms

Method: POST

Request Body: JSON
Add one key-value pair:

sms → Body (from step 04)

Headers: Add one header:

X-API-Secret → <your API_SECRET from .env>

(Optional) Add action: Open URLs

Add Open URLs and enter your dashboard URL to jump straight to the app after a transaction is captured.

https://mpesa.smartshamba.io

Tap Done and test it

Send yourself a test M-Pesa SMS (or ask someone to send KES 1). The automation should fire silently and the transaction should appear in your Ledger tab within seconds.

Tip: iOS will ask for permission to run the automation the first time. Tap Allow. After that, it runs silently in the background forever.

Test without a real SMS: You can POST a sample message directly to verify your setup is working:

curl -X POST https://mpesa.smartshamba.io/api/sms \

        -H "Content-Type: application/json" \

        -H "X-API-Secret: YOUR_SECRET" \

        -d '{"sms":"QK58XXXXX Confirmed. KES1,500.00 sent to JOHN DOE 0712345678 on 10/4/24 at 2:30 PM. New M-PESA balance is Ksh8,500.00."}'

Add your Anthropic API Key

The AI Advisor uses Claude. Without a key it will show an error — everything else works fine. Get a key at console.anthropic.com.

SSH into your VPS

ssh -p 2222 user@your-vps-ip

Edit the .env file in the app directory

nano ~/mpesa-tracker/.env

Set your keys

Your .env should contain:

ANTHROPIC_API_KEY=sk-ant-api03-...
API_SECRET=a-long-random-string-you-choose
APP_URL=https://mpesa.smartshamba.io
PORT=3000

Save with Ctrl+O, exit with Ctrl+X.

Restart the app to apply changes

pm2 restart mpesa-tracker

Never commit .env to git. The .env.example file has empty placeholders — that one is safe to commit. Your actual .env is already in .gitignore.

Verify Everything is Running

Check PM2 process status

pm2 status

You should see mpesa-tracker with status online.

Check the logs

pm2 logs mpesa-tracker --lines 20

Should show ✓ mpesa-tracker running on startup.

Test the SMS endpoint

curl -s -X POST https://mpesa.smartshamba.io/api/sms \
  -H "Content-Type: application/json" \
  -H "X-API-Secret: YOUR_SECRET" \
  -d '{"sms":"Test"}'

Returns JSON with the parsed (or failed) transaction.

All good? Head back to the Dashboard → and wait for your first real M-Pesa SMS to come in.