How to use Umbrel LNbits for small merchants

How to use this wonderful suite LNbits app in Umbrel node as small merchant.

To read more info about LNbits, here I wrote a quick introduction guide.

LNBits, could be used as Bitcoin LN payment processor, in simple steps. Yes, I know, some of you would say “but use BTCPay Server…etc”.

This time, let’s try to use more tools available for merchants. For some specific cases LNbits can fit very well and extend the usage with more extensions. BTCPay is good, is doing great job, but also LNbits is offering more tools and options for a merchant.


Use case scenario

So, let’s take a use case scenario: a small hotel and restaurant or cafe bar, with also a webshop for online ordering, in a simple Wordpress + Woocommerce.

This merchant want the following:

  • receive payments in bitcoins, from its website online ordering, with no intermediary
  • customers also can pay with Bitcoin over Lightning Network, in the restaurant, in a simple manner, directly to the waiter. Also could give tips to the waiter, in his own wallet, directly.
  • have a simple system of TPoS, where the employees just input the value in local currency and create the LN invoice to be paid.
  • have a simple self service offline shop, for example during the night, so the guests can pay and take away some items (beer, wine, sandwiches, snacks). Using LNURLVend extension could be a nice solution.
  • create a type of “fidelity points” to regular customers and give them sats back using a LNURL-withdraw voucher system.
  • customers can also leave tips with sats in a “Tip Jar” or LNURL-pay
  • customers can play some nice songs in the bar lounge, but paying a small fee using the LNBits Jukebox Livestream extension

… and many more use cases, LNbits have a lot of extensions ready to be used, just activate them, configure some simple parameters and done, you are good to go!

But first things first, we need to prepare LNBits to be ready for wide accessibility for any client and device. As we know, in Umbrel all apps are behind Tor network, so not all customers will use Tor (only those advanced users). so we need to give access also to regular users.

Prepare Umbrel LNBits to be visible in "clearnet"

Clearnet is as we know it, the regular internet access, and/or public IP.

Tor network is a parallel internet, over .onion addresses and is not (yet) broadly used/known and accessing payment services over Tor sometimes is buggy and complicated for regular users.

So, let’s say the small merchant have an Umbrel node ready, some LN channels open, LNBits installed and ready, working just fine as it is over its .onion address.

Some aspects to take in consideration:

  • Is better to configure this node in hybrid mode. Here is an amazing guide (by Hakuna) about how to setup your node in hybrid mode.
  • Sending/receiving between internal LNBits wallets can be allowed with this line in your lnd.conf file: allow-circular-route=1 (restart lnd after edit). With this, you can use LNbits wallets with zero internal fee, in direct payments.
  • Learn how to manage the LN node and have good liquidity. Having a good node, good fees, good routes, is offering to your customers a nice experience paying you fast and cheap using LN. Don’t be greedy. Here I wrote a dedicated guide.
  • Engage your regular customers to open channels with your node (if they have a LN node). That will resolve many issues with inbound liquidity that you really need it. Inbound liquidity (able to receive payments) could be very expensive sometimes so if your customers are used to open channels with your node will help a lot, not only them, but also your shop.
  • Have always enough inbound liquidity to receive payments. Is better that each end of day or when you had a busy day, loop out from your channels the sats received, using a swap service, as described in this guide. In this way you will always start the day with more “space” in your channels to receive payments. There is in work a new extension for LNBits with swaps using
  • LNBits do not transact directly onchain, only LN. Anyways, if you really want to charge using onchain address, it is possible using the SatsPay extension linked to a watch only xpub key. But charges onchain require at least 3 confirmations (at least 30min waiting) so for a customer is not so good to keep him waiting. But in special cases, yes it could be used this option.
  • Keep in mind that LNBits is still in beta so are always new developments. Also is waiting for a new awaited extension for user management and more complex access.
  • Save in bookmarks or password manager your access to created users / wallets, also with the details about lndhub URL, admin key, invoice key etc.

To open your LNBits instance to clearnet world, you have these options (amazing guides made by Hakuna and Uxellodunum):

Setup the webshop with LNBits

Ok, so now we have our LNBits accessible from outside with

(or whatever subdomain you want to choose), all wallets and functionalities are tested and working.

In our Wordpress Woocommerce shop we install the simple plugin for LNbits and configure it to connect to our LNbits instance.

Go to your LNBits wallet configured to be used for the webshop (you can have many as you wish) and copy the “invoice/read key” string.


LNBits wwallet details

Then go to your Wordpress - Woocommerce - Payments - LNbits - and paste that string in the API key and next add your lnbits URL


That’s it! You can start taking payments in bitcoins through Lightning Network. No redirected pages, no intermediaries, fast and simple. LNbits plugin is generating the LN invoice in the same page and displayed in the payment step. Once is done, it will show a confirmation message and normally customer receive by email the details of his order.

Yes, the plugin is very basic, with not too much options, to personalize the text in the payment etc, but is well enough to start taking payments with bitcoin.

Taking payments in shop (onsite) by employees

Well… this is another sensible aspect.

We need to give them limited access to the shop wallet funds, only to create invoices, not able to spend from there. And LNbits can do it in a wonderful way.

So we suppose that we do not have any integration in our own PoS system with LNbits or bitcoin payments, we consider BTC as cash, so we can just take the payment in a separate manner, as we do with cash. In the accounting system is marked as “pay in cash” or whatever name you want to use, it doesn’t matter, is cash.

So the waiter/employee will just need a simple way to generate a LN invoice or have a general LNURL ready to receive payments.

LNbits have different approaches, you can use which one suits better your specific activity and type of situations.

We can use the following LNbits extensions:

  • LNDhub (invoice wallet) configured in waiter/employee device. Each waiter/employee can have its own, for better tracking
  • LNURL-pay QR code, printed on a paper. Each waiter can have its own LNURL for better tracking. When customer pays, will just show to the waiter the confirmation on his device screen and done. Is quite hard and useless to fake a LN payment. Remember, BTC/LN payments are irreversible.
  • TPoS extension, configured on each waiter/employee device
  • Offline LNURL-PoS with the small offline devices, in case you do not have good WiFi coverage, you have a terrace that do not have connection. Also available as mobile app (can be run in any old android device, with no internet).

Waiters tips

Employees / waiters can have their own personal LN wallet for tips, or you can setup dedicated ones in your LNBits instance and give them full access to those wallets so they can use it in Bluewallet or Zeus mobile app.


Go to LNBits LNDhub extension and scan the admin or invoice QR code to be imported into Bluewallet or Zeus mobile apps

LNBits wallets also can be used as web app on mobile, just save the wallet URL as web widget bookmark and open it directly. Works perfectly.

For general common Tip Jar can be used the dedicated LNbits extension, easy to configure and presented as a simple webpage. Or can be used a dedicated LNUL-pay QR code, with its own wallet, to separate from regular charges.

Another way could be to use the SplitPayments extension where can be defined the amount of sats that is going to the waiter, from the total of each payment. Very easy to configure.


At the end of day, when waiters/employees will do their end of day counting, in the regular system and just compare with what was charged in LNBits system. A supervisor with full access could also export all the transactions into a csv file and or print it out.

At this section maybe in the future LNbits will have a better accounting system, transaction labeling, personalize. Now is just basic but enough to work.

Also, this is the moment when a supervisor / shop owner will swap out the funds from LN channels, into an onchain wallet and leave the channels almost empty to be ready for the next day to receive more sats.

Fidelity Credits System

If you have some regular customers that can pay upfront for their consumption and get discounts, you can use a system of loaded NFC cards / devices, or simply create a LNDHub wallet for each fidelity client, where they load it with sats and spend them back in your restaurant. In this way fees will be 0 for them and you have a better control of these “fidelity points”.

Also client have full control of his LN wallet, can be imported in his device and use it as a regular LN wallet if he want.

There is a way to build some NFC cards / devices for these wallets. An example here. So clients can just use those devices paying in shop. No need for other apps.

Or you could just simply create some LNURL-withdraw vouchers and give them to your regular customers, as satsback system. Easy, fast, no complications, just print them with your regular ticket printer, client withdraw them when he/she wants or just give them away to somebody else.

Offline Vending Machine

Let’s say you have also an (hotel) accommodation service next to your restaurant and during the night (when you do not have personal available) you want to offer to your guests a simple way to buy some snacks or drinks.

This option could be used also for the room mini-bar.

So a simple box / vending machine with a system to receive offline LN payments, is already available with LNbits. You can choose whatever size or type of the box, important is to link it to your LNbits as described in the tutorial.

Here is a demo and how to build it. The system is simple: client scan QR, pays, item is disposed. The machine doesn’t need access to internet.

Offline Shop

Let’s say you want to implement a system of quick selling products / menus for take away. So some kind of semi self-service.

You have a monitor outside of the shop or just a billboard, listing your products offered for take away.

Customer scan the LNURL for the product desired, pay and get back a word as “proof” of payment. The words can be configured as you wish and changed when you want.

Then customer enter to your local to a special place where you deliver and present that word(s) paid for the products. Employee have then the proof of payment and just deliver.

Here is a tutorial demo how to configure and works.

Here is also a demo for how to pay with sats for a beer with a smart tap.

Another example of use case scenario here how to buy sandwiches with LN.

DJ Lounge music jukebox

Let’s say your customers want to hear a nice music in your bar / restaurant, choosing their own preferred songs. You don’t want to let everybody to change the music, but only for those who pay a fee.

So you could setup a simple music device, link it to your LNbits system and let customers pay for songs and play them.

Incentive for your ambient and offer a nice experience to your customers.

Here is more documentation how to setup Jukebox extension.

Here is a video tutorial demo.

Special customization & backup

In case you want to restrict the access to your “public” LNbits instance, you can edit the settings file doing the following.

Add only specific created user accounts in the LNBits env settings:

  • Enter SSH into your Umbrel node
  • edit the yml conf file: sudo nano ~/umbrel/apps/lnbits/docker-compose.yml
  • add in #App section the line: LNBITS_ALLOWED_USERS: “YOUR_USER_ID_FROM_WALLET_URL” with comma separated if you have more
  • restart lnbits app: sudo ~/umbrel/scripts/app stop lnbits && ~/umbrel/scripts/app start lnbits

Soon will be available a full user management admin extension so will not be needed this customization and also restricting the creation of new wallets. But until then you can use it like this.

Also an important aspect: BACKUP database.

To save a backup of your LNbits instance (including tx history, wallets, accounts), you can save the database folder located in: ~/umbrel/app-data/lnbits/data

In special the database sqlite3 file, but is good to save the entire data folder for all extensions used.

If you need to edit directly into this sqlite database, you can install a simple viewer editor for sqlite. More details here. Then you can open the sqlite db file and edit all necessary tables and items, adjusting balances, removing editing existing users / wallets.


So, that’s it, a full scenario how you could use this amazing solution LNbits for a hotel restaurant. You can extend this to your specific activity, covering all the needs that can be done with LNBits lndhub wallets, now you already see how powerful it is and easy to setup, having full custody of your funds.

I hope this guide can inspire more merchants to start accepting Bitcoin.

Also, those Bitcoin enthusiasts helping those merchants, that don’t have enough skills, building nice solutions for bitcoin payments.

We must create that Bitcoin circular economy!


What an amazing collection of use-cases and how to solve them.
Thank you for putting this together