Enabling lightning invoice communication using deep links on Android

Workflow

The workflow starts with a Service Provider App(game, streaming service app, etc.) generating a lightning invoice for its users. Upon generating the invoice, Service Provider App enables a button that, when clicked, launches a Bitcoin Wallet App where the payment will be made. When the payment is confirmed and the invoice is paid, users are sent back to the Service Provider App where they came from.

Registering an Intent Filter in the Wallet App

To facilitate communication, the Wallet app, must be capable of receiving and processing deep links. This is achieved by registering an intent filter within the app. Intent filters specify which Intents that are sent in the Android system can trigger and be handled by this app. In our case that is any Intent that contains a URI with a "lightning" scheme which indicates that the link pertains to a payment for a lightning invoice.

Example of an AndroidManifest.xml file where the intent filters are registered:

<activity
     android:name=".AppLinksActivity"
     android:exported="true">
     <intent-filter>
          <action android:name="android.intent.action.VIEW" />

          <category android:name="android.intent.category.DEFAULT" />
          <category android:name="android.intent.category.BROWSABLE" />

          <data android:scheme="lightning" />
      </intent-filter>
</activity>

Launching Wallet App from Service Provider App

When the user clicks the payment button in the Service Provider App, the app constructs an ACTION_VIEW Intent containing the URI with the "lightning" scheme which may look like "lightning:///{lightningInvoice}". The intent is then sent to the Android system to be resolved and launched.

Paying the Lightning Invoice in the Wallet App

Upon receiving the intent, the Android system identifies the Wallet App as the appropriate recipient based on the registered intent filter. If there are more than one app that can handle the same Intent, the app chooser is presented by the system. Wallet App then retrieves the lightningInvoice data from the Intent that launched it and completes the payment. The Wallet app may prompt the user for authentication or any other necessary steps to complete the transaction securely.

Returning to the Service Provider App

After the payment process in Wallet App is successfully completed, the Android system ensures that Service Provider App is correctly restored to its previous state. This behavior is managed through the task and back stack mechanism, which retains information about the activities in both apps.

Once the payment process is finished, Wallet App calls the finish() method to close itself and return to the previous task. If the user had directly launched the Wallet App from the launcher (without going through the Service Provider App), the system would restore the task associated with the Wallet App, and the user would stay in the Wallet App after the payment is completed. However, because the user initially launched the Wallet App from the Service Provider App using an ACTION_VIEW Intent, the Android system maintains a record of this task's origin. The system recognises that the task for Wallet App was started by Service Provider App and that the user should return to the Service Provider App after finishing itself.