110 lines
3.9 KiB
Plaintext
110 lines
3.9 KiB
Plaintext
LIGHTNING-SENDPAY(7)
|
|
====================
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
lightning-sendpay - Low-level command for sending a payment via a route.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*sendpay* 'route' 'payment_hash' ['label'] ['msatoshi'] ['bolt11']
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The *sendpay* RPC command attempts to send funds associated with the
|
|
given 'payment_hash', along a route to the final destination in the route.
|
|
|
|
Generally, a client would call lightning-getroute(7) to resolve a route, then
|
|
use *sendpay* to send it. If it fails, it would call lightning-getroute(7)
|
|
again to retry.
|
|
|
|
The response will occur when the payment is on its way to the
|
|
destination.
|
|
The *sendpay* RPC command does not wait for definite success or
|
|
definite failure of the payment.
|
|
Instead, use the *waitsendpay* RPC command to poll or wait for
|
|
definite success or definite failure.
|
|
|
|
The 'label' and 'bolt11' parameters, if provided, will be returned in
|
|
'waitsendpay' and 'listsendpays' results.
|
|
|
|
The 'msatoshi' amount, if provided, is the amount that will be
|
|
recorded as the target payment value.
|
|
If not specified, it will be the final amount to the destination.
|
|
If specified, then the final amount at the destination must be
|
|
from the specified 'msatoshi' to twice the specified 'msatoshi',
|
|
inclusive.
|
|
This is intended to obscure payments by overpaying slightly at
|
|
the destination;
|
|
the actual target payment is what should be specified as the
|
|
'msatoshi' argument. 'msatoshi' is in millisatoshi 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'.
|
|
|
|
Once a payment has succeeded, calls to *sendpay* with the same 'payment_hash'
|
|
but a different 'msatoshi' or destination will fail; this prevents
|
|
accidental multiple payments.
|
|
Calls to *sendpay* with the same 'payment_hash', 'msatoshi', and destination as a
|
|
previous successful payment (even if a different route) will return
|
|
immediately with success.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
On success, an object similar to the output of *listsendpays* will
|
|
be returned.
|
|
This object will have a 'status' field that is typically the
|
|
string '"pending"', but may be '"complete"' if the payment was
|
|
already performed successfully.
|
|
|
|
On error, if the error occurred from a node other than the final
|
|
destination, the route table will be updated so that lightning-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.
|
|
* 201. Already paid with this 'hash' using different amount or
|
|
destination.
|
|
* 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.
|
|
|
|
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
|
|
------
|
|
Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
|
|
|
|
SEE ALSO
|
|
--------
|
|
lightning-listinvoice(7), lightning-delinvoice(7),
|
|
lightning-getroute(7), lightning-invoice(7),
|
|
lightning-pay(7), lightning-waitsendpay(7).
|
|
|
|
RESOURCES
|
|
---------
|
|
Main web site: https://github.com/ElementsProject/lightning
|