lightning-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 created 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 considered (added v24.11)
• limit (u32, optional): If index is specified, limit can be used to specify 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 returned may be less than the limit, as individual payment parts are combined together (added v24.11)

RETURN VALUE

On success, an object containing pays is returned. It is an array of objects, 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 initiated.
• 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 payment 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 description 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 payment was changed (only present if it has changed since creation). (added v24.11)

If status is "complete":

• amount_sent_msat (msat): The amount of millisatoshi 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 destination.
• number_of_parts (u64, optional): The number of parts for a successful payment (only if more than one).

If status is "failed":

• erroronion (hex, optional): The error onion returned 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-pay(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": []
}