|
|
|
|
.TH "LIGHTNING-SENDPAY" "7" "" "" "lightning-sendpay"
|
|
|
|
|
.SH NAME
|
|
|
|
|
lightning-sendpay - Low-level command for sending a payment via a route
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
|
|
|
|
|
\fBsendpay\fR \fIroute\fR \fIpayment_hash\fR [\fIlabel\fR] [\fImsatoshi\fR]
|
|
|
|
|
[\fIbolt11\fR]
|
|
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
|
|
|
|
|
The \fBsendpay\fR RPC command attempts to send funds associated with the
|
|
|
|
|
given \fIpayment_hash\fR, along a route to the final destination in the
|
|
|
|
|
route\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Generally, a client would call \fBlightning-getroute\fR(7) to resolve a route,
|
|
|
|
|
then use \fBsendpay\fR to send it\. If it fails, it would call
|
|
|
|
|
\fBlightning-getroute\fR(7) again to retry\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The response will occur when the payment is on its way to the
|
|
|
|
|
destination\. The \fBsendpay\fR RPC command does not wait for definite
|
|
|
|
|
success or definite failure of the payment\. Instead, use the
|
|
|
|
|
\fBwaitsendpay\fR RPC command to poll or wait for definite success or
|
|
|
|
|
definite failure\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The \fIlabel\fR and \fIbolt11\fR parameters, if provided, will be returned in
|
|
|
|
|
\fIwaitsendpay\fR and \fIlistsendpays\fR results\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The \fImsatoshi\fR 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 \fImsatoshi\fR to twice the specified
|
|
|
|
|
\fImsatoshi\fR, inclusive\. This is intended to obscure payments by
|
|
|
|
|
overpaying slightly at the destination; the actual target payment is
|
|
|
|
|
what should be specified as the \fImsatoshi\fR argument\. \fImsatoshi\fR is in
|
|
|
|
|
millisatoshi precision; it can be a whole number, or a whole number
|
|
|
|
|
ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending
|
|
|
|
|
in \fIsat\fR, or a number with 1 to 11 decimal places ending in \fIbtc\fR\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Once a payment has succeeded, calls to \fBsendpay\fR with the same
|
|
|
|
|
\fIpayment_hash\fR but a different \fImsatoshi\fR or destination will fail;
|
|
|
|
|
this prevents accidental multiple payments\. Calls to \fBsendpay\fR with
|
|
|
|
|
the same \fIpayment_hash\fR, \fImsatoshi\fR, and destination as a previous
|
|
|
|
|
successful payment (even if a different route) will return immediately
|
|
|
|
|
with success\.
|
|
|
|
|
|
|
|
|
|
.SH RETURN VALUE
|
|
|
|
|
|
|
|
|
|
On success, an object similar to the output of \fBlistsendpays\fR will be
|
|
|
|
|
returned\. This object will have a \fIstatus\fR field that is typically the
|
|
|
|
|
string \fI"pending"\fR, but may be \fI"complete"\fR 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
|
|
|
|
|
\fBlightning-getroute\fR(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:
|
|
|
|
|
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
-1: Catchall nonspecific error\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
201: Already paid with this \fIhash\fR using different amount or
|
|
|
|
|
destination\.
|
|
|
|
|
.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\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A routing failure object has the fields below:
|
|
|
|
|
|
|
|
|
|
.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 \fI0:0:0\fR if the destination node raised the error\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIfailcode\fR\. The failure code, as per BOLT #4\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIchannel_update\fR\. The hex string of the \fIchannel_update\fR message
|
|
|
|
|
received from the remote node\. Only present if error is from the
|
|
|
|
|
remote node and the \fIfailcode\fR has the UPDATE bit set, as per BOLT
|
|
|
|
|
#4\.
|
|
|
|
|
|
|
|
|
|
.SH AUTHOR
|
|
|
|
|
|
|
|
|
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
|
|
|
|
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
|
|
|
|
|
\fBlightning-listinvoice\fR(7), \fBlightning-delinvoice\fR(7),
|
|
|
|
|
\fBlightning-getroute\fR(7), \fBlightning-invoice\fR(7), \fBlightning-pay\fR(7),
|
|
|
|
|
\fBlightning-waitsendpay\fR(7)\.
|
|
|
|
|
|
|
|
|
|
.SH RESOURCES
|
|
|
|
|
|
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
|
|
|
|
|
|
.HL
|
|
|
|
|
|
|
|
|
|
Last updated 2019-08-01 14:59:36 CEST
|
|
|
|
|
|
