90 lines
3.1 KiB
Plaintext
90 lines
3.1 KiB
Plaintext
LIGHTNING-PAY(7)
|
|
================
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
lightning-pay - Protocol for sending a payment to a BOLT11 invoice
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent']
|
|
|
|
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 response will occur when the payment fails or succeeds. Once a
|
|
payment has succeeded, calls to *pay* with the same 'bolt11' will
|
|
succeed immediately.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
On success, this returns the payment 'preimage' which hashes to the
|
|
'payment_hash' to prove that the payment was successful.
|
|
|
|
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. A previous *sendpay* or *pay* is in progress.
|
|
* 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.
|
|
* 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.
|
|
|
|
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.
|
|
|
|
|
|
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
|