lightning-delpay.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "delpay",
  "title": "Command for removing a completed or failed payment",
  "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."
  ],
  "request": {
    "required": [
      "payment_hash",
      "status"
    ],
    "additionalProperties": false,
    "properties": {
      "payment_hash": {
        "type": "hash",
        "description": [
          "The unique identifier of a payment."
        ]
      },
      "status": {
        "type": "string",
        "description": [
          "Expected status of the payment. Only deletes if the payment status matches. Deleting a `pending` payment will return an error."
        ],
        "enum": [
          "complete",
          "failed"
        ]
      },
      "partid": {
        "type": "u64",
        "description": [
          "Specific partid to delete (must be paired with *groupid*)."
        ]
      },
      "groupid": {
        "type": "u64",
        "description": [
          "Specific groupid to delete (must be paired with *partid*)."
        ]
      }
    },
    "pairedWith": [
      [
        "partid",
        "groupid"
      ]
    ]
  },
  "response": {
    "required": [
      "payments"
    ],
    "additionalProperties": false,
    "properties": {
      "payments": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "created_index",
            "id",
            "payment_hash",
            "status",
            "amount_sent_msat",
            "created_at"
          ],
          "properties": {
            "created_index": {
              "added": "v23.11",
              "type": "u64",
              "description": [
                "1-based index indicating order this payment was created in."
              ]
            },
            "id": {
              "type": "u64",
              "description": [
                "Old synonym for created_index."
              ]
            },
            "payment_hash": {
              "type": "hash",
              "description": [
                "The hash of the *payment_preimage* which will prove payment."
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "failed",
                "complete"
              ],
              "description": [
                "Status of the payment."
              ]
            },
            "amount_sent_msat": {
              "type": "msat",
              "description": [
                "The amount we actually sent, including fees."
              ]
            },
            "partid": {
              "type": "u64",
              "description": [
                "Unique ID within this (multi-part) payment."
              ]
            },
            "destination": {
              "type": "pubkey",
              "description": [
                "The final destination of the payment if known."
              ]
            },
            "amount_msat": {
              "type": "msat",
              "description": [
                "The amount the destination received, if known."
              ]
            },
            "created_at": {
              "type": "u64",
              "description": [
                "The UNIX timestamp showing when this payment was initiated."
              ]
            },
            "updated_index": {
              "added": "v23.11",
              "type": "u64",
              "description": [
                "1-based index indicating order this payment was changed (only present if it has changed since creation)."
              ]
            },
            "completed_at": {
              "type": "u64",
              "description": [
                "The UNIX timestamp showing when this payment was completed."
              ]
            },
            "groupid": {
              "type": "u64",
              "description": [
                "Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash."
              ]
            },
            "payment_preimage": {
              "type": "secret",
              "description": [
                "Proof of payment."
              ]
            },
            "label": {
              "type": "string",
              "description": [
                "The label, if given to sendpay."
              ]
            },
            "bolt11": {
              "type": "string",
              "description": [
                "The bolt11 string (if pay supplied one)."
              ]
            },
            "bolt12": {
              "type": "string",
              "description": [
                "The bolt12 string (if supplied for pay)."
              ]
            },
            "erroronion": {
              "type": "hex",
              "description": [
                "The error onion returned on failure, if any."
              ]
            }
          }
        }
      }
    },
    "pre_return_value_notes": [
      "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."
    ]
  },
  "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 <<vincenzo.palazzo@protonmail.com>> is mainly responsible."
  ],
  "see_also": [
    "lightning-listpays(7)",
    "lightning-listsendpays(7)",
    "lightning-paystatus(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:delpay#1",
        "method": "delpay",
        "params": {
          "payment_hash": "684b5650b3deb052c93efe1fe16e7703b56272468eecdeb3daac5b81216dcb52",
          "status": "complete"
        }
      },
      "response": {
        "payments": [
          {
            "created_index": 1,
            "id": 1,
            "payment_hash": "684b5650b3deb052c93efe1fe16e7703b56272468eecdeb3daac5b81216dcb52",
            "groupid": 1,
            "updated_index": 1,
            "destination": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
            "amount_msat": 500000000,
            "amount_sent_msat": 500000000,
            "created_at": 1722303670,
            "completed_at": 1722303671,
            "status": "complete",
            "payment_preimage": "bed4140e1db302720d7f9547dc9127d45b115080447cce7e23cfd00b60991831",
            "bolt11": "lnbcrt5m1pn2s39ksp53sknyy2mxxurt4y0wqgp730z0cnm0vz3zmzth8p79xsrtmg5llxspp5dp94v59nm6c99jf7lc07zmnhqw6kyujx3mkdav7643dczgtdedfqdpcv3jhxcmjd9c8g6t0dcs8xetwvss8xmmdv5s8xct5wvsxcvfqw3hjqmpjxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqqduqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgqdz9cftkxe6kcqfddyrvr7j57ulsfxxxkgkjyhr3k77n8v59mzs5rmuexz9lxusyhhehlemd9ujclgahln8e0n8y86stc7u8uys6mjqgqerm6q4"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:delpay#2",
        "method": "delpay",
        "params": [
          "25af7c1858066685212846e0d976263dde0ddbf1a7dc517a652853641dcf81fb",
          "failed"
        ]
      },
      "response": {
        "payments": [
          {
            "created_index": 20,
            "id": 20,
            "payment_hash": "25af7c1858066685212846e0d976263dde0ddbf1a7dc517a652853641dcf81fb",
            "groupid": 1,
            "updated_index": 19,
            "destination": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
            "amount_msat": 50000000,
            "amount_sent_msat": 50000501,
            "created_at": 1722303803,
            "completed_at": 1722303806,
            "status": "failed",
            "bolt11": "lnbcrt500u1pn2s3fwsp5e6nltgzk3yqn5033r6z2q32pzduys3zs5dtzc5cjs60ppcgytrsqpp5ykhhcxzcqeng2gfggmsdja3x8h0qmkl35lw9z7n99pfkg8w0s8asdqcdsenvgryv4ekxunfwp6xjmmwxqyjw5qcqp9rzjqgkjyd3q5dv6gllh77kygly9c3kfy0d9xwyjyxsq2nq3c83u5vw4jqqq0vqqqqgqqyqqqqqpqqqqqzsqqc9qxpqysgqwn7uwmy3x8u9c4ea0ka0yp3qvs0w9m7459g65kalm553vusctq8kseaph7tav4ryjfghnhu0ggjhhkrqmafarqkdsrzsk8stcvdmpmcqwfsajc"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:delpay#3",
        "method": "delpay",
        "params": {
          "payment_hash": "647252f7e45fce7bb964523206874f40f58fbb7b208bc08967caa0e2404990c9",
          "status": "failed",
          "groupid": 1,
          "partid": 2
        }
      },
      "response": {
        "payments": [
          {
            "created_index": 17,
            "id": 17,
            "payment_hash": "647252f7e45fce7bb964523206874f40f58fbb7b208bc08967caa0e2404990c9",
            "groupid": 1,
            "updated_index": 16,
            "partid": 2,
            "destination": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
            "amount_msat": 1000000,
            "amount_sent_msat": 1000000,
            "created_at": 1722303798,
            "completed_at": 1722303799,
            "status": "failed"
          }
        ]
      }
    }
  ]
}