mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
95 lines
3.4 KiB
Plaintext
95 lines
3.4 KiB
Plaintext
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' can be the string "any", which creates an invoice
|
|
that can be paid with any amount.
|
|
|
|
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 number of seconds the invoice is valid for.
|
|
If no value is provided the default of 3600 (1 Hour) 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
|