BTCPayServer for Bitcoin and Lightning Payments


BTCPayServer is a payments platform for Bitcoin on-chain and Lightning off-chain payments. It can also process altcoins, and Liquid transactions with Tether (that will be covered in another post one day).

This document will grow as we integrate more user-side functionality, but I wanted to document some basics here that we require to set up your service.

Note on the difference in on-chain and off-chain:
On-chain Bitcoin is good for large $$$ purchases. We usually recommend setting the minimum receiving of Bitcoin on-chain to $25 or more. It also can take 20 to 40 minutes (or longer) to confirm a Bitcoin payment. This is based on the sat/vB rate of the Bitcoin mempool and how much you price the fee rate. If this is a large $$$ purchase, I’d wait until a few confirmations are received before transferring the goods/services.
Off-chain Bitcoin is called Lightning, and these are instant payments. This is technically an experimental network even though it has been around since 2017. Some payments may fail due to routing issues (not enough liquidity between here and there to transmit the payment). But it is getting better daily, just try the payment again and it may find a different route than previously). We use different providers including IbexPay, Breez, PhoenixD, Strike, BitPay, Zebedee, and others, including your own self-sovereign node with your own established lightning channels.

AlpacaRMS can leverage either your own BTCPayServer instance or we can build an instance on our own BTCPayServer on our GoodMoney node.

For on-chain Bitcoin payments:

If we integrate your BTCPayServer, we will need the following key variables:

  • StoreID – from BTCPayServer store Settings
  • APIkey – from store Settings > Access Tokens, then down in Legacy API Keys click Generate button and grab the API key from the text box.
  • Username – provide a username of a Manager role (create a new user with a separate email than yours)
  • Password – provide a password for the username
  • BTCPayServer URL – provide the URL to load your BTCPayServer login page

If we provide a store in our GoodMoney instance, we will build almost everything. But we will need an xpub/zpub from your Bitcoin wallet in order to sweep funds to that wallet. You can get this from many wallets including Sparrow, Specter, Blue, etc… From last time we checked, you cannot get this from an exchange such as Coinbase. We recommend that you don’t use services such as this to store your Bitcoin long-term as they control access to your account and, ultimately, your funds.

For off-chain Bitcoin Lightning Payments:

If you have your own BTCPayServer, you probably are leveraging either your own internal node and channels that you manage, or you are using a 3rd party LSP such as Breez via a BTCPay plug-in. Nothing more is needed to do than the above key variables that we use.

Breez is a zero-conf LSP (zero config lightning service provider). It is easy to use as Breez manages the lightning channels dynamically for you (for a fee). Alpaca Support will create the connection for you thru BTCPayServer.

IbexPay is super easy to integrate. You create an account at IbexPay, and then we need the bptID from a virtual terminal that you create, and the refresh token. Find out more here…

Zebedee integration needs the base URL, and an APIKey.

Leave a Reply