How BTCpay Server Works Under the Hood

When I tell people I'm setting up a BTCpay server, the most common response is some variation of "what does that actually mean"? It's a fair question. BTCpay Server is one of those tools that's easy to describe at a high level, open-source Bitcoin payment processor, but harder to explain in terms of what's actually running and why it matters that you control it yourself.

What BTCpay Is and Isn't

BTCpay Server is not a cryptocurrency exchange. It's not a custodial wallet. It doesn't hold your Bitcoin on your behalf or act as an intermediary between you and the Bitcoin network.

It's software that runs on a server you control, connects directly to the Bitcoin network through your own node, generates payment addresses for incoming transactions, monitors those addresses for incoming payments, and notifies your application when a payment is confirmed.

The key word is "your". Your server, your node, your addresses, your keys. Nobody else has access to your funds or can freeze your account or take a percentage of your revenue beyond the Bitcoin network's transaction fee.

The Components Running Under the Hood

A full BTCpay deployment runs several interconnected services. Understanding each one helps clarify what's actually happening when a customer pays you.

Bitcoin Core is the foundation. This is the full Bitcoin node, the one that's currently syncing on my server and 61% of the way through the blockchain at the time this post was created. It maintains a complete copy of all Bitcoin transactions, validates new blocks and transactions against consensus rules, and provides the authoritative view of which transactions have been confirmed and to what depth.

NBXplorer is a lightweight indexer that sits on top of Bitcoin Core. Where Bitcoin Core tracks the entire network, NBXplorer tracks specific addresses that BTCpay cares about — the ones it has generated for customer payments. It provides an efficient API for BTCpay to query balance and transaction history for those addresses without having to ask Bitcoin Core to scan the entire blockchain every time.

BTCpay Server itself is the application layer. It's a .NET application that manages stores, invoices, users, and integrations. When a customer initiates a payment, BTCpay generates a fresh Bitcoin address derived from your wallet's extended public key (xpub), creates an invoice, and starts monitoring that address via NBXplorer. When payment arrives, BTCpay marks the invoice as paid and triggers any configured webhooks or notifications.

PostgreSQL handles BTCpay's own application data — stores, invoices, users, settings. This is separate from the Bitcoin blockchain data.

All of this runs in Docker containers, orchestrated by a deployment script that BTCpay provides. The containerization means the components are isolated and upgradeable independently.

The Payment Flow in Detail

When a customer pays through a BTCpay-powered checkout, here's what actually happens:

Your store generates an invoice and BTCpay derives a new Bitcoin address from your xpub. The private key for this address never touches the server — it lives in your wallet.
The customer broadcasts a payment transaction to the Bitcoin network.
Bitcoin Core receives the transaction in its mempool. NBXplorer detects that it involves a tracked address and notifies BTCpay.
BTCpay marks the invoice as "payment detected" and starts waiting for confirmations.
Once a miner includes the transaction in a block (one confirmation), BTCpay marks it as confirmed. Most merchants accept one confirmation for smaller amounts, but this is configurable if you want more confirmations before accepting.
BTCpay fires any webhooks you've configured — telling your e-commerce platform to fulfill the order, for example.

The Bitcoin never passes through BTCpay's hands. It goes directly from the customer's wallet to an address controlled by your private key. BTCpay is just the observer and coordinator.

Why Self-Hosting Matters

The alternative to self-hosted BTCpay is using a third-party Bitcoin payment processor like Coinbase Commerce or BitPay. Those services work, but they introduce dependencies:

They hold your funds temporarily until you withdraw
They can freeze your account or decline to process certain payments
They take fees beyond the network fee
They collect data on your customers and transactions
They can go out of business or change their terms

When you run your own BTCpay server, none of those dependencies exist. The tradeoff is operational responsibility — you need to keep the server running, keep software updated, and manage your own keys. For a developer comfortable with servers, that tradeoff is likely worth it.

What I'm Building on Top of This

My BTCpay server at btcpay.shepherdhosting.com will be operational once the blockchain sync completes. As a technology consultant, my plan is to offer hosted BTCpay accounts — I do the work of maintaining the infrastructure, and businesses or individuals who want to accept Bitcoin can get set up quickly without running their own server.

The operational complexity of running a full node, keeping it synced, managing Docker containers, and handling backups is real. Abstracting that away so others can get the benefits of self-sovereign payments without the technical overhead is the service I'm building.