Receiving payments via mobile notifications

The Breez SDK provides users the 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. To use this feature, you need to set up a webhook that an LSP can call when a payment is received and register it in the Breez SDK. This webhook, a URL endpoint in your application, will handle incoming payment notifications. This URL should be capable of receiving POST requests. The payment received webhook payload is json formatted and contains the following structure:

{
 "template": "payment_received",
 "data": {  
  "payment_hash": [payment hash]
 }
}

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

You will need to run your own NDS because the NDS is configured to send push notifications to your app users and therefore should be configured with the required keys and certificates.

You can use our reference NDS implementation.

Our NDS implementation expects URLs in the following format:

 https://your-nds-service.com/notify?platform=&token=[PUSH_TOKEN]

Once the NDS has received such request it will send a push notification to the corresponding devices.

Step 2: Obtain a mobile push token

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 a webhook

Register the constructed URL with the Breez SDK By calling the register-payment-webook API as follows:

sdk.register_webhook(
    "https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>".to_string(),
)
.await?;

try sdk.registerWebhook(webhookUrl: "https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>")  

try {
    sdk.registerWebhook("https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>")
} catch (e: Exception) {
    // Handle error
}

try {
  await registerWebhook('https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>')
} catch (err) {
  console.error(err)
}

await BreezSDK().registerWebhook(webhookUrl: "https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>");  

sdk_services.register_webhook("https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>")

if err := sdk.RegisterWebhook("https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>"); err != nil {
    log.Printf("Webhook registration failed: %v", err)
}

try
{
    sdk.RegisterWebhook("https://your-nds-service.com/notify?platform=ios&token=<PUSH_TOKEN>");
}
catch (Exception)
{
    // Handle error
}

Step 4: Handling notifications when the app isn't 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.

• For iOS, please follow the steps in iOS NotificationServiceExtension.

• For Android, please follow the steps in Android foreground service.