LIGHTNING-DELPAY(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 LIGHTNING-DELPAY(7) — the delpay glow-up 🎀

okay bestie, welcome to lightning-delpay, straight out of the Core Lightning manual (that's the LIGHTNING-DELPAY(7) energy you're feeling ✨). This is the page for delpay — the command that removes a payment that's already done or already flopped. No cap, it's a little cleanup queen. 🧹💖

🌸 NAME 🌸

delpay — the Command for removing a completed or failed payment. literally that. she deletes things. respectfully. 💅

⭐ SYNOPSIS ⭐

delpay payment_hash status [partid groupid]

that's it. that's the whole vibe. one hash, one status, and optionally the partid/groupid duo if you're being extra specific. 🦋

🫶 DESCRIPTION 🫶

so the delpay RPC command deletes a payment with the given payment_hash — but only if its status is either complete or failed. she's picky like that and honestly? iconic. If partid and groupid are not specified, all payment parts with matchin status are deleted. 💀

here's the cast of characters:

  • payment_hash (hash) — The unique identifier of a payment. her social security number, basically. 🪪
  • 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. so like, don't come for her while she's still mid-glow-up. 🙈
  • partid (u64, optional) — Specific partid to delete (must be paired with groupid). it's giving "these two are a package deal". 🎀
  • groupid (u64, optional) — Specific groupid to delete (must be paired with partid). same energy, other half of the duo. 💜

👑 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. bestie she's thorough, she brings receipts for every single part. 🧾✨

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. the vintage version, still slaying. 👵
  • payment_hash (hash) — The hash of the payment_preimage which will prove payment. 🔐
  • status (string) (one of "pending", "failed", "complete") — Status of the payment. vibe check, basically. 🌈
  • amount_sent_msat (msat) — The amount we actually sent, including fees. yes the fees are real and yes they count. 💸
  • created_at (u64) — The UNIX timestamp showing when this payment was initiated. her birthday. 🎂
  • partid (u64, optional) — Unique ID within this (multi-part) payment. 🧩
  • destination (pubkey, optional) — The final destination of the payment if known. where she's headed. 🗺️
  • 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. the graduation date 🎓
  • 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. the sacred text. 📜
  • 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. the sad little onion of regret 🧅😭

💀 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. (translation: if she ghosts you mid-operation, go check yourself, don't just assume. 🫶)

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. she's not here, girl. 💀

🧚 AUTHOR 🧚

Vincenzo Palazzo vincenzo.palazzo@protonmail.com is mainly responsible. give him his flowers. 💐👑

🦋 SEE ALSO 🦋

lightning-listpays(7), lightning-listsendpays(7), lightning-xpay(7)

go read those too, iykyk. 📚✨

🌐 RESOURCES 🌐

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

🎀 EXAMPLES 🎀

Example 1 🍓

Request:

$ lightning-cli delpay -k "payment_hash"="paymenthashdelpay10101010101010101010101010101010101010101010101" "status"="complete"
{
  "id": "example:delpay#1",
  "method": "delpay",
  "params": {
    "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
    "status": "complete"
  }
}

Response:

{
  "payments": [
    {
      "created_index": 1,
      "id": 1,
      "payment_hash": "paymenthashdelpay10101010101010101010101010101010101010101010101",
      "groupid": 1,
      "updated_index": 1,
      "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "amount_msat": 500000000,
      "amount_sent_msat": 500000000,
      "created_at": 1738000000,
      "completed_at": 1738500000,
      "status": "complete",
      "payment_preimage": "paymentpreimgdp1010101010101010101010101010101010101010101010101",
      "bolt11": "lnbcrt222n1pnt3005720bolt114000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101"
    }
  ]
}

Example 2 💜

Request:

$ lightning-cli delpay "paymenthashdelpay20202020202020202020202020202020202020202020202" "failed"
{
  "id": "example:delpay#2",
  "method": "delpay",
  "params": [
    "paymenthashdelpay20202020202020202020202020202020202020202020202",
    "failed"
  ]
}

Response:

{
  "payments": [
    {
      "created_index": 23,
      "id": 23,
      "payment_hash": "paymenthashdelinv10101010101010101010101010101010101010101010101",
      "groupid": 1,
      "updated_index": 22,
      "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "amount_msat": 50000000,
      "amount_sent_msat": 50000501,
      "created_at": 1738000000,
      "completed_at": 1738500000,
      "status": "failed",
      "bolt11": "lnbcrt222n1pnt3005720bolt113000101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101"
    }
  ]
}

Example 3 🔥

Request:

$ lightning-cli delpay -k "payment_hash"="paymenthashdelpay30303030303030303030303030303030303030303030303" "status"="failed" "groupid"=1 "partid"=2
{
  "id": "example:delpay#3",
  "method": "delpay",
  "params": {
    "payment_hash": "paymenthashdelpay30303030303030303030303030303030303030303030303",
    "status": "failed",
    "groupid": 1,
    "partid": 2
  }
}

Response:

{
  "payments": [
    {
      "created_index": 20,
      "id": 20,
      "payment_hash": "paymenthashdelpay30303030303030303030303030303030303030303030303",
      "groupid": 1,
      "updated_index": 19,
      "partid": 2,
      "destination": "nodeid040404040404040404040404040404040404040404040404040404040404",
      "amount_msat": 1000000,
      "amount_sent_msat": 1000000,
      "created_at": 1738000000,
      "completed_at": 1738500000,
      "status": "failed"
    }
  ]
}
💖 that's the whole page bestie. go delete your payments responsibly. and remember: only complete or failed — pending payments are NOT invited to this party. 🚫🎉

okay so, sign-off time: this masterpiece is from Core Lightning v26.06.9, and yeah, it lives under the LIGHTNING-DELPAY(7) banner. periodt. 💅✨🌷

📦 where this page comes from