Paying 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

{
    "encodedLnUrl": "lnurl1dp68gurn8ghj7et2v4exztnfduhjuam9d3kz66mwdamkutmvde6hymrs9ajkgerexsvtxxe0"
}

Response

You will receive a response like the one below

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

Read on the Decode LN Response 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.

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.

{
    "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, 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 response with the payment details.

Payload

{
  "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": "[email protected]"
}

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