 |
|
| |
LIGHTNING-SENDPAY(7) |
|
LIGHTNING-SENDPAY(7) |
lightning-sendpay -- Low-level command for sending a payment via a
route
sendpay route payment_hash [label]
[amount_msat] [bolt11] [payment_secret] [partid]
[localinvreqid] [groupid] [payment_metadata]
[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. If the route is empty, a
payment-to-self is attempted.
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 (except for already-succeeded
payments, or to-self payments). Instead, use the waitsendpay RPC
command to poll or wait for definite success or definite failure.
Once a payment has succeeded, calls to sendpay with the
same payment_hash but a different amount_msat or destination
will fail; this prevents accidental multiple payments. Calls to
sendpay with the same payment_hash, amount_msat, and
destination as a previous successful payment (even if a different route or
partid) will return immediately with success.
- •
- route (array of objects):
- id (pubkey): The node at the end of this hop.
- channel (short_channel_id): The channel joining these nodes.
- delay (u32): The total CLTV expected by the node at the end of this
hop.
- amount_msat (msat): The amount expected by the node at the end of
this hop.
- payment_hash (hash): The hash of the payment_preimage.
- label (string, optional): The label provided when creating the
invoice_request.
- amount_msat (msat, optional): Amount must be provided if
partid is non-zero, or the payment is to-self, otherwise it must be
equal to the final amount to the destination. 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. The default is in millisatoshi precision.
- bolt11 (string, optional): Bolt11 invoice to pay. If provided, will
be returned in waitsendpay and listsendpays results.
- payment_secret (secret, optional): Value that the final recipient
requires to accept the payment, as defined by the
payment_data field in BOLT 4 and the
s field in the BOLT 11 invoice format. It is
required if partid is non-zero.
- partid (u64, optional): Must not be provided for self-payments. If
provided and non-zero, allows for multiple parallel partial payments with
the same payment_hash. The amount_msat amount (which must be
provided) for each sendpay with matching payment_hash must
be equal, and sendpay will fail if there are differing values
given.
- localinvreqid (hex, optional): Indicates that this payment is being
made for a local invoice_request. This ensures that we only send a payment
for a single-use invoice_request once.
- groupid (u64, optional): Allows you to attach a number which
appears in listsendpays so payments can be identified as part of a
logical group. The pay plugin uses this to identify one attempt at
a MPP payment, for example.
- payment_metadata (hex, optional): Placed in the final onion hop
TLV. (added v0.11.0)
- description (string, optional): Description used in the invoice.
(added v0.11.0)
On success, an object is returned, containing:
- created_index (u64): 1-based index indicating order this payment
was created in. (added v23.11)
- id (u64): Old synonym for created_index.
- payment_hash (hash): The hash of the payment_preimage which
will prove payment.
- status (string) (one of "pending", "complete"):
Status of the payment (could be complete if already sent previously).
- created_at (u64): The UNIX timestamp showing when this payment was
initiated.
- amount_sent_msat (msat): The amount sent.
- updated_index (u64, optional): 1-based index indicating order this
payment was changed (only present if it has changed since creation).
(added v23.11)
- groupid (u64, optional): Grouping key to disambiguate multiple
attempts to pay an invoice or the same payment_hash.
- amount_msat (msat, optional): The amount delivered to destination
(if known).
- destination (pubkey, optional): The final destination of the
payment if known.
- completed_at (u64, optional): The UNIX timestamp showing when this
payment was completed.
- label (string, optional): The label, if given to sendpay.
- partid (u64, optional): The partid, if given to sendpay.
- bolt11 (string, optional): The bolt11 string (if supplied).
- bolt12 (string, optional): The bolt12 string (if supplied).
If status is "complete": -
payment_preimage (secret): The proof of payment: SHA256 of this
payment_hash.
If status is "pending": - message
(string): Monitor status with listpays or waitsendpay.
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.
- -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.
- 212: localinvreqid refers to an invalid, or used, local
invoice_request.
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. In addition erring_direction will indicate which direction
of the channel caused the failure. 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.
lightning-listinvoices(7), lightning-delinvoice(7),
lightning-getroute(7), lightning-invoice(7), lightning-pay(7),
lightning-waitsendpay(7)
Example 1:
Request:
$ lightning-cli sendpay -k "route"='[{"id": "nodeid020202020202020202020202020202020202020202020202020202020202", "channel": "109x1x1", "direction": 1, "amount_msat": 10001, "delay": 15, "style": "tlv"}, {"id": "nodeid030303030303030303030303030303030303030303030303030303030303", "channel": "111x1x1", "direction": 0, "amount_msat": 10000, "delay": 9, "style": "tlv"}]' "payment_hash"="paymenthashinvl0310031003100310031003100310031003100310031003100" "payment_secret"="paymentsecretinvl00310003100031000310003100031000310003100031000"
{
"id": "example:sendpay#1",
"method": "sendpay",
"params": {
"route": [
{
"id": "nodeid020202020202020202020202020202020202020202020202020202020202",
"channel": "109x1x1",
"direction": 1,
"amount_msat": 10001,
"delay": 15,
"style": "tlv"
},
{
"id": "nodeid030303030303030303030303030303030303030303030303030303030303",
"channel": "111x1x1",
"direction": 0,
"amount_msat": 10000,
"delay": 9,
"style": "tlv"
}
],
"payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
"payment_secret": "paymentsecretinvl00310003100031000310003100031000310003100031000"
}
}
Response:
{
"message": "Monitor status with listpays or waitsendpay",
"created_index": 2,
"id": 2,
"payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",
"groupid": 1,
"destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
"amount_msat": 10000,
"amount_sent_msat": 10001,
"created_at": 1738000000,
"status": "pending"
}
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|