WHMCS
Add a TeePay mobile money Pay now button to WHMCS invoices.
The TeePay payment gateway module adds a Pay now button to WHMCS invoices. The client pays with M-Pesa, Airtel Money, Mixx by Yas or HaloPesa on TeePay's hosted checkout, and WHMCS records the payment once TeePay has confirmed it.
- Requires
- WHMCS 8.x, PHP 7.4+ with curl, json and openssl, an HTTPS System URL
- Payment flow
- Hosted checkout
- Currencies
- Invoices in a currency your key supports (currently TZS)
Install
Copy the module
Download the module from TeePay's releases and copy its modules folder into your WHMCS root, merging
with the existing folder:
modules/gateways/teepay.php
modules/gateways/teepay/lib/…
modules/gateways/callback/teepay.phpActivate the gateway
In WHMCS open Configuration → System Settings → Payment Gateways → All Payment Gateways and click TeePay (Mobile Money).
Set up your payment profile
In the TeePay dashboard open Payment profiles and set, on your default profile or one for WHMCS:
| Address | |
|---|---|
| Webhook URL | https://your-whmcs.example/modules/gateways/callback/teepay.php |
| Return URL | https://your-whmcs.example/modules/gateways/callback/teepay.php?action=return |
Use your WHMCS System URL; both addresses are shown on the gateway settings page. Then create the signing secret in Developers → Webhooks.
Enter your keys
Paste the live API key and live webhook signing secret into the gateway settings and save.
Settings
Prop
Type
How invoices are paid
- The client clicks Pay now. Nothing is sent to TeePay until then.
- The module creates a checkout session for the invoice balance, in the client's currency, and redirects the client to TeePay. Clicking again within 12 hours for the same amount reopens the same session.
- TeePay sends a signed
payment.completedwebhook, and the client returns to WHMCS. - The module reads the session with your secret key. It records the payment only when the session is
paidwith a payment reference, belongs to this invoice and this WHMCS installation, is in the active environment, and itsamount_minorandcurrencyequal the invoice balance and currency. - It then calls
addInvoicePaymentwith that exact amount and the TeePay payment reference as the transaction ID. A reference that is already recorded is never added twice.
The return URL and anything in its query string never mark an invoice paid. If the amount or currency does not match, for example because the invoice was edited after the client started paying, nothing is recorded and the gateway log shows Amount Mismatch for you to reconcile.
Test and go live
Test keys (tp_test_) confirm your keys and setup, but checkout sessions run in the live environment
only. To test end to end:
- Turn Test mode off with your live key and secret saved.
- Create a small invoice in TZS for your own client account and pay it from your phone.
- Check that the invoice is Paid with the TeePay reference as the transaction ID, that
Billing → Gateway Log shows a
Successentry forteepay, and that Developers → Webhooks in TeePay shows the delivery with status200.
Refunds
The TeePay API does not offer refunds yet, so the module does not support WHMCS refunds. Arrange the refund with TeePay, then record it in WHMCS manually.
Troubleshooting
Every event is written to Billing → Gateway Log (filter by teepay) with keys, secrets and phone
numbers removed.
| Log status | What to do |
|---|---|
Account Restricted | TeePay has restricted your account, so new payments cannot be started. Clients see that mobile money payments are unavailable right now. Check the TeePay dashboard or contact support with the request ID from the log. |
Configuration Error | Save a valid API key and webhook secret for the active mode. |
Invalid Signature | The webhook secret does not match the environment, the secret was rotated, or the server clock is more than five minutes off. |
Error | An API error. The entry shows the error_code and request_id; see Errors. |
Amount Mismatch | The paid amount or currency differs from the invoice balance. Nothing was recorded; reconcile manually. |
Rejected | The session belongs to another invoice, environment or installation, or the invoice was already paid. |
Pending | TeePay has not confirmed the payment yet. The next webhook or return records it. |
If webhooks do not arrive, check the payment profile's webhook URL, that WHMCS is reachable over HTTPS
from the internet, and that no firewall or bot protection blocks POST requests to
modules/gateways/callback/teepay.php.