Skip to content Link Search Menu Expand Document Video
Text balloon containing a bitcoin.

Receiving bitcoin

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.

Receiving offline

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.

Screen showing a notification that is asking the user to open their wallet so they can receive their payment.

Notify the user that they have a payment incoming and that they should open their app to receive it.

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

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.

Receiving lightning payments

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.

Receiving on-chain payments

This wallet maintains a single lightning balance. To do this, while still allowing for on-chain sending and requesting, a LWS is used that conducts submarine swaps between lightning and on-chain.

Experimental options

Peerswap or collaborative funding may be more trustless options that do not require a third-party LWS to receive and send on-chain payments. However, these are not currently widely adopted.

Failed swaps

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.

Screen showing a warning error notification prompting the user to take action on their failed submarine swap.

If a swap fails, let the user know they need to take action with a persistent notification.

Screen showing the activity menu with an entry for the user to deal with their failed swap.

The activity menu is place where you can indicate to a user that their swap failed.

Screen showing an option for the user to retry the swap.

Make it easy for users to retry the swap or have a channel opened locally if the swap fails again.

Screen showing a form to send to an external on-chain address.

Users should have an option to withdraw to an external address if they wish.

Received payment

When this wallet receives a payment, it notifies the user. If any fees are paid, they are clear to the user when viewing the payment details. Users can save and share a receipt.

More information on presenting a payment history on our activity page.

Screen showing a payment has been received.

Notify the user once their incoming payment is received.

Screen showing an activity entry of a received payment with details on extra fees incurred for opening a channel.

Make it clear to the user if extra fees were incurred, such as from a new channel open.

Now, lets learn how sending bitcoin works.