lightning-invoice.7.txt

LIGHTNING-INVOICE(7)
====================
:doctype: manpage

NAME
----
lightning-invoice - Command for accepting payments.

SYNOPSIS
--------
*invoice* 'msatoshi' 'label' 'description' ['expiry'] ['fallbacks'] ['preimage'] ['exposeprivatechannels']

DESCRIPTION
-----------
The *invoice* RPC command creates the expectation of a payment of a
given amount of milli-satoshi: it returns a unique token which another
lightning daemon can use to pay this invoice.  This token includes a
'route hint' description of an incoming channel with capacity to pay
the invoice, if any exists.

The 'msatoshi' parameter can be the string "any", which creates an invoice
that can be paid with any amount.  Otherwise it is in millisatoshi
precision; it can be a whole number, or a whole number ending in 'msat' or
'sat', or a number with three decimal places ending in 'sat', or a number
with 1 to 11 decimal places ending in 'btc'.

The 'label' must be a unique string or number (which is treated as a
string, so "01" is different from "1"); it is never revealed to other
nodes on the lightning network, but it can be used to query the status
of this invoice.

The 'description' is a short description of purpose of payment,
e.g. '1 cup of coffee'. This value is encoded into the BOLT11 invoice
and is viewable by any node you send this invoice to.  It must be
UTF-8, and cannot use '\u' JSON escape codes.

The 'expiry' is optionally the time the invoice is valid for; without
a suffix it is interpreted as seconds, otherwise suffixes 's', 'm',
'h', 'd', 'w' indicate seconds, minutes, hours, days and weeks
respectively.  If no value is provided the default of 604800 (1w)
is used.

The 'fallbacks' array is one or more fallback addresses to include in
the invoice (in order from most-preferred to least): note that these
arrays are not currently tracked to fulfill the invoice.

The 'preimage' is a 64-digit hex string to be used as payment preimage
for the created invoice.
By default, if unspecified, lightningd will generate a secure
pseudorandom preimage seeded from an appropriate entropy source on
your system.
*IMPORTANT*: if you specify the 'preimage', you are responsible, to
ensure appropriate care for generating using a secure pseudorandom
generator seeded with sufficient entropy, and keeping the preimage
secret.
This parameter is an advanced feature intended for use with cutting-edge
cryptographic protocols and should not be used unless explicitly needed.

If specified, 'exposeprivatechannels' overrides the default route hint
logic, which will use unpublished channels only if there are no
published channels.  If 'true' unpublished channels are always
considered as a route hint candidate; if 'false', never.

RETURN VALUE
------------

On success, a hash is returned as 'payment_hash' to be given to the payer,
and the 'expiry_time' as a UNIX timestamp.
It also returns a BOLT11 invoice as 'bolt11' to be given to the
payer.

On failure, an error is returned and no invoice is created.  If the
lightning process fails before responding, the caller should use
lightning-listinvoice(7) to query whether this invoice was created or not.

The following error codes may occur:

* -1. Catchall nonspecific error.
* 900. An invoice with the given 'label' already exists.
* 901. An invoice with the given 'preimage' already exists.

One of the following warnings may occur (on success):

* 'warning_offline' if no channel with a currently
  connected peer has the incoming capacity to pay this invoice
* 'warning_capacity' if there is no channel at all with sufficient
  incoming capacity to pay this invoice.

AUTHOR
------
Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO
--------
lightning-listinvoice(7), lightning-delinvoice(7),
lightning-getroute(7), lightning-sendpay(7).

RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning