"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."
],
"request":{
"required":[],
"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"
],
"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":{
"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":{
"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":{
"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*."
