home | help 
LIGHTNING-DELPAY(7)					     LIGHTNING-DELPAY(7)

NAME
     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 speci-
     fied, 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 pay-
     ment 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 ob-
     ject 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  ini-
	tiated.
     *	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 pay-
	ment was changed (only present if it has changed since creation). (added
	v23.11)
     *	completed_at (u64, optional): The UNIX timestamp showing when this  pay-
	ment 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 re-
     sponding, 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-xpay(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"
	 }
       ]
     }

Core Lightning v26.06.1 				     LIGHTNING-DELPAY(7)
home | help