LNURL-Withdrawal
Lnurl-withdrawal provides a simple way to pay someone without asking them for a lightning invoice. An example is a game where players earn rewards, how do you pay them without asking them for bank accounts, wallet addresses, or lightning invoices? Lnurl-withdrawal!
In order to payout those rewards, you can generate a lnurl-withdrawal static QR for each player, when they scan the QR, their wallet and the web service communicate to transfer the funds to their wallet.
This is beautiful for gifting bitcoins, processing refunds, offline Lightning Network ATM, simpler withdrawals from exchange accounts, withdrawing change from a PoS terminal, and many more beautiful use cases.
To pay a LnAdddress, a handshake protocol must be established by sending the LnAdddress to be decoded (opens in a new tab) and getting a callback
. The callback is the URL of the service to call for the next steps of paying to the LnAddress.
How it works
The user is presented with a static QR
They scan the QR, their wallet decodes the text from the QR into something like
# Example of a LNURL that is recognized by lightning wallets (mostly used in QR form)
LNURL1DP68GURN8GHJ7UM5V9NKJMN894SHQ6FWVEKX7AM9WF6X7UPW0PUH5TMSDVHXZWPH8PNZUETYXD3RQDRYX3JXYVFJ89SNXC34VYHKCMN4WFK8WTE3VG6NJENZ8YCNVEFSXS6RJEPCXFSNJEG5MZMLE
# decodes to
https://sandboxapi.bitnob.co/pk.a878f.ed3b04d4db129a3b5a/lnurlwithdrawal/1b59fb916e0449d82a9e
1000000
The wallet service sends a request to the endpoint which returns a response similar to
# GET https://api.lnpay.co/v1/wallet/wa_Opnn4kGOGBMnfCLFXtsDnjTb/lnurl-process?ott=2pHDk5C0N8HD&num_satoshis=3
{
"callback": "https://sandboxapi.bitnob.co/pk.a878f.ed3b04d4db129a3b5a/lnurlwithdrawal/1b59fb916e0449d82a9e",
"k1": "k1",
"maxWithdrawable": 2000, //the amount in msats
"defaultDescription": "LNURL Withdraw", //description that will be used on the invoice
"minWithdrawable": 0,
"tag": "withdrawRequest"
}
In order to create a lnurl-withdraw QR, send the following data to us
Sample Request
{
"amount": 1000, //satoshis
"description": "Here's some free bitcoin for you",
"customerEmail": "customer email"
}
We will send a response with the lnurl withdrawal details
{
"status": true,
"message": "lnUrl Withdrawal successfully created",
"data": {
"tld": "https://sandboxapi.bitnob.co",
"identifier": "1b59fb916e0449d82a9e",
"lnUrl": "LNURL1DP68GURN8GHJ7UM5V9NKJMN894SHQ6FWVEKX7AM9WF6X7UPW0PUH5TMSDVHXZWPH8PNZUETYXD3RQDRYX3JXYVFJ89SNXC34VYHKCMN4WFK8WTE3VG6NJENZ8YCNVEFSXS6RJEPCXFSNJEG5MZMLE",
"lnUrlQR": "https://chart.googleapis.com/chart?chs=500x500&cht=qr&chl=LNURL1DP68GURN8GHJ7UM5V9NKJMN894SHQ6FWVEKX7AM9WF6X7UPW0PUH5TMSDVHXZWPH8PNZUETYXD3RQDRYX3JXYVFJ89SNXC34VYHKCMN4WFK8WTE3VG6NJENZ8YCNVEFSXS6RJEPCXFSNJEG5MZMLE",
"lnUrlTag": "withdrawalRequest",
"k1": "a578c66f1ae7",
"satMinWithdrawable": "1000",
"satMaxWithdrawable": "1000",
"identifierType": null,
"description": null,
"image": null,
"id": "ba23d74c-f5df-4f86-92ff-ba66145d3f9f",
"createdAt": "2021-12-05T01:43:43.021Z",
"updatedAt": "2021-12-05T01:43:43.021Z"
}
}