Your node may receive payments over Lightning by providing an invoice to payees, or spontaneously through the use of the experimental Keysend feature. Please see the comparison table below to assess suitability for your use case. Note that there is a similar table in the sends chapter, expressed from the perspective of the sending entity.
The AddInvoice endpoint adds an invoice to your node, and returns the add_index and a payment request for the invoice. The payment request encodes all of the information that sending nodes need to pay your node, and can be encoded into QR codes.
The following parameters are useful when adding an invoice:
lndmaintains two indexes on the invoices that it stores:
- Add index: a monotonically increasing index which indicates the order in which invoices were added.
- Settle index: a monotonically increasing index which indicates the order in which invoices were settled.
The SubscribeInvoices endpoint provides a stream of updates for lnd’s invoices, informing you about newly added invoices and sending notifications when they are settled. This endpoint supports historical streams, and can be queried with an add_index to query all invoices that were added after the index provided, or a settle_invoice to query all invoices that were settled after the invoice provided. This can be helpful for syncing up your program’s state after a restart. If you would like to subscribe to individual invoices, SubscribeSingleInvoice can be queried with the invoice’s payment hash as an identifier.
Alternatively, the invoices that your node has can be polled using the ListInvoices endpoint. The output of this call is paginated using add_index to order payments, and can be queried in reverse to list invoices from most to least recent.