Guide · Updated February 2026

How to Accept Bitcoin on WHMCS (Complete Setup Guide)

If you run a hosting company on WHMCS, you already know that payment processing is one of the most annoying parts of the business. PayPal holds funds for "review." Stripe flags accounts for selling VPS to customers in certain countries. Credit card chargebacks hit you months after a server was provisioned and used.

Bitcoin fixes most of these problems. And WHMCS has solid support for it through the BTCPay Server payment gateway module.

This guide covers everything: why WHMCS bitcoin payments make sense for hosting companies, how to set up BTCPay Server with the official WHMCS plugin, and how to handle recurring invoices.

Why Hosting Companies Should Accept Bitcoin

This isn't a generic "crypto is the future" pitch. There are specific, practical reasons why WHMCS bitcoin payments make sense for hosting providers.

Your Customers Already Want It

A significant chunk of VPS and dedicated server buyers actively prefer paying with Bitcoin. Privacy-conscious developers, open-source projects, international freelancers, businesses in countries with limited banking access -- these people are already looking for hosting providers that accept BTC. If you don't offer it, they go to a competitor who does.

No Chargebacks

This is the big one for hosting. A customer signs up, uses a dedicated server for two months, then files a chargeback on their credit card. You lose the revenue and the cost of the server resources they consumed. Bitcoin transactions are irreversible. Once a payment confirms on-chain, it's done. No disputes, no arbitration, no lost revenue months later.

International Payments Without the Headaches

Hosting is a global business. You have customers in 50+ countries, and every payment processor has its own list of "restricted regions." Bitcoin doesn't care about borders. A customer in Lagos pays the same way as a customer in London. No currency conversion fees, no blocked transactions, no "your country isn't supported" errors at checkout.

Lower Processing Costs

Stripe charges 2.9% + 30 cents per transaction. PayPal takes 3.49% + 49 cents. On a $200/month dedicated server, that's $6-7 per month going to the payment processor. BTCPay Server is free and open-source software. On-chain fees are paid by the customer (typically under $1), and Lightning payments cost fractions of a cent.

How WHMCS Bitcoin Payments Work

WHMCS has a modular payment gateway system. You can add new gateways by dropping a module into the /modules/gateways/ directory. BTCPay Server has an official WHMCS gateway module that plugs directly into this system.

Here's the flow:

1. WHMCS generates an invoice (manually or from a recurring service)
2. The customer clicks "Pay" and selects Bitcoin
3. The BTCPay module creates a corresponding invoice on your BTCPay Server instance
4. The customer sees a payment page with a Bitcoin address and QR code (on-chain and Lightning options)
5. Once payment is detected, BTCPay sends a webhook back to WHMCS
6. WHMCS marks the invoice as paid and activates/renews the service automatically

The key thing: invoice matching is automatic. BTCPay generates a unique Bitcoin address for every invoice. When payment arrives at that address, it knows exactly which WHMCS invoice to mark as paid. No manual reconciliation.

What You Need Before Starting

Before you set up WHMCS bitcoin payments, make sure you have:

• A working WHMCS installation (version 8.x recommended)
• Admin access to your WHMCS instance
• A BTCPay Server instance (self-hosted or managed)
• A Bitcoin wallet -- hardware wallet recommended (Trezor, Ledger, ColdCard)
• SSH/file access to your WHMCS server (for installing the gateway module)

If you don't have a BTCPay Server instance yet, you can either self-host it on a VPS (you're a hosting company, you have the infrastructure) or use a managed service like Wootoshi that handles the setup and maintenance.

Step-by-Step: Setting Up BTCPay Server for WHMCS

Step 1: Configure Your BTCPay Server Store

Log into your BTCPay Server dashboard. Create a new store (or use an existing one). Go to Settings → Wallet and connect your Bitcoin wallet by entering your extended public key (xpub). This lets BTCPay generate unique receiving addresses for each invoice without ever touching your private keys.

If you want to accept Lightning payments too (recommended -- instant confirmation is great for hosting signups), set up a Lightning node connection under Settings → Lightning.

Step 2: Download and Install the WHMCS Module

Get the official BTCPay Server WHMCS module from the BTCPay Server GitHub repository. Upload the module files to your WHMCS installation:

• Copy the gateway files to /modules/gateways/
• Copy the callback file to /modules/gateways/callback/

Make sure file permissions are set correctly. The gateway files should be readable by your web server (typically 644 for files).

Step 3: Activate the Gateway in WHMCS

In your WHMCS admin panel, go to Setup → Payments → Payment Gateways. You should now see "BTCPay" in the list of available gateways. Click to activate it.

You'll need to fill in:

• BTCPay Server URL -- the full URL of your BTCPay instance (e.g., https://btcpay.yourdomain.com)
• API Key -- generate this in BTCPay under Account → Manage Account → API Keys. Grant permissions for store management and invoice creation.
• Store ID -- found in your BTCPay store settings
• Webhook Secret -- you'll set this up in the next step

Step 4: Set Up the Webhook

This is the part people skip and then wonder why invoices aren't being marked as paid. The webhook is how BTCPay tells WHMCS that a payment was received.

In your BTCPay Server dashboard, go to Settings → Webhooks and create a new webhook:

• Payload URL: https://yourdomain.com/modules/gateways/callback/btcpay.php
• Events: Select invoice-related events (invoice payment settled, invoice expired, etc.)
• Secret: Generate a random secret string and enter the same value in your WHMCS gateway configuration

The webhook secret ensures that only legitimate notifications from your BTCPay Server are processed. Without it, anyone could send fake payment confirmations to your callback URL.

Step 5: Test the Integration

Create a test invoice in WHMCS for a small amount. Log in as a client (or use a test client account) and attempt to pay the invoice using Bitcoin. You should see:

1. A redirect to your BTCPay Server payment page
2. A Bitcoin address and QR code (and Lightning invoice if configured)
3. After sending payment, the BTCPay page updates to show "Paid"
4. Back in WHMCS, the invoice status changes to "Paid" automatically

If the invoice stays unpaid in WHMCS after BTCPay confirms the payment, the webhook isn't working. Check your WHMCS gateway log under Utilities → Logs → Gateway Log for errors.

Handling Recurring Invoices with Bitcoin

This is the question every hosting provider asks: "How do recurring payments work with Bitcoin? There's no auto-charge."

You're right -- Bitcoin doesn't support automatic recurring charges like a credit card. Here's how it works in practice:

1. WHMCS generates the recurring invoice on the normal schedule (e.g., 14 days before due date)
2. The customer receives an invoice email with a "Pay Now" link
3. They click the link, select Bitcoin, and pay through BTCPay
4. The webhook confirms payment and WHMCS renews the service

It's a manual payment each cycle, yes. But most hosting customers paying with Bitcoin expect this. They chose Bitcoin specifically because they don't want a payment method that can be charged automatically.

To make this smooth, configure your WHMCS invoice reminders well. Send the first reminder 14 days before due, a second at 7 days, and a final reminder on the due date. Give customers enough time to pay without feeling pressured.

Also set your overdue suspension days to something reasonable -- 3 to 5 days. On-chain Bitcoin transactions can sometimes take a few hours during high-fee periods, and customers might pay on the last day.

Troubleshooting Common Issues

• Invoice created in BTCPay but WHMCS doesn't update -- 90% of the time this is the webhook. Verify the callback URL is correct and publicly accessible. Check that the webhook secret matches in both BTCPay and WHMCS.
• "Gateway connection error" in WHMCS -- check your BTCPay Server URL. It must include https:// and have a valid SSL certificate. Also verify the API key hasn't expired or been revoked.
• Customer sees "Payment expired" -- BTCPay invoices have a default expiration (typically 15 minutes). If the customer doesn't pay in time, they need to create a new payment. You can adjust the invoice expiration time in your BTCPay store settings.
• Lightning payments not showing -- make sure your Lightning node is online and has inbound liquidity. A common mistake is having a Lightning node with channels open but no capacity to receive payments.
• Wrong amount received -- BTCPay handles exchange rate calculation at invoice creation time. If Bitcoin's price changes between invoice creation and payment, the BTC amount adjusts. If a customer underpays, BTCPay will show the invoice as partially paid and WHMCS won't mark it as complete.
• Module not appearing in WHMCS -- double-check that the gateway files are in the correct directory and that file permissions allow your web server to read them. Clear WHMCS template cache if needed.

Tips From Running WHMCS Bitcoin Payments in Production

A few things we've learned from managing WHMCS + BTCPay integrations for hosting providers:

• Display Bitcoin prominently on your checkout page. Don't bury it at the bottom of the payment method list. Customers who want to pay with Bitcoin are more likely to complete the purchase if they see the option immediately.
• Show both on-chain and Lightning. BTCPay presents both options by default. On-chain works for larger invoices (dedicated servers, annual plans), while Lightning is better for smaller amounts (shared hosting, domains).
• Set your BTCPay payment speed setting appropriately. For low-risk services, you can accept zero-confirmation transactions. For expensive dedicated servers, wait for at least one confirmation.
• Keep your BTCPay Server updated. Security patches and compatibility fixes come out regularly. If you're self-hosting, schedule monthly update checks.
• Monitor your Lightning channels. If you accept Lightning, make sure you have enough inbound liquidity. Nothing frustrates a customer more than a Lightning payment that won't route.

Why BTCPay Server Over Other Options

You might wonder about alternatives like Coinbase Commerce, BitPay, or CoinGate for WHMCS bitcoin payments. Here's the short version:

• Coinbase Commerce -- custodial (they hold your funds), can freeze your account, charges fees. They've been known to close hosting-related merchant accounts with little warning.
• BitPay -- requires extensive KYC, charges 1% processing fee, and forces customers to use their specific wallet app or pay extra network fees through their payment protocol.
• CoinGate -- custodial, charges 1% fee, and adds another third party between you and your money.
• BTCPay Server -- free, open-source, non-custodial. Payments go directly to your wallet. Nobody can freeze your account or hold your funds. You control everything.

For hosting companies especially, the non-custodial and censorship-resistant nature of BTCPay matters. Hosting is a business that payment processors sometimes view with suspicion. With BTCPay, there's no processor to appease.

Related Guides

• How to Accept Bitcoin on WooCommerce
• How to Set Up BTCPay Server on LunaNode
• How to Accept Bitcoin Without KYC