WHMCS Payment Gateway Integration
Accept direct, non-custodial cryptocurrency payments in WHMCS. Automatically process on-chain USDT deposits across TRC20 and ERC20 networks with instant invoice settlement, zero middleman custody, and seamless integration powered by the official PayCow PHP SDK.
paycow-whmcs-payment-gateway.zip
Architecture: Powered by PayCow PHP SDK
The WHMCS payment gateway is built on top of the official, reusable PayCow PHP SDK. Rather than bundling bespoke HTTP routines inside WHMCS, communication with the PayCow REST API and cryptographic webhook validation are handled through a clean, isolated SDK layer:
The SDK is fully embedded in the module distribution package under modules/gateways/paycow/sdk/ with a standalone PSR-4 autoloader. No external Composer commands are required for deployment.
1 Upload & Extract Module
Download the archive and extract it directly into your root WHMCS directory. The files will populate the standard WHMCS gateway paths:
Ensure standard web server permissions are applied: directories 755 and files 644.
2 Activate Gateway in WHMCS
- Log in to your WHMCS Admin Area.
- Navigate to:
- WHMCS 8.x+: Configuration → System Settings → Payment Gateways
- WHMCS 7.x: Setup → Payments → Payment Gateways
- Click the All Payment Gateways tab.
- Find PayCow Non-Custodial Crypto in the list and click Activate.
3 Configure Merchant Credentials
Fill in your merchant credentials obtained from the PayCow Merchant Dashboard:
| Field | Description | Value / Guidance |
|---|---|---|
| Show on Order Form | Enables the payment gateway for client order checkout | Checked |
| Display Name | Public title shown to clients on checkout and invoices | PayCow Non-Custodial Crypto |
| API Key | Your PayCow Merchant API Key | From PayCow Dashboard → Settings → API Settings |
| API Secret | Your PayCow Merchant API Secret | From PayCow Dashboard → Settings → API Settings |
| Webhook Secret | Cryptographic signing secret for HMAC-SHA256 signature verification | From PayCow Dashboard → Settings → Webhook Settings |
| Network Mode | Blockchain network for USDT deposits | TRC20, ERC20, or Let Customer Choose (TRC20 or ERC20) |
| Wallet Serial Number | Specific main wallet serial to receive deposits | Leave blank for automatic wallet rotation |
PayCow crypto payments settle directly on-chain in USDT. WHMCS invoices must be billed in USDT. If an invoice in another currency is presented, the gateway informs the client to switch their currency to USDT.
PayCow never holds merchant funds or manages private keys. Payments sent by customers are verified on-chain and settled directly into the merchant main wallet linked to your PayCow merchant account.
4 Configure Webhook in PayCow
To enable automatic invoice settlement upon on-chain payment confirmation:
- Copy the Webhook Notification URL displayed in the gateway settings in WHMCS:
https://example.com/modules/gateways/callback/paycow.php
- Log in to your PayCow Merchant Dashboard.
- Go to Settings → Webhook Settings.
- Paste the URL into the Webhook URL field.
- Copy the Webhook Secret from the dashboard and paste it into the Webhook Secret field in your WHMCS gateway settings.
- Click Send Test Webhook in the PayCow dashboard to verify end-to-end connectivity.
Webhook Event Lifecycle
The module receives cryptographically signed webhooks dispatched by PayCow's blockchain listener and updates WHMCS invoices accordingly:
| Event | On-Chain State | WHMCS Action |
|---|---|---|
payment.detected |
Unconfirmed transfer broadcast on-chain | Logged in WHMCS Gateway Log |
payment.confirming |
Block confirmations accruing on-chain | Logged in WHMCS Gateway Log with confirmation count |
payment.paid |
Required confirmations reached, funds delivered | Verifies exact amount, registers on-chain txHash, executes addInvoicePayment(), marks invoice Paid |
payment.expired |
Session timed out without valid on-chain payment | Logged in WHMCS Gateway Log |
payment.rejected |
Session rejected or invalid deposit | Logged in WHMCS Gateway Log |
webhook.test |
Dashboard connection ping | Logged in WHMCS Gateway Log; responds HTTP 200 |
Security & Audit Logging
- Timing-Safe HMAC Verification: Every webhook payload is validated using
hash_equals()against an HMAC-SHA256 signature generated over${timestamp}.${rawBody}. - Replay Attack Prevention: Signatures with timestamps drifting more than 300 seconds from the server clock are automatically rejected.
- Credential Redaction: All sensitive credentials (API keys, secrets) are strictly excluded from WHMCS transaction logs.
- Safe Money Handling: Micro-amount decimal checks ensure invoices are never marked paid unless the full required amount has been received on-chain.