What BTCPay Server is
BTCPay Server is free software for accepting bitcoin as a business, a charity or a freelancer. It makes invoices and checkout pages, runs a point-of-sale screen for a shop counter, and plugs into online shops. Payments go straight to your own wallet. In the words of its user guide, it "does not hold funds as a payment intermediary".
It is open source under the MIT licence and you run it yourself. The project says it is not a company, and the BTCPay Server Foundation, which supports it, is a non-profit funded by donations. BTCPay charges nothing. Its FAQ says: "We do not charge you anything. However, to run it, you should host it." Your costs are the server and normal network fees.
This guide was checked against version 2.4.7, released on 29 October 2026. It was a security release fixing 85 findings, and the project strongly recommends updating, especially on servers shared by several merchants.
If you only want to be paid now and then, an ordinary wallet is enough. BTCPay is for when you need invoices tied to orders, a till, refunds and records.
BTCPay Server ↗ · BTCPay Server 2.4.7 release ↗
Where to run it
BTCPay needs a Bitcoin node and a machine that stays online. There are three common routes.
- A server you rent. The official install uses Docker on a rented server, with your own domain name for a secure web address. The project's own guidance puts the bare minimum at 4 GB of memory, 2 processor cores and 50 GB of SSD storage with a pruned node, usually around $20 a month or less. LunaNode offers a one-click setup for about $10 a month.
- Your home node. BTCPay is an app on Umbrel and Start9. The BTCPay community says it cannot support these setups. Umbrel warns that online shops such as Shopify or WordPress cannot reach a home server unless you set up dynamic DNS.
- Someone else's server. Some people run BTCPay and let others open stores on it. See the warnings below before you use one.
The Bitcoin node takes between one and five days to sync the first time. As soon as the server is up, create your account. The first account to register becomes the server's administrator. If someone else got there first, the documentation says to start again with a new server.
BTCPay: deployment options ↗ · BTCPay Docker deployment ↗
Using someone else's server
A third-party host is cheap and quick, and BTCPay's documentation is frank about the trade. You trust the owner of the server.
- A host never needs your private key. The documentation says that if a host asks for one or creates one for you, "be sure it's a scam".
- Connect a wallet you already hold, by its public key, never a hot wallet. A dishonest host could still run altered software that swaps in their own key, so future payments go to them. Check regularly that payments arrive in your own wallet.
- The host can see how you use your store. By default, stores on a shared server cannot use the server's Lightning node or create hot wallets.
The documentation suggests third-party hosts for testing and learning, not for large or frequent payments.
Create a store
- Choose Create account and register.
- On Create your first store, enter a Name, a Default currency for your prices and a Preferred Price Source, the exchange rate BTCPay uses to convert them. The suggested source is fine to start with. Choose Create Store.
- The dashboard shows what is left: Set up a wallet and, if you want it, Set up a Lightning node.
Connect a wallet
Choose Set up a wallet. BTCPay offers two paths.
Connect an existing wallet is the safer one. BTCPay only gets your wallet's public key, which lets it make a fresh address for every invoice but not spend. The project's FAQ puts it this way: "Even if your server gets hacked, your funds from the on-chain transactions are always safe." The import options are:
- Connect hardware wallet, using BTCPay's Vault app on your computer with the device plugged in.
- Import wallet file, a file exported from a wallet such as Sparrow.
- Enter extended public key, pasted by hand.
- Scan wallet QR code, which BTCPay lists for BlueWallet, Passport and others.
- Enter wallet seed, marked Not recommended. Never type your recovery words into a server.
Create a new wallet makes the keys on the server. A Hot wallet keeps the private key there, so BTCPay can spend for you, for refunds and payouts, but anyone with admin access to the server can too. BTCPay's own advice is to "regularly withdraw funds to a different wallet". A Watch-only wallet shows you the recovery words once and erases the private key from the server.
When BTCPay asks for an address type, Segwit (Recommended) suits most stores.
Create a store to begin accepting payments.
The recommended price source gets chosen based on the default currency.
The gap limit. Your wallet app looks a fixed number of unused addresses ahead, usually 20. Each invoice uses a new address, so after 20 unpaid invoices in a row your wallet can stop seeing new payments, even though BTCPay records them. If your wallet has a gap limit setting, raise it. Payments are not lost, only hidden until the wallet looks further.
BTCPay FAQ: wallets and the gap limit ↗ · BTCPay Vault ↗
Lightning
Lightning is optional and off by default. On Connect to a Lightning node there are two choices.
- Use internal node runs a Lightning node on the BTCPay server itself. It is a hot wallet on a machine reachable from the internet. BTCPay's documentation warns, "Do not use more than you can afford to lose." Its recovery words bring back only the on-chain part, and channels need their own backup.
- Use custom node connects to a Lightning node you run elsewhere. BTCPay supports LND, Core Lightning, Phoenixd and Eclair. LNDhub connections now need a plugin.
You can also take Lightning payments without a node of your own, through plugins. They are covered below.
Ways to get paid
- Invoices. Payments, then Invoices, then Create Invoice, for a one-off amount in your currency.
- Point of Sale. A till for a shop or stall, for example as a product list, a product list with a cart, or a keypad for typing in an amount.
- Requests. A payment request is a page you send to a client. If you allow it, it can be paid in parts, and each payment uses the exchange rate at the time.
- Crowdfund. A fundraising page in the style of Kickstarter, paid straight to your wallet.
- Pay Button. A button for a website. BTCPay warns it "should only be used for tips and donations", because the buyer can change the order details it sends.
- Subscriptions. Recurring plans billed monthly, quarterly, yearly or once for life. Bitcoin has no direct debit, so customers either pay an invoice each period after a reminder, or top up a credit balance that renewals draw from.
- Lightning Address. Once Lightning is on, the store can have addresses in the form name@yourserver, which anyone can pay from a Lightning wallet.
- Pull Payments. The opposite of an invoice. You set an amount and send a link, and the person claims it to an address of their choice. BTCPay uses these for refunds, and they also suit payouts to staff or contributors.
- Pay by NFC. The checkout page can take a tap from a contactless Lightning card, such as a Boltcard.
Wait for an invoice to show Settled before you hand over goods. A customer paying from an exchange sometimes sends slightly less, because the exchange deducts its own withdrawal fee. BTCPay then marks the invoice as partly paid.
BTCPay user guide ↗ · BTCPay: Shopify V2 ↗
Online shops and plugins
Online shops. BTCPay connects to most shop software. WooCommerce uses a WordPress plugin installed on your website. Shopify uses version 2 of BTCPay's integration, which runs on your BTCPay server and needs a Shopify Partner account. The original version is retired. BTCPay's documentation also covers Magento, PrestaShop, Odoo, Wix, Ghost, Zapier and others, and there is an API for your own systems.
Plugins add features to the server itself. The Plugin Directory, under the Plugins menu at the top right, listed 57 for version 2.4.7. Some useful ones:
- Lightning without your own node. Strike and Blink receive into an account with those companies, which holds the money for you. Breez and Flint run a lightweight Lightning wallet inside BTCPay, but keep its recovery words on the server, where the server's operator can reach them. Flint also holds the balance on Spark, a separate network whose own documentation says the money is not in your sole custody. Arkade and Bark use Ark, a newer way of making payments off the blockchain, and are early software.
- Your own node. The LSPS-1 plugin buys an incoming channel from a Lightning service provider, so a new node can receive straight away.
- Nostr. The Nostr plugin gives the store a Nostr address, accepts zaps, and can receive into a wallet you connect with Nostr Wallet Connect, such as Alby Hub.
- Splitting and cashing out. Prism splits each payment between several destinations, for example partners or a savings wallet. Bringin forwards a share of what you receive to a euro account with Bringin.
- Letting customers pay in other coins. SideShift, FixedFloat and Trocador add an exchange to the checkout. The customer pays in another coin and you receive bitcoin. Each exchange is a third party with its own terms.
- Selling tickets and in person. TicketTailor and Satoshi Tickets sell event tickets. The Boltcards Extension programs contactless cards that hold a Lightning balance. BTC Map adds your shop to a map of places that take bitcoin.
- Other currencies. There are plugins for Monero, Zcash and USDt. The Monero plugin warns that it uses one wallet for every store on the server, so use it only on a server you do not share.
- Ecash. BTCNutServer accepts Cashu ecash. Its own description says it is an early beta that has not been audited.
Only the server's administrator can install plugins, so on someone else's server you get whatever they have installed. Plugins run inside BTCPay with access to its data. BTCPay's own notice says they "have not undergone review by the BTCPay Server team", and its documentation advises installing only from sources you trust. Check who maintains a plugin, keep it updated, and back up the server first.
Plugins are developed by third parties. They need to be updated and maintained regularly in addition to BTCPay Server. Use plugins at your own risk.
BTCPay docs: plugins ↗ · BTCPay plugin directory ↗ · BTCPay docs: WooCommerce ↗
Refunds and records
On an invoice, Issue Refund lets you refund at the rate when the customer paid, at today's rate, in your own currency or as a custom amount. BTCPay then gives you a link to send the customer. They enter their own address, and you approve and send the payout under Payments, then Payouts.
For your accounts, Payments, then Reporting, exports invoices, payments, sales, refunds and more as a spreadsheet file. The wallet can also export its transaction labels in the standard BIP 329 format.
Security and privacy
- Turn on two-factor sign-in. Under Two-Factor Authentication on your account you can add an authenticator app or a FIDO2 security key. BTCPay also supports passkeys.
- Keep the server updated. Watch BTCPay's releases, as 2.4.7 shows.
- Keep hot wallets small, if you use one at all.
- Install only the plugins you need, and keep them updated with the server.
- Payjoin, which makes payments harder to trace, needs a hot wallet in BTCPay. The Payjoin guide explains it.
- Tor is optional. BTCPay's FAQ adds that turning it on "doesn't make you anonymous at all".
Every invoice uses a fresh address, which helps your customers' privacy and your own.
BTCPay: hardening ↗ · BTCPay: plugins ↗
Before you take real payments
- You registered the admin account yourself, straight after setup.
- The store uses a wallet you hold, connected by its public key, and its recovery words are on paper.
- You paid a test invoice and saw it arrive in your own wallet app.
- Two-factor sign-in is on for every account on the server.
- Staff know to wait for Settled.
- You know how to issue a refund.
- Someone checks for BTCPay updates.
Sources & further reading
Researched 18 November 2026. Software and services change: check the current documents before you act.
- BTCPay Server ↗
- BTCPay Server: source code ↗
- BTCPay Server 2.4.7 release ↗
- BTCPay Server user guide (2.4.7) ↗
- BTCPay source: wallet setup options ↗
- BTCPay source: hot and watch-only wallets ↗
- BTCPay Docker deployment and hardware specs ↗
- BTCPay docs: deployment options ↗
- BTCPay docs: third-party hosting ↗
- BTCPay docs: wallet FAQ and gap limit ↗
- BTCPay docs: general FAQ ↗
- BTCPay docs: BTCPay Vault ↗
- BTCPay docs: Lightning ↗
- BTCPay docs: Shopify V2 ↗
- BTCPay docs: hardening ↗
- BTCPay docs: plugins ↗
- BTCPay Server Foundation ↗
- Umbrel: BTCPay Server app ↗
- BTCPay plugin directory ↗
- BTCPay docs: WooCommerce ↗
- BTCPay docs: subscriptions ↗
- BTCPay docs: pull payments ↗
- Flint plugin: trust model ↗
- Monero plugin ↗
- BTCNutServer (Cashu) plugin ↗
- Prism, Nostr, Bringin, SideShift and other plugins ↗
Umbrel: run a node and connect your wallets to it → · Start9: run a node and connect your wallets to it → · Sparrow: build a wallet you can inspect → · Payjoin → · Choose the Lightning setup you can maintain → · Your balance is a collection of stories → · Alby Hub: your own Lightning node, connected to your apps →
