Setting up BTCPay Server
BTCPay Server is a self-hosted payment processor with open source code. If you accept Bitcoin (and not just) and don't want to pay commissions to payment gateways or give them control over your transactions—this is the standard solution. No KYC requirements for the shop owner, no third party between you and the payment.
What BTCPay Can Do Out of the Box
- Unique address generation per invoice (BIP-44 HD wallet)
- Support for Bitcoin, Lightning Network, Monero, Litecoin and others
- Plugins for WooCommerce, Shopify, Magento, PrestaShop
- API for custom integration
- Point-of-Sale interface
- Crowdfunding functionality
- Payouts (mass payouts)
- Webhook notifications about payments
Infrastructure: Deployment Options
Docker on VPS (Recommended)
Official Docker deployment—the simplest path. Requirements: Ubuntu 20.04/22.04, minimum 2 CPU / 4 GB RAM / 500 GB SSD (Bitcoin full node—~550 GB in 2024).
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
export BTCPAY_HOST="pay.yourdomain.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="lnd" # or clightning
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
. ./btcpay-setup.sh -i
opt-save-storage—enables pruned node (Bitcoin pruned to ~5 GB instead of 550 GB). Suitable for most shops, not suitable if full block explorer needed.
Without Own Node (External Electrum Server)
Can connect BTCPay to someone else's Electrum server instead of syncing a full node. Faster startup, lower disk requirements. Compromise—trust in external server for transaction verification.
Lightning Network: LND vs CLN
BTCPay supports both LN implementations. LND (Lightning Labs) is simpler to set up and has more documentation. CLN (Core Lightning, formerly c-lightning)—more modular, preferred by developers for custom scenarios.
For Lightning you need a bitcoin hot wallet with liquidity. Channels require on-chain transactions to open. Minimum working balance for receiving payments: ~0.01 BTC in channels (inbound liquidity). Services like Voltage or Amboss Magma help with inbound liquidity for a fee.
Integration via API
For custom payment flows—Greenfield API (REST):
// Creating an invoice
const invoice = await fetch(`${BTCPAY_URL}/api/v1/stores/${STORE_ID}/invoices`, {
method: 'POST',
headers: {
'Authorization': `token ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '99.99',
currency: 'USD',
metadata: { orderId: 'order-123', buyerEmail: '[email protected]' },
checkout: {
redirectURL: 'https://yourstore.com/order/123/success',
defaultPaymentMethod: 'BTC'
}
})
})
Webhook on invoice status change—configured via UI or API. Statuses: New → Processing → Settled (or Expired/Invalid).
Important: verify webhook signature. BTCPay signs payload via HMAC-SHA256 with your secret—don't ignore this check, otherwise anyone can send a fake payment notification.
SSL and Security
BTCPay automatically gets a Let's Encrypt certificate. Requires: domain must resolve to server IP before startup. If behind Cloudflare—disable proxying for BTCPay domain or use Cloudflare Origin Certificate.
Bitcoin wallet seed phrase in BTCPay—export and store offline. Standard advice, but half of installations lose access on server change precisely because they didn't save the seed.
What Gets Done in 2–3 Days
Deployment of BTCPay Server to your VPS, domain and SSL configuration, Bitcoin setup (full or pruned) and optionally Lightning Network, connection to CMS or API integration setup, webhook configuration for your order system, basic uptime monitoring and disk space monitoring.