home | help 
LIGHTNING-INVOICE(7)					    LIGHTNING-INVOICE(7)

NAME
     invoice -- Command for accepting payments

SYNOPSIS
     invoice  amount_msat label description [expiry] [fallbacks] [preimage] [ex-
     poseprivatechannels] [cltv] [deschashonly]

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  de-
     scription	of  an incoming channel with capacity to pay the invoice, if any
     exists.

     *	amount_msat (msat_or_any): The string any, which creates an invoice that
	can be paid with any amount. Otherwise it is a positive  value	in  mil-
	lisatoshi  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.
     *	label (one of): 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  in-
	voice.:
	*  (string)
	*  (integer)
     *	description  (string): 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 (unless deschashonly is
	true as described below). It must be UTF-8, and cannot use \u  JSON  es-
	cape codes.
     *	expiry	(u64,  optional): The time the invoice is valid for, in seconds.
	If no value is provided the default of 604800 (1 week) is used.
     *	fallbacks (array of strings, optional): 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.:
	*  (string, optional)
     *	preimage  (hex,  optional):  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 keep-
	ing 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.
     *	exposeprivatechannels (one of, optional): If specified, it overrides the
	default  route	hint  logic, which will use unpublished channels only if
	there are no published channels.:
	*  (boolean): If True unpublished channels are always  considered  as  a
	   route hint candidate; if False, never.
	*  (array of short_channel_ids): Array of short channel ids (or a remote
	   alias),  only  those specific channels will be considered candidates,
	   even if they are public or dead-ends.
	*  (short_channel_id, optional)
	*  (short_channel_id): If it is a short channel id  (e.g.  1x1x3),  only
	   this  specific  channel  will  be considered candidate, even if it is
	   public or dead-end.
     *	cltv (u32, optional): If specified, sets the  min_final_cltv_expiry  for
	the invoice. Otherwise, it's set to the parameter cltv-final.
     *	deschashonly (boolean, optional): If True, then the bolt11 returned con-
	tains  a  hash	of  the description, rather than the description itself:
	this allows much longer descriptions, but they must be communicated  via
	some other mechanism. The default is False.

RETURN VALUE
     On success, an object is returned, containing:

     *	bolt11 (string): The bolt11 string.
     *	payment_hash  (hash):  The hash of the payment_preimage which will prove
	payment.
     *	payment_secret (secret): The payment_secret to place in the onion.
     *	expires_at (u64): UNIX timestamp of when invoice expires.
     *	created_index (u64): 1-based index indicating  order  this  invoice  was
	created in. (added v23.08)

     The following warnings may also be returned:

     *	warning_capacity:  Even  using all possible channels, there's not enough
	incoming capacity to pay this invoice.
     *	warning_offline: There would be enough incoming capacity, but some chan-
	nels are offline, so there isn't.
     *	warning_deadends: There would be  enough  incoming  capacity,  but  some
	channels  are  dead-ends (no other public channels from those peers), so
	there isn't.
     *	warning_private_unused: There would be	enough	incoming  capacity,  but
	some  channels	are  unannounced  and exposeprivatechannels is false, so
	there isn't.
     *	warning_mpp: There is sufficient capacity, but not in a single	channel,
	so the payer will have to use multi-part payments.

ERRORS
     On  failure,  an error is returned and no invoice is created. If the light-
     ning process fails before responding,  the  caller  should  use  lightning-
     listinvoices(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.
     *	902: None of the specified exposeprivatechannels were usable.

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

SEE ALSO
     lightning-listinvoices(7), lightning-delinvoice(7), lightning-xpay(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli invoice -k "amount_msat"=10000 "label"="lbl_l31" "description"="Invoice description l31"

     {
       "id": "example:invoice#1",
       "method": "invoice",
       "params": {
	 "amount_msat": 10000,
	 "label": "lbl_l31",
	 "description": "Invoice description l31"
       }
     }

     Response:

     {
       "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
       "expires_at": 1739000000,
       "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000",
       "payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000",
       "created_index": 2
     }

     Example 2:

     Request:

     $ lightning-cli invoice -k "amount_msat"="50000msat" "label"="lbl_l32" "description"="l32 description"

     {
       "id": "example:invoice#2",
       "method": "invoice",
       "params": {
	 "amount_msat": "50000msat",
	 "label": "lbl_l32",
	 "description": "l32 description"
       }
     }

     Response:

     {
       "payment_hash": "paymenthashinvl0320032003200320032003200320032003200320032003200",
       "expires_at": 1739000000,
       "bolt11": "lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000",
       "payment_secret": "paymentsecretinvl00032003200320032003200320032003200320032003200",
       "created_index": 3
     }

Core Lightning v26.06.1 				    LIGHTNING-INVOICE(7)
home | help