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

FreeBSD Manual Pages


home | help
LIGHTNING-SENDPAY(7)	       lightning-sendpay	  LIGHTNING-SENDPAY(7)

       lightning-sendpay - Low-level command for sending a payment via a route

       sendpay route payment_hash [label] [msatoshi] [bolt11] [payment_secret]

       The sendpay RPC command attempts	to  send  funds	 associated  with  the
       given  payment_hash,  along  a  route  to  the final destination	in the

       Generally, a client  would  call	 lightning-getroute(7)	to  resolve  a
       route,  then  use sendpay to send it. If	it fails, it would call	light-
       ning-getroute(7)	again to retry.

       The response will occur when the	payment	is on its way to the  destina-
       tion.  The  sendpay  RPC	 command does not wait for definite success or
       definite	failure	of the payment.	Instead, use the waitsendpay RPC  com-
       mand to poll or wait for	definite success or definite failure.

       The label and bolt11 parameters,	if provided, will be returned in wait-
       sendpay and listsendpays	results.

       The msatoshi amount must	be provided if partid 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 num-
       ber 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 payment_secret is the 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

       The  partid value, if provided and non-zero, allows for multiple	paral-
       lel partial payments with the same payment_hash.	 The  msatoshi	amount
       (which  must  be	 provided) for each sendpay with matching payment_hash
       must be equal, and sendpay will fail  if	 there	are  already  msatoshi
       worth of	payments pending.

       Once  a	payment	 has  succeeded,  calls	 to sendpay with the same pay-
       ment_hash but a different msatoshi or destination will fail; this  pre-
       vents accidental	multiple payments. Calls to sendpay with the same pay-
       ment_hash, msatoshi, and	destination as a previous  successful  payment
       (even if	a different route or partid) will return immediately with suc-

       On success, an object similar to	the output of listsendpays will	be re-
       turned.	This  object  will  have  a status field that is typically the
       string "pending", but may be "complete" if the payment was already per-
       formed successfully.

       On error, if the	error occurred from a node other than the final	desti-
       nation, the route table will be updated so  that	 lightning-getroute(7)
       should return an	alternate route	(if any). An error from	the final des-
       tination	implies	the payment should not be retried.

       The following error codes may occur:

	      o	     -1: Catchall nonspecific error.

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

	      o	     202: Unparseable onion reply. The data field of the error
		     will have an onionreply field, a hex  string  representa-
		     tion of the raw onion reply.

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

	      o	     204: Failure along	route; retry a	different  route.  The
		     data field	of the error will be routing failure object.

       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.

       Rusty Russell> is	mainly responsible.

       lightning-listinvoice(7),      lightning-delinvoice(7),	    lightning-
       getroute(7),  lightning-invoice(7),  lightning-pay(7),  lightning-wait-

       Main web	site:



Want to link to this manual page? Use this URL:

home | help