NAME

lightning-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 <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

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"


    }


  ]
}