Once a user has shared a payment request, the next step is receiving the payment. Ideally, there is no user action to take at this stage of the payment flow. However, there are things to consider and edge cases to deal with. This page covers how to design with these constraints in mind and gives an overview of how receiving a payment works.
Users can not receive lightning payments in a non-custodial manner when offline. This is problematic for a mobile wallet like this which is regularly offline. This means there will be times when a payment can not be received.
This wallet uses a lightning wallet server (LWS) to intercept and hold payments for offline users until they come online. The LWS sends a push notification to the user to open their wallet so the payment can be received.
To avoid payment failures, when generating a request, it’s indicated to the user that they should keep their wallet open until the payment is received. More on this here.
Offline payments, also known as async payments, are still not standards in the lightning ecosystem. Keep this in mind when developing your product. More on this on the lightning services page.
Once the user is online, a payment channel with inbound liquidity is required to receive a payment. If the user already has a payment channel with enough inbound liquidity, the payment will be received.
If the user does not have a channel open, or one with enough inbound liquidity, a new channel needs to be opened. Any additional fees required to open a channel need to be communicated to users when creating a payment request, and before they share it.
In this wallet channel opens and management are done by a lightning service provider (LSP). Channel opens happen on-demand and use zero confirmation channel opens so users can receive and spend their bitcoin instantly.
In the vast majority of scenarios, the submarine swap succeeds and the user is able to receive on-chain bitcoin to their lightning wallet without even thinking about this complex process happening behind the scenes. However, in some edge cases, the swap can fail for various reasons.
LWS swap service is offline
Receiving more than the users inbound capacity
Re-using a swap-address to receive another on-chain payment
When this occurs, the funds will show up as “pending” in the user’s activity, and a prompt on the home screen appears that lets the user know that an action needs to be taken. They are given two options to deal with this, either re-trying the swap or sending to an external on-chain address.
If the swap fails again, the wallet can open a new channel locally without using the LWS. The pending message can be the same, as the user doesn’t need to know the complexities of what is happening behind the scenes.