sipsorcery's blog

Occassional posts about VoIP, SIP, WebRTC and Bitcoin. response times SIP Sorcery Last 3 Hours
daily weekly status

BTCPay Server Manual Install

Update – 2 Jun 2019: An updated and more comprehensive article for a BTCPay Server Manual install is now available in the official documentation.

BTCPay Server is an open source project that allows merchants to accept cryptocurrency payments using their OWN self-hosted server. Being an OWN solution is a big deal. As someone who has dealt with payment processors for online payment processing for 20 years I can vouch for the fact that it’s always been a big pain point to the hip pocket. It generally boils down to a choice between PayPal or the hassle of setting up a merchant account to be able to accept credit card payments. In the last 4 or 5 years crypto-currencies have become another alternative but that option has always involved another 3rd party processor and it hardly seems worth the effort to switch from PayPal to a cryptocurrency gateway and incur the inevitable customer confusion for roughly the same level of cost.

With BTCPay Server things have changed. Now as a merchant it’s feasible to accept payments without the need for any kind of central payment processor. If you need to convert your cytpo-currency, such as Bitcoin, to a fiat currency, such as USD, then you’ll need to use a gateway but hopefully over time the need to do that will diminish.

The easy way to get up and running with BTCPayServer is to use a hosted set up as per the all-in-one wizard from Luna Node (note that this existence of the wizard owes a huge amount to if you find it useful buy something from him).

This post is about the hard way of setting up a minimal BTCPayServer:

  • Bitcoin – the Bitcoin daemon which interacts with the Bitcoin network and blockchain,
  • Lightning (c-lightning or lnd) – the Lightning daemon for near real-time payments on top of Bitcoin,
  • NBXplorer – a dotnet core application that monitors the Bitcoin blockchain to detect on-chain payments.
  • BTCPay Server – a dotnet core web application that glues all the pieces together for a merchant solution.

The instructions in this post are probably only useful for very technical users or programmers. For merchants a far easier and more sensible option is the Luna Node wizard.

The steps below were all been carried out on an Ubuntu 18.04 virtual machine.


First step is to set up a bitcoin daemon and synchronise the blockchain which should definitely be testnet at this stage.

Below are the steps I use but with bitcoin you should always be careful about what to trust. Ideally double check that the PGP key I refer to matches what’s listed on other other web sites. This verification process is not academic. For example in 2017 when Bitcoin Gold forked their blockchain I downloaded their software and performed the verification steps only to find the SHA checksum failed. Consequently I did not install the software and shortly thereafter a critical warning notice was issued.

  • sudo apt install gnupg2
  •  gpg2 –keyserver –recv-keys 0x90C8019E36C2E964 # Imports Wladimir J. van der Laan’a PGP key (gpg2 edit 01EA5486DE18A882D4C2684590C8019E36C2E96 & then trust if reqd)
  • Download required BTC version from (e.g.
  • Download the hash file (e.g.
  • gpg2 –verify SHA256SUMS.asc
  • sha256sum -c –ignore-missing SHA256SUMS.asc
  • tar zxf bitcoin-0.17.0-x86_64-linux-gnu.tar.gz
  • cd bitcoin-0.17.0
  • sudo cp bitcoind bitcoin-cli /usr/bin
  • mkdir /etc/bitcoin

To run bitcoind as a service there is a systemd configuration template available here.

The basic /etc/bitcoin/bitcoin.conf file I use is:

rpcauth=admin:91f1e6765bb4f8d6ba3a2da16cbd4b1$24f22f6fee475c15a24182d01cd060922e2dff1de9b633ce486f2a68cf9687b0 # admin/password

If the bitcoind service doesn’t start use:

sudo journalctl –unit bitcoind –follow

Check the status of the blockchain synchronisation:

bitcoin-cli -testnet -rpccookiefile=/blockchains/bitcoin/testnet3/.cookie getblockchaininfo

Bitcoind RPC

NBXplorer and any Lightning servers will need to connect to the bitcoind via its RPC interface. To use the interface either a username/password is required or alternatively bitcoind generates a cookie file with a random value that can be used. If the bitcoind data directory is left in its default location then NBXplorer and the Lightning servers should automatically find the cookie file. If the data directory is moved, for example to take advantage of a network drive then an extra configuration option will be required and the instructions in the relevant sections below show them.

The bitcoin-cli client also needs to be authenticated. To save some typing create a ~/.bitcoin directory, e.g. /home/admin/.bitcoin, and within it create a bitcoin.conf file along the lines of:



The second step is to install a Lightning node. For c-lightning the software must be built from source as per the instructions here. Once built lightning can also be configured to run as a systemd daemon.

  • sudo cp /usr/local/bin/lightningd /usr/local/bin/lightning-cli /usr/bin # The lightningd service file looks in /usr/bin.
  • The lightning programs rely on the bitcoin-cli client. There are a few different ways to configure bitcoin-cli authentication to the bitcoind RPC server. See the section “Bitcoind RPC” section above for one approach (note if the bitcoind data directory is left as default then the RPC authentication should just work),
  • Like bitcoind & bitcoin-cli the c-lightning application has lightningd & lightning-cli. Once the lightningd daemon is running RPC connectivity can be checked with lightning-cli getinfo .

To run lightningd as a service there is a systemd configuration template available here.

The basic /etc/lightningd/lightningd.conf that I use is:


If the lightningd service doesn’t start use:

sudo journalctl –unit lightningd –follow

Check the daemon with:

lightning-cli getinfo


The third step is to install NBXplorer. Its purpose is to monitor the Bitcoin blockchain so merchants know when they have received a payment. NBXplorer requires dotnet core.

  • git clone
  • ./
  • Configure the settings.conf file as shown below,
  • Check with: /usr/bin/dotnet “/home/admin/src/NBXplorer/NBXplorer/bin/Release/netcoreapp2.1/NBXplorer.dll” -testnet
  • Set up NBXplorer as a systemd service. This guide is a useful starting point.

NBXplorer config file in /home/admin/.nbxplorer/TestNet/settings.conf


My basic NBXplorer systemd service file:

Description=NBXplorer daemon

ExecStart=/usr/bin/dotnet "/home/admin/src/NBXplorer/NBXplorer/bin/Release/netcoreapp2.1/NBXplorer.dll" --network=testnet




The fourth step is to install BTCPayServer. This is the web application that will be used by the merchant for administering their stores, invoices etc.

  • git clone
  • ./
  • Configure the settings.conf file as shown below,
  • Check with: cd ~/src/btcpayserver/BTCPayServer; dotnet run –network=testnet –no-launch-profile
  • Set up BTCPayServer as a systemd service.

BtcPayServer config file in /home/admin/.btcpayserver/TestNet/settings.conf


My basic BTCPayServer systemd service file:

Description=BtcPayServer daemon

ExecStart=/usr/bin/dotnet "/home/admin/src/btcpayserver/BTCPayServer/bin/Release/netcoreapp2.1/BTCPayServer.dll" --testnet



There are two additional steps that the Luna Node wizard performs:

  • Installs Postgresql for use by NBXPlorer and BTCPayServer. By default SQLite is used which is a not ideal for production deployments,
  • Install NGinx with an auto-provisioned and auto-renewing TLS certificate from LetsEncrypt.

Accepting Payments

Once BTCPayServer is running there are still quite a few steps required before being able to accept payments:

  • A Bitcoin BIP32 wallet needs to be chosen and used to set the derivation scheme for a Store,
  • The lightning node connection string needs to be configured with the Store,
  • To test lightning payments a lightning wallet such as Zap or Spark needs to be installed and in some cases will require additional server components,
  • Lightning channels need to be connected and funded,
  • The merchant web site needs to integrate with BTCPayServer to automate invoices and checkout (see NBitPayClient for .Net sites).