Setting up BTCPay Server

Installing BTCPay WooCommere Plugin

While you’re on fire installing the plugins, let’s install the BTCPay plugin, which will allow us to connect our own Bitcoin Payment processing system on the VPS server and our Woocommerce store. The plugin is a “bridge” between the two.

For now, we will just install it.

At the time of writing, BTCPay Server has not been added to WordPress plugins repository, so we will need to install it manually. But do not worry, it’s easy enough.

UPDATE: BTCPay for WooCommerce is now added. You can install plugin directly from the  plugins > add new > btcpay for woocommerce.

First, we need to download the WooCommerce plugin from the GitHub.

Go to BTCPay WooCommerce plugin section, and click on the “Releases” tab.

Locate the latest release and download a woocommece.zip file by clicking on it.

In your WordPress dashboard, click “Plugins > Add new” and “Choose File.”

Select the downloaded file marked usually as btcpay-woocommerce.zip and upload it to the website.

Click “Install Now” to install the uploaded plugin.

Do not close the page, wait for few seconds and click “Activate plugin” once the installation is completed.

• 1. Hosted solution
• 2. Self-hosted solution

Connecting to a Third-Party Host

BTCPay Hosts are running their own BTCPay Server. In their settings, they enabled registration for other people. You’re never uploading your private key to hosts.

There are free third-party hosts and paid ones. In this step, I will show you how to connect to a free host. For the up to date list of BTCPay Server hosts, check this document.

The process of connecting to a host is similar for each of them. We have to register and pair the API keys with your WooCommece Store. I will be using BTCPay Jungle host in this example, but feel free to use any other you prefer. If you’re hosting BTCPay server yourself, you can show this guide to your friends so that they can connect to your node and receive payment to their Bitcoin wallet.

Registering with a third-party host

The first step is to register and enter the login credentials. Head over to BTCPay Jungle.

1. Click on “Register”
2. Enter your e-mail and password
3. Go to your e-mail inbox, and verify the e-mail address.

4. Log in to the host website

5. Click on the “Stores”

6. Click “Create new store”

7. Enter store name

8. Click “Create”

Pairing your store with a host

Now it’s time to pair your payment processor to your website. The BTCPay plugin we installed, is a bridge between your host and your store.

Go back to your store dashboard. WooCommerce > Settings > Payments. Click BTCPay.

1. In the field, enter the full URL of your host (including the https) – https://btcpayjungle.com
2. Click on the generated link which will redirect you back to your BTCPay host.

3. Click on request pairing
4. Approve the pairing

5. Copy the pairing code
6. Go back to your store and paste the pairing code
7. Click “Pair”
8. When you see the image, it means you successfully paired your host and your store

Installing BTCPay self-hosted Server

UPDATE. While this section is still valid, there’s now a much easier way to install BTCPay Server without ever using code. Please visit this article I wrote. and follow the video below.

You can still folllow the instructions below, since you will need to register and buy hosting with lunanode, but the deployment method is much easier and takes less than 2 minutes.

Having your payment processor server handled by a third party has its pros and cons. The cost reduction and fewer efforts are are the most notable advantages. Relying on someone else’s full node brings privacy and trust issues. Furthermore, the self-hosted BTCPay offers additional features (Lightning Network) that only work if you’re the server admin (owner).

Once you outgrow the third-party solution, you should consider running your BTCPy instance on a VPS, for the ultimate privacy, versatility, and trustlessness.

There are many ways in which you can run your own BTCPay. If you’re technically advanced user, you can look into software documentation and choose the method which suits your knowledge.

In this tutorial, we’re focused on ease of use and cost-effectiveness. For that reason, I decided to showcase you a method which is the cheapest. Even though it requires that you add a piece of code here and there, provided that you follow the instructions, you shouldn’t have any issues.

This part of the article is based on Nicolas Dorier article. I’ve decided to modify it slightly so that it fits the style of the entire tutorial.

BTCPay Server can be deployed and run Bitcoin and Lightning network on any Virtual Private Server which meets the minimal requirements :

1. 2048MB of RAM
2. 80GB of storage

The 80GB storage is enough if you use the pruned mode. If you want to accept other cryptocurrencies supported in BTCPay, go with a larger storage. For Bitcoin and Lightning Network, 80GB is enough.

Buying the VPS

In this tutorial, I wanted to use a VPS provider which accepts Bitcoin payments. While the list of such services is quite decent, it was a real challenge for the entire community to find an appropriate solution and find the right balance between the price and offered features. The choice came down to Canadian VPS provider – LunaNode.

LunaNode has a large number of plans. For our purpose, the ideal solution would be the c.1 plan, but its price is 20$/month.

To save a bit of money, we will go with the m.2 plan 7$/month and purchase additional storage space for $2.4. We also have to pay $3.5 as a one-time only for CPU points so that our node can sync. The total cost would be $9.4/month + $3.5 for the first month.

Creating an account

1. Click “Sign Up” and enter account information
2. Verify your email address
3. Click “Deposit Credit” to pre-fill your account
4. Choose a payment method and the amount and click “Add Credit” button.
5. Add your phone number and “Continue”
6. Verify your phone by entering 4 digit PIN you received via SMS.
7. Wait for your invoice confirmation (you will receive a confirmation e-mail)

1-CLICK BTCPay Server Deployment

From here there is no need to follow the rest of the guide on how to deploy btcpay. The video bellow will show you how to launch BTCPay Server in less than 2 minutes.

Creating the Virtual Machine

Wait for e-mail confirmation of your order. When you receive the confirmation email, click on the link. Log into LunaNode dashboard.

1. Click “Create VM” on the left-hand side menu.
2. Give your VM a name in the “hostname” field, for example – btcpay.
3. Click on the “Memory optimized” plans from the tabbed selection
4. Choose the m.2 plan
5. Scroll down, and in the “Image” section, select the operating system for your machine – Ubuntu 18.04 64-bit.
6. Create virtual machine.

Buying  additional volume

Now that we purchased our computer and installed an operating system on it, we must add a bit of storage. In laymen words, we’re plugging a 80 gigabyte USB stick into our PC.

Let’s go ahead and purchase additional storage for our virttual machine.

1. Go to “Volumes” in the dashboard.
2. Select volume location from the dropdown menu, add name and write 80 in the size field.
3. Create volume

Attaching a volume

We now created an 80GB storage, which we need to attach to our virtual machine.

1. In Volumes, scroll down to the “Volume List”
2. Find the volume you previosly created and click on to “Manage”
3. When the volume opens, choose “Attach to VM”
4. In the pop-up window, choose the virtual machine to which you want to attatch the volume.
5. Attach volume to VM

Enabling CPU usage

So far, we created our machine, installed an operating system on it, created a storage volume and attached a volume to it. Because this machine needs to sync with bloca kchain, it needs a little bit of extra power. Let’s enable additional CPU usage. If you’re using a better plan than the m.2, you probably won’t need extra settup like CPU or additional volume.

1. Virtual Machines > Find your machine > Manage.
2. Click on the “CPU” from the tabbed menu
3. From the first drop down menu “Pay for CPU utlization” – select YES.
4. Click Update.

DNS Settup

Now that we set up our Virtual Machine entirely, we need to configure our DNS. The setup will be similar t whatever host you’re using, but since our entire store setup is on SiteGround, I’ll show you on the SiteGround platform.

1. Log into your Sitegrond account.
2. From the upper menu, choose “My Account“
3. Click on go to C-panel.
4. DNS Zone Editor
5. Open a new tab in browser and go to LunaNode > Virtual Machine and select your VM.
6. In General tab of your virtual machine, copy the “External IP”
7. Go back to Siteground Simple DNS zone editor. In the add an a-record section, select the name and paste the external IP. If put the name to btcpay for example, sitegrund will immediatelly show you what will the the url location for your BTCPay Server. In my case, btcpay.wootoshi.com
8. Click “add an a-record“

Deploying BTCPay Server

Now that we have our virtual machine ready, it’s time to run software on it. That software is BTCPay combined with few more things. This part of the tutorial may seem like a rocket-science, but in essence, you will just be copy-pasting stuff into the terminal of your PC.

Firt, open a terminal if you are using Mac or Linux. For Windows users, download and install Putty (Direct Link).

To open a terminal on Mac, open > Applications folder, then > Utilities folder. Open the Terminal application. You can also tell Siri to do it for you “Siri, Terminal”.

We will be pasting a few pieces of code into the terminal. The chunks of code will be marked as gray boxes. Copy each of these boxes of codes into your terminal, one by one. You have to do modifications and add your domain name/email in the bolded pieces.

Copy-paste the code into terminal by making modification in clearly marked areas. It’s not as complicated as it may seem at first, do not be scared! 🙂

First, you need to log into the virtual machine from your PC. To do that copy the command below, and replace the bolded part with your own domain name. Ubuntu is a default username for all LunaNode users. You are replacing the domain you configured in Siteground. In my example it’s btcpay.wootoshi.com.

Replace the domain with your own and paste in your terminal. Hit enter.

ssh ubuntu@btcpay.wootoshi.com

Enter the password. The password for your virutal machine can be found in LunaNode dashboard. Virtual Machine > General Tab (where you copied the external IP earlier).
Paste the password (it won’t be visible in terminal). Hit enter.

Copy the following commands without making any changes

sudo su -

mkfs.ext4 /dev/vdc
mkdir /mnt/dockervolume
mount /dev/vdc /mnt/dockervolume
echo "/dev/vdc        /mnt/dockervolume        ext4   defaults        0 0" >> /etc/fstab

ln -s /mnt/dockervolume /var/lib/docker

apt-get update && apt-get install -y git

git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"

export BTCPAYGEN_LIGHTNING="lnd"

export ACME_CA_URI="https://acme-v01.api.letsencrypt.org/directory"
ssh-keygen -t rsa -f /root/.ssh/id_rsa_btcpay -q -P ""
echo "# Key used by BTCPay Server" >> /root/.ssh/authorized_keys
cat /root/.ssh/id_rsa_btcpay.pub >> /root/.ssh/authorized_keys
export BTCPAY_HOST_SSHKEYFILE=/root/.ssh/id_rsa_btcpay

Please replace the btcpay.wootoshi.com with your own name. Replace only the content inside the quotation mark, not the quotation marks. Copy – Paste.

export BTCPAY_HOST="btcpay.wootoshi.com"

Please replace the e-mail address with your e-mail. Replace only the content inside the quotation mark, not the quotation marks. Copy – Paste.

export LETSENCRYPT_EMAIL="youremail@example.com"

Copy-paste the following commands without making any changes. When you paste the last piece of code, wait for 5-6 minutes for everything to be installed.

export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s"

. ./btcpay-setup.sh

. ./btcpay-setup.sh -i

When everything is installed, you’ll be able to access your BTCPay Server page by entering domain name in your browser. In my example that’s btcpay.wootoshi.com

Connecting BTCPay with your wallet

The process of connecting a wallet and your BTCPay server is the same for both third-party or self-hosted solution. Your private keys are never uploaded nor required by the BTCPay Server. You’re only uploading the xpub key of your wallet.

BTCPay works with any wallet, but I strongly recommend Electrum, if you use software wallet and Ledger Nano S for a hardware wallet, since it’s integrated into BTCPay. Of course, you can use any other wallet which gives you the ability to access your public key -xpub.

Input your xpub, then on the second screen, if you see a wrong address, input the first address of your wallet so that BTCPay can help you to configure correctly.

There are two ways in which you can connect your BTCPay to your wallet:

1. Automatic with Ledger Nano S
2. Manual with any wallet supporting xpub (Electrum recommended)

Connecting your wallet with Ledger Nano S

Please make sure that you have Bitcoin app installed on your Nano S, and that you’re using Google Chrome as a browser.

1. Plug Nano S and enter Bitcoin App
2. Go to Store > Settings
3. Scroll down to Derivation Scheme, and click Modify next to the currency you wish to receive.
4. Ledger Nano S will be detected
5. Select your account
6. Derivation scheme will be added automatically
7. Select “Enable” checkbox at the bottom
8. Click “Confirm”
9. Compare the receiving addresses in your BTCPay and Ledger Nano S

Connecting your BTCPay manually

The second way, which probably most of you will use is to connect your wallet with BTCPay by using the manual method. The process is very similar to the one above, the only difference is – you have to set your derivation scheme yourself. In the previous step Nano S did it for you.

1. Go to Store > Settings
2. Scroll down to Derivation Scheme, and click Modify next to the currency you wish to receive.
3. You will see a notification that no Ledger has been detected.
4. Go to your wallet and copy xpub. In this example, in Electrum wallet, go to Electrum > Wallet Information > Public Master Seed
5. Copy the Public master seed
6. Paste the public master seed into BTCPay derivation scheme part
7. Set up the address type. The Electrum will show your address type in Electrum > Wallet Information
8. Select “Enable” checkbox at the bottom
9. Click “Confirm”
10. Compare the receiving addresses in your BTCPay and your wallet

Testing BTCPay Checkout

Before going live, it’s crucial that you test out your store. In this step, you need to put yourself in the customers’ shoes and see if everything works in your store as expected.

Watch the video below to see how you can set up the Electrum Gap limit and then the checkout process.

• Go ahead, add the item to cart.
• Checkout and fill in the required information
• Select Pay with Bitcoin
• Pay the order from your Bitcoin wallet
• Check if the order appears in your WooCommerce under WooCommerce > Orders.
• Check if the test payment appears in your Bitcoin wallet, Electrum for example
• Go to your BTCPay (self-hosted or third party, and check if the invoice is visible in > Invoices.
• Go to your BTCPay Internal Wallet and check if the transaction is there. > Wallet

You can create a low-valued item for the testing purpose.

PreviousNext Step