core-lightning/doc/lightning-invoice.7

.TH "LIGHTNING-INVOICE" "7" "" "" "lightning-invoice"
.SH NAME
lightning-invoice - Command for accepting payments
.SH SYNOPSIS

\fBinvoice\fR \fImsatoshi\fR \fIlabel\fR \fIdescription\fR [\fIexpiry\fR]
[\fIfallbacks\fR] [\fIpreimage\fR] [\fIexposeprivatechannels\fR] [\fIcltv\fR]

.SH DESCRIPTION

The \fBinvoice\fR 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
\fIroute hint\fR description of an incoming channel with capacity to pay the
invoice, if any exists\.


The \fImsatoshi\fR parameter can be the string "any", which creates an
invoice that can be paid with any amount\. Otherwise it is a positive value in
millisatoshi precision; it can be a whole number, or a whole number
ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending
in \fIsat\fR, or a number with 1 to 11 decimal places ending in \fIbtc\fR\.


The \fIlabel\fR 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 \fIdescription\fR is a short description of purpose of payment, e\.g\. \fI1
cup of coffee\fR\. 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 \fI\u\fR JSON escape codes\.


The \fIexpiry\fR is optionally the time the invoice is valid for; without a
suffix it is interpreted as seconds, otherwise suffixes \fIs\fR, \fIm\fR, \fIh\fR,
\fId\fR, \fIw\fR indicate seconds, minutes, hours, days and weeks respectively\.
If no value is provided the default of 604800 (1w) is used\.


The \fIfallbacks\fR 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 \fIpreimage\fR 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\. \fBIMPORTANT\fR: if you specify the
\fIpreimage\fR, 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, \fIexposeprivatechannels\fR overrides the default route hint
logic, which will use unpublished channels only if there are no
published channels\. If \fItrue\fR unpublished channels are always considered
as a route hint candidate; if \fIfalse\fR, never\.  If it is a short channel id
(e\.g\. \fI1x1x3\fR) or array of short channel ids, only those specific channels
will be considered candidates, even if they are public or dead-ends\.


The route hint is selected from the set of incoming channels of which:
peer’s balance minus their reserves is at least \fImsatoshi\fR, state is
normal, the peer is connected and not a dead end (i\.e\. has at least one
other public channel)\. The selection uses some randomness to prevent
probing, but favors channels that become more balanced after the
payment\.


If specified, \fIcltv\fR sets the \fImin_final_cltv_expiry\fR for the invoice\.
Otherwise, it's set to the parameter \fBcltv-final\fR\.

.SH RETURN VALUE

On success, an object is returned, containing:

.RS
.IP \[bu]
\fBbolt11\fR (string): the bolt11 string
.IP \[bu]
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
.IP \[bu]
\fBpayment_secret\fR (hex): the \fIpayment_secret\fR to place in the onion (always 64 characters)
.IP \[bu]
\fBexpires_at\fR (u64): UNIX timestamp of when invoice expires

.RE

The following warnings may also be returned:

.RS
.IP \[bu]
\fBwarning_capacity\fR: even using all possible channels, there's not enough incoming capacity to pay this invoice\.
.IP \[bu]
\fBwarning_offline\fR: there would be enough incoming capacity, but some channels are offline, so there isn't\.
.IP \[bu]
\fBwarning_deadends\fR: there would be enough incoming capacity, but some channels are dead-ends (no other public channels from those peers), so there isn't\.
.IP \[bu]
\fBwarning_private_unused\fR: there would be enough incoming capacity, but some channels are unannounced and \fIexposeprivatechannels\fR is \fIfalse\fR, so there isn't\.
.IP \[bu]
\fBwarning_mpp\fR: there is sufficient capacity, but not in a single channel, so the payer will have to use multi-part payments\.

.RE

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


The following error codes may occur:

.RS
.IP \[bu]
-1: Catchall nonspecific error\.
.IP \[bu]
900: An invoice with the given \fIlabel\fR already exists\.
.IP \[bu]
901: An invoice with the given \fIpreimage\fR already exists\.
.IP \[bu]
902: None of the specified \fIexposeprivatechannels\fR were usable\.

.RE
.SH AUTHOR

Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.

.SH SEE ALSO

\fBlightning-listinvoices\fR(7), \fBlightning-delinvoice\fR(7), \fBlightning-pay\fR(7)\.

.SH RESOURCES

Main web site: \fIhttps://github.com/ElementsProject/lightning\fR

\" SHA256STAMP:d88271f45513d2811f76d476cc94b3354f3d307448913762eee3069120444793