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
pendingpayment 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 <[email protected]> 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"="684b5650b3deb052c93efe1fe16e7703b56272468eecdeb3daac5b81216dcb52" "status"="complete"
{
"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"
}
]
}
Example 2:
Request:
lightning-cli delpay "25af7c1858066685212846e0d976263dde0ddbf1a7dc517a652853641dcf81fb" "failed"
{
"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"
}
]
}
Example 3:
Request:
lightning-cli delpay -k "payment_hash"="647252f7e45fce7bb964523206874f40f58fbb7b208bc08967caa0e2404990c9" "status"="failed" "groupid"=1 "partid"=2
{
"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"
}
]
}