Paying LNURL

Making payments to other services using lnurl

Any lightning-enabled wallet can scan an LNURL QR code to initiate payments to other services.

There are two ways to pay a LnURL based on your architecture and use case.

Paying through a Callback
Paying directly through Bitnob

Pay using callback

Firstly a handshake is established

Handshake

To pay a LnURL, a handshake protocol must be established by sending the LnURL decoded and getting a callback. The callback is the URL of the service to call for the next steps of paying to the LnURL.

Payload

JSON

{
  "status": true,
  "message": "lnurl decoded successfully",
  "data": {
    "image": "",
    "identifier": "satoshi@bitcoin.org",
    "description": "Satoshis to satoshi@bitcoin.org",
    "callback": "https://bitcoin.org/.well-known/lnurlp/satoshi",
    "commentAllowed": 1000,
    "satMinSendable": 1,
    "satMaxSendable": 100000
  }
}

Read on the Decode LN Response (opens in a new tab) to see a breakdown of the response.

Next, a callback query is made to generate a lightning invoice for the receiver

Callback query

After getting the callback, a GET request is made using this format. This request is made to generate a lightning invoice to make payment on behalf of the receiver. The amount sent must be within the satMinSendableand satMaxSendablefrom the handshake response.

Text

https://bitcoin.org/.well-known/lnurlp/satoshi?amount=<amount>&comment=<comment>

To complete the process; payment is made to the pr invoice of the response from the callback request.

JSON

{
  "success": true,
  "data": {
    "routes": [],
    "pr": "lntb1u1p3raa9upp5ss02znv6kuf3npjuwum5k8tgudznzy76jtuc464fcu30s8a84zyshp5hkth2etmm3e6v9xw52dhtgrxnk2y0vq0tf7levq2ly2efua25p4qcqzpgxqr23sfppq4mk0ml964sgju0s3pkq4z2pf9g5pxgh8sp5m7cd8kd35jlg8eqwz8vn9cjcygxnlay26l65f7qatgcs0kzuxqks9qyyssqlgjjpzhm407xjvnshjk8e7dfz75gdgtmxlj7fs9nt4pq6q7x2jwk83dfl2xvjkxnvmlk6uy06j8kdu49hd6sjhpt2743pr4pynk9hmqp4cnrxr",
    "disposable": null,
    "successAction": {
      "message": "Thank you.",
      "tag": "message"
    }
  }
}

Pay directly through Bitnob

When you send the below payload to pay a lnurl (opens in a new tab), Bitnob will request an invoice for the specified amount from that service, run checks and complete the payment on your behalf. When the payment is completed, you will receive a btc.lightning.send.success webhook (opens in a new tab) response with the payment details.

JSON

{
  "encodedLnUrl": "lnurl1dp68gurn8ghj7et2v4exztnfduhjuam9d3kz66mwdamkutmvde6hymrs9ajkgerexsvtxxe0",
  "satoshis": 1000,
  "reference": "randomstring", //you are to generate the reference yourself to use for keeping track of your invoices
  "comment": "payment description/comment",
  "customerEmail": "santorini@bitcoin.org"
}

Response

add sample response

📘

Recommended Approach

We recommend using the 2nd approach. With this approach, you don't need to contact the service yourself. Once you supply the encoded LNURL, amount, reference, comment, and customer email to us, we will handle the rest of it for you.

🚧

Charging your customers before paying a Lightning address

Because Bitnob handles the payment of invoices, you need to deduct the amount you send to us from the customer's account. One way to do this is to create a pending transaction with the reference you send to us, when we send a webhook response to you, you can update the transaction status based on the kind of response you receive.

There are different ways of doing this based on your architecture, the most important thing is to ensure you charge the user before asking us to pay the lightning address

Decoding LNURL Receiving with LNURLs