Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIGHTNING-PAY(7)		 lightning-pay		      LIGHTNING-PAY(7)

NAME
       lightning-pay - Command for sending a payment to	a BOLT11 invoice

SYNOPSIS
       pay  bolt11 [msatoshi] [label] [riskfactor] [maxfeepercent] [retry_for]
       [maxdelay] [exemptfee]

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.  msatoshi is in millisatoshi precision; it	can be a whole number,
       or a whole number with suffix msat or sat, or  a	 three	decimal	 point
       number  with suffix sat,	or an 1	to 11 decimal point number suffixed by
       btc.

       (Note: if experimental-offers is	enabled,  bolt11  can  actually	 be  a
       bolt12 invoice, such as one received from lightningd-fetchinvoice(7)).

       The  label field	is used	to attach a label to payments, and is returned
       in lightning-listpays(7)	and lightning-listsendpays(7). The  riskfactor
       is  described  in  detail in lightning-getroute(7), and defaults	to 10.
       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
       exemptfee option	can be used for	tiny payments which would be dominated
       by  the fee leveraged by	forwarding nodes. Setting exemptfee allows the
       maxfeepercent check to be skipped on fees that are smaller than exempt-
       fee (default: 5000 millisatoshi).

       The response will occur when the	payment	fails or succeeds. Once	a pay-
       ment has	succeeded, calls to pay	with the same bolt11 will succeed  im-
       mediately.

       Until  retry_for	 seconds  passes  (default: 60), the command will keep
       finding routes and retrying the payment.	However, a payment may be  de-
       layed for up to maxdelay	blocks by another node;	clients	should be pre-
       pared for this worst case.

       When using lightning-cli, you may skip  optional	 parameters  by	 using
       null. Alternatively, use	-k option to provide parameters	by name.

RANDOMIZATION
       To protect user privacy,	the payment algorithm performs some randomiza-
       tion.

       1: Route	Randomization

       Route randomization means the payment algorithm does not	always use the
       lowest-fee  or shortest route. This prevents some highly-connected node
       from learning all of the	user payments by reducing their	fees below the
       network average.

       2: Shadow Route

       Shadow  route  means  the  payment  algorithm will virtually extend the
       route by	adding delays and fees along it, making	it appear to  interme-
       diate nodes that	the route is longer than it actually is. This prevents
       intermediate nodes from	reliably  guessing  their  distance  from  the
       payee.

       Route  randomization  will  never  exceed maxfeepercent of the payment.
       Route randomization and shadow routing will not take routes that	 would
       exceed maxdelay.

RETURN VALUE
       On success, an object is	returned, containing:

	      o	     payment_preimage  (hex):  the proof of payment: SHA256 of
		     this payment_hash (always 64 characters)

	      o	     payment_hash (hex):  the  hash  of	 the  payment_preimage
		     which will	prove payment (always 64 characters)

	      o	     created_at	(number): the UNIX timestamp showing when this
		     payment was initiated

	      o	     parts (u32): how many attempts this took

	      o	     amount_msat (msat): Amount	the recipient received

	      o	     amount_sent_msat (msat): Total amount we sent  (including
		     fees)

	      o	     status (string): status of	payment	(always	"complete")

	      o	     destination  (pubkey, optional): the final	destination of
		     the payment

       The following warnings may also be returned:

	      o	     warning_partial_completion: Not all parts of a multi-part
		     payment have completed

       You  can	monitor	the progress and retries of a payment using the	light-
       ning-paystatus(7) command.

       The following error codes may occur:

	      o	     -1: Catchall nonspecific error.

	      o	     201: Already paid with this hash using  different	amount
		     or	destination.

	      o	     203:  Permanent failure at	destination. The data field of
		     the error will be routing failure object.

	      o	     205: Unable to find a route.

	      o	     206: Route	too expensive. Either the fee  or  the	needed
		     total  locktime  for the route exceeds your maxfeepercent
		     or	maxdelay settings, respectively. The data field	of the
		     error will	indicate the actual fee	as well	as the feeper-
		     cent percentage that the fee has of the destination  pay-
		     ment amount. It will also indicate	the actual delay along
		     the route.

	      o	     207: Invoice expired. Payment took	too long before	 expi-
		     ration, or	already	expired	at the time you	initiated pay-
		     ment. The data field of the error indicates now (the cur-
		     rent  time)  and  expiry (the invoice expiration) as UNIX
		     epoch time	in seconds.

	      o	     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:

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

	      o	     erring_node:  The hex string of the pubkey	id of the node
		     that reported the error.

	      o	     erring_channel: The short channel ID of the channel  that
		     has  the  error,  or 0:0:0	if the destination node	raised
		     the error.

	      o	     failcode: The failure code, as per	BOLT #4.

	      o	     channel_update. The hex string of the channel_update mes-
		     sage 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-listpays(7),	  lightning-decodepay(7),    lightning-listin-
       voice(7), lightning-delinvoice(7), lightning-getroute(7), lightning-in-
       voice(7).

RESOURCES
       Main web	site: https://github.com/ElementsProject/lightning

							      LIGHTNING-PAY(7)

NAME | SYNOPSIS | DESCRIPTION | RANDOMIZATION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lightning-pay&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help