lightning/doc/lightning-sendpay.7

.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] [\fIpayment_secret\fR] [\fIpartid\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 must be provided if \fIpartid\fR is non-zero, otherwise
it must be equal to the final
amount to the destination\. By default it 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\.


The \fIpayment_secret\fR is the value that the final recipient requires to
accept the payment, as defined by the \fBpayment_data\fR field in BOLT 4
and the \fBs\fR field in the BOLT 11 invoice format\.  It is required if
\fIpartid\fR is non-zero\.


The \fIpartid\fR value, if provided and non-zero, allows for multiple parallel
partial payments with the same \fIpayment_hash\fR\.  The \fImsatoshi\fR amount
(which must be provided) for each \fBsendpay\fR with matching
\fIpayment_hash\fR must be equal, and \fBsendpay\fR will fail if there are
already \fImsatoshi\fR worth of payments pending\.


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 or \fIpartid\fR) 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:

.RS
.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\.

.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 \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\.

.RE
.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

\" SHA256STAMP:ad0330702e519f55a65c7ef3b5e532114ec66cc4a2a34c7d3a9e0663085cd052