How to Setup BTC and Lightning Payment Gateway with BTCPayServer on Linux [Manual Install]

Photo by BTCPay

One of the largest Bitcoin payment providers BitPay has been under the fire from Bitcoiners for quite a while.

The community called for a boycott which was smartly used by a developer Nicolas Dorier to his advantage.

Nicolas has created an open-source and self-hosted BitPay-compatible payment gateway called BTCPayServer which has been well received by the community.

While there are many guides on how to set it up using Docker and other methods, I like to have control over what I install on my server while also learning how it works.

If you for whatever reason prefer a manual installation of BTCPayServer, I wrote a step-by-step guide on how to do that.

This tutorial is written for Ubuntu 18.04 but should work on older versions and other Debian-based distributions too.

Before you start, make sure you have Bitcoin Core and Lightning Network node running.

Install Dependencies

To run the BTCPayServer you will need to install .NET Core SDK, NBXplorer and PostgreSQL.

Install .NET Core SDK

Go to your Downloads folder or any other folder that you use to store temporary files:

cd ~/Downloads

and download Microsoft Packages necessary for the .NET Core SDK:

wget -qO- | gpg --dearmor > microsoft.asc.gpg
sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/
wget -q$(lsb_release -sr)/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list

Update the package cache and install the .NET Core:

sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.1

Install NBXplorer

We'll need to install NBXplorer In order to track incoming on-chain transactions.

Create the source folder if you haven't already and open it:

mkdir ~/source
cd ~/source

Clone the repository and build the code:

git clone
cd NBXplorer

Create the data folder:

mkdir -p ~/.nbxplorer/Main
cd ~/.nbxplorer/Main

and a new config file:

touch settings.config

Open the file with the editor of your choice and add the following lines:

btc.rpc.auth=<bitcoind rpc user>:<bitcoind rpc password>

Make sure to use your bitcoind's rpc login credentials. You can find them with the command:

cat ~/.bitcoin/bitcoin.conf | grep rpc

Test if everything is set up correctly:

/usr/bin/dotnet ~/source/NBXplorer/NBXplorer/bin/Release/netcoreapp2.1/NBXplorer.dll -c ~/.nbxplorer/Main/settings.config

If so, hit the ctrl+c to kill the process and download the Systemd service:

cd /usr/lib/systemd/system
sudo wget

Edit the file according to your environment.

Enable the service, start it and check the status:

sudo systemctl enable nbxplorer.service
sudo service nbxplorer start
sudo service nbxplorer status

If you see no errors go to the next step.

Install PostgreSQL

I wasn't able to set up BTCPayServer with MySQL/MariaDB so I was forced to use PostgreSQL.

Install it first and open a shell prompt as a newly created system user:

sudo apt install postgresql postgresql-contrib
sudo -i -u postgres

Create a new database user:

createuser --pwprompt --interactive

Type in the following (you can change satoshi, to any username you like):

Create a new database user and set roles

Create a new database:

createdb -O satoshi btcpayserver

If you see no errors exit the shell:


Install BTCPayServer

Clone the repository and build the code:

cd ~/source
git clone
cd btcpayserver

Create the data folder:

mkdir -p ~/.btcpayserver/Main
cd ~/.btcpayserver/Main

and a new config file:

touch settings.config

Get the LND's certificate fingerprint and paste it into the below config file.

openssl x509 -noout -fingerprint -sha256 -inform pem -in ~/.lnd/tls.cert

Open settings.config and add the following lines:

BTC.lightning=type=lnd-rest;server=;macaroonfilepath=~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon;certthumbprint=<finger print>
postgres=User ID=<your db user>;Password=<your db password>;Host=localhost;Port=5432;Database=btcpayserver;

Change the highlighted "variables" according to your settings.

Check if everything is working correctly.

/usr/bin/dotnet run -p ~i/source/btcpayserver/BTCPayServer/BTCPayServer.csproj -c ~/.btcpayserver/Main/settings.config --network=mainnet

If so, hit ctrl+c to kill the process and download the Systemd service:

cd /usr/lib/systemd/system
sudo wget

Edit the file based on your environment.

Enable the service, start it and check whether it's running correctly:

sudo systemctl enable btcpayserver.service
sudo service btcpayserver start
sudo service btcpayserver status

Congrats, you just got past the hardest part!

Allow incoming connections (optional)

If you want to run your server remotely, you will have to open a port 23001.

First, go to your router settings and find a section along the lines of "Virtual Server" or "Port Forwarding" and set up a port forwarding on the above-mentioned port.

Then go back to your linux machine and open the port with iptables:

sudo iptables -A INPUT -p tcp --dport 23001 -j ACCEPT

If you use iptables-save run the following too:

sudo iptables-save > /etc/iptables/rules.v4

You should be now able to connect to your server from a different machine.

Setup BTCPayServer

Go to your BTCPayServer administration, Register a new admin account and login.

Now, go to Stores and click Create a new store. When done go to the store settings and scroll down to Derivation Scheme.

Set up your on-chain wallet

Under the "BTC" click Modify and on your computer/phone open a wallet that supports BIP32.

For the purpose of the tutorial, I will use Electrum.

It's recommended to create a fresh wallet instead of using an old one so you don't have to bother rescanning balances on your addresses.

When finished, click Wallet -> Information, copy the Master Public Key, paste it back to BTCPayServer administration, check Enabled, and save it.

Add a master public key of your BIP32-compatible wallet

Next, scroll down to Lightning nodes (Experimental) and click Modify.

Set up your Lightning Network node

Your Connection string should be set up but if not, paste in the following:

type=lnd-rest;server=;macaroonfilepath=/home/satoshi/.lnd/data/chain/bitcoin/mainnet/admin.macaroon;certthumbprint=<your cert fingerprint>

Remember to add your LND's certificate fingerprint that you've got earlier and change the home directory to your own one.

Your Lightning Network node configuration

Click Test connection and if everything's ok check Enabled and click Submit.

In the case, the server runs on a separate machine that you want to access via a domain name, go to Server Settings -> Maintenance, and in the section Change domain name add your name (you will, of course, have to buy it first).

Add your own domain name

You will also have to add a CNAME or A DNS record with your domain name provider depending on your setup. Sorry, I can't help you on that one, there are too many providers.

Now you should be able to access your BTCPayServer administration with the new domain name like so:

To create a POS terminal, go to Apps -> Create a new app and fill out the short form. You will then be taken to the app settings where you can change the list of items via a template.

An example Point-of-sale tea store

You can also add a simple Pay button to your website that you can configure in Stores -> Settings -> Pay Button as well as create an invoice manually in Stores -> Invoices -> Create a new invoice. that you can then send to a customer.

BTCPay's payment gateway supporting BTC both on-chain and via Lightning Network

Of course, the front-end design of the payment gate is fully customizable so you can set your own logo and colors.

Setup SSL certificate from Let's Encrypt (Optional)

First lets install Apache 2 that will be uses as a reversed proxy.

sudo apt-get install apache2

Enable required modules:

sudo a2enmod rewrite
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_ajp
sudo a2enmod deflate
sudo a2enmod headers
sudo a2enmod proxy_balancer
sudo a2enmod proxy_connect
sudo a2enmod proxy_html

Restart the server:

sudo systemctl restart apache2

Install Let's Encrypt certificate for your domain name. But you can use any other certification authority.

Replace the content of /etc/apache2/sites-enabled/000-default.conf with the following:

<VirtualHost *:80>
ServerAdmin webmaster@localhost
RewriteEngine on
RewriteCond %{SERVER_NAME}
        RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined

Change ServerName based on your needs.

Then, replace the content of /etc/apache2/sites-enabled/000-default-le-ssl.conf with the following:

<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin webmaster@localhost
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
ProxyPass "/"  ""
ProxyPassReverse / ""
ProxyPreserveHost On
SSLCertificateFile /etc/letsencrypt/live/
SSLCertificateKeyFile /etc/letsencrypt/live/
Include /etc/letsencrypt/options-ssl-apache.conf

Again, edit ServerName and make sure SSLCertificateFile and SSLCertificateKeyFile point to right files.

Reload the server:

sudo systemctl reload apache2

Now go back to ~/.btcpayserver/Main/settings.config and add:


Once again, change the server name to your own one.

You can also remove bind= from the configuration because the remote connection will be proxied through Apache from now.

Restart BTCPayServer:

sudo service btcpayserver restart

Open your browser and check if your newly installed SSL certificate works correctly.


I hope you find this tutorial helpful. If you run into any issues let me know in the comments section below.

Feel free to share your online stores running BTCPayServer in the comments too.

P.S. If you appreciate Nicolas' work please support him on his Donation page.

We hope you like the post. Please share it with your followers. Thank you for your support!

Subscribe to our newsletter for weekly thoughts and tutorials. You'll receive a FREE e-book as a bonus!

What do you think?

Are you tired of political parasites getting in your way of life?

If yes, let us help you out with our EXCLUSIVE newsletter.


Hide your financial assets with Bitcoin and other cryptocurrencies.

Make your communication private using open-source cryptographic tools.

Mitigate the risk of single point of failure in anything you do with decentralized technologies.

Are you intersted? Then become our subscriber, receive exclusive content straight to your inbox + claim your FREE e-book!

* required


Freedom Node is the edge every crypto enthusiast needs to get ahead in this industry. Click that sleek button to learn more about exactly​ what it is we offer.

Learn More


Your email address is safe with us. We promise!

* required