NAME

lightning-listsendpays -- Low-level command for querying sendpay status

SYNOPSIS

listsendpays [bolt11] [payment_hash] [status] [index [start] [limit]]

DESCRIPTION

The listsendpays RPC command gets the status of all sendpay commands (which is also used by the pay command), or with bolt11 or payment_hash limits results to that specific payment. You cannot specify both. It is possible to filter the payments also by status.

Note that there may be more than one concurrent sendpay command per pay, so this command should be used with caution.

• bolt11 (string, optional): Bolt11 invoice.

• payment_hash (hash, optional): The hash of the payment_preimage.

• status (string, optional) (one of "pending", "complete", "failed"): Whether the invoice has been paid, pending, or failed.

• index (string, optional) (one of "created", "updated"): If neither bolt11 or payment_hash is specified, index controls ordering, by created (default) or updated. (added v23.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). (added v23.11)

• limit (u32, optional): If index is specified, limit can be used to specify the maximum number of entries to return. (added v23.11)

RETURN VALUE

Note that the returned array is ordered by increasing id. On success, an object containing payments is returned. It is an array of objects, where each object contains:

• created_index (u64): 1-based index indicating order this payment was created in. (added v23.11)

• id (u64): Old synonym for created_index.

• groupid (u64): Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash.

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

• amount_sent_msat (msat): The amount sent.

• partid (u64, optional): Part number (for multiple parts to a single payment).

• updated_index (u64, optional): 1-based index indicating order this payment was changed (only present if it has changed since creation). (added v23.11)

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

• destination (pubkey, optional): The final destination of the payment if known.

• 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: experimental-offers only).

If status is "complete": - payment_preimage (secret): The proof of payment: SHA256 of this payment_hash. - completed_at (u64, optional): The UNIX timestamp showing when this payment was completed. (added pre-v0.10.1)

If status is "failed": - erroronion (hex, optional): The onion message returned.

AUTHOR

Christian Decker <decker.christian@gmail.com> is mainly responsible.

SEE ALSO

lightning-listpays(7), lightning-sendpay(7), lightning-listinvoices(7)

RESOURCES

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

EXAMPLES

Example 1:

Request:

$ lightning-cli listsendpays -k "bolt11"="lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000"

{


  "id": "example:listsendpays#1",


  "method": "listsendpays",


  "params": {


    "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000"


  }
}

Response:

{


  "payments": [


    {


      "created_index": 2,


      "id": 2,


      "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",


      "groupid": 1,


      "updated_index": 2,


      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "amount_msat": 10000,


      "amount_sent_msat": 10001,


      "created_at": 1738000000,


      "completed_at": 1739000000,


      "status": "complete",


      "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"


    }


  ]
}

Example 2:

Request:

$ lightning-cli listsendpays

{


  "id": "example:listsendpays#2",


  "method": "listsendpays",


  "params": {}
}

Response:

{


  "payments": [


    {


      "created_index": 2,


      "id": 2,


      "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100",


      "groupid": 1,


      "updated_index": 2,


      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "amount_msat": 10000,


      "amount_sent_msat": 10001,


      "created_at": 1738000000,


      "completed_at": 1739000000,


      "status": "complete",


      "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101"


    },


    {


      "created_index": 3,


      "id": 3,


      "payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101",


      "groupid": 0,


      "updated_index": 3,


      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "amount_msat": 10000,


      "amount_sent_msat": 10001,


      "created_at": 1738010000,


      "completed_at": 1739010000,


      "status": "complete",


      "payment_preimage": "paymentpreimage1010101010101010101010101010101010101010101010101"


    },


    {


      "created_index": 4,


      "id": 4,


      "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201",


      "groupid": 0,


      "updated_index": 4,


      "destination": "nodeid040404040404040404040404040404040404040404040404040404040404",


      "amount_msat": 10000000,


      "amount_sent_msat": 10000202,


      "created_at": 1738020000,


      "completed_at": 1739020000,


      "status": "complete",


      "payment_preimage": "paymentpreimage2020202020202020202020202020202020202020202020202"


    },


    {


      "created_index": 5,


      "id": 5,


      "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",


      "groupid": 0,


      "updated_index": 5,


      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "amount_msat": 10000,


      "amount_sent_msat": 10001,


      "created_at": 1738030000,


      "completed_at": 1739030000,


      "status": "failed"


    },


    {


      "created_index": 6,


      "id": 6,


      "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301",


      "groupid": 0,


      "updated_index": 6,


      "partid": 1,


      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",


      "amount_msat": 10000,


      "amount_sent_msat": 10001,


      "created_at": 1738040000,


      "completed_at": 1739040000,


      "status": "complete",


      "payment_preimage": "paymentpreimage3030303030303030303030303030303030303030303030303"


    }


  ]
}