mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 02:27:51 +01:00
2ddecdc95a
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
140 lines
4.3 KiB
Groff
Generated
140 lines
4.3 KiB
Groff
Generated
.TH "LIGHTNING-WAITSENDPAY" "7" "" "" "lightning-waitsendpay"
|
|
.SH NAME
|
|
lightning-waitsendpay - Command for sending a payment via a route
|
|
.SH SYNOPSIS
|
|
|
|
\fBwaitsendpay\fR \fIpayment_hash\fR [\fItimeout\fR] [\fIpartid\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBwaitsendpay\fR RPC command polls or waits for the status of an
|
|
outgoing payment that was initiated by a previous \fBsendpay\fR
|
|
invocation\.
|
|
|
|
|
|
The \fIpartid\fR argument must match that of the \fBsendpay\fR command\.
|
|
|
|
|
|
Optionally the client may provide a \fItimeout\fR, an integer in seconds,
|
|
for this RPC command to return\. If the \fItimeout\fR is provided and the
|
|
given amount of time passes without the payment definitely succeeding or
|
|
definitely failing, this command returns with a 200 error code (payment
|
|
still in progress)\. If \fItimeout\fR is not provided this call will wait
|
|
indefinitely\.
|
|
|
|
|
|
Indicating a \fItimeout\fR of 0 effectively makes this call a pollable query
|
|
of the status of the payment\.
|
|
|
|
|
|
If the payment completed with success, this command returns with
|
|
success\. Otherwise, if the payment completed with failure, this command
|
|
returns an error\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBid\fR (u64): unique ID for this payment attempt
|
|
.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): status of the payment (always "complete")
|
|
.IP \[bu]
|
|
\fBcreated_at\fR (u64): the UNIX timestamp showing when this payment was initiated
|
|
.IP \[bu]
|
|
\fBamount_sent_msat\fR (msat): The amount sent
|
|
.IP \[bu]
|
|
\fBamount_msat\fR (msat, optional): The amount delivered to destination (if known)
|
|
.IP \[bu]
|
|
\fBdestination\fR (pubkey, optional): the final destination of the payment if known
|
|
.IP \[bu]
|
|
\fBlabel\fR (string, optional): the label, if given to sendpay
|
|
.IP \[bu]
|
|
\fBpartid\fR (u64, optional): the \fIpartid\fR, if given to sendpay
|
|
.IP \[bu]
|
|
\fBbolt11\fR (string, optional): the bolt11 string (if pay supplied one)
|
|
.IP \[bu]
|
|
\fBbolt12\fR (string, optional): the bolt12 string (if supplied for pay: \fBexperimental-offers\fR only)\.
|
|
|
|
.RE
|
|
|
|
If \fBstatus\fR is "complete":
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBpayment_preimage\fR (hex): the proof of payment: SHA256 of this \fBpayment_hash\fR (always 64 characters)
|
|
|
|
.RE
|
|
|
|
On error, and even if the error occurred from a node other than the
|
|
final destination, the route table will no longer be updated\. Use the
|
|
\fIexclude\fR parameter of the \fBgetroute\fR command to ignore the failing
|
|
route\.
|
|
|
|
|
|
The following error codes may occur:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
-1: Catchall nonspecific error\.
|
|
.IP \[bu]
|
|
200: Timed out before the payment could complete\.
|
|
.IP \[bu]
|
|
202: Unparseable onion reply\. The \fIdata\fR field of the error will
|
|
have an \fIonionreply\fR field, a hex string representation of the raw
|
|
onion reply\.
|
|
.IP \[bu]
|
|
203: Permanent failure at destination\. The \fIdata\fR field of the error
|
|
will be routing failure object\.
|
|
.IP \[bu]
|
|
204: Failure along route; retry a different route\. The \fIdata\fR field
|
|
of the error will be routing failure object\.
|
|
.IP \[bu]
|
|
208: A payment for \fIpayment_hash\fR was never made and there is
|
|
nothing to wait for\.
|
|
.IP \[bu]
|
|
209: The payment already failed, but the reason for failure was not
|
|
stored\. This should only occur when querying failed payments on very
|
|
old databases\.
|
|
|
|
.RE
|
|
|
|
A routing failure object has the fields below:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fIerring_index\fR: The index of the node along the route that reported
|
|
the error\. 0 for the local node, 1 for the first hop, and so on\.
|
|
.IP \[bu]
|
|
\fIerring_node\fR: The hex string of the pubkey id of the node that
|
|
reported the error\.
|
|
.IP \[bu]
|
|
\fIerring_channel\fR: The short channel ID of the channel that has the
|
|
error (or the final channel if the destination raised the error)\.
|
|
.IP \[bu]
|
|
\fIerring_direction\fR: The direction of traversing the
|
|
\fIerring_channel\fR:
|
|
.IP \[bu]
|
|
\fIfailcode\fR: The failure code, as per BOLT #4\.
|
|
.IP \[bu]
|
|
\fIfailcodename\fR: The human-readable name corresponding to \fIfailcode\fR,
|
|
if known\.
|
|
|
|
.RE
|
|
.SH AUTHOR
|
|
|
|
ZmnSCPxj \fI<ZmnSCPxj@protonmail.com\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-sendpay\fR(7), \fBlightning-pay\fR(7)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
\" SHA256STAMP:50109bd21f9b8cdd35b0cb5ed2d20064190c6ae841179dc08817610a305c0f10
|