BTCPay Server: a self-hosted Bitcoin payment processor with no intermediary

The problem BTCPay Server solves for a merchant

A conventional Bitcoin payment processor sits between the buyer and the seller. It generates the address, watches the chain, and credits the merchant, which means it holds funds at some point and charges for the service. BTCPay Server removes that party. The README describes it as a "free and open-source Bitcoin payment processor which allows you to accept bitcoin without fees or intermediaries." The only cost it acknowledges is the Bitcoin network fee paid to miners.

The design consequence is custody. The README lists the wallet as "non-custodial (complete control over the private key)." That is the whole pitch and also the whole risk: nobody can freeze your balance, and nobody can recover it for you either. The project is aimed at merchants, but also at anyone who wants to take donations, run a point of sale, or raise funds, since the README lists apps for point of sale, crowdfunding, and a donation button.

A second audience is less obvious: people who want to share one instance. The feature list includes multi-tenant hosting, so an operator can run BTCPay Server and give accounts to other merchants rather than each one deploying separately. The documentation points to a third-party hosting page for those who would rather not self-host at all.

How the invoice flow actually works

The repository is a .NET solution, not a single binary. The top-level entries show the split: BTCPayServer holds the web application, BTCPayServer.Data the persistence layer, BTCPayServer.Client a client library, BTCPayServer.Abstractions the plugin contract surface, and BTCPayServer.Rating the exchange-rate component used to price an invoice. The Dockerfile copies each of those project files separately, runs dotnet restore, then copies the sources and publishes the BTCPayServer project. That layout tells you the plugin system is a first-class part of the architecture rather than an afterthought: abstractions are compiled into their own assembly so extensions can target them.

Operationally, the server is a full-node reliant wallet. It needs a Bitcoin node to see the chain and to construct transactions, which is why the deployment documentation is organized around node-plus-server stacks rather than a lone container. Lightning support is not built in from scratch; the README names LND, Core Lightning (CLN), and Eclair as the implementations it talks to. So a Lightning-enabled setup is at least three processes: the node, the Lightning daemon, and BTCPay Server.

That is the trade-off worth stating plainly. Running a node gives you verification and privacy, and it also means you own disk growth, initial block download time, and the upgrade cadence of every component. The README's privacy claim ("Enhanced privacy & security") follows from that architecture, not from a feature toggle.

Installing BTCPay Server and taking a first payment

The README does not present a single install command. It says to first decide between self-hosting and a third-party host, and then points to a deployment page that lists several documented ways to deploy. Docker is the path the documentation favors, and the repository ships a Dockerfile and a Docker/ directory. The Dockerfile builds on the .NET SDK and runtime images, installs iproute2, openssh-client, ca-certificates and jq, and sets BTCPAY_DATADIR to /datadir with /datadir declared as a volume. Anything you care about lives under that path, so it is the directory to back up.

If you would rather build from source, the README gives two scripts. On Linux:

./build.sh

On Windows PowerShell, the equivalent is `./build.ps1`. The README states that this requires the .NET SDK v10.0 installed as specified on the Microsoft download page. After a build, the run scripts expose the server's command-line arguments. This example prints them:

./run.sh --help

For debugging, the README points to JetBrains Rider or Visual Studio 2022. It does not document a supported path for running the server productively without a node, so treat the source build as a development workflow.

Once an instance is up, the README directs you to the getting started guide to register an account and the walkthrough guide for the first invoice. To try the software without deploying anything, the README links a demo instance at mainnet.demo.btcpayserver.org. That demo runs on mainnet, so anything you do there involves real bitcoin.

Where BTCPay Server is the wrong choice

If your business needs to receive dollars or euros into a bank account, BTCPay Server does not do that. It settles bitcoin to a wallet you control. The README's feature list is Bitcoin-only, with a separate community-maintained altcoin build named as the alternative for other chains. There is no fiat off-ramp in the core product.

The second limitation is operational. Because the server relies on a full node, the failure modes are the node's failure modes: an out-of-sync node, a stalled Lightning daemon, or a full disk will interrupt payment detection. The repository has no README section on rollback or disaster recovery for a corrupted datadir, and the deployment documentation is where that ground is covered. A merchant without the appetite to monitor a node should use a third-party host, which reintroduces exactly the intermediary the project was built to remove.

Third, the project is volunteer-built. The README states that BTCPay Server is "built and maintained entirely by volunteer contributors around the internet." Releases are frequent, with v2.4.4 on 2026-09-07, v2.4.3 on 2026-08-24, and v2.4.2 on 2026-08-07, and the last push to the repository was on 2026-09-18. Frequent releases are good for fixes and also mean you are expected to keep up; the repository carries a RELEASE-CYCLES.md and a RELEASE-CHECKLIST.md, which signals a structured cadence rather than a set-and-forget product. There is no commercial support tier in the README.

BTCPay Server compared with a custodial processor

The obvious alternative is a custodial Bitcoin payment processor, the kind that gives you an API key and a dashboard and settles to your bank. The difference is not a feature list, it is where the private key lives. With a custodial processor, the provider holds funds at some point, performs its own compliance checks, and charges a percentage. With BTCPay Server, the README's claim is "No fees, middleman or KYC," and the cost shifts to infrastructure and your own time.

That shift is real. A custodial processor handles chain reorgs, confirmations, and exchange-rate risk in the invoice window for you. BTCPay Server handles the mechanics, but you supply the node, the uptime, and the wallet. The BTCPayServer.Rating project exists precisely because invoices are priced in a currency and settled in bitcoin, and someone has to fetch that rate.

For merchants who already run infrastructure, this is a favorable trade. For a small shop that wants to accept bitcoin next week with no server, the custodial route is faster and the BTCPay route is a project. The multi-tenant feature is the middle path: find an operator running BTCPay Server and let them host your account, which keeps the software open while outsourcing the node.

Licence, upgrades, and what maintenance costs you

BTCPay Server is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: you can run it commercially, modify it, and redistribute it, provided the copyright notice and permission notice are preserved. That matters for the plugin ecosystem, since third parties can ship extensions under their own terms. This is not legal advice; if you are embedding the software in a product, read the licence text and the licence of each plugin you install.

Upgrade cost is the part to budget for. The Dockerfile pins specific base images, including the SDK and ASP.NET runtime tags, and the build takes a GitCommit argument that is compiled into the published output. That means an upgrade is a rebuild plus a container swap, and the version you are running is traceable from the binary. Because the server depends on a node and, optionally, a Lightning implementation, an upgrade is rarely a single component. The release cadence shown by the recent tags suggests you should plan to move forward rather than stay on an old minor version indefinitely.

The repository also includes a SECURITY.md and a .github directory, so there is a defined channel for reporting vulnerabilities. The README asks that GitHub issues be reserved for technical problems that cannot be resolved through community channels, and points to a community chat and discussions for everything else. That is a support model, not a support contract.

Editorial conclusion

Adopt BTCPay Server if you already run a Bitcoin node or are willing to run one, and you want settlement to your own keys with no processor in between. Do not adopt it if you need fiat settlement, card rails, or a hosted service with a support contract, because the project is volunteer-built and the deployment burden is yours. Verify first that your chosen deployment path is documented for your platform, that your Lightning implementation appears in the supported list, and that you have a backup plan for the wallet seed before you take a single payment.

Frequently asked questions

Official sources

1. btcpayserver/btcpayserver on GitHub
2. License: MIT
3. Project website
4. README
5. Releases