171 lines
5.8 KiB
Groff
171 lines
5.8 KiB
Groff
.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 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 (could be complete if already sent previously) (one of "pending", "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 \fIlabel\fR, 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 supplied)
|
|
.IP \[bu]
|
|
\fBbolt12\fR (string, optional): the bolt12 string (if supplied: \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
|
|
|
|
If \fBstatus\fR is "pending":
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBmessage\fR (string): Monitor status with listpays or waitsendpay
|
|
|
|
.RE
|
|
|
|
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\. In
|
|
addition \fIerring_direction\fR will indicate which direction of the
|
|
channel caused the failure\.
|
|
.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:5abab6ab51d61c0a4222f73abc40951b67ca466fca7c05f59507ca1246bfc525
|