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
{
"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.
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 (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.
{
"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