How to Integrate Mpesa With a Billing System: 8 Tools

Stop Manual M-Pesa Reconciliation. Start Automating.

A common ISP growth problem in Kenya looks like this. Payments are coming into M-Pesa all day, but the actual service workflow still depends on people checking statements, matching transaction codes to subscribers, updating invoices, and logging into MikroTik to reconnect lines. That process may hold for a small customer base. It starts failing once payment volume rises and customers expect reconnection within minutes, not hours.

The first cracks usually show up in operations. Finance spends hours reconciling payments that should have posted automatically. Support handles avoidable calls from customers who already paid. Network staff end up doing billing work because internet access still depends on a manual handoff between M-Pesa, the billing app, and the router.

In Kenya, that gap matters because customers already expect M-Pesa to work as the primary payment rail. If your stack cannot accept payment, confirm it, reconcile it, and push the result into network access control in one flow, your team is left patching the process with spreadsheets, screenshots, and late-night router logins.

The practical way to approach M-Pesa billing integration is to design the whole path from payment request to service activation. That means choosing the right API or gateway, handling callbacks properly, validating payloads before they touch your billing records, queuing background jobs with Celery, and syncing account state with MikroTik without race conditions. Good teams also treat webhook hygiene as part of billing reliability. A simple JSON validation step, like the patterns covered on e2eAgent.io's site, can prevent bad callback data from creating hard-to-trace billing errors.

This guide takes that full-stack view. It covers direct API options, aggregator trade-offs, router integration, async job handling, webhook design, Django-based billing architecture, and the point where building in-house stops making financial sense. For a grounded example of what an ISP-focused M-Pesa billing stack looks like in practice, see this guide to ISP billing with M-Pesa mobile money integration.

1. Safaricom M-Pesa API Documentation and REST Integration

A customer pays at 10:03 p.m., expects service back in seconds, and calls support at 10:05 if nothing happens. That is the actual standard an ISP integration has to meet. Safaricom's Daraja API gives you the direct path to that outcome because your billing system can initiate payment, receive the callback, reconcile the transaction, and hand off activation to the network layer without a staff member checking a portal.

For Kenyan ISPs, direct M-Pesa REST integration usually makes sense once transaction volume is high enough that manual confirmation starts creating delays, disputes, and after-hours support work. STK Push is the part where initial development typically begins, but the callback flow is what makes the billing process reliable. If the callback handler is weak, the whole stack becomes fragile. A practical reference for an ISP-focused implementation path is this guide to ISP billing with M-Pesa mobile money integration.

What to set up first

Start with the basics that affect reconciliation and uptime, not just payment collection. You need your shortcode, consumer key, consumer secret, passkey, callback URL, timeout handling, and a transaction table that can store invoice ID, phone number, checkout request ID, M-Pesa receipt, amount, status, and the full raw payload.

The raw payload matters more than many teams expect.

When a customer says, "I paid but my account is still off," the fastest path to the answer is a stored callback body plus an internal audit trail showing when the request was sent, when Safaricom replied, and whether the billing job reached MikroTik.

Use this pattern:

• Create one internal reference per payment attempt: Do not reuse invoice references across retries.

• Store Safaricom identifiers separately: CheckoutRequestID, MerchantRequestID, and M-Pesa receipt should not be collapsed into one field.

• Acknowledge callbacks quickly: Return success fast, then send heavy processing to a worker queue.

• Keep idempotency checks on both sides: A retried callback should not credit the same invoice twice.

• Log failed application steps separately from failed payments: Payment success and service activation are related, but they are not the same event.

That separation prevents a common ISP failure mode. Money is received, but the customer stays disconnected because the router update fails or the background worker stalls.

Where direct Daraja integration works best

Daraja fits best when the ISP wants tight control over the billing flow and is willing to own the operational details. That includes credential management, callback security, retry handling, reconciliation scripts, and support tooling for finance and NOC teams. The reward is cleaner automation and fewer handoffs between systems.

PayBill is usually the better fit for subscriber billing because the account reference gives you a cleaner match back to the customer record. Till works for general collections, but for recurring internet subscriptions it often creates more cleanup work, especially when several customers pay similar amounts.

There is a trade-off. Direct integration gives better control, but it also gives you more responsibility. If your team cannot maintain callback reliability, monitor failures, and reconcile exceptions daily, an aggregator can be the safer first step.

For callback payload checks and schema validation, e2eAgent.io's site is a useful reference while building and testing your handler.

The main design decision is simple. Do not treat Daraja as just a checkout feature. Treat it as one layer in a full ISP billing pipeline that must stay consistent from payment request to invoice update to router action. That is where direct integration pays off.

2. Pesapal Payment Gateway SDK and Aggregators incl afriCash and Lipisha

A small ISP can get stuck for weeks waiting on direct provider setup while invoices keep piling up and customers still want instant reconnection after payment. Aggregators such as Pesapal, afriCash, and Lipisha shorten that path. They let the team start collecting through M-Pesa and other channels while keeping the billing system in charge of invoices, service status, and audit history.

For Kenyan ISPs, that matters most in the early build stage. The business usually needs collections working before the full stack is polished from payment callback to MikroTik enforcement to scheduled retries in Celery. An aggregator can buy time, but only if the architecture stays clean underneath.

Where aggregators fit best

Aggregators work well when the billing application already has a clear payment ledger and a reliable webhook handler. In that model, the gateway is an input source, not the control centre. The subscriber account, package state, and router actions should still live in your own system.

That approach is especially practical for operators who want more than one collection method without rebuilding the billing core each time. If one branch has customers paying mostly through M-Pesa and another relies on card or bank transfer, the same invoice and reconciliation logic can still sit behind all of it.

A good implementation usually includes:

• A normalised payment record: store provider, external transaction reference, invoice or account reference, amount received, currency, raw payload, and final status

• An internal idempotency check: reject duplicate callbacks before they create double credit or trigger repeated service activation

• A reconciliation process: map settlements to invoices, then flag exceptions such as underpayments, overpayments, chargebacks, and delayed confirmations

• A manual review path: support staff need a queue for payments that do not match cleanly to a subscriber account

Many deployments either stay manageable or become messy very fast at this stage.

Understanding the trade-off

Aggregators reduce setup effort, but they also insert another operational dependency between the customer and your billing logic. When a payment goes missing, the team may need to check the customer message, the aggregator dashboard, the webhook logs, and the billing database before finding the fault. That is acceptable for many small and mid-sized ISPs. It is still extra moving parts.

The practical question is not which gateway looks simpler in a demo. The practical question is where you want complexity to sit.

With Pesapal or similar providers, some complexity moves away from direct Safaricom integration and into reconciliation, support follow-up, and provider-side dependency management. For an ISP without an in-house backend engineer, that can be a sensible compromise. For a larger operator running strict automation from payment event to MikroTik reactivation, the extra layer can become frustrating because it limits visibility and control.

What usually fails is using the aggregator portal as if it were the billing platform. It is only a payment rail. The billing application must remain the source of truth, especially if the wider stack includes Django models for subscriber accounts, Celery workers for background jobs, webhook verification, and router actions that should happen only after the payment state is confirmed.

Used that way, aggregators are a practical first phase. They are not the whole blueprint.

3. Flutterwave Payment API and SDKs

A common ISP scenario is straightforward. Customers pay mostly through M-Pesa, a few ask for card or bank options, and the billing team wants one payment intake layer without rewriting the whole backend for each channel. Flutterwave can fit that setup if the business is serving more than one market, or if payment choice matters enough to justify another layer in the stack.

I've seen Flutterwave work best where the ISP already has discipline in the core billing flow. Invoice generation, account status, arrears handling, and reactivation logic still belong in the billing application. The gateway should collect money and report payment events. It should not decide whether a subscriber gets back online.

Good fit for multi-channel billing

Flutterwave is useful when the actual requirement is payment consolidation. The API gives one entry point for several rails, but the backend still needs a single ledger and a single set of subscriber rules. In practice, that means every confirmed payment should land in the same reconciliation process, whether it started as mobile money, card, or bank transfer.

That architecture matters more than the SDK.

A clean implementation usually looks like this. Flutterwave sends a webhook. Django records the event and marks it as pending verification. A Celery worker checks the transaction against the provider reference, matches it to the right invoice, and only then triggers the service action, including any MikroTik reactivation. That pattern keeps payment intake separate from service control, which is how billing stacks stay supportable once volumes rise.

Teams building toward that model usually benefit from studying how an ISP billing software stack for Africa ties payments, subscriber records, and network actions together.

Where teams get into trouble

The failures are usually operational, not technical. An ISP adds Flutterwave before it has stable invoice references, duplicate-payment handling, or webhook retry logic. Then support starts seeing cases where a customer paid once, the webhook fired twice, and the wrong account was reactivated.

Another common mistake is treating Flutterwave as the center of the system because the dashboard looks convenient. That creates problems during disputes and reconciliation. The billing database must remain the source of truth for subscriber identity, invoice status, and payment allocation.

For Kenyan ISPs, mobile money still drives routine collections, so Flutterwave should usually sit around M-Pesa, not replace it in the design. If most subscribers already pay through M-Pesa, keep that path first-class in your data model, references, and support workflows. Add Flutterwave because it reduces integration sprawl across channels, not because it removes the need for careful billing logic.

4. Stripe Integration with Mobile Money Extensions

Stripe is rarely the first recommendation for a local Kenyan ISP focused only on domestic collections. It becomes more relevant when the business has international customers, group-level finance requirements, or a product stack that already runs heavily on Stripe subscriptions.

For that kind of operator, Stripe can sit above your local billing logic and handle broader payment orchestration. The caution is simple. Don't force Stripe into places where a direct M-Pesa integration already solves the problem better.

When Stripe is worth the effort

Stripe is strongest when recurring billing, retries, subscription state, and customer records need to line up across multiple markets. If your Nairobi operation is one part of a wider platform, centralising some payment logic can make sense.

That's also where a billing platform built for African ISP operations becomes useful. The background on ISP billing software for Africa reflects that broader requirement well. You need local payment support, but you also need service logic tied to network access.

• Keep local reconciliation local: Don't hide M-Pesa-specific references inside a generic abstraction layer.

• Preserve invoice ownership: Your billing system should still decide whether a subscriber is active, suspended, or due.

• Map retries carefully: A failed recurring charge should trigger dunning, not random service toggles.

What Stripe won't fix

Stripe won't solve MikroTik automation by itself. It won't understand your PPPoE profile changes, hotspot vouchers, or router-side suspensions. If teams forget that, they end up with a polished payment flow and a manual network workflow.

That gap matters. One verified source notes a major content gap around M-Pesa integration for MikroTik-based networks, especially linking payment confirmations to subscriber access control for PPPoE and hotspot environments, according to BizKit's M-Pesa integration page. In practice, that's why a payment processor alone is never enough for an ISP.

5. MikroTik API and RouterOS Integration Guide

A subscriber pays at 9:12 PM and expects the internet back by 9:13 PM. If your billing system records the payment but the router still holds the account in a suspended state, support gets the call, not finance.

That is why MikroTik integration sits at the centre of an ISP billing stack in Kenya. M-Pesa confirms payment. The billing system decides whether the account is now current. RouterOS then enforces that decision on PPPoE, hotspot, or queue policies. If any one of those steps is manual, the whole flow slows down.

The handoff point matters. Trigger router changes only after the billing application has matched the payment to the right customer account, updated the invoice, and committed the new service state. Triggering on a raw payment event is how operators reconnect the wrong user, extend the wrong package, or create disputes around partial payments and PayBill reference errors.

A working production flow usually looks like this:

• Invoice or renewal request generated: The subscriber gets a prompt to pay.

• Payment callback received and verified: The billing system matches the M-Pesa transaction to the customer account.

• Account status recalculated: Arrears, expiry date, package validity, and grace rules are updated.

• RouterOS command sent: PPPoE secrets, hotspot users, address lists, or simple queues are changed based on the new billing state.

The practical design rule is simple. Keep billing logic in the billing system. Keep enforcement logic on MikroTik.

That split prevents a lot of pain. RouterOS is good at access control and session handling. It is not the right place to store invoice truth, credit rules, or payment reconciliation history. Teams that push subscriber state into scripts on the router usually end up with conflicting records between finance and network operations.

For Kenyan ISPs, the common integration methods are API calls over the MikroTik API service, SSH-driven scripting, or scheduled imports. API-driven updates are usually the better choice for live billing because they let the application reconnect, suspend, or reprofile a customer immediately after account state changes. SSH scripts can work for small deployments, but error handling is weaker and audit trails are harder to keep clean. Scheduled imports are acceptable for nightly sync jobs, not for instant reactivation after an M-Pesa payment.

Centipid's public guide to MikroTik billing integration for ISP automation covers this operational gap well. The recurring issue is not collecting the money. It is getting the router and the ledger to agree, every time, under retries, duplicate callbacks, and delayed confirmations.

Common mistakes

Manual reconnection after finance shares a paid list still shows up in smaller WISPs. It works for a while, then fails during peak hours, month-end renewals, or staff handovers.

Another mistake is tying service restoration directly to a successful STK push response. An STK prompt only means the request reached the customer handset. It does not mean the funds settled or the account was matched correctly. Restore service only after confirmed payment application inside your billing records.

Also avoid putting package expiry calculations on the router. Expiry, grace periods, pro-rating, debt carry-forward, and invoice allocation belong in the billing application. RouterOS should receive a clear instruction such as activate, suspend, reconnect, change profile, or disconnect active session.

The teams that get this right treat MikroTik as one layer in a wider automation chain. Payment API, billing logic, router control, job queue, and callback handling all need to line up. If one part is weak, staff end up doing manual corrections, and subscribers feel that delay immediately.

6. Celery and Celery Beat for asynchronous billing operations

At 8 p.m. on a month-end evening, an ISP can receive a burst of M-Pesa callbacks, overdue reminders need to go out, and several paid customers expect service back within minutes. If the billing app tries to handle all of that inside one web request, the weak point shows up fast. Requests time out, callbacks get retried, and router actions start competing with invoice logic.

Celery fixes that by moving background work into a queue. Celery Beat handles the scheduled side. For a Kenyan ISP running Django or another Python stack, that split is usually the difference between a demo that works in testing and a billing system that survives renewal day.

The practical rule is simple. The web layer should receive the event, validate it, save enough state, and return quickly. The workers should do the heavier jobs after that.

Use Celery for work that can be slow, retried, or temporarily blocked by another dependency:

• callback parsing and payment matching

• duplicate transaction checks

• invoice allocation and receipt creation

• SMS or email notifications

• service activation, suspension, and reconnection jobs against MikroTik

• retries when Safaricom, the database, or the router API is slow

Use Celery Beat for time-based operations that must run on a schedule:

• monthly invoice generation

• grace-period expiry checks

• overdue reminder batches

• nightly reconciliation reports

• queue cleanup and failed-task review jobs

A few design choices matter more than the tool itself.

Make tasks idempotent. If Safaricom retries a callback or a worker crashes halfway through, rerunning the task should not post a second payment, generate another receipt, or reconnect an already active customer.

Pass a single reference across the whole chain. Transaction ID, invoice reference, account number, router username, and task ID should be easy to trace together in logs. During support calls, that traceability saves more time than any dashboard.

Keep payment acceptance separate from network changes. A payment can be valid while the router is unreachable. In that case, mark the payment as applied, queue the reconnection, and alert operations if the retry window is exceeded. Do not force the customer to pay again because the network action failed.

This also helps with reconciliation. As noted earlier, many providers only get rid of painful month-start cleanups after they stop relying on staff to process payments and restorations by hand. Queue workers make that possible because each step is recorded, retried, and auditable.

Celery Beat needs restraint. It is useful for predictable jobs, but it should not become a dumping ground for business logic that really belongs in event-driven processing. For example, "reconnect every paid user every five minutes" is a crude safety net, not a clean design. A better pattern is event first, scheduled repair second. Apply the payment on callback, queue the router action immediately, then let a scheduled task only catch the exceptions that were missed.

Operations teams should also plan for failure states, not just happy paths. Use separate queues for payment processing, notifications, and router commands so a stuck SMS provider does not delay service restoration. Set retry limits and dead-letter handling for jobs that keep failing. If your team manages webhook endpoints in WordPress for surrounding business systems, the guidance on how to secure WordPress webhooks with FirePhage is useful for tightening callback handling around those edge integrations.

For ISPs building the full stack themselves, Celery is the control layer between M-Pesa, Django, and MikroTik. It is what lets the payment API, billing records, and network state move in the right order instead of racing each other. That blueprint is more reliable than cron-heavy billing scripts, and it is much easier to support once the subscriber base grows.

7. Webhook integration patterns and security best practices guide

Most M-Pesa billing failures aren't caused by the payment request itself. They happen after payment, when the system mishandles callbacks, trusts bad payloads, or processes the same event twice.

Webhook discipline is what separates a demo from a working billing system.

The minimum standard

Your webhook endpoint should authenticate what it receives, persist the payload, acknowledge quickly, and push processing to a queue. That's the baseline.

Then add protection against replay and duplication. Use unique constraints around provider transaction IDs and internal payment references. If the same event arrives twice, the second one should be harmless.

Field note: If you can't replay a webhook safely in staging, your production design still needs work.

A verified source says integrated M-PESA setups for ISPs can slash manual processing time by 90% through zero-touch reconciliation and instant payment confirmations via callbacks, according to Alternet ISP Billing's article on M-PESA Pay Bill integration. That result depends heavily on callback reliability.

Security and operational checks

Use HTTPS endpoints. Restrict what your webhook route exposes. Don't let the callback directly manipulate network state without billing validation.

A few practical controls matter more than fancy diagrams:

• Verify before acting: Don't trust a payload because it reached your server.

• Acknowledge fast: Long-running webhook handlers create timeouts and duplicate retries.

• Preserve an audit trail: Keep request bodies, processing timestamps, and final status.

• Alert on silence: Missing callbacks can be as damaging as failed ones.

If you run webhook-driven integrations on web platforms too, the security concepts in FirePhage's guide to protecting WordPress webhooks are a useful parallel. The stack is different, but the core pattern is the same. Verify, isolate, log, and retry safely.

8. Django Python billing application frameworks and sample implementations

A Kenyan ISP usually hits the same point in growth. Payments are coming in, routers are enforcing sessions, support needs a clear customer record, and spreadsheet-based reconciliation starts breaking under daily load. Django fits this stage well because it gives you a strong admin panel, mature ORM, permissions, and an API layer you can wire into M-Pesa callbacks, MikroTik actions, and background workers without fighting the framework.

The hard part is the domain model.

An ISP billing system has to track subscriber identity, service plans, prorated charges, suspensions, retries, wallet or overpayment balances, router commands, and payment reconciliation as separate concerns. If all payment state lives on the invoice table, reconciliation gets messy fast. Keep invoices, payment transactions, ledger entries, and service status changes in separate models with clear relationships and timestamps. That structure makes disputes, reversals, and delayed callbacks much easier to investigate.

Tax handling also needs its own design. If your operation must support KRA processes such as eTIMS-linked invoicing, treat tax artifacts and invoice numbering as first-class records, not fields added late in the project. Retrofitting compliance into a live billing system is expensive and usually forces awkward migrations.

A practical Django stack for ISPs often looks like this: Django and Django REST Framework for the app layer, PostgreSQL for transactional integrity, Celery for retries and scheduled jobs, Redis as the broker, and a small webhook ingestion service or dedicated endpoint set for payment providers. Router actions should pass through a queue instead of running inline with payment processing. That avoids cases where a successful M-Pesa confirmation is tied to a slow or failed network command.

Sample implementations also fail when they stop at invoices and receipts. Real deployments need package changes, grace periods, partial payments, credit control, and a support-friendly audit trail. The broader architecture behind an ISP subscriber management system matters as much as the payment code because billing, service activation, and customer operations share the same workflow.

Build custom Django billing only if your team can support it for years. You will own schema changes, callback edge cases, tax updates, queue failures, and every odd payment mismatch that lands in support. For some ISPs, that control is worth it. For many, Django works best as the foundation for a customized operations layer, not as a blank canvas for rebuilding an entire billing product from scratch.

MPesa Billing Integration: 8-Resource Comparison

Making the Right Choice From DIY to a ready-made solution

A Kenyan ISP often reaches the same turning point the month manual follow-up stops working. Payments are coming in through M-Pesa, some subscribers need immediate reactivation, others have paid the wrong reference, and support is stuck cross-checking SMS messages, router sessions, and invoice records. At that point, the question is no longer whether to integrate. The primary decision is how much of the stack to build and maintain yourself.

The answer depends less on features and more on operating discipline. A working billing stack has to coordinate M-Pesa payment requests, verified callbacks, invoice matching, customer notifications, and MikroTik actions without creating duplicate credits or leaving paid users offline. If any one of those steps is weak, the result shows up quickly in support queues, failed activations, and end-of-month reconciliation work.

Build in-house if the business already has the right team. That usually means Python or Django capability, solid DevOps habits, and enough transaction volume to justify owning callback handling, retry logic, task queues, audit trails, and RouterOS automation. The trade-off is ongoing maintenance. Safaricom requirements change, webhook failures need investigation, tax and billing rules shift, and router workflows rarely stay static for long.

That implementation gap is well covered in IntaSend's M-Pesa API integration guide, especially around the move from sandbox testing to production behavior, callback handling, and operational reliability. Kenyan ISP teams usually underestimate that part. Getting an STK push to work is the easy milestone. Keeping billing state, payment state, and subscriber access in sync every day is the harder job.

For many MikroTik-based ISPs, a ready-made platform is the safer commercial choice because it removes a lot of glue code. Instead of wiring separate tools for payments, billing, async jobs, and access control, operations staff work from one system with one source of truth. That reduces training overhead and lowers the chance that finance, support, and network teams are looking at conflicting records.

Centipid fits that model in practical terms. From the documentation available at Centipid's documentation portal, the product is built around recurring ISP billing, M-Pesa workflows, and MikroTik RouterOS v7 automation for PPPoE and hotspot environments. That matters because the full chain is already considered as one process: invoice generated, payment received, callback processed, account updated, and service state changed on the network.

Use a simple test when choosing between DIY and ready-made. Ask what your team can run reliably every month with the people you already have. In ISP billing, dependable operations beat architectural purity. The better option is the one that keeps customers connected, finance records clean, and engineers out of preventable billing incidents.

For a broader software perspective, Cloudvara's application integration overview gives useful background on how systems exchange data across boundaries.

If you want a platform built for this exact workflow, Centipid Technologies Ltd. is worth reviewing. It combines M-Pesa billing flows, recurring invoicing, and MikroTik-based access automation in one ISP-focused system, which can reduce the engineering and support burden of building the full stack yourself.