delpay -- Command for removing a completed or failed payment

SYNOPSIS

delpay payment_hash status [partid groupid]

DESCRIPTION

The delpay RPC command deletes a payment with the given payment_hash if its status is either complete or failed. If partid and groupid are not specified, all payment parts with matchin status are deleted.

payment_hash (hash): The unique identifier of a payment.
status (string) (one of "complete", "failed"): Expected status of the payment. Only deletes if the payment status matches. Deleting a pending payment will return an error.
partid (u64, optional): Specific partid to delete (must be paired with groupid).
groupid (u64, optional): Specific groupid to delete (must be paired with partid).

RETURN VALUE

The returned format is the same as lightning-listsendpays(7). If the payment is a multi-part payment (MPP) the command return a list of payments will be returned -- one payment object for each partid.
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.
payment_hash (hash): The hash of the payment_preimage which will prove payment.
status (string) (one of "pending", "failed", "complete"): Status of the payment.
amount_sent_msat (msat): The amount we actually sent, including fees.
created_at (u64): The UNIX timestamp showing when this payment was initiated.
partid (u64, optional): Unique ID within this (multi-part) payment.
destination (pubkey, optional): The final destination of the payment if known.
amount_msat (msat, optional): The amount the destination received, if known.
updated_index (u64, optional): 1-based index indicating order this payment was changed (only present if it has changed since creation). (added v23.11)
completed_at (u64, optional): The UNIX timestamp showing when this payment was completed.
groupid (u64, optional): Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash.
payment_preimage (secret, optional): Proof of payment.
label (string, optional): The label, if given to sendpay.
bolt11 (string, optional): The bolt11 string (if pay supplied one).
bolt12 (string, optional): The bolt12 string (if supplied for pay).
erroronion (hex, optional): The error onion returned on failure, if any.

ERRORS

On failure, an error is returned. If the lightning process fails before responding, the
caller should use lightning-listsentpays(7) or lightning-listpays(7) to query whether this payment was deleted or not.

The following error codes may occur:

-32602: Parameter missed or malformed;
211: Payment status mismatch. Check the correct status via paystatus;
208: Payment with payment_hash not found.

AUTHOR

Vincenzo Palazzo [email protected] is mainly responsible.

RESOURCES

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

EXAMPLES

Example 1:

Request:

lightning-cli delpay -k "payment_hash"="19472d43110fb74d7c29468b1aec09ad2f00a91faf7b1b3974d07630defe76a1" "status"="complete"

{
  "id": "example:delpay#1",
  "method": "delpay",
  "params": {
    "payment_hash": "19472d43110fb74d7c29468b1aec09ad2f00a91faf7b1b3974d07630defe76a1",
    "status": "complete"
  }
}

Response:

{
  "payments": [
    {
      "created_index": 1,
      "id": 1,
      "payment_hash": "19472d43110fb74d7c29468b1aec09ad2f00a91faf7b1b3974d07630defe76a1",
      "groupid": 7924647788710609214,
      "updated_index": 1,
      "partid": 1,
      "destination": "033845802d25b4e074ccfd7cd8b339a41dc75bf9978a034800444b51d42b07799a",
      "amount_msat": 500000000,
      "amount_sent_msat": 500000000,
      "created_at": 1738000000,
      "completed_at": 1738000000,
      "status": "complete",
      "payment_preimage": "09e7f193a0100e9f09e7f193a0100e9f09e7f193a0100e9f09e7f193a0100e9f",
      "bolt11": "lnbcrt5m1pne035qsp5f7fj3w9sqj6974p0gnpd7snqr2qfezav2mp26e20nx3vty5cweaqpp5r9rj6sc3p7m56lpfg6934mqf45hsp2gl4aa3kwt56pmrphh7w6ssdpcv3jhxcmjd9c8g6t0dcs8xetwvss8xmmdv5s8xct5wvsxcvfqw3hjqmpjxqyjw5qcqp9rzjq08vhlwxs4zvcktzywmgecr3pj096tyukvt7upuz9k2s0xkvwq7nzqqqwcqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgqxjn3ms2m2xm65w5pf0ulf7km28ma0luz2whhgpajnt5ecmwhp2x3ks3qzwxr907fc9g5l3quwn97u8tf0gkm5ppfvxh2dndy3z6up0cqyk54qc"
    }
  ]
}

Example 2:

Request:

lightning-cli delpay "dc36f84df16cc35f768c5a4c50304d8601fe71d317024a5ccfe7c1073bb5979c" "failed"

{
  "id": "example:delpay#2",
  "method": "delpay",
  "params": [
    "dc36f84df16cc35f768c5a4c50304d8601fe71d317024a5ccfe7c1073bb5979c",
    "failed"
  ]
}

Response:

{
  "payments": [
    {
      "created_index": 23,
      "id": 23,
      "payment_hash": "dc36f84df16cc35f768c5a4c50304d8601fe71d317024a5ccfe7c1073bb5979c",
      "groupid": 8789338917165744446,
      "updated_index": 22,
      "partid": 1,
      "destination": "03cecbfdc68544cc596223b68ce0710c9e5d2c9cb317ee07822d95079acc703d31",
      "amount_msat": 50000000,
      "amount_sent_msat": 50000501,
      "created_at": 1738000000,
      "completed_at": 1738000000,
      "status": "failed",
      "bolt11": "lnbcrt500u1pne035qsp5zkz2glrfqgvw7dar86umteldh7rrspqg6qt0s7t5qrs2zwr7urkspp5msm0sn03dnp47a5vtfx9qvzdscqluuwnzupy5hx0ulqswwa4j7wqdqcdsenvgryv4ekxunfwp6xjmmwxqyjw5qcqp99qxpqysgqajsulk3lmdklgd8y6vf942m874kpgew4xnk3qp8dxz0jz4nscn6r6wxmuu8fw76nhcpcpqyzgrwgk0eqjv5hzja6cqdp22wv8de3mygp7kgefl",
      "erroronion": "7ba35f9458338a60a01ca6716c7df8433fb6af60f349064ae3dda4e0795c52bfbd68428a565ab1ff4f437982b47c8925478488786c4d8793f9e3b46af3a76367a8569bcdbf58ccdd37c4bbaf00633bafa089cf9650df9fa903942358853e3b886fbdfa1143d762e016093c3e4a6278595ee1db1b94ff44a96ac7cc5cbe3164e7a01aedb06109de0e6b0e9376a482e14a81619801075ac250fa3b433b55c284c9e949da053b8ace0a32a8da568945043d7e2d310bc022a595c7ae77d982ac086b904492bc718581872ce28ec12c487efec50235234fd67ed2cb3e49820dce94727d6d07262e5cc98b1906f70d310275731c489ae5f32b61cf8bf9b61e3d34c362f57fc151804ed08dddb456f1cd8196f98e8da125fd71755fd438c757897f4e61578fcf09"
    }
  ]
}

Example 3:

Request:

lightning-cli delpay -k "payment_hash"="917d0cb42f300c663e8fa4ec70db9ed8e8d1d715cde8b968e869ac45bba165ff" "status"="failed" "groupid"=1 "partid"=2

{
  "id": "example:delpay#3",
  "method": "delpay",
  "params": {
    "payment_hash": "917d0cb42f300c663e8fa4ec70db9ed8e8d1d715cde8b968e869ac45bba165ff",
    "status": "failed",
    "groupid": 1,
    "partid": 2
  }
}

Response:

{
  "payments": [
    {
      "created_index": 20,
      "id": 20,
      "payment_hash": "917d0cb42f300c663e8fa4ec70db9ed8e8d1d715cde8b968e869ac45bba165ff",
      "groupid": 1,
      "updated_index": 19,
      "partid": 2,
      "destination": "02287bfac8b99b35477ebe9334eede1e32b189e24644eb701c079614712331cec0",
      "amount_msat": 1000000,
      "amount_sent_msat": 1000000,
      "created_at": 1738000000,
      "completed_at": 1738000000,
      "status": "failed"
    }
  ]
}

delpay -- Command for removing a completed or failed payment

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

AUTHOR

SEE ALSO

RESOURCES

EXAMPLES