How to set up BTCPay Server

BTCPay Server is the self-hosted, open-source answer to Bitcoin payment processing. Zero platform fees, full custody of your keys, and a polished merchant experience that competes with hosted processors on UX. The cost is operational — you (or a consultant) run the server.

This guide is the realistic walkthrough. Not the marketing version.

Decide where it runs

Three reasonable options:

• Managed BTCPay host (~$8/month). Voltage or LunaNode runs BTCPay for you; you log in via the web. Fastest path; closest to “click a button, have a working store.” You retain custody, but the host runs the infrastructure.
• Self-hosted on a VPS (~$5–$20/month). Hetzner, DigitalOcean, Vultr. You run the Docker-based install yourself.
• Self-hosted at home (~$0). On a Raspberry Pi, Umbrel, Start9, or an existing home server. Full sovereignty, requires home internet uptime.

For most small merchants, managed BTCPay is the right starting point. You retain custody and zero platform fees, you avoid the sysadmin work, and you can migrate to self-hosted later.

Install (self-hosted path)

If you’re going self-hosted on a VPS, the official BTCPay docs are the reference; the broad shape is:

1. Provision the server. Linux VPS, 2 GB RAM minimum, 1+ TB disk for full Bitcoin node, public IP.
2. Install Docker and Docker Compose.
3. Clone the BTCPay Server install repo (btcpayserver-docker).
4. Configure environment variables — your domain, your email, the Lightning implementation (LND or CLN).
5. Run the install script.
6. Wait for the Bitcoin node to sync. This is the slow part — hours to days depending on bandwidth and disk speed.
7. Wait for the Lightning node to start.
8. Log in via your domain and configure your first store.

The official docs and the BTCPay community (Mattermost, Telegram) are responsive — if you get stuck, ask. Most stuck points are environmental rather than BTCPay-specific.

Configure your store

Once BTCPay is running:

1. Create a store. Set the name, default currency, and payment methods.
2. Connect a wallet for on-chain Bitcoin receiving. Either:
   • Generate a new BTCPay-managed wallet (BTCPay holds the keys).
   • Connect your existing hardware wallet for non-custodial setup (recommended for serious volume).
3. Connect Lightning. Use the BTCPay-managed Lightning node (default) or connect to an external Lightning node you already run.
4. Set your store branding. Logo, store URL, contact email.
5. Configure invoice expiry (default is reasonable; some merchants tune to 15–30 minutes).

Fund Lightning liquidity

This is the step most people underestimate. To receive Lightning payments, your Lightning node needs inbound liquidity — channels with capacity coming in. Options:

• Open outbound channels and use the network’s loop. Opens a channel to a well-connected node, sends sats there, sends them back via Lightning. Costs a bit; gives you balanced liquidity.
• Lightning Network+ swaps. Community service that helps you get inbound liquidity in exchange for outbound from someone else.
• Pay a Liquidity Service Provider (LSP). Services like Voltage, Magma, Amboss offer “buy inbound channels” for a fee. Cleanest for non-experts.
• Splicing-aware setups. Some configurations can splice in liquidity without traditional channel opens.

Budget realistic numbers: if you expect $500/day in Lightning sales, you need ~$1500–$3000 of inbound capacity comfortably (so spikes don’t fill your channels). An LSP fee for that capacity is typically 1–3% of capacity, one-time.

Add ecommerce plugins

BTCPay’s 30+ integrations make adding Lightning to an existing store cheap:

• WooCommerce / WordPress — official plugin, mature.
• Shopify V2 — newer plugin, works.
• Magento, PrestaShop — official plugins.
• Ghost, Cal.com, Zaprite, ECWID, GiveWP — added through 2025.
• Custom site — Greenfield API.

Pick the plugin for your platform, paste your BTCPay API key, configure Lightning as the payment method. Test with a small purchase.

Test, test, test

Before going live:

1. Send a small Lightning payment from another wallet to your BTCPay invoice page. Verify it shows as confirmed.
2. Test the full ecommerce checkout flow if you have a store.
3. Test a refund — generate a Lightning invoice in your customer’s wallet, pay it from BTCPay.
4. Test point-of-sale mode if you’ll use it.

The goal is to find any configuration issues before your first real customer does.

Common gotchas

• Channel-open mining fees during a busy mempool. If you fund your Lightning node during high-fee periods, channel opens can cost more than expected. Wait for low-fee windows, or use an LSP.
• Channel state backups. BTCPay handles this by default for LND; verify if you use CLN. Losing channel state can force-close all channels.
• DNS and HTTPS. BTCPay needs a domain with a valid HTTPS certificate. Cloudflare’s free tier works.
• Updates. BTCPay updates regularly. Test updates on a staging environment before applying to your production store, especially after major version bumps.

When to use a consultant

If you’re:

• Running a busy merchant operation where downtime costs sales.
• Not comfortable with Linux, Docker, and basic networking.
• Planning to add custom integrations beyond the standard plugins.

…hire a BTCPay consultant. There’s a growing community of independent BTCPay specialists, particularly in Europe. The cost is usually $500–$2000 one-time for a full setup, which is cheap relative to the operational time you save.

Next step

• BTCPay Server vs OpenNode — if you’re still deciding.
• Lightning merchant setup checklist — the broader checklist this guide sits inside.
• How to accept Bitcoin in a café — the physical-retail variant.

FAQ

How long does setup take? +

Plan for a weekend if you're self-hosting from scratch. A managed BTCPay host (Voltage, LunaNode) cuts this to about an hour. The variable is Lightning channel liquidity — opening a well-funded channel can take a day to settle on-chain depending on the fee market.

What does it cost? +

Software is free. Server hosting is ~$5–$15/month on a basic VPS, or free if self-hosted on a Raspberry Pi or existing home server. Channel-open mining fees vary with the mempool — budget a few dollars for the first on-chain transaction. Total realistic monthly cost: $0 to $15.

Do I need to run my own Bitcoin node too? +

BTCPay runs a Bitcoin node internally as part of the standard install. You don't need a separate one. The trade-off is that the initial sync downloads the full Bitcoin blockchain, which is hundreds of GB and takes hours to days.