mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 22:31:48 +01:00
259 lines
7 KiB
JSON
259 lines
7 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"rpc": "waitinvoice",
|
|
"title": "Command for waiting for specific payment",
|
|
"description": [
|
|
"The **waitinvoice** RPC command waits until a specific invoice is paid, then returns that single entry as per **listinvoice**."
|
|
],
|
|
"request": {
|
|
"required": [
|
|
"label"
|
|
],
|
|
"properties": {
|
|
"label": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "integer"
|
|
}
|
|
],
|
|
"description": [
|
|
"Unique label of the invoice waiting to be paid."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"label",
|
|
"description",
|
|
"payment_hash",
|
|
"status",
|
|
"created_index",
|
|
"expires_at"
|
|
],
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"Description used in the invoice."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the *payment_preimage* which will prove payment."
|
|
]
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"paid",
|
|
"expired"
|
|
],
|
|
"description": [
|
|
"Whether it's paid or expired."
|
|
]
|
|
},
|
|
"expires_at": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of when it will become / became unpayable."
|
|
]
|
|
},
|
|
"amount_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount required to pay this invoice."
|
|
]
|
|
},
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT11 string (always present unless *bolt12* is)."
|
|
]
|
|
},
|
|
"bolt12": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT12 string (always present unless *bolt11* is)."
|
|
]
|
|
},
|
|
"created_index": {
|
|
"type": "u64",
|
|
"added": "v23.08",
|
|
"description": [
|
|
"1-based index indicating order this invoice was created in."
|
|
]
|
|
},
|
|
"updated_index": {
|
|
"type": "u64",
|
|
"added": "v23.08",
|
|
"description": [
|
|
"1-based index indicating order this invoice was changed (only present if it has changed since creation)."
|
|
]
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"paid"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"pay_index",
|
|
"amount_received_msat",
|
|
"paid_at",
|
|
"payment_preimage"
|
|
],
|
|
"properties": {
|
|
"label": {},
|
|
"description": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"bolt11": {},
|
|
"bolt12": {},
|
|
"expires_at": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"pay_index": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Unique incrementing index for this payment."
|
|
]
|
|
},
|
|
"amount_received_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
|
|
]
|
|
},
|
|
"paid_at": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of when it was paid."
|
|
]
|
|
},
|
|
"paid_outpoint": {
|
|
"type": "object",
|
|
"description": [
|
|
"Outpoint this invoice was paid with."
|
|
],
|
|
"added": "v23.11",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"txid",
|
|
"outnum"
|
|
],
|
|
"properties": {
|
|
"txid": {
|
|
"added": "v23.11",
|
|
"type": "txid",
|
|
"description": [
|
|
"ID of the transaction that paid the invoice."
|
|
]
|
|
},
|
|
"outnum": {
|
|
"added": "v23.11",
|
|
"type": "u32",
|
|
"description": [
|
|
"The 0-based output number of the transaction that paid the invoice."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"payment_preimage": {
|
|
"type": "secret",
|
|
"description": [
|
|
"Proof of payment."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"else": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"label": {},
|
|
"description": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"bolt11": {},
|
|
"bolt12": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"expires_at": {}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"errors": [
|
|
"On error the returned object will contain `code` and `message` properties, with `code` being one of the following:",
|
|
"",
|
|
"- -32602: If the given parameters are wrong.",
|
|
"- -1: If the invoice is deleted while unpaid, or the invoice does not exist.",
|
|
"- 903: If the invoice expires before being paid, or is already expired."
|
|
],
|
|
"json_example": [
|
|
{
|
|
"request": {
|
|
"id": "example:waitinvoice#1",
|
|
"method": "waitinvoice",
|
|
"params": {
|
|
"label": "inv2"
|
|
}
|
|
},
|
|
"response": {
|
|
"label": "inv2",
|
|
"bolt11": "lnbcrt10n1pjmxtwjsp5mzvdu6v8hqsf2tlj0nlyks23afqp7ejs444syjxf74p60ztmld8qpp5q4ayz5pys3t0yj0dmkmh7ctarkv9z434paz4u9rdwnj4f43thhaqdq8d9h8vvsxqyjw5qcqp99qxpqysgqn0055ttns6pafsxh6xuqce6e4vz8gtxlzqx0l9d9f5crmqx4jymh4zy9jdaszm0dj89sq39fvhpwcs626dt0n3gw8kassfdehp5sy3sq7fzy3w",
|
|
"payment_hash": "057a4150248456f249edddb77f617d1d985156350f455e146d74e554d62bbdfa",
|
|
"amount_msat": 1000,
|
|
"status": "paid",
|
|
"pay_index": 1,
|
|
"amount_received_msat": 1000,
|
|
"paid_at": 1706241494,
|
|
"payment_preimage": "34ccd37cc85e067cb376f9ea8c70d70469f58bf296f2566ed9ad4dfb70971a26",
|
|
"description": [
|
|
"Inv2."
|
|
],
|
|
"expires_at": 1706846290,
|
|
"created_index": 2,
|
|
"updated_index": 1
|
|
}
|
|
}
|
|
],
|
|
"author": [
|
|
"Christian Decker <<decker.christian@gmail.com>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-waitanyinvoice(7)",
|
|
"lightning-listinvoice(7)",
|
|
"lightning-delinvoice(7)",
|
|
"lightning-invoice(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
]
|
|
}
|