BTCPay Server Tutorial: The Zero-Fee Bitcoin Payment Setup That Actually Puts You in Control

This BTCPay server tutorial starts with the number that matters most: 0%. BTCPay Server charges zero processing fees on every Bitcoin transaction you receive. Server hosting costs approximately $8 per month. That is your entire infrastructure cost. Compare that to a 1% hosted processor at $100,000 monthly revenue: $12,000 per year going to a third party, every year, for the privilege of accessing funds that are already yours. BTCPay Server eliminates that entirely, and it puts your private keys on your own server, under your direct control.

This is not a theoretical exercise. It is a production-grade, open-source payment infrastructure stack trusted by thousands of merchants globally, including Namecheap, which processed $73 million in BTC revenue across 1.1 million transactions through BTCPay.

The setup requires a server, a domain name, and about two hours of active work. The Bitcoin node sync that follows takes longer, but it runs in the background. Here is exactly how to do it.

What BTCPay Server Is and Why It Matters

BTCPay Server is open-source, self-hosted Bitcoin payment processing software. No third party touches your funds. No KYC requirements. No transaction fees taken by the payment processor. Payments go directly from your customer's wallet to yours, peer-to-peer.

The architecture is built around a full Bitcoin node running on your server. Every payment your customers make is verified by your own copy of the Bitcoin blockchain, not delegated to a third-party API. That is what "self-hosted" actually means in practice: you are the infrastructure.

BTCPay Server for WooCommerce is a self-hosted, open-source payment gateway that provides zero fees, a fully automated payment system, QR code checkout display, direct wallet payments as a self-custodial service, and Lightning Network integration out of the box for instant, fast, and low-cost payments and payouts.

The tradeoff for zero fees and full custody is clear: you own the uptime, updates, and security. For a merchant running significant volume, that tradeoff is obviously correct. For a merchant just starting out, it requires a realistic assessment of technical comfort.

What You Need Before You Start

Skipping prerequisites is how people spend four hours on a failed install. Cover these first.

Hard requirements:

• A VPS (Virtual Private Server) with at least 2 CPU cores, 4 GB RAM, and 1 TB storage (a full Bitcoin node requires approximately 600+ GB as of 2026)
• A registered domain name pointing to your VPS via an A record
• SSH access to your server (Linux command line basics required)
• A Bitcoin wallet for receiving payments (hardware wallet recommended for production)
• Approximately 2 hours for initial setup, plus sync time (hours to days depending on server speed)

Optional but recommended:

• A Lightning wallet or willingness to run an internal LND or Core Lightning node
• A WooCommerce or Shopify store if integrating with e-commerce

Hosting Options Compared

You can deploy BTCPay Server on any clean server, but turnkey providers like LunaNode and Voltage offer preconfigured images and wizards that simplify setup, SSL, and ongoing updates. The self-managed VPS approach provides maximum control and potentially the lowest monthly cost, with full customization, but you own security hardening, Docker and OS updates, domain and SSL management, backup strategy, and must react to incidents continuously.

For production merchant use, a self-managed or BTCPay-ready VPS is the correct path. Shared instances mean someone else controls your server, which reintroduces the custodial risk you are specifically trying to eliminate.

Step-by-Step: Installing BTCPay Server via Docker

The officially supported and recommended installation method is Docker-based. It handles dependencies, updates, and service orchestration automatically.

Step 1: Provision Your VPS

Spin up a new Ubuntu 22.04 or 24.04 VPS instance with the specifications listed above. Connect via SSH as root or a sudo user. Run initial updates:

sudo apt update && sudo apt upgrade -y

Create a non-root user if you have not already, and configure your firewall to allow ports 80 (HTTP), 443 (HTTPS), and 22 (SSH).

Step 2: Point Your Domain

Before running the BTCPay setup script, your domain must already resolve to your server's IP address. Log into your DNS registrar. Create an A record pointing btcpay.yourdomain.com (or whichever subdomain you choose) to your VPS public IP address.

DNS propagation can take up to 24 hours, but typically resolves within 30 to 60 minutes. BTCPay's automated SSL provisioning via Let's Encrypt requires this DNS record to be live before setup runs. If you skip this, the SSL certificate step will fail and you will need to restart.

Step 3: Run the BTCPay Setup Script

The officially supported setup is driven by Docker and Docker-Compose. The btcpay-setup.sh utility makes sure Docker and Docker-Compose are installed on your system and generates a Docker-Compose configuration adapted for your needs based on environment variables.

The key environment variables to set before running setup:

• BTCPAY_HOST: your domain (e.g. btcpay.yourdomain.com)
• NBITCOIN_NETWORK: mainnet for live payments (use testnet for testing)
• BTCPAYGEN_CRYPTO1: btc to enable Bitcoin
• BTCPAYGEN_LIGHTNING: lnd or clightning if you want Lightning support
• BTCPAYGEN_REVERSEPROXY: nginx for SSL termination

Run the setup:

sudo su -. <(curl -s https://btcpayserver.github.io/btcpayserver-docker/btcpay-setup.sh) -i

The script installs Docker if absent, generates your Docker-Compose configuration, starts all services, and provisions SSL certificates automatically. A successful setup ends with BTCPay Server accessible at your domain over HTTPS.

Step 4: Wait for Bitcoin Node Sync

This is the step where patience is required.

Your BTCPay Server is now running a full Bitcoin node. That node needs to download and verify the entire Bitcoin blockchain, which as of 2026 is over 600 gigabytes. On a fast server with a good internet connection, this takes between 6 and 24 hours. On slower hardware, it can take several days.

You cannot accept live payments until your node is fully synced. You can monitor sync progress from the server status dashboard after logging in. Do not panic if it seems slow early on: initial block download is I/O intensive and the rate typically accelerates once historical blocks are processed.

Use this time to configure your store settings (next section) and test on testnet mode if desired.

Creating Your First BTCPay Store

Once your node is synced, the BTCPay server tutorial continues with store configuration. Log into your BTCPay Server admin panel at your domain. Create a new account, then navigate to create your first store.

Each store has its own wallet, can create apps such as Point of Sale or Payment Buttons and Crowdfunds, or be paired with external e-commerce software through one of the integrations available. Admin does not have control over the private keys of the other user's stores.

Connecting Your Bitcoin Wallet

Your store needs a Bitcoin wallet to receive payments. BTCPay Server is non-custodial: it generates payment addresses derived from your wallet's extended public key (xpub or zpub), but the private keys never leave your wallet.

The process:

1. Navigate to your store, then to "Wallet" settings.
2. Choose "Connect an existing wallet" or generate a new one within BTCPay.
3. For a hardware wallet (recommended for production), export your xpub from the device and paste it into BTCPay. Your hardware wallet signs transactions; BTCPay only watches the public key.
4. Save and confirm. BTCPay will derive addresses from your xpub automatically for each invoice.

BTCPay's wallet is feature-rich and has privacy features built-in. Furthermore it has full hardware wallet integration, so you can manage your funds with a compatible hardware wallet directly from your BTCPay.

Enabling Lightning Network

Lightning is where BTCPay Server becomes genuinely powerful for high-frequency payments. BTCPay Server currently offers both Core Lightning (CLN) and LND implementations. If you chose to include Lightning during setup, the internal node runs alongside your Bitcoin node automatically.

To activate it for your store:

1. Navigate to Store Settings, then Lightning.
2. Select "Use internal node" if you ran setup with Lightning enabled.
3. Fund your Lightning wallet with on-chain BTC to create outbound channels.
4. Open at least one channel to a well-connected routing node.

Running Lightning nodes is still somewhat complex. You need to ensure proper backups to recover funds. Using the Lightning Network can put your money at risk. Do not use more than you can afford to lose.

For merchants who want Lightning payment capability without running a full node, BTCPay supports external custodial Lightning wallets including Blink (with optional fiat auto-conversion) as plugin integrations.

Integrating BTCPay Server with Your BTCPay Server Tutorial: WooCommerce or Shopify

Both platforms have mature, officially supported integrations.

WooCommerce integration:

In the BTCPay Server dashboard, generate an API key with the following permissions: View invoices, Create invoice, Modify invoices, Modify stores webhooks, View your stores, and Create non-approved pull payments (used for refunds). In your WordPress admin, navigate to WooCommerce, then Settings, then Payments, and enable the BTCPay default payment gateway. Enter your BTCPay Server URL and API key in the plugin settings.

Place a test order on your WooCommerce store and select Bitcoin as the payment method. Verify the BTCPay invoice page loads correctly with both on-chain and Lightning payment options. Complete a small real payment to confirm the full flow: invoice creation, payment detection, and order status update.

Shopify integration:

The BTCPay-Shopify integration works through Shopify's manual payment method system. The customer selects Bitcoin at checkout, gets redirected to the BTCPay payment page, pays the invoice, and is redirected back to the Shopify order status page. BTCPay Server handles refunds for Shopify orders paid with Bitcoin by sending the customer a refund-claim link for the refunded amount.

Both integrations handle invoice creation, payment detection, order status updates, and refunds automatically. Manual intervention is only required for exceptional cases.

Testing Your Setup Before Going Live

Never skip testing. A misconfigured webhook or wallet derivation error on a production store means missed payments and frustrated customers.

Testing checklist:

• Switch BTCPay to testnet mode (NBITCOIN_NETWORK=testnet) and install the WooCommerce plugin or Shopify app using testnet credentials.
• Create a test product priced at a small amount.
• Place a test order and select Bitcoin at checkout.
• Verify the BTCPay checkout page appears with a correct QR code and address.
• Send a testnet BTC payment from a testnet wallet (available freely online).
• Confirm the order status updates correctly in WooCommerce or Shopify.
• If using Lightning, test a Lightning payment separately.
• Switch back to mainnet credentials only after every step above passes cleanly.

Making a small real payment to confirm the full flow: invoice creation, payment detection, order status update. Check that the payment arrives in your connected wallet.

Hardening and Maintaining Your Server

The install is not the last step. A payment server that goes offline loses sales. One that is compromised loses funds.

Essential ongoing practices:

• Keep BTCPay updated: Run btcpay-update.sh regularly. BTCPay releases security patches that must be applied promptly. The btcpay-update.sh script updates BTCPay Server to the latest version.
• Backup your wallet seed: Your Bitcoin wallet's seed phrase (and Lightning channel backup files) must be stored securely and offline. If your server dies without a backup, funds can be lost permanently.
• Configure a watchtower for Lightning: A watchtower monitors the blockchain for fraudulent channel closure attempts when your node is offline. Essential if you are running a Lightning node in production.
• Monitor disk space: A full Bitcoin node requires continuous storage growth. Set up disk usage alerts to avoid running out of space mid-sync.
• Restrict SSH access: Disable root login, use SSH key authentication instead of passwords, and consider limiting SSH access by IP.
• Run changedomain.sh if you ever need to change your domain. The changedomain.sh script changes the domain of your BTCPay Server. Remember to disable 2FA and U2F first, as you risk being unable to log in to your account.

What the Full BTCPay Server Tutorial Means for Your BTC Position

There is a dimension to running BTCPay Server that connects directly to how you think about BTC as an asset, not just a payment rail.

Every payment received into your self-custodial BTCPay wallet is BTC you hold outright. No exchange. No counterparty. No withdrawal delay. The moment a customer pays, the BTC is in a wallet your hardware device controls. For merchants who believe in Bitcoin's long-term value profile, this means business revenue and personal BTC holdings can converge into a single, unified, self-sovereign position.

Traders on platforms like BYDFi who also run BTCPay Server for their business effectively accumulate BTC through both channels: active trading and passive merchant revenue. That is a structurally interesting position. To monitor BTC's current price as you decide how much merchant BTC to hold versus convert, the BYDFi BTC overview page provides live price data and market sentiment readings. The BYDFi Crypto Calculator handles BTC-to-fiat conversions for any invoice or treasury sizing decisions. And if you need to acquire BTC to fund your Lightning channels at launch, the how to buy BTC guide on BYDFi covers the full purchasing process.

FAQ

Q: What server specifications do I need to run BTCPay Server?

The minimum practical requirements in 2026 are 2 CPU cores, 4 GB RAM, and 1 TB storage (a Bitcoin full node requires over 600 GB). A VPS on providers like DigitalOcean, Hetzner, or Vultr starting at $8 to $20 per month meets these requirements.

Q: How long does BTCPay server tutorial setup and Bitcoin sync take?

Initial BTCPay Server installation via the setup script takes 30 to 60 minutes on a prepared VPS. Bitcoin node synchronization takes 6 to 24 hours on fast hardware with a good internet connection, and up to several days on slower setups. You cannot accept live payments until sync completes.

Q: Can I use BTCPay Server with Shopify without technical expertise?

The Shopify integration requires installing the BTCPay-Shopify app and configuring a manual payment method in your Shopify admin. It is not fully plug-and-play: you need a running BTCPay Server instance first. Technical confidence with server setup is required, but the Shopify connection itself is straightforward once BTCPay is live.

Q: Is BTCPay Server safe for accepting real Bitcoin payments?

Yes, when set up correctly. BTCPay Server uses your wallet's public key only, meaning private keys never touch the server. The software is open-source with over 7,400 GitHub stars and has processed hundreds of millions of dollars in merchant transactions. Proper server hardening, wallet backups, and regular updates are required to maintain that security.

Q: What happens if my BTCPay Server goes offline?

Pending invoices will not detect new payments while the server is offline. Customers who sent BTC to an unpaid invoice during downtime will need manual reconciliation. Existing received funds in your wallet are unaffected since they are secured by your wallet keys, not the server. Maintain server uptime and monitor disk space to prevent unplanned outages.