mirror of
https://github.com/aljazceru/breez-sdk-docs.git
synced 2025-12-17 05:44:20 +01:00
Merge branch 'lnurlpay' of github.com:breez/breez-sdk-docs into lnurlpay
* 'lnurlpay' of github.com:breez/breez-sdk-docs: Update lnurlpay.md Update lnurlpay.md Update SUMMARY.md Update SUMMARY.md
This commit is contained in:
Roei Erez
@@ -12,15 +12,15 @@
|
||||
- [Receiving payments via mobile notifications](guide/payment_notification.md)
|
||||
- [iOS](guide/ios_notification_service_extension.md)
|
||||
- [Android](guide/android_notification_foreground_service.md)
|
||||
- [Receiving payments via lnurlpay](guide/lnurlpay.md)
|
||||
- [Connecting to an LSP](guide/connecting_lsp.md)
|
||||
- [Receiving an on-chain transaction](guide/receive_onchain.md)
|
||||
- [Sending an on-chain transaction](guide/send_onchain.md)
|
||||
|
||||
- [Using LNURL](guide/lnurl.md)
|
||||
- [LNURL-Pay](guide/lnurl_pay.md)
|
||||
- [LNURL-Withdraw](guide/lnurl_withdraw.md)
|
||||
- [LNURL-Auth](guide/lnurl_auth.md)
|
||||
- [Sending payments using LNURL-Pay](guide/lnurl_pay.md)
|
||||
- [Receiving payments using LNURL-Pay](guide/lnurlpay.md)
|
||||
- [Receiving payments using LNURL-Withdraw](guide/lnurl_withdraw.md)
|
||||
- [Authenticating using LNURL-Auth](guide/lnurl_auth.md)
|
||||
- [Supporting fiat currencies](guide/fiat_currencies.md)
|
||||
- [Buying Bitcoin](guide/buy_btc.md)
|
||||
- [Exporting channels backup](guide/static_channel_backup.md)
|
||||
|
||||
@@ -1,45 +1,49 @@
|
||||
# Receiving via lnurl-pay
|
||||
# Receiving payments using LNURL-Pay
|
||||
|
||||
Using the Breez SDK users have the ability to receive Lightning payments via lnurl-pay.
|
||||
The lnurlpay protocol requires a web server that respons to lnurlpay requests. This service needs to communicate with the user node in order to fetch the required data and the payment request.
|
||||
In order to interact with the user node the service uses a simple protocol over push notifications.
|
||||
The service sends a push notification to the user node with the lnurlpay request and a reply url, the user node then uses the reply url to responds with the required data which is then forwarded from the service to the payer.
|
||||
Breez SDK users have the ability to receive Lightning payments using [LNURL-Pay](https://github.com/lnurl/luds/blob/luds/06.md).
|
||||
|
||||
LNURL-Pay requires a web service that serves LNURL-Pay requests. This service needs to communicate with the user node in order to fetch the necessary metadata data and the associated payment request.
|
||||
To interact with the user node, the service uses a simple protocol over push notifications:
|
||||
* The service sends a push notification to the user's mobile app with the LNURL-Pay request and a reply URL.
|
||||
* The app responds to reply URL with the required data.
|
||||
* The data is forwarded from the service to the payer.
|
||||
|
||||
## General workflow
|
||||
The protocol is application specific and the steps detiled below refer to the c-breez wallet implementation which requires running <b>[breez-lnurl](https://github.com/breez/breez-lnurl) </b>service.
|
||||
|
||||
### Step 1: User node register for an lnurlpay service
|
||||
Use a POST request to the service endpoint <b>https://app.domain/lnurlpay/[pubkey]</b> to register the user node for an lnurlpay service.
|
||||
This request should contain the following payload:
|
||||
<section>
|
||||
<pre>
|
||||
### Step 1: Registering for an LNURL-Pay service
|
||||
Use a POST request to the service endpoint:
|
||||
|
||||
```
|
||||
https://app.domain/lnurlpay/[pubkey]
|
||||
```
|
||||
With the following payload:
|
||||
|
||||
```
|
||||
{
|
||||
"time": "seconds since epoch",
|
||||
"webhook_url": "notification service webhook url",
|
||||
"signature": "signed payload"
|
||||
}
|
||||
</pre>
|
||||
</section>
|
||||
```
|
||||
|
||||
to register the app for an LNURL-Pay service.
|
||||
The signature is refers to the following string: ```[time]-[webhook_url]``` where ```time``` and ```webhook_url``` are the payload fields.
|
||||
|
||||
In order to verify the request the following payload fields should be signed with the user node private key: <b>[time]-[webhook_url]</b>.
|
||||
The service responds with following payload:
|
||||
<section>
|
||||
<pre>
|
||||
```>
|
||||
{
|
||||
"lnurl": "[valid lnurlpay url]",
|
||||
"lnurl": "https://app.domain.com/lnurlp/[pubkey]",
|
||||
}
|
||||
</pre>
|
||||
</section>
|
||||
```
|
||||
|
||||
### Step 2: Processing an LNURL-Pay request
|
||||
When an LNURL-Pay request is triggered a GET request to:
|
||||
```
|
||||
https://app.domain.com/lnurlp/[pubkey]
|
||||
```
|
||||
The service then sends a push notification to the app with the LNURL-Pay request and a callback URL. Such payload may look like the following:
|
||||
|
||||
### Step 2: External wallet scans the lnurlpay url
|
||||
The external wallet scans the lnurlpay url and parse the lnurlpay request.
|
||||
It then behaves according to the lnurlpay protocol and performs a GET request to the scanned lnurl pay url.
|
||||
This hits the service which in respond sends a push notification to the user node with the lnurlpay request and a callback url. Such payload may look like this:
|
||||
|
||||
<section>
|
||||
<pre>
|
||||
```
|
||||
{
|
||||
"template": "lnurlpay_info",
|
||||
"data": {
|
||||
@@ -47,17 +51,15 @@ This hits the service which in respond sends a push notification to the user nod
|
||||
"callback_url": https://app.domain.com/lnurlpay/invoice
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</section>
|
||||
```
|
||||
|
||||
The <b>reply_url</b> is used by the user node to respond to the lnurlpay request.
|
||||
The <b>callback_url</b> is the lnurlpay callback url for the payer to fetch the invoice.
|
||||
The <b>reply_url</b> is used by the app to respond to the lnurlpay request.
|
||||
The <b>callback_url</b> s the LNURL-Pay callback URL, used by the payer to fetch the invoice.
|
||||
|
||||
### Step 3: User node responds to the callback url
|
||||
The user node receives the push notification, parses the payload and then uses the reply_url to responds with the required data as per the lnurlpay protocol, for example:
|
||||
### Step 3: Responding to the callback url
|
||||
When the app receives the push notification, it parses the payload and then uses the reply_url to respond with the required data, for example:
|
||||
|
||||
<section>
|
||||
<pre>
|
||||
```
|
||||
{
|
||||
"callback": "https://app.domain.com/lnurlpay/invoice",
|
||||
"maxSendable": 10000,
|
||||
@@ -65,20 +67,22 @@ The user node receives the push notification, parses the payload and then uses t
|
||||
"metadata": "[[\"text/plain\",\"Pay to Breez\"]]",
|
||||
"tag": "payRequest"
|
||||
}
|
||||
</pre>
|
||||
</section>
|
||||
```
|
||||
|
||||
The service receives the response from the mobile and forward the response to the external wallet.
|
||||
The service receives the response from the app and forwards it to the sender.
|
||||
|
||||
### step 4: External wallet fetches the invoice
|
||||
### Step 4: Fetching a bolt11 invoice
|
||||
|
||||
The external wallet uses the callback_url to fetch the invoice and perform a GET request with the amount as a parameter. In our example it is: <b>https://app.domain.com/lnurlpay/invoice?amount=1000</b>
|
||||
The push notification is used again to send the request to the user node and the user node replies with the invoice.
|
||||
The sender fetchs a bolt11 invoice by invoking a GET request to the callback_url with adding a specific amount as a query parameter. For example:
|
||||
```
|
||||
https://app.domain.com/lnurlpay/invoice?amount=1000
|
||||
```
|
||||
An additional push notification is triggered to send the invoice request to the app. Then the app replied with the bolt11 invoice data.
|
||||
|
||||
### step 5: External wallet pays the invoice
|
||||
This is the last step in the lnurlpay protocol, the external wallet pays the invoice and the payment is received by the user node. See [payment_notification](payment_notification.md) for more details on how to receive payments via push notifications.
|
||||
### Step 5: Paying the invoice
|
||||
In the last step, the payer pays the received bolt11 invoice. Follow the steps [here](payment_notification.md) to receive payments via push notifications.
|
||||
|
||||
## Reference implementation
|
||||
All the above steps are payloads are one option among many, the service and the user node can agree on any other payload format.
|
||||
For a complete reference, see how we implemented it in c-breez wallet: [NotificationService.swift](https://github.com/breez/c-breez/blob/main/ios/Breez%20Notification%20Service%20Extension/NotificationService.swift).
|
||||
And the lnurlpay service: [breez-lnurl](https://github.com/breez/breez-lnurl)
|
||||
For a complete reference implementation, see:
|
||||
* [Breez's NotificationService](https://github.com/breez/c-breez/blob/main/ios/Breez%20Notification%20Service%20Extension/NotificationService.swift)
|
||||
* [Breez's LNURL-Pay service](https://github.com/breez/breez-lnurl)
|
||||
|
||||
Reference in New Issue
Block a user