{
  "$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](mailto: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](https://github.com/ElementsProject/lightning)"
  ],
  "examples": [
    {
      "request": {
        "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"
          }
        ]
      }
    },
    {
      "request": {
        "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"
          }
        ]
      }
    },
    {
      "request": {
        "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"
          }
        ]
      }
    }
  ]
}
