94 lines
2.9 KiB
Groff
94 lines
2.9 KiB
Groff
.TH "LIGHTNING-WAITANYINVOICE" "7" "" "" "lightning-waitanyinvoice"
|
|
.SH NAME
|
|
lightning-waitanyinvoice - Command for waiting for payments
|
|
.SH SYNOPSIS
|
|
|
|
\fBwaitanyinvoice\fR [\fIlastpay_index\fR] [\fItimeout\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBwaitanyinvoice\fR RPC command waits until an invoice is paid, then
|
|
returns a single entry as per \fBlistinvoice\fR\. It will not return for
|
|
any invoices paid prior to or including the \fIlastpay_index\fR\.
|
|
|
|
|
|
This is usually called iteratively: once with no arguments, then
|
|
repeatedly with the returned \fIpay_index\fR entry\. This ensures that no
|
|
paid invoice is missed\.
|
|
|
|
|
|
The \fIpay_index\fR is a monotonically-increasing number assigned to an
|
|
invoice when it gets paid\. The first valid \fIpay_index\fR is 1; specifying
|
|
\fIlastpay_index\fR of 0 equivalent to not specifying a \fIlastpay_index\fR\.
|
|
Negative \fIlastpay_index\fR is invalid\.
|
|
|
|
|
|
If \fItimeout\fR is specified, wait at most that number of seconds, which
|
|
must be an integer\.
|
|
If the specified \fItimeout\fR is reached, this command will return with an
|
|
error\.
|
|
You can specify this to 0 so that \fBwaitanyinvoice\fR will return
|
|
immediately with an error if no pending invoice is available yet\.
|
|
If unspecified, this command will wait indefinitely\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBlabel\fR (string): unique label supplied at invoice creation
|
|
.IP \[bu]
|
|
\fBdescription\fR (string): description used in the invoice
|
|
.IP \[bu]
|
|
\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR which will prove payment (always 64 characters)
|
|
.IP \[bu]
|
|
\fBstatus\fR (string): Whether it's paid or expired (one of "paid", "expired")
|
|
.IP \[bu]
|
|
\fBexpires_at\fR (u64): UNIX timestamp of when it will become / became unpayable
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat, optional): the amount required to pay this invoice
|
|
.IP \[bu]
|
|
\fBbolt11\fR (string, optional): the BOLT11 string (always present unless \fIbolt12\fR is)
|
|
.IP \[bu]
|
|
\fBbolt12\fR (string, optional): the BOLT12 string (always present unless \fIbolt11\fR is)
|
|
|
|
.RE
|
|
|
|
If \fBstatus\fR is "paid":
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBpay_index\fR (u64): Unique incrementing index for this payment
|
|
.IP \[bu]
|
|
\fBamount_received_msat\fR (msat): the amount actually received (could be slightly greater than \fIamount_msat\fR, since clients may overpay)
|
|
.IP \[bu]
|
|
\fBpaid_at\fR (u64): UNIX timestamp of when it was paid
|
|
.IP \[bu]
|
|
\fBpayment_preimage\fR (hex): proof of payment (always 64 characters)
|
|
|
|
.RE
|
|
|
|
Possible errors are:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
904\.
|
|
The \fItimeout\fR was reached without an invoice being paid\.
|
|
|
|
.RE
|
|
.SH AUTHOR
|
|
|
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-waitinvoice\fR(7), \fBlightning-listinvoice\fR(7),
|
|
\fBlightning-delinvoice\fR(7), \fBlightning-invoice\fR(7)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
\" SHA256STAMP:df915f7735c2d5d229f2609bcf3d19fafc568ede0144d4137836d6e6af541a3b
|