LNURL Setup

LNURL is a set of subprotocols that can be used to improve the UX of payments over lightning. For example, lnurl-pay makes it possible to receive lightning payments using a static QR or a lnurl address. Using lnurl-pay, payments can be made to the same QR multiple times instead of the typical flow of lightning where one has to generate an invoice and share it with the payer.

Assuming you're building a donation site or an offline POS, a static QR code allows you to receive payments from all customers/donors without having to manually generate a QR code for them.

When setting up lnurl for a business/user, the minimum and maximum amounts that can be received are specified, any special comments, messages, and images can also be set. This gives more functionality to regular lightning invoices. Using these QR codes also ensures privacy for the recipient, anyone can scan to pay, unlike a Bitcoin QR code where one can scan the address and find all the payments sent to that address, this is more private.

To add lnurl support to your business without having to do the whole configuration or infrastructure setup yourself, follow this guide.

• Create a lnurl for the customer by sending this payload

Sample Request

{
    "identifier": "satoshi",
    "identifierType": "username",
    "tld": "bitcoin.org",
    "customerEmail": "[email protected]",
    "satMinSendable": 1, //satoshis
    "satMaxSendable": 1000000 //satoshis
}

📘

The tld is the domain you will be using for your lnurl.
e.g after using bitcoin.org, the lnurl will appear as bitcoin.org/api?q=LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7MF0V9CXJ0M385EKVCENXC6R2C35XVUKXEFCV5MKVV34X5EKZD3EV56NYD3HXQURZEPEXEJXXEPNXSCRVWFNV9NXZCN9XQ6XYEFHVGCXXCMYXYMNSERXFQ5FNS

• The api in the URL above is arbitrary, it depends on whatever you name your service endpoint.
• Bitnob uses the username you've sent to map the lnurl to the customer and for later generating lightning addresses. The identifier type in this case is a special type that can identify if an lnurl is either tied to a username, bank account or mobile money account. There are special cases where this will come in handy. The default identifier type is "username"

Sample Response

When an lnurl is successfully generated for the customer, you will receive this response. The response is an encoding of the details sent above into a bech32-encoded HTTPS/onion URL.

The lnUrlQR property in the response is the QR representation of the lnurl. If you want to generate your own lnurl QR, ensure that the lnurl you use is all uppercase

{
    "status": true,
    "message": "lnurl successfully created",
    "data": {
        "id": "bc8e077c-5e43-4804-9497-21a0281a9d4",
        "tld": "bitcoin.org",
        "identifier": "satoshi",
        "identifierType": "username",
        "lnUrl": "LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7MF0V9CXJ0M385EKVCENXC6R2C35XVUKXEFCV5MKVV34X5EKZD3EV56NYD3HXQURZEPEXEJXXEPNXSCRVWFNV9NXZCN9XQ6XYEFHVGCXXCMYXYMNSERXFQ5FNS",
        "lnUrlQR": "https://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7MF0V9CXJ0M385EKVCENXC6R2C35XVUKXEFCV5MKVV34X5EKZD3EV56NYD3HXQURZEPEXEJXXEPNXSCRVWFNV9NXZCN9XQ6XYEFHVGCXXCMYXYMNSERXFQ5FNS",
        "satMinSendable": "1",
        "satMaxSendable": "1000000",
        "createdAt": "2021-11-20T08:49:07.333Z",
        "updatedAt": "2021-11-20T08:49:07.333Z"
    }
}

📘

Max and Minimum Spendable

The Lnurl protocol uses millisatoshis, but to make it easier, you should send the amount to us in satoshis, we will handle the conversions.

You decide what the max and minimum amount a particular customer can receive via lnurl is. For example if your KYC requires a user to be able to receive $100 - $1000, you can tie their lnurl-pay to that amount (in satoshis)