The confirmation SMS is already a complete record
Every time someone pays you on M-Pesa, Safaricom sends a confirmation SMS. Look at one closely and you will notice it already contains everything your accounts need: the transaction code, the amount, the payer's name, the time, and often the account or reference they entered. The information exists the instant the money moves.
The problem is where that information sits. It lands in a phone's inbox, where a human has to read it and type the details into a system - or, more often, not bother, and reconcile in a rush at month end. The data is perfect; the delivery is the weak link. Fixing that delivery is exactly what an SMS gateway does.
How a phone becomes a payment gateway
The idea is simple. You dedicate an Android phone to the M-Pesa line that receives payments, and you install a small app on it. That app watches for incoming SMS from M-Pesa and forwards each one to your server over the internet the moment it arrives.
- The paying line's SIM sits in a dedicated phone that stays on and charged.
- The gateway app reads incoming M-Pesa messages and posts them to a URL you control.
- Your backend receives the message, parses it, and updates the invoice or ledger.
- Staff see the payment appear automatically, usually within seconds of the customer paying.
Why the naive version fails, and what a real gateway fixes
It is tempting to think this is a weekend script: read SMS, POST to a webhook, done. That version works in a demo and quietly loses money in production. Real conditions break it - the internet drops, the phone reboots, Android kills background apps to save battery, the same message gets sent twice, or a fake SMS tries to inject a payment that never happened.
Upeosoft's open-source SMS Gateway (github.com/Upeosoft-Limited/upeo-sms-gateway) is built for exactly those conditions. It stores messages in an encrypted on-device queue so nothing is lost when the connection fails, and retries with backoff until they land. It runs as a persistent foreground service with a scheduled backstop, so it survives battery optimisation and reboots. It signs every message with a shared secret using HMAC, so your server can reject anything that is not genuinely from your device. And it guarantees exactly-once delivery using a message hash and nonce, so one payment is never recorded as two.
The part you still have to get right: parsing and matching
Forwarding the SMS is half the job. The other half happens on your server, and it is a business decision as much as a technical one. Your backend has to parse the message text to extract the amount, code, name and reference, then match that payment to the correct invoice.
The amount alone will not identify an invoice, because two customers can owe the same figure. The reliable signal is the account reference the customer entered. If your reference scheme is clean - an invoice number, member number or account number your system recognises - matching is automatic. If it is messy, you fall back to manual matching. Designing that reference scheme well is what turns forwarded messages into a self-updating ledger.
Where this fits, and where full integration is better
The SMS gateway shines when Daraja is off the table: a personal line, a till you cannot register for C2B, or a business that needs automatic recording today. It is honest, low-cost, and it works. But it is a bridge. Where you can get a registered paybill or till and Daraja credentials, direct integration is cleaner - it gives you structured data, STK Push at checkout, and payouts.
We often deploy the SMS gateway first to stop the manual typing immediately, then move a business to full Daraja integration as it grows, or run both together for coverage. The right choice depends on your line, your volume, and how the money actually flows through your business.
How Upeosoft can help
The SMS Gateway is open source, so you can inspect exactly how it handles your payment data - the security model, the queue, the delivery guarantees are all there to read. What most businesses want, though, is the whole loop working: the phone forwarding messages, the backend parsing them correctly for your M-Pesa message format, and the payments matching your invoices in your accounting or ERP system automatically.
That is what we build. If you are drowning in manual M-Pesa reconciliation, or you cannot get Daraja on your line, talk to us and we will set up the gateway, wire the parsing to your system, and design the reference scheme so payments match themselves from day one.
