aljaz/breez-sdk-docs
1
0
Fork 0
mirror of https://github.com/aljazceru/breez-sdk-docs.git synced 2025-12-18 06:14:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update payment_notification.md

Browse Source
This commit is contained in:
Roy Sheinfeld
2023-12-17 15:14:34 +02:00
committed by GitHub
parent 4215047124
commit 9fe892b709
1 changed files with 36 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
src/guide/payment_notification.md
View File

@@ -1,16 +1,16 @@
# Receiving Payment Notifications via Webhook in Breez SDK
# Receiving payments via mobile notifications
## Overview
The Breez SDK provides a robust feature for applications to receive real-time notifications for incoming payments over the Lightning Network. This is achieved through the use of webhooks. A webhook is a powerful tool that allows your application to be notified via a specified URL when a payment is about to be received.
The Breez SDK provides usersthe ability to receive Lightning payments via mobile notifications. It uses a webhook that allows your application to be notified (via a pre-specified URL) when a payment is about to be received.
## Setting Up the Webhook
To utilize this feature, you need to set up a webhook that the LSP can call when a payment is received.
## Setting up a webhook
To use this feature, you need to set up a webhook that an LSP can call when a payment is received.
### Step 1: Define Your Webhook URL
First, you need to define the URL endpoint in your application that will handle incoming payment notifications. This URL should be capable of receiving POST requests.
### Step 1: Define your webhook URL
Firstly, you need to define the URL endpoint in your application that will handle incoming payment notifications. This URL should be capable of receiving POST requests.
### Step 2: Register the Webhook with Breez
Next, register this URL with the Breez SDK. This step involves calling a specific SDK function.
### Step 2: Register your Webhook
Next, register this URL with the Breez SDK. This step involves calling the register-webook API as follows:
<custom-tabs category="lang">
<div slot="title">Rust</div>
@@ -79,10 +79,10 @@ Next, register this URL with the Breez SDK. This step involves calling a specifi
</custom-tabs>
## Handling Incoming Notifications
## Handling incoming notifications
When a payment is received, the LSP will send a POST request to your webhook URL. The request body will contain details about the payment.
### Expected Webhook Payload
### Expected webhook payload
The payment received webhook payload is json formatted and contains the following structure:
<section>
@@ -96,29 +96,27 @@ The payment received webhook payload is json formatted and contains the followin
</pre>
</section>
## Processing the Payload
Processing of the Payload can be done according to the application's needs. One of the major use cases that can be handled via webhooks is receiving a payment in a mobile app while the app is not running, or in short "offline receive"
## Webhook integration for "offline receive"
In the context of mobile applications using the Breez SDK for Lightning Network payments, a crucial architectural component involves the seamless flow of payment notifications to the user's mobile device. This process is facilitated through a Notification Delivery Service (NDS) acting as an intermediary. When a payment is made to a user, the LSP sends a notification to the NDS configured with a specific webhook URL. The NDS then processes this information and dispatches a push notification to the intended mobile device, ensuring the user receives timely updates about incoming payments. This architecture necessitates vendors setting up and maintaining their own NDS, tailored to handle and forward these notifications efficiently.
## Webhook integration for receiving payments while the app isn't running
You can use this webhook to allow mobile users to receive Lightning payments even if they aren't running the app at the time of the payment. This process involves using a Notification Delivery Service (NDS) acting as an intermediary. When a payment is made to a user, the LSP sends a notification to the NDS configured with a specific webhook URL. The NDS then processes this information and dispatches a push notification to the intended mobile device, ensuring the user receives timely updates about incoming payments. This architecture necessitates vendors setting up and maintaining their own NDS, tailored to handle and forward these notifications efficiently.
### Step 1: Run your own NDS
As written above you will need to run your own NDS because the NDS is configured to send push notifications to your app users, therefore configured with the required keys and certificates.
If you don't want to write it from scratch, you can use our own <a href="https://github.com/breez/notify">NDS</a> implementation.
You will need to run your own NDS because the NDS is configured to send push notifications to your app users, therefore configured with the required keys and certificates.
You can use our [reference NDS implementation](https://github.com/breez/notify).
Our NDS implementation expects URLs in the following format:
<section><i>https://your-nds-service.com/notify?platform=<ios|android>&token=[PUSH_TOKEN]</i></section>
Once the NDS has received such request it will send a push notification to the matched device.
Once the NDS has received such request it will send a push notification to the corresponding devices.
### Step 2: Obtain a mobile push token
First, ensure that your mobile application is set up to receive push notifications and can generate a push token. This token uniquely identifies the device for push notifications.
Ensure that your mobile application is set up to receive push notifications and can generate a push token. This token uniquely identifies the device for push notifications.
* For iOS, use Apple Push Notification Service (APNs) to get the token.
* For Android, use Firebase Cloud Messaging (FCM) to obtain the token.
### Step 3: Register the Webhook with Breez
Register the constructed URL with the Breez SDK By calling an SDK function.
### Step 3: Register a webhook
Register the constructed URL with the Breez SDK By calling the register-payment-webook API as follows:
<custom-tabs category="lang">
<div slot="title">Rust</div>
@@ -187,43 +185,40 @@ Register the constructed URL with the Breez SDK By calling an SDK function.
</custom-tabs>
## Step 4: Handling Notifications When the App is Not Running
## Step 4: Handling notifications when the app is'nt running
To ensure that your mobile application can handle payment notifications even when it is not actively running, specific implementations are required for both iOS and Android platforms. This involves waking up the app upon receiving a push notification, connecting with the Breez SDK, and then waiting for the payment to be fully received.
### iOS Implementation Using NotificationServiceExtension
### iOS: using NotificationServiceExtension
#### Overview
For iOS, the app must use NotificationServiceExtension to process notifications in the background.
#### Steps for Implementation
* Integrate NotificationServiceExtension: Add NotificationServiceExtension to your iOS project. This extension allows your app to process the incoming push notification data in the background before presenting it to the user.
#### Implementation
* Integrate NotificationServiceExtension: add NotificationServiceExtension to your iOS project. This extension allows your app to process the incoming push notification data in the background before presenting it to the user.
* Wake Up the App: When a push notification is received, the NotificationServiceExtension will be triggered, waking up the app.
* Wake-up the app: when a push notification is received, the NotificationServiceExtension will be triggered, waking up the app.
* Connect with Breez SDK: Inside the extension, implement the logic for establishing a connection with the Breez SDK to process the incoming payment.
* Connect with Breez SDK: in the extension, establish a connection with the Breez SDK to process the incoming payment.
* Wait for Payment Completion: Once connected, the app should wait for completion status from the Breez SDK that the payment has been received.
* Wait for payment completion: once connected, the app should wait for completion status from the Breez SDK that the payment has been received.
* Handle the Notification: After confirming the payment, handle the notification accordingly by updating the app's UI.
* Display a notification: after confirming the payment, display a notification.
As a reference implementation, see how we did it in c-breez wallet: <a href="https://github.com/breez/c-breez/blob/main/ios/Breez%20Notification%20Service%20Extension/NotificationService.swift">NotificationService.swift</a>
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).
### Android Implementation Using WorkManager
### Android: using WorkManager
#### Overview
On Android, WorkManager is used to perform background tasks when the app is not active.
#### Steps for Implementation
#### Implementation
* Integrate WorkManager: Add WorkManager to your Android project. This component allows the app to handle background tasks efficiently.
* Integrate WorkManager: add WorkManager to your Android project. This component allows the app to handle background tasks efficiently.
* Wake Up the App: Configure WorkManager to trigger a background task when a push notification for a payment is received.
* Wake-up the app: configure WorkManager to trigger a background task when a push notification for a payment is received.
* Connect with Breez SDK: In the background task, implement logic to establish a connection with the Breez SDK.
* Connect with Breez SDK: in the background task, establish a connection with the Breez SDK to process the incoming payment.
* Wait for payment completion: once connected, the app should wait for completion status from the Breez SDK that the payment has been received.
* Wait for Payment Completion: Once connected, the app should wait for completion status from the Breez SDK that the payment has been received.
* Handle the Notification: After confirming the payment, handle the notification accordingly by updating the app's UI.
## Conclusion
Implementing these mechanisms on both iOS and Android ensures that your application remains responsive to payment notifications via the Breez SDK, even when it is not running in the foreground.
* Display a notification: after confirming the payment, display a notification.