btcpayserver / btcpayserver-doc

BTCPay Server Official Documentation

BTCPay Server

Accept Bitcoin payments ₿

BTCPay Server is a free and open-source Bitcoin payment processor which allows you to accept bitcoin without fees or intermediaries.

Website | Documentation | API | Contribute | YouTube | Chat

_{"This is lies, my trust in you is broken, I will make you obsolete" 💚}

View Demo · Report a bug · Request a feature · FAQ

💼 Table of Contents

• Features
• Getting Started
• Documentation
• Contributing
• Developing
  • API
• Community
• License
• Supporters

🎨 Features

• Direct, peer-to-peer Bitcoin payments
• No transaction fees (other than the network fee)
• No fees, middleman or KYC
• Non-custodial (complete control over the private key)
• Enhanced privacy & security
• Self-hosted
• SegWit support
• Lightning Network support (LND, Core Lightning (CLN), Eclair)
• Tor support
• Share your instance with friends (multi-tenant)
• Invoice management and Payment requests
• Apps: Point of sale, crowdfunding, donation button
• Full-node reliant wallet with hardware wallet integration and SegWit support
• Bitcoin-only build, separate community-maintained altcoin build (supported altcoins)

🚀 Getting Started

Firstly, decide if you want to host an instance yourself or use a third-party host. If you've chosen to self-host, there are plenty of documented ways to deploy BTCPay Server.

After successful deployment, make sure to check our getting started and walkthrough guides. In case you would like to use Lightning Network, see Lightning guide.

📗 Documentation

Please check out our official website, complete documentation and FAQ for more details.

If you have trouble using BTCPay Server, consider joining communities listed on the official website to get help from other contributors. Only create a GitHub issue for technical issues you can't resolve through other channels or feature requests you've validated with other members of the community.

🤝 Contributing

BTCPay Server is built and maintained entirely by volunteer contributors around the internet. We welcome and appreciate new contributions.

If you're a developer looking to help, but you're not sure where to begin, check the good first issue label, which contains small pieces of work that have been specifically flagged as being friendly to new contributors.

Contributors looking to do something a bit more challenging, before opening a pull request, please join our community chat or start a GitHub discussion to get early feedback, discuss the best ways to tackle the problem, and ensure there is no work duplication.

There are many other ways to get involved with the project. Check our contribution guidelines. To get the big-picture of the project development, visit our evolving roadmap.

🧑‍💻 Developing

To begin developing locally, visit our local development guide. There are also several video-tutorials:

• Setting up development environment on Windows
• Setting up development environment Linux (Ubuntu)
• Setting up development environment MacOS

How to build

While the documentation advises using docker-compose, you may want to build BTCPay Server yourself.

First, install .NET SDK v8.0 as specified by the Microsoft website.

On Powershell:

.\build.ps1

On linux:

./build.sh

How to run

Use the run scripts to run BTCPay Server, this example shows how to print the available command-line arguments of BTCPay Server.

On Powershell:

.\run.ps1 --help

On linux:

./run.sh --help

How to debug

If you want to debug, use Jetbrain's Rider or Visual Studio 2022.

You need to run the development time docker-compose as described in the test guide.

You can then run the debugger by using the Launch Profile Docker-Regtest.

If you need to debug ledger wallet interaction, install the development time certificate with:

# Install development time certificate in the trust store
dotnet dev-certs https --trust

Then use the Docker-Regtest-https debug profile.

Other dependencies

For more information, see the documentation: How to deploy a BTCPay Server instance.

🧪 API

BTCPay Server has two APIs:

• Greenfield API (New)
  • Greenfield API documentation
  • Greenfield API examples with CURL
• Legacy API

The Greenfield API is our brand-new API which is still in development. Once complete, it will allow you to run BTCPay Server headlessly. The Legacy API, is fully compatible with BitPay's API. It has limited features, but allows instant migration from BitPay.

💚 Community

Our community is the ❤️ of the project. To chat with other community members in real-time, join our Mattermost chat. We're also on GitHub discussions.

📝 License

BTCPay Server software, logo and designs are provided under MIT License.

🙏 Supporters

The BTCPay Server Project is proudly supported by these entities through the BTCPay Server Foundation.

If you'd like to support the project, please visit the donation page.

btcpayserver-doc's Issues

Re-structure Documentation Repository

Documentation needs to be categorized and put in folders for it to appear in a structured way on GitBook. This can mess the structure of the links/images, but it's a necessary step toward better-organized resources. This change will be applied when the new user influx calms down, as we don't want to break links for the new users possibly.

While folders are no longer a necessity, we still need a structure for #51

Proposed Structure

Introduction

• What it is
• Why it exists
• How it works
  • In a nutshell
  • How is it different
  • How it keeps funds secure
  • How it keeps data private
  • How it resists censorship

Getting Started

• README.md
• GettingStarted.md
• UseCases.md (#45)
• TryitOut.md
• LightningNetwork.md (we need to determine where to put this one)

Deployment

• Web-Deployment
  • LunaNodeWebDeployment.md
• Azure Deployment
  • AzureDeployment.md
  • Pennypitching.md
  • ChangeDomain.md
• DockerDeployment.md
• Manual Setup (ManualDeployment.md)
• Third-Party Hosting

Integrations

• WooCommerce
  • WooCommerce.md
  • Xadrez.md (needs to be re-configured)
• Drupal.md
• Magento.md ( #47 )
• CustomIntegration.md

Development

• Architecture.md
• LocalDevelopment.md
• Altcoins.md

Support and Community

• FAQ.md
• Community.md

Contribute

• Readme.md (contribute.md) (#49 )
• Translation.md (#49 )

The proposed structure is just a start and tries to use already created documentation.

Feel free to make suggestions and kudos to @BobleChinois for helping out with the structure.

How to create Bitcoin PoS

Video that explains how to create and customize PoS app in BTCPay.

Cryptocurrency Payment Processors - Comparison

I remember @NicolasDorier had an idea of having a chart comparing different payment processors to BTCPay.

I think it can be really helpful to have such a document for the upcoming users. The biggest problem is figuring out what to compare and what features to include.

If anyone has an idea or wants to tackle this, feel free to comment.

Launched on LunaNode, lightning isn't working

Troubleshooting.md

It's obvious that in order to solve the issue for the users, we need to educate them towards steps they need to do in order to troubleshoot their instance.

There are people who don't know how to SSH login and find logs, so we need to cover that.

I was thinking that we need to create a document that will guide the user step by step on how to properly define the issue, try to solve it and if that fails, how to ask for help and where.

This should include an explanation on how to pull the logs from different directories. Since my knowledge on this is not the best, I may require some assistance from the devs.

The document can include technical issues from the FAQ.

BTCPay WooCommerce Installaton Infographic

Not sure if it will look good or if it's doable, but I'm gonna give this one a try. Leaving it here as a reminder.

New infographic - How BTCPay is different

Inspired by recent #120 and #57 it may be handy to create one more infographic that will very clearly explain what BTCPay does different compared to others (traditional fiat or crypto) payment processors.

[New Doc] Google Cloud Deployment

One more deployment method should be added to the docs - BTCPayServer Google Cloud. - GoogleCloudDeployment.md

After that is done, we need to update:

• Deployment Section in readme
• Summary.md - Deployment

Issue trying to pair with btcpayserver and Magento 2 plugin

I have setup this extension but it does not seem to to pair with Btcpayserver using Magento 2.2.6

[New Doc] Summary.md (for GitBook)

I found a way to leave all docs intact on GitHub, but have a good structure on GitBook

We need to create summary.md and manually add the structure, if GitBook recognizes that a repo has a summary.md it will structure the docs that way and ignore folders.

Providing a summary is optional. If you don't specify a summary, and GitBook does not find a SUMMARY.md file at the root of your docs, GitBook will infer the table of contents from the folder structure and the Markdown files below. (https://docs.gitbook.com/integrations/github/content-configuration#summary)

Lightning Network and BTCPay

Record a video that will show people how to use LN. We now have a technical video, but there are no videos beyond installation. I'd like to show users how to use Zap and maybe even c-lightning command line, but in two separate videos.

• Deploying Lightning Node (BTCPay LunaNode)
• Cover the risks
• Connecting to Zap
• Open a channel
• Make a payment
• Request a payment
• Closing a channel
• Troubleshooting

Fix Troubleshooting.md

Troubleshooting md needs to be updated with BTCPay and Bitcoin Core logs once this PR is merged

• Add BTCPay Logs
• Add Bitcoin Core logs ?
• Add links to newly created /FAQ folder
• Add Troubleshooting to Summary.md

Document Accounting in BTCPay

Document accounting in BTCPay:

• Record a short video on accounting export in BTCPay (pivot tables Excel)
• Record a video tutorial on accounting with QuickBooks
• Document Accounting.md as a new doc explaining the above

Unfortunately due to differences in countries/jurisdictions doc can only cover technical and not the legal aspect of accounting in BTCPay.

@JeffVandrewJr if you at any point want to tackle any of these before I do, just let me know. Leaving this on a to-do so that anyone can tackle it in the meanwhile.

Add Deployment.md

Proposal to add a general deployment document: Deployment.md

• General info on different deployments
• Prices, difficulty, Lightning options, payment methods
• Links to various deployment methods

Reference to #87

Translation.md

Proposal to add 2 new documents : Translation.md and Contribute.md inside the Contribute folder.

Translation.md

There are many non tech-savvy users who want to contribute to BTCPay but they just don't know how.

Currently it's only possible to translate the checkout. Until we figure out the system how to do handle front-end translations, I believe it would be beneficial to create Translation.md and teach these users how to help with translations step by step.

## Contribute.md

Build on this and expand to other use-cases.

How can I contribute to BTCPay? The easiest way is to use the software for your business, provide feedback and report any bugs or issues you or your customers encounter. Translating BTCPay, helping us with documentation are also ways in which you can help, even if you're not a developer or tech-savvy.

Support for ERC20 tokens

Requesting support for ERC20 coins such as USDC and DAI. DAI is currently supported on the Dappos App, can it be replicated here? https://github.com/Dappos/Dappos

[New Doc] Add Magento.md

I haven't seen much instructions on how to use Magento integration with BTCPay.

It would be handy if users using this integration can help with writing a concise document on how to install and configure Magento BTCPay plugin.

WooCommerce Plugin - Order Status and e-mail templates

to-do:

• Update WooCommerce.md with new direct installation from WP repo.
• Update Bitcoin Store article with link to new plugin
• Update Bitcoin Store with LunaNode installation
• Explain each order status in WooCommerce.md or create separate doc
• Explain how users can customize e-mail templates in Woo and customize order statuses
• Change WooCommerce FAQ accordingly
• Add links to Document in WordPress plugin
• Update WooCommerce readme - add FAQ section.

[New Doc] Quick Start Guide

Create some sort of quick start guide that can be easily printed out and handed to people at conferences.

Emphasizing the basic concept, features, integrations, pros, etc.

Add a doc about Derivation Scheme (HD wallet setup) config

Currently the derivation scheme settings are not very clear. I am familiar with the different types of HD wallets, but no derivation path I use as input seems to be valid. I've tried xpub like in the table, and m/44'/0'/0'/0 which is the BIP44 scheme. I'm sure this works for Ledger, but I can't quite figure out what to do in the text field.

Also, there is no Check ExtPubKey (on a Ledger only?)

Ah I see now - BTCPay format memo is a table where you insert your xpub(s) instead of the token xpub (or xpub1 or xpub2) - and it gives you a followup prompt to confirm addresses.

I think it would be good to have a guide / link to information about generating an offline xprv/xpub, even if they dont have a Ledger

[New Doc] Add Walkthrough.md

This document that should cover concisely describe the the features and functions of UI found in BTCPay Server. It should be added into ''Getting Started" Section.

The goal of the document is to introduce users to all the settings and features and explain them concisely.

• Server settings

  • Users
  • Rates
  • Email server
  • Policies
  • Services
  • Theme
  • Maintenance
  • Hangfire

• Stores

  • Create New Store
  • Stores Settings
    • General settings
    • Rates
    • Checkout experience
    • Access Tokens
    • Users
    • Pay Button
  • Remove Store

• Apps

  • Create New
  • Settings
  • View
  • Remove

• Wallets

• Invoices

• My Settings

  • Profile
  • Password
  • Two-factor authentication

Add new Manuall installation guide

I saw that someone wrote the article on how to deploy BTCPay Srever on Linux manually.

https://freedomnode.com/blog/114/how-to-setup-btc-and-lightning-payment-gateway-with-btcpayserver-on-linux-manual-install

We should find the place for it. Should we just put a link to it on manual deployment
It's a great guide and should to be added.

• Decide where to add it
• Add it to "community articles" in readme

Document third-party hosting more in-depth

I think we should document differences between self-hosting and third-party hosting more in depth and include possible pros and cons together with attach vectors.
Related

While we can't protect users who use third-party hosts from potentially malicious hosts, we can educate them on potential attack vectors and pros/cons of using third-party hosts in general.

Of course, this is by no means attack on third-party hosts, I think they are one of the most important part of the ecosystem in adoption, we just need to explain the trade-offs better.

I'm not even sure where this can be put. @britttttk any ideas?

Document Spark Integration

• Lightning Network.md

Joule Extension and BTPay

• Make a video based on the instructions here
• Tackle Yubikey and Yalls if possible

Create /media folder

We need to create a file where we can dump all of BTCPay logos, infographics and graphic design work, so that merchants,media and other members who want to advertise and spread the word can can use it.
Imho /img is a bit to crowded, but we can create a subfolder inside /img as /graphics or /logos /branding or whatever you guys want us to call that folder, ideas welcome.

Re-Structure FAQ

Right now we have lots of good information scattered around and it would be a good idea to consolidate and categorize them.

My suggestion is to have three types of documents:

1. FAQ.md - General BTCPay questions which are more about navigation, options, features.
2. Troubleshooting.md #48 - Document that will describe how users can troubleshoot a certain problem and get help. This is more general information document rather than coding instructions.
3. Common Issues - This will be a huge document with all the technical issues categorized. The goal is to provide code so that people can use. I propose we take a look at FAQ and the Wiki to create categories and structure the questions. For instance, - Synchronisation - all questions about the sync (why it's needed, how long it takes, what to do if it's stuck.

The 3. document will potentially take time and we'll need to think of the "categories" for the issues. The easiest is to just take a look at NBitstack Wiki and try to group similar issues.

Thoughts?

What is BTCPay

Create a "what is BTCPay video" animated.
Video can be embedded at the front page.
Think of a concise storyline.
Ideas welcome.

Improve understanding: Allow anyone to create an invoice

Allow anyone to create invoice
You should enable this option if you want to enable users to create invoices themselves. This option is only useful if you're using POS App or the payment button.

not clear enough

Maybe something like this:

Allow registered users of your store (store - settings - users) to create invoices themselves.
On top of that, this option needs to be enabled if you will be using the payment button or generating invoices through third party HTML or API. POS app does not need this enabled as it is preauthorised.

something like that maybe would be more clear

Add drupal doc

Document drupal integration on https://github.com/btcpayserver/btcpayserver-doc/blob/master/Integration.md ping @ndeet .

Will also try drupal myself a bit later.

Document BTCPAY_HOST="IP" and SSL 500/503

We need to document that 503 and SSL errors a bit better somewhere and explain clearly why it happens when it happens and how to fix it.

@NicolasDorier help with this is appreciated

Payout Support / Docs

Is the BitPay Payouts API supported by BTCPayServer? Specifically, this functionality:
https://bitpay.com/api#resource-Payouts

I can’t find the documentation for the REST api of BTCPayServer, so I’m assuming it’s an exact match?

Thanks for the help!

High Availability

Hi Guys,

Is there a recommended set up if I want high availability / clustering?

Improving Introduction (readme)

Docs main page, the readme, needs to be worked on a bit. Let's talk about the structure of it. It should provide easy to understand information and links to everything important in docs.

I like how Bisq handles their docs, the structure of the intro is:

What it is
Why it exists
How it works
    In a nutshell
    How is it different
    How it keeps funds secure
    How it keeps data private
    How it resists censorship

It requires minor cleanup and adding clarity and making navigation easier.

NPM library with 2m installs has a backdoor.

Does this issue effect btcpayserver? The BitPay Copay wallet was/is vulnerable.
dominictarr/event-stream#116

Lapps Video Series

Leaving this as a public promise that I'll do a video series once Lightning Network Apps aka lapps are integrated.

Plan is to record an introductory video explaining lapps, how they work in BTCPay and then do short setup video and explanation for each of the lapps.

The link for testnet website is outdated

In Getting-Started.md , the link for testnet website is outdated.

http://btcpay-server-testnet.azurewebsites.net/

Add a doc about front-end customization options

Perhaps:

• a script / instructions how to set an app (or a blank page) as the homepage
• a simple example webpage with an invoice button

And a docs section about the Theme part of the settings

Deployment Decision Infographic

As we develop more options for implementing BTCPayServer, I think it could be helpful for new users to have a way to determine which solution is best for them. Lately people have been asking questions in the Slack where they are using multiple tutorials at once that can't be used together.

I was thinking we could create an infographic decision tree that shows which deployment methods will be best suited for the user depending on their needs and links? to skip to different parts in the process. If any one has ideas about how to organize the info, feel free to change/add. Since developers can make these decisions on their own, I think it should be more Newbie friendly...

Some of these could be:

-You need to build a website
-You already have a website
-You care about price / hosting Providers
-You want to use a 3rd Party BTCPay Host
-You want to make a simple donation page
-Hardware deployment options
-You want developer capability / manual builds
-You want to use the Lightning Network

Document Wallet Re-Scan

Explain wallet re-scan and add it to

• Add to Walkthrough.md
• Add to FAQ-wallet.md

Spark c-lightning wallet

• What is Spark
• How to connect Spark and BTCPay via browser (internal wallet)
• How to connect Spark and BTCPay via external wallet
• How to add on-chain funds
• How to open a channel
• How to pay an invoice
• How to create an invoice
• How to close the channel

Cannot change port or get BTCPay Server up and running

I am able to get up to the point where I clone BTCPay server in and do dotnet run help, but I get this error....could it be that my BTCD is running on port 8332? How do I change it if so? I tried --port 8332....nothing works.

btcpay server magento 2 plugin

Although someone has forked it and listed it as an option, the fork doesn't appear to contain even a simple search and replace to change bitpay to btcpayserver. Additionally, there is no issue tracker enabled on this fork. It would be nice to see at least one commit on this "fork". It's basically useless right now -- it's 6 commits behind and 0 ahead of the original... and not even a document suggesting what the purpose of it is.

[New Doc] Add HardwareDeployment.md

It's very important to have a document in > Deployment section which will describe how a user can:

1. Deploy BTCPay on a hardware wallet (recommended for tech-savvy users).
2. Links to store which sell plug and play solutions.

If @ketominer and @normandmickey or anyone else can help with documenting this that would be great.

Benefits? Clarification

Dear BTCPay maintainers,

I have been tasked with setting up a standalone BTCPay server. I chose to do it under Linux, with .Net Core 2.0.2 and Postgres.

I am slightly confused as to the benefits of such an installation. It looks like my client wants to use the features listed in:
https://btcpay-server-testnet.azurewebsites.net/

In that case, I am slightly confused as to the setup procedure for Linux. I am following the steps given for "local development", and would like any clarification you could provide.

How to embed Bitcoin payment (donation) button on your website

Make a video that will teach people how to create and embed donation buttons on their website with BTCPay.

Configuration file

Where can i write the configuration of database server?

Add Docker Tooling to BTCPay Docs

Docker repo has amazing documentation.

I think we need somehow to clone that repo into doc repo and then add that to GitBook section > Development.

Common UX Issues Guide for Merchants

Create documentation to help merchants troubleshoot common user experience issues during the checkout/payment process and how to solve them. The information should also be available (possibly infographic) for merchants to print and keep on hand for quick employee reference in physical stores where POS is used.

Explain customer payment issues such as:

• Underpaid
• Paid Late
• Invalid
• Refunds
• Unconfirmed

MERCHANT FEEDBACK & INPUT IS REQUESTED in order to make this document. Please comment any customer payment issues and questions commonly experienced during checkout process.
(Related to: #433 & #434)

[New Doc] UseCases.md

Proposal to document possible use-cases of BTCPay.
A good starting point is this

Who can use BTCPay?

• Merchants with an online or a physical store (connect your store to your BTCPay with one of many integrations or use a Point of Sale app)
• Charities, organizations or content creators (receive donations via POS app or payment button)
• Users who want to deploy Lightning Network node easily
• Users who want to become payment processors for their friends or local community
• Exchanges which want to integrate with BTCPay and allow merchants to receive fiat payments
• Hosting providers which want to offer 1-click deployment to customers
• Developers who want to help and learn

Add heading for each category of users and explain concisely what problem BTCPay solves for them and what tools are available. Clearly emphasizing advantages over other tools.