Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This guide will cover, in order:
Selecting the right hosting method for your needs and skills
Managing admin access to your store
Creating your store within BTCPay Server
Setting up and managing your Bitcoin wallet for receiving payments
Adding the Lightning payment option to your store
Setting currency and rate provider
Setting up your Point of Sale app
Additional configurations
By the end of this guide, you will be able to receive payments in bitcoin for products and services both online and in-person using BTCPay Server.
This option avoids deploying or building your own node and greatly accelerates and simplifies the process of getting your own BTCPay Server up and running.
You avoid the time it takes for your server to be fully synced, you do not need any technical know-how and you do not need to deal with maintenance.
If this is an option you'd like to use, please contact us so that we can get you onboarded. You can refer to the rest of this guide in order to know how to connect your wallet and customize your shop.
Note that enabling Lightning payments is a custodial service. You will need to contact your account manager in order to withdraw funds accrued from Lighting payments. On the other hand, accepting on-chain Bitcoin payments remains entirely self-custodial.
Once your BTCPay Server deployed, you must register for an account to begin using it.
The first created account on a newly-deployed BTCPay Server is named admin
automatically.
To register, visit your BTCPay Server URL and fill in the account registration form on the right.
Input your password, password confirmation, e-mail and click Register
.
BTCPay Server is a free and open-source, self-hosted Bitcoin payment processor. There are no third parties and zero additional fees for accepting payments. It allows for small and large merchants alike to accept payments in a secure and censorship-resistant manner, using either Bitcoin on-chain or the Lightning Network.
You can launch your own server in the cloud, use your own hardware to host it or use an existing hosting service.
You can use BTCPay Server in combination with all major Bitcoin wallets to receive your payments directly to them.
✅ Free and Open-Source
✅ No middlemen and no fees for accepting Bitcoin payments
✅ Customizable shop and checkout experience
✅ Integrations with other major online ecommerce platforms
✅ Takes care of payment refunding and bitcoin management
❌ Can require some technical knowledge for setting up
Selling your products and service online or in person in exchange for bitcoin.
Tracking and accounting bitcoin payments received in exchange for goods and services.
Avoid manually creating bitcoin invoices for your goods and services.
Avoid censorship from traditional fiat payment processors or limited access to their services.
Avoid paying high fees to traditional payment processors or similar Bitcoin service providers.
There are several options which enable you to host BTCPay Server on your own hardware device. You can either build the device yourself or purchase it pre-assembled.
Once the hardware in hand, you can then select the service (some offer free versions) you'd like to use to download and manage your node:
Build or buy any one of the above nodes to begin using BTCPay Server on your self-hosted device.
BTCPay Server also provides instructions for setting up your self-hosted server from scratch, but this method is much more technically advanced. Find it here.
Create an account here.
Click “Deposit Credit” to pre-fill your account.
The best plan to chose is m.2 under "Memory Optimized".
Choose a payment method and the amount and click Add Credit
button.
Add your phone number and Continue
.
Verify your phone by entering the 4 digit PIN you received via SMS.
Wait for your invoice confirmation (you will receive a confirmation e-mail).
Click “Create VM” on the left-hand side menu.
Give your VM a name in the hostname
field, for example – btcpay.
Click on the Memory optimized
plans from the tabbed selection
Choose the m.2
plan.
Scroll down, and in the Image
section, select the operating system for your machine – Ubuntu 18.04 64-bit.
Create virtual machine.
Go to Volumes
in the dashboard.
Select volume location
from the dropdown menu, add name and write 80 in the size field.
Create volume.
In Volumes
, scroll down to the Volume List
.
Find the volume you previosly created and click on to “Manage”.
When the volume opens, choose Attach to VM
.
In the pop-up window, choose the virtual machine to which you want to attach the volume.
Attach volume to VM.
We need to enable additional CPU usage so that our node can properly sync Bitcoin's blockchain. If you select a better plan than m.2, this might not be necessary.
Virtual Machines > Find your machine > Manage
.
Click on the CPU
from the tabbed menu.
From the first drop down menu Pay for CPU utilization
– select YES
.
Click Update
.
Go to the API section and create a new API.
Do not close that page and proceed to the next step.
Paste the API Key and API ID created in the previous section and continue.
Use your own domain or an automatically-generated one by LunaNode.
Customize the web-wizard settings according to your needs.
Click Launch VM
.
Wait 6-7 minutes for Virtual Machine deployment.
If you've used a custom domain:
SSH into the VM using either the password generated by LunaNode or your private-public key pair.
Run the following commands:
Visit the domain, create an account and log in.
Now you need to wait for the blockchain to sync fully. With CPU utilization enabled, with Bitcoin and LND, it will take 1-2 days.
The sync pop-up window will disappear when your node fully syncs.
There are multiple options for hosting your BTCPay Server solution depending on your level of technical knowledge, the needs you're looking to fulfill and the cost your willing to pay.
This guide will cover LunaNode and third-party hosting through Bull Bitcoin. You will be provided with the resources in order to also use hardware solutions. To learn more about the other options, go here.
LunaNode is a Canadian-based hosting provider that accepts Bitcoin payments and requires no personal identification except for a phone number verification.
This method is highly recommended if you don't have a lot of technical knowledge.
You will be able to use all of BTCPay Server's features, including the Lightning Network payment option by hosting a Bitcoin node through their service.
Bull Bitcoin has a BTCPay Server hosting solution which allows you to avoid deploying your own self-hosted BTCPay Server and managing it.
You still receive payments directly to your wallet. We never ask for your Bitcoin private key to do so.
BTCPay Server does not allow server hosts to view the stores of other users nor have access to any personal data (except for a registration email address). The extended public key and even balances of other users can't be seen.
All payments made through the Lightning Network will go to your third-party's wallet. Take precautions and only use this option while using a trustworthy third-party host to ensure you get your funds back.
You also have the option of building your own node using hardware that you purchase.
Method | Difficulty | All features available? | Approx. Monthly Cost |
---|---|---|---|
LunaNode
Yes
$10
Third-party host
Host: Yes Hostee: No
Free or Paid
Hardware & Cloud as a Service
Yes
Varies on provider
Virtual Private Network
Yes
$10-$70
Manual deployment
Yes
Components + Electricity
Hardware Build
Yes
Components + Electricity
When using your own hosting solution, you can create an unlimited number of stores, with each one connected to a wallet.
They can also each have apps, like Point of Sale, Payment Buttons and Crowdfunding, or be tied to an external e-commerce software.
Make sure that you are first logged into your account. Then go to:
Stores;
Click on Create a New Store
;
Enter the store name;
Click on Create
.
Once logged in go to:
Store;
Click on Settings
.
There, you can modify the confirmations, invoice expiry, and more.
There are two ways to set up a wallet in BTCPay Server:
Connect an existing wallet.
Create a new wallet.
There are several options on how to set up a wallet to use with your BTCPay Store. Below you will see instructions on how to set up BlueWallet, Wasabi Wallet, and Coldcard.
On the Sidebar menu, click on Payment Methods
.
Click on Setup
next to BTC.
Click on Connect an Existing Wallet
.
Click on Scan wallet QR code
In BlueWallet:
Open Wallet Settings;
Click on Show Wallet XPUB
;
Scan the Blue Wallet QR Code on BTCPay Server.
Click on Import wallet file
;
In Wasabi:
Click on Tools
;
Select Wallet Manager
;
Click on Open Wallets Folder
;
Import the file on BTCPay Server.
Click on Import wallet file;
In your Coldcard:
Insert a microSD card in your Coldcard;
Unlock your Coldcard;
Go to Advanced ❯ MicroSD Card ❯ Export Wallet ❯ Electrum Wallet
Import the file on BTCPay Server.
You can easily connect BTCPay to your online store. Currently, BTCPay offers the following integrations (click on the platform you are using to obtain instructions):
Install the Vault on your PC (Windows, MacOS or Linux).
Open the BTCPay Vault app.
Plug in the hardware wallet into your PC and make sure it’s in a wake up state.
Go to your BTCPay Server’s Store > Settings > Wallet > Setup >
Import from a hardware wallet
.
Grant the permission.
The public key will automatically be imported in the store and configured to an appropriate format.
Validate that the address shown on BTCPay is the same as the one on your device.
Click Save
.
Once you’ve received funds to your wallet and you decide to spend them, you can sign the transaction with your hardware wallet, all inside BTCPay Server.
Open BTCPay Vault app on your PC.
Plug in the hardware wallet and make sure it’s in a wake up state.
In BTCPay Server, go to Wallets > Manage > Send
.
Fill in the Destination address
and the Amount
.
Select Sign with a hardware wallet
.
Verify the transaction on your hardware wallet and confirm it.
Broadcast the transaction.
To refund an invoice, go in the Invoices
page and click Details
on the invoice.
Click Issue a refund
.
Select refund's payment method.
Select the amount
you want to refund.
Share the link of this page with your customer.
Once a customer clicks on the link you've provided and adds their refund Bitcoin address and claims the invoice, the next step is to process a refund.
Go to the Payouts
tab in your sidebar.
Select the Payouts you want to process, go to actions and select Approve and send
.
Sign and broadcast the transactions.
The payout has now been signed and is in progress, awaiting confirmation on the blockchain. This is reflected to the claimant in their display.
After the transaction has been confirmed on the blockchain, the status of the payout will be completed
.
BTCPay Server offers several tools that make bookkeeping easier.
To export the invoices:
Go to Invoices
.
Click on Export invoices
.
Select the export format (CSV/JSON) and download the file.
You can then customize the fields to fit your business needs and import the data into your accounting software, or create pivot tables from the exported data.
The fields are the following:
Field name | Description |
---|
BTCQBO is a third-party plugin that enables QuickBooks Online users to connect their BTCPay Server easily. Besides bookkeeping, users can quickly generate invoices from their QuickBooks. For more information about the BTCQBO and all the features it offers, .
ReceivedDate | Date the payment has been received |
StoreId | The store receiving the payment |
OrderId | The order Id of the invoice |
InvoiceId | The invoice ID |
InvoiceCreatedDate | Date of creation of the invoice |
InvoiceExpirationDate | Date of expiration of the invoice |
InvoiceMonitoringDate | Date your BTCPay Server ceases to monitor events of the invoice |
PaymentId | Unique identifier of a payment |
Destination | The destination address the customer paid to |
PaymentType | The type of payment ( |
CryptoCode | Currency code of the method of payment (e.g. |
Paid | Amount paid in the currency defined in CryptoCode |
NetworkFee |
ConvertionRate | The conversion rate at the time of invoice creation between |
InvoiceCurrency | The currency code of the invoice (e.g. |
InvoiceDue | The amount still due to fully pay the invoice after this payment (minus |
InvoicePrice | The total price of the invoice (minus Network Fee, denominated in |
InvoiceItemCode | The item code afferent to the products/services billed by the invoice |
InvoiceItemDesc | The item description afferent to the products/services billed by the invoice |
InvoiceFullStatus | The full status of the invoice (e.g. |
InvoiceStatus | The simplified status of the invoice (e.g. |
InvoiceException | The status of the invoice (e.g. |
paid by the user in this payment
Below are the most common use-cases for BTCPay Server:
Merchants who sell products and services online or in-person.
Self-sovereign individuals wanting to protect their wealth and manage their funds and full Bitcoin node.
Charities and non-profits looking to accept donations or crowdfund their dream project.
Developers building on top of Bitcoin and bleeding-edge payment infrastructure.
Members of local communities willing to onboard people to their BTCPay instance and offer payment processing as a service or for free, creating a circular economy.
Exchanges offering instant conversions for the users of BTCPay Server.
Hosting providers offering BTCPay as a cloud service or ready-to-use hardware.
Allows users with brick and mortar stores to readily accept bitcoin without fees or a third-party, directly to their wallet. The PoS can be displayed easily on tablets or any other devices which support web browsing. Users can easily create a homescreen shortcut for a quick access to the web-app.
Adding new products is easy. The app has a shopping cart feature, tips, product inventory, custom payment options, and more.
The Point of sale app can also be used to receive donations, tips or even as a small e-commerce shop, depending on the options or customizations applied.
Currently, the Point of Sale app supports three different views:
A Static
view representing only the items for sale.
A Cart
view including items for sale and a cart for checkout.
A Light
view consisting only of a keypad for easy and quick payments.
To get your first Point of Sale app running, follow these few simple steps:
Go to Apps
and Create a new app
.
Add a name
for your app.
Choose app type > Point Of Sale
.
Select the store
to associate with the app.
Click on Settings
to modify the elements in the store.
Customize your PoS by choosing a view
(Static, Cart, Light), adding your own items
with prices, photos, and a description.
Click Save Settings
.
Click View App
to view your PoS (Your customers can access the PoS through that link).
You can change the appearance of your Point of Sale app by following the theme customization guide.
Crowdfunding is an application which you can launch from BTCPay Server interface that allows you to create a self-hosted funding campaign, similar to Kickstarter or Indiegogo. Unlike traditional crowdfunding platforms, the creator of the campaign is the owner of the platform. Funds go directly to the creator’s wallet without any fees.
Go to Apps
.
Add a name for your app.
Choose app type : Crowdfund
.
Select the store to associate with the app.
Customize your Crowdfund by adding your own perks with prices, photos, and description.
Check the box Allow crowdfund to be publicly visible
.
Click Save Settings
.
Click View App
to view your Crowdfund (Contributors can access the crowdfund through that link).
This app allows you to embed a payment button to receive tips and donations.
Steps:
In your left menu bar, find Payments and click Pay Button
.
Allow anyone to create invoices.
Customize your button.
Copy the generated form and embed it on your website.
On the Sidebar menu, click on Payment Methods
.
Click on Setup
next to BTC
, under Lightning
.
Click on Use internal node
, then click on Save
.
Go back to the Payment Methods
page and click on Settings
on the Lightning box.
Toggle on Enable LNURL
, LNURL Classic Mode
and LNURL enabled for standard invoices
.
Click on Save
.
Your Lightning wallet is enabled!
Ask your account manager to activate the Lightning option if you are using the Bull Bitcoin hosting service.
Payment Requests are a feature which allows BTCPay store owners to create long-lived invoices. Funds paid to a payment request use the exchange rate at the time of payment. This allows users to make payments at their convenience without having to negotiate or verify exchange rates with the store owner at the time of payment.
Users can pay requests in partial payments. The payment request will remain valid until it is paid in full or if the store owner requires an expiration time. Addresses are never reused.
A new address is generated each time the user clicks pay to create an invoice for the payment request.
Store owners can also print payment requests (or export invoice data) for record keeping and accounting. BTCPay automatically labels invoices as Payment Requests in your store's invoice list.
Click Payment Requests > Create new payment request
.
Provide the Request Name, Amount, Display Denomination, Associated Store, Expiration Time & Description (Optional).
Select the option Allow payee to create invoices in their own denomination if you want to allow partial payments to be made.
Payment requests are store-dependent, which means that each payment request is associated with a store during creation. Be sure to have a wallet connected to your store which the payment request belongs to.
Click Save & View
to review your payment request.
BTCPay creates a URL for the payment request. Share this URL to view your payment request.
The status will appear as Settled
if the payment has been received in full. If only a partial payment was made, the Amount Due
will show the balance due.
Invoice Amount - Set Requested Payment Amount
Denomination - Show Requested Amount in Fiat or Cryptocurrency
Payment Quantity - Allow only single payments or partial payments
Expiration Time - Allow payments until a date or without expiry
Description - Text Editor, Data Tables, Embed Photos & Videos
Appearance - Color and Style with CSS Themes
In order to be able to receive payments over the Lightning Network, you must have inbound liquidity to your node. To do this, you can either add Bitcoin to your Lightning wallet and open a channel with other Lightning Network nodes, or you can use a service provider that will grant you inbound liquidity for a small fee.
Get your node information so that the service provider knows with whom to open a channel with. To do this, go to:
Store
> Settings
> Modify
.
Click on Open Public Node Info Page
.
Copy the public node information.
Use one of the following Inbound liquidity service providers:
Thor by Bitrefill
Y'alls by Alex Bosworth
Amboss Space by Zero Fee Routing
Select the channel capacity you want to have.
Pay the invoice using Lightning.
Enter your node information (copied in step 3).
Confirm purchase.
The instructions are slightly different for users running an Umbrel node. Please refer to this post to know how to proceed.
Log into your BTC Pay Server account.
Select Server Settings
from the top menu.
Select Services
from the left-hand menu.
Select Ride the Lightning Server.
To access it on your desktop, just click on the link.
To access it on another device, click on Show confidential QR code
and scan it with your other device.
Select Lightning
and then Transactions
.
Click on Payments
if you want to withdraw funds. You must create an invoice in your other Lightning wallet (like Blue Wallet or Breez) and paste the invoice in your Dashboard after clicking on Send Payment
.
Click on Invoices
to see the transactions that you have received.
Ask your account manager to activate the Lightning option if you are using the Bull Bitcoin hosting service.
There are two options to withdraw bitcoins that will be presented. There are multiple other ways, but they are significantly more complicated.
On bullbitcoin.com , you can sell your bitcoins using the Lightning network and receive fiat in any Canadian bank account, or pay a bill on the same or next business day.
Just click on the Sell Bitcoin
button on the left-hand menu, and select the Lightning Network
as your payment network. Copy the payment invoice and paste it into your Ride the Lightning (RTL) Wallet payment section.
Under Lightning
, click on Transactions
.
Under Payments
, click on Send Payment
(you don’t need to touch the Advanced Options).
Enter the Payment Request and click Send Payment.
Once you created a Lightning wallet in BlueWallet, create an invoice to paste into RTL by clicking on Receive
(as in the instructions described above).
Once you have funds in your Lightning wallet, click on Manage Funds
(in the Lightning wallet).
Now click on Exchange
. This will open up a website where you can send Bitcoin on the Lightning Network and they will send you an equivalent minus fees to a Bitcoin address that you provide.
Once you created a Lightning wallet in Breez Wallet, create an Invoice to paste into RTL by clicking on Receive
(as in the instructions described above).
They will charge a small processing fee that is only applicable to the first transaction.
Now that you have bitcoins in your Lightning wallet, click on Send
.
Select Send to BTC address
.
Enter your address and confirm the transaction.
They have a system where it looks like they treat on-chain BTC and Lightning BTC as if they were the same, but there is a swap going on behind the scenes.
If you are using the Bull Bitcoin hosting service, please contact your account manager to withdraw funds.
It's recommended that server admins configure SMTP settings. Email setup enables easier password reset for the instance users in case of forgotten credentials.
To allow other users to access your server, you need to enable registration in Server Settings > Policies
.
If you are using the Bull Bitcoin hosting solution, contact your account manager to change your password.
For further enhancement of security and protection of your account, it's recommended to enable two-factor authentication (both 2FA and U2F are supported). To enable 2FA or U2F, click on the user settings icon in the header menu.
If you are using the Bull Bitcoin hosting solution, contact your account manager to activate 2FA.
Click on the Rates
page, on the sidebar menu.
Select Bylls, or any other, as your preferred rate provider.
At the bottom of the page, enter the currency pair you wish to use on the Default currency pairs
field. Click on Save
.
Enter 1
on the field named Add a spread on exchange rate of ... %.