{ "$schema": "../rpc-schema-draft.json", "type": "object", "rpc": "listsendpays", "title": "Low-level command for querying sendpay status", "description": [ "The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11* or *payment_hash* limits results to that specific payment. You cannot specify both. It is possible to filter the payments also by *status*.", "", "Note that there may be more than one concurrent *sendpay* command per *pay*, so this command should be used with caution." ], "categories": [ "readonly" ], "request": { "required": [], "additionalProperties": false, "properties": { "bolt11": { "type": "string", "description": [ "Bolt11 invoice." ] }, "payment_hash": { "type": "hash", "description": [ "The hash of the payment_preimage." ] }, "status": { "type": "string", "enum": [ "pending", "complete", "failed" ], "description": [ "Whether the invoice has been paid, pending, or failed." ] }, "index": { "type": "string", "added": "v23.11", "enum": [ "created", "updated" ], "description": [ "If neither bolt11 or payment_hash is specified, `index` controls ordering, by `created` (default) or `updated`." ] }, "start": { "type": "u64", "added": "v23.11", "description": [ "If `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)." ] }, "limit": { "type": "u32", "added": "v23.11", "description": [ "If `index` is specified, `limit` can be used to specify the maximum number of entries to return." ] } }, "dependentUpon": { "index": [ "start", "limit" ] } }, "response": { "required": [ "payments" ], "additionalProperties": false, "properties": { "payments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "id", "created_index", "payment_hash", "status", "groupid", "created_at", "amount_sent_msat" ], "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." ] }, "groupid": { "type": "u64", "description": [ "Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash." ] }, "partid": { "type": "u64", "description": [ "Part number (for multiple parts to a single payment)." ] }, "payment_hash": { "type": "hash", "description": [ "The hash of the *payment_preimage* which will prove payment." ] }, "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)." ] }, "status": { "type": "string", "enum": [ "pending", "failed", "complete" ], "description": [ "Status of the payment." ] }, "amount_msat": { "type": "msat", "description": [ "The amount delivered to destination (if known)." ] }, "destination": { "type": "pubkey", "description": [ "The final destination of the payment if known." ] }, "created_at": { "type": "u64", "description": [ "The UNIX timestamp showing when this payment was initiated." ] }, "amount_sent_msat": { "type": "msat", "description": [ "The amount sent." ] }, "label": { "type": "string", "description": [ "The label, if given to sendpay." ] }, "bolt11": { "type": "string", "description": [ "The bolt11 string (if pay supplied one)." ] }, "description": { "type": "string", "description": [ "The description matching the bolt11 description hash (if pay supplied one)." ] }, "bolt12": { "type": "string", "description": [ "The bolt12 string (if supplied for pay: **experimental-offers** only)." ] } }, "allOf": [ { "if": { "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "complete" ] } } }, "then": { "additionalProperties": false, "required": [ "payment_preimage" ], "properties": { "id": {}, "created_index": {}, "updated_index": {}, "partid": {}, "groupid": {}, "payment_hash": {}, "status": {}, "msatoshi": {}, "amount_msat": {}, "destination": {}, "created_at": {}, "msatoshi_sent": {}, "amount_sent_msat": {}, "label": {}, "bolt11": {}, "description": {}, "bolt12": {}, "completed_at": { "type": "u64", "added": "pre-v0.10.1", "description": [ "The UNIX timestamp showing when this payment was completed." ] }, "payment_preimage": { "type": "secret", "description": [ "The proof of payment: SHA256 of this **payment_hash**." ] } } } }, { "if": { "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "failed" ] } } }, "then": { "additionalProperties": false, "required": [], "properties": { "id": {}, "created_index": {}, "updated_index": {}, "partid": {}, "groupid": {}, "payment_hash": {}, "status": {}, "msatoshi": {}, "amount_msat": {}, "destination": {}, "created_at": {}, "completed_at": {}, "msatoshi_sent": {}, "amount_sent_msat": {}, "label": {}, "bolt11": {}, "description": {}, "bolt12": {}, "erroronion": { "type": "hex", "description": [ "The onion message returned." ] } } } }, { "if": { "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "pending" ] } } }, "then": { "additionalProperties": false, "required": [], "properties": { "id": {}, "created_index": {}, "updated_index": {}, "partid": {}, "groupid": {}, "payment_hash": {}, "status": {}, "msatoshi": {}, "amount_msat": {}, "destination": {}, "created_at": {}, "msatoshi_sent": {}, "amount_sent_msat": {}, "label": {}, "bolt11": {}, "description": {}, "bolt12": {} } } } ] } } }, "pre_return_value_notes": [ "Note that the returned array is ordered by increasing *id*." ] }, "author": [ "Christian Decker <> is mainly responsible." ], "see_also": [ "lightning-listpays(7)", "lightning-sendpay(7)", "lightning-listinvoices(7)" ], "resources": [ "Main web site: " ], "examples": [ { "request": { "id": "example:listsendpays#1", "method": "listsendpays", "params": { "bolt11": "lnbcrt100n1pnt2bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000bolt11invl030100000000" } }, "response": { "payments": [ { "created_index": 2, "id": 2, "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100", "groupid": 1, "updated_index": 2, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738000000, "completed_at": 1739000000, "status": "complete", "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101" } ] } }, { "request": { "id": "example:listsendpays#2", "method": "listsendpays", "params": {} }, "response": { "payments": [ { "created_index": 2, "id": 2, "payment_hash": "paymenthashinvl0310031003100310031003100310031003100310031003100", "groupid": 1, "updated_index": 2, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738000000, "completed_at": 1739000000, "status": "complete", "payment_preimage": "paymentpreimagew010101010101010101010101010101010101010101010101" }, { "created_index": 3, "id": 3, "payment_hash": "paymenthashkey01k101k101k101k101k101k101k101k101k101k101k101k101", "groupid": 0, "updated_index": 3, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738010000, "completed_at": 1739010000, "status": "complete", "payment_preimage": "paymentpreimage1010101010101010101010101010101010101010101010101" }, { "created_index": 4, "id": 4, "payment_hash": "paymenthashkey02k201k201k201k201k201k201k201k201k201k201k201k201", "groupid": 0, "updated_index": 4, "destination": "nodeid040404040404040404040404040404040404040404040404040404040404", "amount_msat": 10000000, "amount_sent_msat": 10000202, "created_at": 1738020000, "completed_at": 1739020000, "status": "complete", "payment_preimage": "paymentpreimage2020202020202020202020202020202020202020202020202" }, { "created_index": 5, "id": 5, "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301", "groupid": 0, "updated_index": 5, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738030000, "completed_at": 1739030000, "status": "failed" }, { "created_index": 6, "id": 6, "payment_hash": "paymenthashkey03k301k301k301k301k301k301k301k301k301k301k301k301", "groupid": 0, "updated_index": 6, "partid": 1, "destination": "nodeid030303030303030303030303030303030303030303030303030303030303", "amount_msat": 10000, "amount_sent_msat": 10001, "created_at": 1738040000, "completed_at": 1739040000, "status": "complete", "payment_preimage": "paymentpreimage3030303030303030303030303030303030303030303030303" } ] } } ] }