home | help 
LIGHTNING-LISTPAYS(7)					   LIGHTNING-LISTPAYS(7)

NAME
     listpays -- Command for querying payment status

SYNOPSIS
     listpays [bolt11] [payment_hash] [status] [index] [start] [limit]

DESCRIPTION
     The  listpays RPC command gets the status of all pay commands (by combining
     results from listsendpays which lists every payment part), or a single  one
     if either bolt11 or payment_hash was specified.

     *	bolt11 (string, optional): Bolt11 string to get the payment details.
     *	payment_hash (hash, optional): Payment hash to get the payment details.
     *	status	(string,  optional) (one of "pending", "complete", "failed"): To
	filter the payment by status.
     *	index (string, optional)  (one	of  "created",	"updated"):  If  neither
	in_channel  nor  out_channel is specified, it controls ordering, by cre-
	ated or updated. (added v24.11)
     *	start (u64, optional): If index is specified, start may be specified  to
	start  from  that  value,  which  is  generally returned from lightning-
	wait(7).  NOTE: if this is used,  amount_sent_msat  and  number_of_parts
	fields may be lower than expected, as not all payment parts will be con-
	sidered (added v24.11)
     *	limit (u32, optional): If index is specified, limit can be used to spec-
	ify  the  maximum  number  of entries to return.  NOTE: if this is used,
	amount_sent_msat and number_of_parts fields may be lower than  expected,
	as  not all payment parts will be considered NOTE: the actual number re-
	turned may be less than the limit, as individual payment parts are  com-
	bined together (added v24.11)

RETURN VALUE
     On  success,  an  object containing pays is returned. It is an array of ob-
     jects, where each object contains:

     *	payment_hash (hash): The hash of the payment_preimage which  will  prove
	payment.
     *	status	(string) (one of "pending", "failed", "complete"): Status of the
	payment.
     *	created_at (u64): The UNIX timestamp showing when this payment was  ini-
	tiated.
     *	created_index  (u64):  1-based	index  indicating order this payment was
	created in. (added v24.11)
     *	destination (pubkey, optional): The final destination of the payment  if
	known.
     *	completed_at  (u64, optional): The UNIX timestamp showing when this pay-
	ment was completed.
     *	label (string, optional): The label, if given to sendpay.
     *	bolt11 (string, optional): The bolt11 string (if pay supplied one).
     *	description (string, optional): The description matching the bolt11  de-
	scription hash (if pay supplied one).
     *	bolt12 (string, optional): The bolt12 string (if supplied for pay).
     *	updated_index  (u64, optional): 1-based index indicating order this pay-
	ment was changed (only present if it has changed since creation). (added
	v24.11)

     If status is "complete": - amount_sent_msat  (msat):  The	amount	of  mil-
     lisatoshi	we  sent  in  order  to  pay  (may  include  fees  and not match
     amount_msat).  - preimage (secret): Proof of payment.  - amount_msat (msat,
     optional): The amount of millisatoshi we intended to send to  the	destina-
     tion.  This  can  only  be  missing in the case of someone manually calling
     sendonion without the amount_msat	parameter  (which  no  plugin  currently
     does).   -  number_of_parts (u64, optional): The number of parts for a suc-
     cessful payment (only if more than one).

     If status is "failed": - erroronion (hex, optional): The  error  onion  re-
     turned on failure, if any.

     The returned array is ordered by increasing created_at fields.

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-xpay(7), lightning-paystatus(7), lightning-listsendpays(7)

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

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli listpays -k "bolt11"="lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000"

     {
       "id": "example:listpays#1",
       "method": "listpays",
       "params": {
	 "bolt11": "lnbcrt100n1pnt2bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000bolt11invl032000000000"
       }
     }

     Response:

     {
       "pays": []
     }

     Example 2:

     Request:

     $ lightning-cli listpays

     {
       "id": "example:listpays#2",
       "method": "listpays",
       "params": {}
     }

     Response:

     {
       "pays": []
     }

Core Lightning v26.06.1 				   LIGHTNING-LISTPAYS(7)
home | help