{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "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"
    ],
    "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"
    ],
    "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: **experimental-offers** only)."
              ]
            },
            "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": "4fa2f1b001067ec06d7f95b8695b8acd9ef04c1b4d1110e3b94e1fa0687bb1e0",
          "status": "complete"
        }
      },
      "response": {
        "payments": [
          {
            "id": 1,
            "payment_hash": "8dfd6538eeb33811c9114a75f792a143728d7f05643f38c3d574d3097e8910c0",
            "destination": "0219f8900ee78a89f050c24d8b69492954f9fdbabed753710845eb75d3a75a5880",
            "msatoshi": 1000,
            "amount_msat": "1000msat",
            "msatoshi_sent": 1000,
            "amount_sent_msat": "1000msat",
            "created_at": 1596224858,
            "status": "complete",
            "payment_preimage": "35bd4e2b481a1a84a22215b5372672cf81460a671816960ddb206464359e1822",
            "bolt11": "lntb10n1p0jga20pp53h7k2w8wkvuprjg3ff6l0y4pgdeg6lc9vsln3s74wnfsjl5fzrqqdqdw3jhxazldahx2xqyjw5qcqp2sp5wut5jnhr6n7jd5747ky2g5flmw7hgx9yjnqzu60ps2jf6f7tc0us9qy9qsqu2a0k37nckl62005p69xavlkydkvhnypk4dphffy4x09zltwh9437ad7xkl83tefdarzhu5t30ju5s56wlrg97qkx404pq3srfc425cq3ke9af"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:delpay#2",
        "method": "delpay",
        "params": [
          "c9d4547473d0d646f1fdd8ca7f01803e4d31ceab01df33c79456f9c24b04034e",
          "failed"
        ]
      },
      "response": {
        "payments": [
          {
            "created_index": 2,
            "id": 2,
            "payment_hash": "c9d4547473d0d646f1fdd8ca7f01803e4d31ceab01df33c79456f9c24b04034e",
            "groupid": 1,
            "updated_index": 2,
            "destination": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
            "amount_msat": 100000,
            "amount_sent_msat": 100002,
            "created_at": 1706316468,
            "completed_at": 1706316471,
            "status": "failed",
            "bolt11": "lnbcrt1u1pjmg54nsp5ke626txv6wwwmqmpuy63t3jnu9hqxwj880zsfkkj7jjqagdaz2sqpp5e829garn6rtydu0amr987qvq8exnrn4tq80n83u52muuyjcyqd8qdq8v3jhxccxqyjw5qcqp99qxpqysgqalktfwy9svsamvvvrzzzzpdaa4rh7n6s5p7t9lx7qv0raz4vnm9knkh5ury3u5cmnhx2gms98nxkclm3833uhjrlnzmftc685vz2f0gpfnjy4y"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:delpay#3",
        "method": "delpay",
        "params": {
          "payment_hash": "bbc35e0a46d1483292a4ff8d4daaceaab8c3c084dd835be4128785b52e469c64",
          "status": "complete",
          "groupid": 1,
          "partid": 1
        }
      },
      "response": {
        "payments": [
          {
            "created_index": 3,
            "id": 3,
            "payment_hash": "bbc35e0a46d1483292a4ff8d4daaceaab8c3c084dd835be4128785b52e469c64",
            "groupid": 1,
            "updated_index": 3,
            "partid": 1,
            "destination": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
            "amount_msat": 100000,
            "amount_sent_msat": 102100,
            "created_at": 1708641193,
            "completed_at": 1708641194,
            "status": "complete",
            "payment_preimage": "a6ebb1cfbf69e76200f196f1eafd28a3d850633499c223a7eb7a7dba3b995286"
          }
        ]
      }
    }
  ]
}