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 is	returned, containing:

	      o	     id	(u64): unique ID for this payment attempt

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

	      o	     status (string): status of	the payment (could be complete
		     if	already	sent  previously)  (one	 of  "pending",	 "com-

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

	      o	     amount_sent_msat (msat): The amount sent

	      o	     amount_msat (msat,	optional):  The	 amount	 delivered  to
		     destination (if known)

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

	      o	     label (string, optional): the label, if given to sendpay

	      o	     partid (u64, optional): the partid, if given to sendpay

	      o	     bolt11 (string, optional):	the  bolt11  string  (if  sup-

	      o	     bolt12  (string,  optional):  the	bolt12 string (if sup-
		     plied: experimental-offers	only).

       If status is "complete":

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

       If status is "pending":

	      o	     message  (string):	 Monitor status	with listpays or wait-

       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.  In  addition	erring_direction will indicate
		     which direction of	the channel caused the failure.

	      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