M-Pesa Daraja STK Push Setup Guide for Tanzania Merchants

Most Tanzanian shops know the drill. The cashier shouts the till number across a noisy counter. The customer squints at their phone, types six digits, hits send. Then everyone stares at their handsets, waiting for an SMS that may take five seconds or three minutes — and sometimes shows the wrong amount. STK Push ends that ritual. The customer still pays with M-Pesa, but it is the shop that pushes the prompt to their phone. Tap "pay", enter PIN, done. Money lands in your till before the cashier finishes scanning the next item. This guide walks Tanzanian merchants through registering for M-Pesa Daraja, getting the right credentials, wiring it into a POS like NinoPOS, and dodging the reconciliation traps that catch nearly every shop in its first month live.

What is M-Pesa Daraja, and what is STK Push?

M-Pesa is Vodacom Tanzania’s mobile-money service — the country’s default way to pay anyone for anything, second only to physical cash. Walk into any retailer or restaurant in Dar es Salaam, Arusha, or Mwanza and the till accepts it.

Daraja is the developer API behind it. It lets a POS, a website, or a custom app speak to M-Pesa directly instead of relying on the customer to type a till number. Without Daraja you live in the SMS-confirmation lane: customer pays, you wait for the text, you type the reference into the POS, and you cross your fingers that the amount matches.

With Daraja, the script flips. The cashier picks M-Pesa on the POS, types the customer’s phone number, and the customer’s screen lights up: "Pay TZS 25,000 to MwanzaHardware?" They enter their PIN. The money lands. The POS marks the invoice paid. The receipt prints. The whole exchange takes under a minute, and the data is structured from second one — no manual reference entry, no amount guesswork.

That second flow has a name: STK Push, also called Lipa Na M-Pesa Online on Vodacom Tanzania. The merchant initiates; the customer confirms. Less typing on both sides, no transposed digits, and an audit trail that lines up with your bank statement at end-of-day instead of end-of-month.

Daraja vs paybill vs till — which one do you have?

Three M-Pesa receiving setups exist, and people confuse them constantly:

Setup	What it is	Who uses it	Daraja-eligible?
Personal M-Pesa	Your own phone number	Hawkers, casual transactions	No
Lipa Namba (Till) / Buy Goods	A 5–7-digit till number for a registered business	Most retailers, restaurants	Yes — with a separate Daraja application
PayBill / Business Number	Multi-account paybill for utilities, schools, SaaS subscriptions	Recurring billers	Yes — different Daraja flow than till

For a typical Tanzanian retailer or restaurant, you want Lipa Namba (Buy Goods) for in-store and over-the-counter sales, plus optionally PayBill for recurring invoicing.

Compliance note: NinoPOS is a POS and business-management platform. We do not claim an official Vodacom, Safaricom, M-Pesa, or Daraja partnership unless separately verified. Businesses should confirm Daraja access, account approval, credential issuance, transaction rules, fees, and dispute processes directly with Vodacom Tanzania or the relevant provider — or contact our team and we’ll point you to the right resource.

Step-by-step: setting up M-Pesa Daraja STK Push in Tanzania

Step 1 — Register your business for M-Pesa Lipa Namba

You’ll need:

• Business registration certificate (BRELA)
• TIN
• A valid company-registered phone number for the M-Pesa till administrator
• Bank account in the business name (M-Pesa settlement runs to a registered bank account)

Visit the nearest Vodacom shop or apply through the Vodacom business team. Activation is typically a few business days. The output is your Till Number (the 5–7-digit number customers will pay).

Important: Register the till in your business name, not your personal name. Personal till numbers cannot get Daraja API access, and switching later means a new till number — which means resetting everything that points at the old one. Get this right on day one.

Step 2 — Apply for Daraja API access

Daraja API access is a separate application after the till is active. You’ll be asked for:

• The till number
• Business documents
• The technical contact who’ll receive credentials
• The list of API endpoints you need (for STK Push, you need Lipa Na M-Pesa Online aka C2B Express Online Payment)

The application goes through Vodacom’s developer team. Approval typically takes 1–2 weeks. The official Daraja developer documentation lives at the Safaricom Daraja Developer Portal (the API is shared between Vodacom Tanzania and Safaricom Kenya, with merchant relationships handled by each operator separately).

Step 3 — Get your API credentials

When approved, you’ll receive:

• Consumer Key and Consumer Secret — your API "username and password"
• Business Short Code — your till number, in API format
• Pass Key (also called Lipa Na M-Pesa Online Passkey) — used to sign STK Push requests

Treat these like banking credentials:

• Don’t email them in plaintext
• Don’t paste them into a chat thread
• Don’t store them in a Google Doc shared with the whole team
• Rotate them if a former employee had access

NinoPOS stores these encrypted at rest. Other systems vary — ask before you paste.

Step 4 — Test on sandbox

Before going live, every Daraja credential set goes through Vodacom’s sandbox. Sandbox transactions:

• Use a fake test PIN (typically 0000 or 1234)
• Don’t actually move money
• Return the same JSON shape as production
• Let you confirm your callback URL receives results

Run at least 5 test scenarios:

1. Successful payment
2. Customer cancellation
3. Customer enters wrong PIN
4. Customer ignores the prompt (timeout)
5. Insufficient balance

Each scenario produces a different response code. Your POS should handle all five gracefully.

Step 5 — Move to production

Once sandbox is green, flip the API URL to production and re-issue credentials. Some practical tips:

• Start with low-value transactions first. Take 5 real payments of 1,000–5,000 TZS each, end-to-end, before relying on Daraja for full-volume operations.
• Set a daily reconciliation alarm. At end of day, compare what the POS says (paid invoices) with what the M-Pesa statement shows (settled transactions). Drift in week 1 is normal; persistent drift after week 2 is a process bug.
• Decide who has the credentials. One owner, one written-down recovery plan. Don’t lose them — re-issuance takes days.

How NinoPOS handles M-Pesa payments

Credentials are the easy part. The harder question is how the payment lands cleanly on every other surface — your POS, your stock, your invoices, your books — without anyone typing anything twice.

POS checkout — three taps to take a payment

The NinoPOS POS Checkout module drives the till. A typical M-Pesa sale runs as follows: the cashier rings the items and taps Pay, picks M-Pesa, and types the customer’s phone in the form +255 7XX XXX XXX (or scans a QR if the customer has a NinoPOS profile). NinoPOS fires the STK Push request to Daraja. The customer’s screen prompts; they enter their PIN; the result lands back at the till in under sixty seconds. The receipt prints. No reference number to read out, nothing to type into the system after the fact.

If the customer cancels, mistypes their PIN, or just lets the prompt time out, the POS shows the reason inline and offers three exits: retry, switch to cash, or mix tenders. The line keeps moving.

Invoices — STK Push from a WhatsApp link

Walk-ins are the easy case. The harder ones are delivery orders, B2B invoicing, and recurring billing — sales where the customer is somewhere else when it’s time to pay. The Invoices module handles those with a hosted invoice page. Send the link via WhatsApp; the customer opens it, taps "Pay with M-Pesa", and the STK Push goes to whichever number they enter.

That pairs cleanly with the workflow in our WhatsApp Business + POS playbook: order placed in chat, invoice link sent in chat, payment completed in chat. The customer never leaves the conversation, and you never read out a till number.

Inventory — stock deducts only on confirmed payment

This is the failure mode that costs shops the most: a unit sold over WhatsApp but the M-Pesa transaction never finished, so the inventory says one is gone but the cash drawer disagrees. NinoPOS Inventory avoids it by holding stock against an in-progress order until Daraja confirms the payment. If the customer cancels or the transaction fails, the hold releases automatically, and the next walk-in customer sees the unit as available — not a stale "sold" state from twenty minutes ago.

Reconciliation — books match Daraja, automatically

The Payments module is where end-of-day actually closes. One screen lists every STK Push attempt — success, failed, cancelled, and timeout — with the Daraja transaction ID alongside each successful payment (masked from non-finance roles). Settled-to-bank status updates as M-Pesa pushes funds to your settlement account. The unmatched bucket is the one to watch: M-Pesa SMS confirmations that came in but don’t map to any POS sale, usually from a customer who paid the till manually outside the system. That bucket is where leaks happen, and the only way to catch them is to look every day. NinoPOS surfaces it on the homepage tile so it’s the first thing you see when you log in.

Refunds — supported via Daraja Reversal API where enabled

Refunding an M-Pesa payment is heavier lifting than refunding a card. Vodacom provides a Daraja Reversal API, but it isn’t turned on by default — you apply for the Reversal permission separately, usually after your account has racked up a few weeks of clean transaction history. Once it’s live, a refund initiated from the POS or invoice credits the customer’s M-Pesa, marks the original transaction reversed, and rolls stock back into inventory in one step.

Before Reversal is enabled, refunds still happen — they’re just manual. NinoPOS records the refund and your team processes it as cash or as a fresh M-Pesa send to the customer. Apply for Reversal as soon as your account qualifies; it removes a category of mistakes that compound otherwise.

Retail use case — a wholesaler in Dar es Salaam

Picture an illustrative depot in Kariakoo selling household goods to small kiosks and corner supermarkets. Average ticket: TZS 80,000 to 250,000. Roughly seven in ten orders settle on M-Pesa.

The old workflow had a familiar rhythm. A buyer arrives, picks goods, gets a handwritten invoice. The cashier reads out the till number; the buyer thumbs it into their phone; everyone waits for the SMS. Out of every hundred sales, six come back wrong — a transposed digit, a missing reference, an amount that doesn’t quite match. Six small mysteries. Multiply by twenty-five working days and reconciliation eats half of every month-end.

With Daraja STK Push driving the till, the same exchange runs differently. The cashier scans the items, picks M-Pesa, types the buyer’s number. The prompt hits the buyer’s phone in about four seconds; their PIN closes the transaction eight seconds later. The invoice marks itself paid, stock decrements, and the receipt prints — all before the buyer has put their phone back in their pocket. End-of-day reconciliation goes from half a day to three minutes.

For more retail patterns, see our retail POS landing page.

Restaurant use case — a takeaway in Mwanza

Twelve tables, dine-in plus a busy delivery channel. M-Pesa carries six in ten payments.

Before Daraja, the delivery loop ended the same way every night: the rider knocks on a door, asks for cash or a till payment, and one customer in five says "I’ll send it later." Most of them mean it. Some of them forget. The manager spends an hour every morning chasing yesterday’s ghosts.

The new loop closes earlier. The order arrives on WhatsApp; the kitchen confirms it; an invoice link goes back in the same chat. The customer taps Pay, enters their PIN, and the transaction settles while the food is still being plated. By the time the rider leaves, payment is already in the bank ledger. The only thing left to say at the door is "your food’s here — asante."

The restaurant module and other restaurant-specific flows are documented on our restaurant POS landing page.

How M-Pesa fits with TRA fiscal compliance

Mobile-money payment is one channel; fiscal compliance is a separate obligation. They meet at the receipt. NinoPOS records the M-Pesa transaction reference on every paid invoice, with TIN, VRN, and VAT line — so when you connect a TRA-approved VFD gateway, the M-Pesa-paid sales feed clean fiscal data the same as cash or card sales. See our TRA EFD/VFD setup guide for the full picture.

Common mistakes to avoid

Every shop hits a few of these in the first month. The good news: they’re all cheap to fix on day one and expensive to fix on day thirty.

1. Registering the till in a personal name. Personal tills can’t get Daraja access. Switching later means a new till number and re-pointing every receipt, sticker, and customer who already knows your old one. Register in the business name from the start.
2. Sharing API credentials in chat threads. Treat Consumer Secret and Pass Key like bank passwords. Don’t email them in plaintext. Don’t paste them into a group chat. Don’t store them in a Google Doc the whole team can open.
3. Skipping sandbox. Going straight to production means your first paying customer is also your first real test. Don’t. Burn an afternoon in sandbox first.
4. Not reconciling daily. Mismatches on day one take five minutes to fix. The same mismatches at month-end take half a day and a forensic mood. Set an end-of-day alarm and look every night, even when it’s "probably fine."
5. Treating timeouts as failures. A timed-out STK Push isn’t a failure — it’s unknown status. The customer may have paid; the SMS confirmation may just be slow. Always query Daraja’s Transaction Status endpoint before re-charging, or you’ll double-bill someone.
6. Forgetting the transaction cap. Vodacom Tanzania caps single transactions, and the cap changes. Check current rules. For a TZS 800,000 sale you may need to split into two STK Pushes — building that into the POS workflow now beats discovering it mid-transaction with a customer waiting.
7. No fallback when Daraja is down. Daraja has occasional outages. Your POS should detect them and let the cashier fall back to manual M-Pesa reference entry, which then reconciles automatically once Daraja comes back. A cashier staring at a frozen screen with a queue forming is not a contingency plan.
8. Not applying for Reversal early. Manual refunds are error-prone. The day your Daraja account is two weeks old and clean is the day to apply for Reversal — easier to get then than later, and it removes a whole class of small leaks.

Ready to take M-Pesa cleanly?

NinoPOS gives you the structured POS, invoice, inventory, and reconciliation layer that makes M-Pesa Daraja safe to rely on every day.

• Start a 30-day free trial — no card required: Try NinoPOS free
• Compare plans: pricing page
• Want help mapping your specific M-Pesa flow into NinoPOS? Contact our team.

Frequently Asked Questions

Is NinoPOS officially certified by Vodacom or Safaricom?

No. NinoPOS uses Vodacom Tanzania’s public Daraja API the same way any compliant integrator does. We don’t claim partnership or certification we don’t have. For Daraja account approval, credentials, and any transaction disputes, contact Vodacom Tanzania directly.

Can I use my personal M-Pesa number with NinoPOS?

For Daraja STK Push, no — Daraja requires a business till (Lipa Namba / Buy Goods or PayBill). You can manually record M-Pesa payments to a personal number in NinoPOS, but the STK Push automation only works with a registered business till.

How long does Daraja API approval take in Tanzania?

Typically 1–2 weeks after your business till is active and your application is complete. Incomplete applications loop back; complete ones move quickly.

What happens if the customer’s STK Push times out?

The status is unknown — they may have paid (and the SMS is slow), they may not have. NinoPOS automatically queries Daraja’s Transaction Status endpoint to confirm before allowing a retry. Don’t re-charge a timed-out push without confirming.

Can I refund an M-Pesa payment through NinoPOS?

Yes, if your Daraja account has the Reversal API permission enabled (a separate application after your main Daraja approval). Without Reversal, NinoPOS records the refund and your team processes it manually.

Are STK Push fees passed to the customer or absorbed by the merchant?

That’s controlled by your Daraja merchant configuration with Vodacom — typically the merchant absorbs them, but check your contract. Either way, NinoPOS records the gross amount; fees are reconciled when M-Pesa settles to your bank.

Can I take M-Pesa payments without internet?

STK Push requires the merchant to be online to send the request. NinoPOS can queue M-Pesa-paid sales offline (manual entry), and process the STK Push retroactively when connectivity returns — but the customer’s PIN entry happens on their phone, which has its own connectivity.

What about Tigo Pesa, Airtel Money, and HaloPesa?

NinoPOS supports all major Tanzania mobile-money providers. Each has its own API and credentials; the cashier picks the method on the POS and the right flow runs. Daraja covers M-Pesa specifically; the other providers have equivalent APIs that NinoPOS plugs into.

Can different stores have different M-Pesa accounts?

Yes. NinoPOS supports per-store Daraja credentials, so each branch deposits into its own M-Pesa account. Useful for franchise structures or for owners who want clean per-store P&L.

Do M-Pesa receipts count as fiscal receipts for TRA?

M-Pesa receipts are payment receipts, not fiscal receipts. For VAT compliance, the fiscal receipt comes from your EFD/VFD setup. The two should reconcile — every M-Pesa-paid sale should have a matching fiscal record.