93 lines
3.0 KiB
Plaintext
93 lines
3.0 KiB
Plaintext
LIGHTNING-WAITSENDPAY(7)
|
|
========================
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
lightning-waitsendpay - Protocol for sending a payment via a route.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*waitsendpay* 'payment_hash' ['timeout']
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The *waitsendpay* RPC command polls or waits for the status of
|
|
an outgoing payment that was initiated by a previous *sendpay*
|
|
invocation.
|
|
|
|
Optionally the client may provide a 'timeout', an integer in
|
|
seconds, for this RPC command to return.
|
|
If the 'timeout' 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 'timeout' is not provided this call will wait indefinitely.
|
|
|
|
Indicating a 'timeout' 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.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
On success, an object similar to the output of *listpayments* will
|
|
be returned.
|
|
This object will have a 'status' field that is the
|
|
string '"complete"'.
|
|
|
|
On error, if the error occurred from a node other than the final
|
|
destination, the route table will be updated so that getroute(7)
|
|
should return an alternate route (if any). An error from the final
|
|
destination implies the payment should not be retried.
|
|
|
|
The following error codes may occur:
|
|
|
|
* -1. Catchall nonspecific error.
|
|
* 200. Timed out before the payment could complete.
|
|
* 202. Unparseable onion reply. The 'data' field of the error
|
|
will have an 'onionreply' field, a hex string representation
|
|
of the raw onion reply.
|
|
* 203. Permanent failure at destination. The 'data' field of
|
|
the error will be routing failure object.
|
|
* 204. Failure along route; retry a different route. The 'data'
|
|
field of the error will be routing failure object.
|
|
* 208. A payment for 'payment_hash' was never made and there is
|
|
nothing to wait for.
|
|
* 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.
|
|
|
|
A routing failure object has the fields below:
|
|
|
|
* 'erring_index'. 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.
|
|
* 'erring_node'. The hex string of the pubkey id of the node
|
|
that reported the error.
|
|
* 'erring_channel'. The short channel ID of the channel that
|
|
has the error, or '0:0:0' if the destination node raised
|
|
the error.
|
|
* 'failcode'. The failure code, as per BOLT #4.
|
|
* 'channel_update'. The hex string of the 'channel_update'
|
|
message received from the remote node. Only present if
|
|
error is from the remote node and the 'failcode' has the
|
|
UPDATE bit set, as per BOLT #4.
|
|
|
|
AUTHOR
|
|
------
|
|
ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible.
|
|
|
|
SEE ALSO
|
|
--------
|
|
lightning-sendpay(7), lightning-pay(7).
|
|
|
|
RESOURCES
|
|
---------
|
|
Main web site: https://github.com/ElementsProject/lightning
|