WHMCS
Install and configure the Snippe payment gateway for WHMCS
The Snippe WHMCS module adds Pay with Snippe to invoice pages and settles payments automatically via webhook.
Requirements
| Requirement | Version |
|---|---|
| WHMCS | 8.0+ |
| PHP | 7.4+ with curl, json, hash |
| HTTPS | Required (publicly reachable for webhooks) |
| Currency | TZS only, minimum 500 TZS |
Install
Copy the module files
From the release zip, copy:
modules/gateways/snippe.php→<whmcs-root>/modules/gateways/snippe.phpmodules/gateways/snippe/whmcs.json→<whmcs-root>/modules/gateways/snippe/whmcs.jsonmodules/gateways/callback/snippe.php→<whmcs-root>/modules/gateways/callback/snippe.php
Activate the gateway
In WHMCS Admin: Setup → Payments → Payment Gateways → All Payment Gateways, find Snippe in the list, and click to activate.
Configure
Fill in the configuration fields (see below).
Register the webhook
In the Snippe Dashboard under Webhooks → Add endpoint, register:
https://<your-whmcs-domain>/modules/gateways/callback/snippe.phpEnable the payment.completed event.
Configuration
| Field | Required | Description |
|---|---|---|
| API Key | Yes | snp_... from Dashboard → Settings → API Keys |
| Webhook Signing Secret | Yes | From Dashboard → Settings → Webhook Secret |
| Payment Profile ID | No | prof_... to apply branding (see Payment Profiles) |
| Allowed Methods | No | Restrict to mobile money, card, or QR |
| Session Expiry | No | Seconds until the checkout link expires (default 3600) |
Invoice flow
Customer clicks "Pay with Snippe"
The gateway POSTs to /api/v1/sessions with the invoice amount, customer details, and a metadata reference back to the WHMCS invoice ID.
Customer is redirected to Snippe checkout
WHMCS issues an HTTP 302 to the hosted checkout_url. The customer pays via mobile money, card, or QR.
Snippe sends a webhook
payment.completed is delivered to callback/snippe.php. The callback verifies the HMAC-SHA256 signature, rejects timestamps older than 5 minutes, then calls WHMCS's addInvoicePayment() to mark the invoice paid.
Customer is returned to the invoice
Once payment completes, the customer lands on viewinvoice.php?id=<id>&paymentsuccess=true.
Supported payment methods
Mobile money (M-Pesa, Airtel Money, Mixx by Yas, Halotel), Visa/Mastercard, and dynamic QR — Snippe selects the right rail based on what the customer chooses on the hosted checkout. To restrict the options, set Allowed Methods in the gateway config.
Troubleshooting
- Invoice stays unpaid after a successful payment — confirm the webhook URL in the Snippe dashboard exactly matches your
callback/snippe.phpURL, and that your server returns 2xx within 30 seconds. Snippe retries 5 times with exponential backoff before abandoning. - "Invalid signature" in the gateway log — the Webhook Signing Secret in WHMCS must match the one shown in Dashboard → Settings → Webhook Secret.
- HTTP 400 on session creation — currency must be
TZSand amount must be ≥ 500.