You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
4.3 KiB
117 lines
4.3 KiB
LIGHTNING-PAY(7)
|
|
================
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
lightning-pay - Protocol for sending a payment to a BOLT11 invoice
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent'] ['retry_for']
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The *pay* RPC command attempts to find a route to the given destination,
|
|
and send the funds it asks for. If the 'bolt11' does not contain an amount,
|
|
'msatoshi' is required, otherwise if it is specified it must be 'null'. If
|
|
'bolt11' contains a description hash ('h' field) 'description' is
|
|
required, otherwise it is unused. The 'riskfactor' is described in detail
|
|
in lightning-getroute(7), and defaults to 1.0.
|
|
The 'maxfeepercent' limits the money paid in fees, and defaults to 0.5.
|
|
The `maxfeepercent' is a percentage of the amount that is to be
|
|
paid.
|
|
|
|
The *pay* RPC command will randomize routes slightly, as long as the
|
|
route achieves the targeted 'maxfeepercent'.
|
|
|
|
The response will occur when the payment fails or succeeds. Once a
|
|
payment has succeeded, calls to *pay* with the same 'bolt11' will
|
|
succeed immediately.
|
|
|
|
The command will keep finding routes and retrying the payment until
|
|
it succeeds, or the given 'retry_for' seconds passes.
|
|
Note that the command may stop retrying while a pending payment is
|
|
ongoing, which you need to monitor with *listpayments* or *waitsendpay*.
|
|
'retry_for' defaults to 60 seconds and can only be an integer.
|
|
|
|
When using 'lightning-cli', you may skip optional parameters by using
|
|
'null'.
|
|
Alternatively, use *-k* option to provide parameters by name.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
On success, this returns the payment 'preimage' which hashes to the
|
|
'payment_hash' to prove that the payment was successful.
|
|
It will also return, a 'getroute_tries' and a 'sendpay_tries'
|
|
statistics for the number of times it internally called *getroute*
|
|
and *sendpay*.
|
|
|
|
On error, if the error occurred from a node other than the final
|
|
destination, the route table will be updated so that 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.
|
|
* 200. Payment timed out while a payment is in progress. Monitor
|
|
the status of that payment with 'listpayments' command, or
|
|
wait for that payment to complete with 'pay' command.
|
|
* 201. Already paid with this 'hash' using different amount or
|
|
destination.
|
|
* 203. Permanent failure at destination. The 'data' field of
|
|
the error will be routing failure object.
|
|
* 205. Unable to find a route.
|
|
* 206. Route too expensive. The 'data' field of the error will
|
|
indicate the actual 'fee' as well as the 'feepercent'
|
|
percentage that the fee has of the destination payment
|
|
amount.
|
|
* 207. Invoice expired. Payment took too long before expiration,
|
|
or already expired at the time you initiated payment.
|
|
The 'data' field of the error indicates 'now' (the current time)
|
|
and 'expiry' (the invoice expiration) as UNIX epoch time in
|
|
seconds.
|
|
* 210. Payment timed out without a payment in progress.
|
|
|
|
Error codes 202 and 204 will only get reported at *sendpay*;
|
|
in *pay* we will keep retrying if we would have gotten those
|
|
errors.
|
|
|
|
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.
|
|
|
|
The 'data' field of errors will include statistics
|
|
'getroute_tries' and 'sendpay_tries'.
|
|
It will also contain a 'failures' field with detailed data
|
|
about routing errors.
|
|
|
|
|
|
AUTHOR
|
|
------
|
|
Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
|
|
|
|
SEE ALSO
|
|
--------
|
|
lightning-listpayments(7), lightning-decodepay(7),
|
|
lightning-listinvoice(7), lightning-delinvoice(7),
|
|
lightning-getroute(7), lightning-invoice(7).
|
|
|
|
RESOURCES
|
|
---------
|
|
Main web site: https://github.com/ElementsProject/lightning
|
|
|