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

NAME
     waitinvoice -- Command for waiting for specific payment

SYNOPSIS
     waitinvoice label

DESCRIPTION
     The  waitinvoice  RPC  command waits until a specific invoice is paid, then
     returns that single entry as per listinvoices.

     *	label (one of): Unique label of the invoice waiting to be paid.:
	*  (string)
	*  (integer)

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

     *	label (string): Unique label supplied at invoice creation.
     *	payment_hash (hash): The hash of the payment_preimage which  will  prove
	payment.
     *	status	(string)  (one	of  "paid", "expired"): Whether it's paid or ex-
	pired.
     *	expires_at (u64): UNIX timestamp of when it will  become  /  became  un-
	payable.
     *	created_index  (u64):  1-based	index  indicating order this invoice was
	created in. (added v23.08)
     *	description (string, optional): Description used in the invoice.
     *	amount_msat (msat, optional): The amount required to pay this invoice.
     *	bolt11 (string, optional): The	BOLT11	string	(always  present  unless
	bolt12 is).
     *	bolt12	(string,  optional):  The  BOLT12  string (always present unless
	bolt11 is).
     *	updated_index (u64, optional): 1-based index indicating order  this  in-
	voice  was  changed  (only  present  if  it has changed since creation).
	(added v23.08)

     If status is "paid": - pay_index (u64): Unique incrementing index for  this
     payment.	-  amount_received_msat  (msat):  The  amount  actually received
     (could be slightly greater than amount_msat, since clients may overpay).  -
     paid_at (u64): UNIX timestamp of when it was paid.  - payment_preimage (se-
     cret): Proof of payment.  - paid_outpoint (object, optional): Outpoint this
     invoice was paid with. (added v23.11): - txid (txid): ID of the transaction
     that paid the invoice. (added v23.11) - outnum (u32):  The  0-based  output
     number of the transaction that paid the invoice. (added v23.11)

ERRORS
     On error the returned object will contain code and message properties, with
     code being one of the following:

     *	-32602: If the given parameters are wrong.
     *	-1:  If the invoice is deleted while unpaid, or the invoice does not ex-
	ist.
     *	903: If the invoice expires before being paid, or is already expired.

AUTHOR
     Christian Decker decker.christian@gmail.com is mainly responsible.

SEE ALSO
     lightning-waitanyinvoice(7),  lightning-listinvoices(7),	lightning-delin-
     voice(7), lightning-invoice(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli waitinvoice -k "label"="inv2"

     {
       "id": "example:waitinvoice#1",
       "method": "waitinvoice",
       "params": {
	 "label": "inv2"
       }
     }

     Response:

     {
       "label": "inv2",
       "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
       "payment_hash": "paymenthashwaitinv0101010101010101010101010101010101010101010101",
       "amount_msat": 2000,
       "status": "paid",
       "pay_index": 5,
       "amount_received_msat": 2000,
       "paid_at": 1738500000,
       "payment_preimage": "paymentpreimagewaitinv0010101010101010101010101010101010101010101",
       "description": "inv2",
       "expires_at": 1739000000,
       "created_index": 13,
       "updated_index": 5
     }

     Example 2:

     Request:

     $ lightning-cli waitinvoice "inv3"

     {
       "id": "example:waitinvoice#2",
       "method": "waitinvoice",
       "params": [
	 "inv3"
       ]
     }

     Response:

     {
       "label": "inv3",
       "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv02020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
       "payment_hash": "paymenthashwaitinv0202020202020202020202020202020202020202020202",
       "amount_msat": 3000,
       "status": "paid",
       "pay_index": 6,
       "amount_received_msat": 3000,
       "paid_at": 1738500000,
       "payment_preimage": "paymentpreimagewaitinv0020202020202020202020202020202020202020202",
       "description": "inv3",
       "expires_at": 1739000000,
       "created_index": 14,
       "updated_index": 6
     }

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