From 7a25c8ce245d26f159dfeb561376f3bd51cb6c70 Mon Sep 17 00:00:00 2001 From: Tiago Vasconcelos Date: Wed, 2 Jun 2021 18:16:03 +0100 Subject: [PATCH] Docs (#196) Updated docs for LNURL pay, LNURL withdraw and Offline shop Co-authored-by: Tiago Vasconcelos --- lnbits/extensions/lnurlp/README.md | 26 ++++++++++++++ lnbits/extensions/offlineshop/README.md | 35 ++++++++++++++++++ lnbits/extensions/withdraw/README.md | 48 ++++++++++++++++++++----- 3 files changed, 101 insertions(+), 8 deletions(-) diff --git a/lnbits/extensions/lnurlp/README.md b/lnbits/extensions/lnurlp/README.md index 34a4bc0b..0832bfb7 100644 --- a/lnbits/extensions/lnurlp/README.md +++ b/lnbits/extensions/lnurlp/README.md @@ -1 +1,27 @@ # LNURLp + +## Create a static QR code people can use to pay over Lightning Network + +LNURL is a range of lightning-network standards that allow us to use lightning-network differently. An LNURL-pay is a link that wallets use to fetch an invoice from a server on-demand. The link or QR code is fixed, but each time it is read by a compatible wallet a new invoice is issued by the service and sent to the wallet. + +[**Wallets supporting LNURL**](https://github.com/fiatjaf/awesome-lnurl#wallets) + +## Usage + +1. Create an LNURLp (New Pay link)\ + ![create lnurlp](https://i.imgur.com/rhUBJFy.jpg) + + - select your wallets + - make a small description + - enter amount + - if _Fixed amount_ is unchecked you'll have the option to configure a Max and Min amount + - you can set the currency to something different than sats. For example if you choose EUR, the satoshi amount will be calculated when a user scans the LNURLp + - You can ask the user to send a comment that will be sent along with the payment (for example a comment to a blog post) + - Webhook URL allows to call an URL when the LNURLp is paid + - Success mesage, will send a message back to the user after a successful payment, for example a thank you note + - Success URL, will send back a clickable link to the user. Access to some hidden content, or a download link + +2. Use the shareable link or view the LNURLp you just created\ + ![LNURLp](https://i.imgur.com/C8s1P0Q.jpg) + - you can now open your LNURLp and copy the LNURL, get the shareable link or print it\ + ![view lnurlp](https://i.imgur.com/4n41S7T.jpg) diff --git a/lnbits/extensions/offlineshop/README.md b/lnbits/extensions/offlineshop/README.md index 254bc688..79bbe41d 100644 --- a/lnbits/extensions/offlineshop/README.md +++ b/lnbits/extensions/offlineshop/README.md @@ -1 +1,36 @@ # Offline Shop + +## Create QR codes for each product and display them on your store for receiving payments Offline + +[![video tutorial offline shop](http://img.youtube.com/vi/_XAvM_LNsoo/0.jpg)](https://youtu.be/_XAvM_LNsoo 'video tutorial offline shop') + +LNBits Offline Shop allows for merchants to receive Bitcoin payments while offline and without any electronic device. + +Merchant will create items and associate a QR code ([a LNURLp](https://github.com/lnbits/lnbits/blob/master/lnbits/extensions/lnurlp/README.md)) with a price. He can then print the QR codes and display them on their shop. When a costumer chooses an item, scans the QR code, gets the description and price. After payment, the costumer gets a confirmation code that the merchant can validate to be sure the payment was successful. + +Costumers must use an LNURL pay capable wallet. + +[**Wallets supporting LNURL**](https://github.com/fiatjaf/awesome-lnurl#wallets) + +## Usage + +1. Entering the Offline shop extension you'll see an Items list, the Shop wallet and a Wordslist\ + ![offline shop back office](https://i.imgur.com/Ei7cxj9.png) +2. Begin by creating an item, click "ADD NEW ITEM" + - set the item name and a small description + - you can set an optional, preferably square image, that will show up on the costumer wallet - _depending on wallet_ + - set the item price, if you choose a fiat currency the bitcoin conversion will happen at the time costumer scans to pay\ + ![add new item](https://i.imgur.com/pkZqRgj.png) +3. After creating some products, click on "PRINT QR CODES"\ + ![print qr codes](https://i.imgur.com/2GAiSTe.png) +4. You'll see a QR code for each product in your LNBits Offline Shop with a title and price ready for printing\ + ![qr codes sheet](https://i.imgur.com/faEqOcd.png) +5. Place the printed QR codes on your shop, or at the fair stall, or have them as a menu style laminated sheet +6. Choose what type of confirmation do you want costumers to report to merchant after a successful payment\ + ![wordlist](https://i.imgur.com/9aM6NUL.png) + + - Wordlist is the default option: after a successful payment the costumer will receive a word from this list, **sequentially**. Starting in _albatross_ as costumers pay for the items they will get the next word in the list until _zebra_, then it starts at the top again. The list can be changed, for example if you think A-Z is a big list to track, you can use _apple_, _banana_, _coconut_\ + ![totp authenticator](https://i.imgur.com/MrJXFxz.png) + - TOTP (time-based one time password) can be used instead. If you use Google Authenticator just scan the presented QR with the app and after a successful payment the user will get the password that you can check with GA\ + ![disable confirmations](https://i.imgur.com/2OFs4yi.png) + - Nothing, disables the need for confirmation of payment, click the "DISABLE CONFIRMATION CODES" diff --git a/lnbits/extensions/withdraw/README.md b/lnbits/extensions/withdraw/README.md index 950da202..0e5939fd 100644 --- a/lnbits/extensions/withdraw/README.md +++ b/lnbits/extensions/withdraw/README.md @@ -1,14 +1,46 @@ # LNURLw -## Withdraw link maker -LNURL withdraw is a very powerful tool and should not have his use limited to just faucet applications. With LNURL withdraw, you have the ability to give someone the right to spend a range, once or multiple times. This functionality has not existed in money before. -https://github.com/btcontract/lnurl-rfc/blob/master/spec.md#3-lnurl-withdraw -With this extension to can create/edit LNURL withdraws, set a min/max amount, set time (useful for subscription services) +## Create a static QR code people can use to withdraw funds from a Lightning Network wallet -![lnurl](https://i.imgur.com/qHi7ExL.png) +LNURL is a range of lightning-network standards that allow us to use lightning-network differently. An LNURL withdraw is the permission for someone to pull a certain amount of funds from a lightning wallet. +The most common use case for an LNURL withdraw is a faucet, although it is a very powerful technology, with much further reaching implications. For example, an LNURL withdraw could be minted to pay for a subscription service. Or you can have a LNURLw as an offline Lightning wallet (a pre paid "card"), you use to pay for something without having to even reach your smartphone. -## API endpoint - /withdraw/api/v1/lnurlmaker -Easily fetch one-off LNURLw +LNURL withdraw is a **very powerful tool** and should not have his use limited to just faucet applications. With LNURL withdraw, you have the ability to give someone the right to spend a range, once or multiple times. **This functionality has not existed in money before**. - curl -H "Content-type: application/json" -X POST https://YOUR-LNBITS/withdraw/api/v1/lnurlmaker -d '{"amount":"100","memo":"ATM"}' -H "X-Api-Key: YOUR-WALLET-ADMIN-KEY" +[**Wallets supporting LNURL**](https://github.com/fiatjaf/awesome-lnurl#wallets) + +## Usage + +#### Quick Vouchers + +LNBits Quick Vouchers allows you to easily create a batch of LNURLw's QR codes that you can print and distribute as rewards, onboarding people into Lightning Network, gifts, etc... + +1. Create Quick Vouchers\ + ![quick vouchers](https://i.imgur.com/IUfwdQz.jpg) + - select wallet + - set the amount each voucher will allow someone to withdraw + - set the amount of vouchers you want to create - _have in mind you need to have a balance on the wallet that supports the amount \* number of vouchers_ +2. You can now print, share, display your LNURLw links or QR codes\ + ![lnurlw created](https://i.imgur.com/X00twiX.jpg) + - on details you can print the vouchers\ + ![printable vouchers](https://i.imgur.com/2xLHbob.jpg) + - every printed LNURLw QR code is unique, it can only be used once + +#### Advanced + +1. Create the Advanced LNURLw\ + ![create advanced lnurlw](https://i.imgur.com/OR0f885.jpg) + - set the wallet + - set a title for the LNURLw (it will show up in users wallet) + - define the minimum and maximum a user can withdraw, if you want a fixed amount set them both to an equal value + - set how many times can the LNURLw be scanned, if it's a one time use or it can be scanned 100 times + - LNBits has the "_Time between withdraws_" setting, you can define how long the LNURLw will be unavailable between scans + - you can set the time in _seconds, minutes or hours_ + - the "_Use unique withdraw QR..._" reduces the chance of your LNURL withdraw being exploited and depleted by one person, by generating a new QR code every time it's scanned +2. Print, share or display your LNURLw link or it's QR code\ + ![lnurlw created](https://i.imgur.com/X00twiX.jpg) + +**LNBits bonus:** If a user doesn't have a Lightning Network wallet and scans the LNURLw QR code with their smartphone camera, or a QR scanner app, they can follow the link provided to claim their satoshis and get an instant LNBits wallet! + +![](https://i.imgur.com/2zZ7mi8.jpg)