Before you start

You need four things in place. Two are on your server, two come from Safaricom.

Installation

1. Upload the files The download contains a modules folder. Upload its contents into your WHMCS installation so that you end up with modules/addons/mpesapro/ and modules/gateways/mpesapro.php alongside your existing modules. Uploading over an earlier version is safe — nothing is deleted.
2. Restart PHP If your server uses OPcache, which most do, restart PHP-FPM or LiteSpeed after uploading. Skipping this is the most common reason an upgrade appears not to have taken effect.
3. Activate the addon In WHMCS go to System Settings → Addon Modules, find M-Pesa Payments Pro and activate it. Tick the admin roles that should have access. The module creates its own database tables at this point.
4. Open the module once Addons → M-Pesa Payments Pro. This confirms the tables exist and shows the dashboard. It will be empty until you add credentials.

First-time setup

1. Credentials

Open Settings → Credentials and fill in:

Press Test connection. It fetches an access token and moves no money. If it fails, the message tells you which credential Safaricom rejected. Do not continue until this passes.

2. Register your callback address

Go to Settings → Paybill. You will see two addresses, both ending in mpp.php/confirmation and mpp.php/validation. Press Register these addresses.

Safaricom stores one pair of addresses per shortcode. Registering replaces whatever was there, and the developer portal usually wants the old pair deleted first. If you have used another M-Pesa module before, its addresses are almost certainly the ones on file — check Self Service → URL Management on the portal before assuming payments will reach you.

3. Turn on the gateway

Go to System Settings → Payment Gateways, activate M-Pesa, and set:

4. Prove it end to end

1. Open one of your own unpaid invoices and pay a small amount with a real phone.
2. Watch the invoice page — it should turn paid on its own without you reloading.
3. Open API log in the module. You should see an outgoing payment request and an incoming result within seconds of each other.
4. If your shortcode is a paybill, also send a small payment directly to it, quoting an invoice number as the account number, and check that it appears in Transactions as applied.

How money reaches you

Payment requests from the invoice page

The client presses your Pay Now button, a window opens, they enter their number and approve the payment on their phone. The page watches for the result and refreshes itself when the invoice is settled. If they close the window, the module keeps watching and reopens it when the result arrives.

The amount requested is always what is still owing, not the invoice total, so a partly paid invoice asks only for the remainder. Safaricom accepts whole shillings only, so an amount with cents is rounded up — see Amounts for how that is absorbed.

Payments made straight to the paybill

Someone can pay your paybill from their phone with no browser involved. Safaricom sends the payment to your registered address, the module records it and works out which invoice it belongs to. If the payer had your invoice open at the time, that page updates itself too.

Settings reference

Settings are grouped into sections down the left of the Settings tab. Each section saves on its own, so you can change one area without touching another.

Taking payments

Paybill

Amounts and fees

Matching

Records and privacy

How matching works

When a payment arrives without being tied to an invoice, the module scores every plausible invoice and records the reasons. Each candidate starts from whichever rule found it, then gains or loses points.

Scores are capped at 0–99. A payment is applied automatically only when all three of these hold: the best score clears your threshold, the invoice still has a balance, and the best candidate beats the runner-up by your margin.

What that means in practice

If you match on the account number only, which is the common setup, the everyday outcomes are:

Lowering the threshold to 70 lets typo repairs and part payments through while still stopping overpayments and payments against settled invoices — which are exactly the cases that need a human decision.

Typo repair

The module strips spaces, dashes, hashes and dots, removes your configured prefix, and maps the characters people actually mistype on a keypad: O, Q and D become zero; I, L and the pipe become one; S becomes five; Z becomes two; B becomes eight; G becomes six. If the result is not entirely digits, it is not treated as an invoice number — so "HOSTNALI" and "rent for july" correctly match nothing rather than being forced into a number.

Payments that arrive before their invoice

Unmatched payments are retried automatically for seven days, so someone who pays before the invoice is generated is picked up once it exists.

Working the matching queue

The Matching tab lists everything waiting, with a badge showing the count. Each card gives the payer, the account number they gave, the amount, the reason it is waiting, and the candidates with their scores and reasons. The invoice the payer actually named is always shown first and tagged, even when it scores badly.

Rows marked Paid, not yet applied are payments Safaricom confirmed but never named with a receipt. They usually resolve themselves; if not, Reconciliation can recover the receipt from your statement.

Amounts, fees and currency

Rounding

Safaricom accepts whole shillings only. An invoice of KES 3,499.50 therefore always collects 3,500 and overpays by fifty cents — every single time. The Ignore small overpayments tolerance absorbs that silently. Set it to 0 only if you want every cent tracked as credit.

Fees

M-Pesa charges you, the merchant, separately. Recording a percentage or flat cost here does not charge the customer anything — it stores the cost alongside the payment so your net revenue in WHMCS is accurate.

Other currencies

By default, invoices billed in anything other than Kenya Shillings are refused. Switching to convert uses your WHMCS exchange rates, always routing through your default currency. If a rate is missing, the payment is refused rather than converted with a guessed figure.

Reconciliation

Safaricom provides no way to fetch a statement automatically, so this works from the CSV you export from the M-Pesa portal.

1. Export a statement from the M-Pesa portal covering the period you want to check.
2. Upload it on the Reconciliation tab. Column names are matched loosely, and only money-in rows are read.
3. Read the four figures that come back.

Clearing an imported statement removes only the imported lines. No payment is affected.

Refunds

Refunds send money out of your paybill, so they need the API operator credentials from Settings → Refunds: an initiator name and a security credential.

The guards

A refund cannot exceed the original payment less anything already refunded. Safaricom confirms the outcome separately, usually within a minute, and the log shows the result either way.

Payment codes and tills

A Buy Goods till collects no account number, and many tills never deliver a confirmation to the seller at all. The answer is the one every Kenyan shop already uses: the customer reads out the code from their M-Pesa message.

Switch on Settings → Payment codes and an "Already paid? Enter the M-Pesa code" box appears in the payment window. A code is treated as a claim, not proof, and is checked in this order:

1. Have we already recorded that receipt? Then it is spoken for.
2. Did a confirmation for it arrive? Match it and apply.
3. Is it on a statement you have imported? Same.
4. Otherwise ask Safaricom directly, if the refund credentials are set.

What stops abuse

• A code already used against another invoice is refused outright.
• Safaricom's answer is checked to confirm the money came to your shortcode.
• A code paid from a number not on the client's account waits for a person, rather than applying itself. You can relax this if your clients routinely pay from a friend's phone or an agent.
• Six attempts per client per fifteen minutes.
• Codes must look like codes, so prose never reaches your queue.

Anything unresolved appears at the top of the Matching tab, where you can ask Safaricom again or set it aside.

Paybill balance

Your shortcode balance appears on the dashboard, on each transaction and in the payment email. It reaches the module two ways.

• With each paybill payment. Safaricom includes the balance on paybill confirmations at no extra cost. If most of your payments come through the invoice page rather than directly to the paybill, this figure will rarely move.
• By asking. With the refund credentials set, the module asks Safaricom about once an hour, and there is a button to ask immediately.

The figure always states where it came from and when, so a stale number cannot be mistaken for a live one.

Notifications

Three events, each switched on or off separately: a payment received and recorded, a payment that needs matching, and a payment request that did not complete. The third is off by default because it fires on every cancelled prompt.

Notifications go out through your WHMCS SMTP settings, so they come from the same address as your invoices. The settings screen shows which sending method it detected before you send anything, and the Send test email button reports which path was used and why if it failed.

Client area

Clients get a page listing every M-Pesa payment on their account, with totals and receipt codes, at index.php?m=mpesapro.

Roles and permissions

Off by default: every admin who can open the module can use all of it. Switching on Settings → Access lets you assign fourteen capabilities per WHMCS admin role — seven for seeing each tab, seven for actions such as matching, reconciling, requesting a refund, approving one, changing settings and removing data.

Full Administrators always keep complete access and are not listed, so nobody can lock themselves out. Admins whose role has no access see a plain message rather than an error, and are sent to the first tab they are allowed to see.

Licensing

One licence covers one WHMCS domain. Enter your key either on the addon's configuration screen or under Settings → Licence — both write to the same place. The status panel shows the licensed domain and when it was last checked, with a button to check immediately.

Accounting

M-Pesa payments are recorded through WHMCS's own payment routine, so any accounting module that reads WHMCS payments picks them up with no extra work — and the module deliberately does not post its own journal, which would double your revenue.

If you use Ledgerly, map the mpesapro gateway to your M-Pesa settlement account under Ledgerly → Tools → Payment Method Mapping, so receipts land in the right account rather than your default bank account.

Upgrading and removing

Upgrading

Upload the new files over the old ones and restart PHP. The database updates itself the next time you open the module. Settings, transactions and history are preserved. No release has ever required a manual database step.

Deactivating

Deactivating the addon stops the module but keeps every record. Reactivating picks up exactly where you left off.

Removing everything

Under Settings → Access, the danger zone removes every table the module created: transactions, statements, refunds, notifications, the API log and your settings. Payments already recorded against invoices in WHMCS are untouched, but the record of how they arrived is gone. It requires typing REMOVE and is available only to Full Administrators.

Troubleshooting

DELETE FROM mod_mpp_settings
WHERE skey IN ('license_status','license_message','license_lastcheck','license_lastgood');

Technical reference

Callback addresses

All routes live under one endpoint, using a path rather than a query string because Daraja is particular about both:

https://your-whmcs.example/modules/gateways/callback/mpp.php/confirmation
https://your-whmcs.example/modules/gateways/callback/mpp.php/validation
https://your-whmcs.example/modules/gateways/callback/mpp.php/stk

Refund, balance and code-verification results use further routes on the same file, sent automatically with each request; nothing else needs registering.

Database tables

What the cron does

• Closes payment requests whose result never arrived, by asking Safaricom.
• Retries unmatched payments for seven days.
• Recognises payments WHMCS already has recorded and closes them.
• Sends anything left in the notification queue.
• Refreshes the paybill balance, at most hourly.
• Prunes API logs past your retention setting, and rechecks the licence nightly.

Exports

The Transactions tab exports the current filtered view as CSV, including the split amounts, recorded costs, matching confidence and the paybill balance at the time.

M-Pesa Payments Pro by Hostnali — $4.20 or KSh 500 per month. Still stuck after reading this? Email [email protected] with your WHMCS version and the relevant lines from the module's API log.

M-Pesa and Safaricom are trademarks of Safaricom PLC. This module is not affiliated with or endorsed by Safaricom.