mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-03-13 11:09:14 +01:00
6f0dbbb20f
Payer metadata is a field that controls the payer ID
provided during the fetchinvoice process.
There are use cases where this is highly useful, such as
proving that the payer has paid for the correct item.
Imagine visiting a merchant's website to pay for multiple offers, where
one of these offers is a default offer (with no description and no set amount).
In this scenario, the merchant could claim not to have received
payment for a specific item. Since the same offer may be used to
fetch invoices for different products, there needs to be a way to
identify which product the invoice corresponds to.
With this commit, it will be possible to inject payer metadata,
which helps solve the issue described above.
For example, possible payer metadata could be `to_hex(b"{payer_node_id}.{product_id}.{created_at}")`.
Changelog-Added: JSON-RPC: `fetchinvoice` allows setting invreq_metadata via `payer_metadata` parameter.
Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
231 lines
8.6 KiB
JSON
231 lines
8.6 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"rpc": "fetchinvoice",
|
|
"title": "Command for fetch an invoice for an offer",
|
|
"description": [
|
|
"The **fetchinvoice** RPC command contacts the issuer of an *offer* to get an actual invoice that can be paid. It highlights any changes between the offer and the returned invoice.",
|
|
"",
|
|
"If **fetchinvoice-noconnect** is not specified in the configuation, it will connect to the destination in the (currently common!) case where it cannot find a route which supports `option_onion_messages`."
|
|
],
|
|
"request": {
|
|
"required": [
|
|
"offer"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"offer": {
|
|
"type": "string",
|
|
"description": [
|
|
"Offer string to get an actual invoice that can be paid."
|
|
]
|
|
},
|
|
"amount_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"Required if the offer does not specify an amount at all, otherwise it is optional (but presumably if you set it to less than the offer, you will get an error from the issuer)."
|
|
]
|
|
},
|
|
"quantity": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Required if the offer specifies quantity_max, otherwise it is not allowed."
|
|
]
|
|
},
|
|
"recurrence_counter": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Required if the offer specifies recurrence, otherwise it is not allowed. recurrence_counter should first be set to 0, and incremented for each successive invoice in a given series."
|
|
]
|
|
},
|
|
"recurrence_start": {
|
|
"type": "number",
|
|
"description": [
|
|
"Required if the offer specifies recurrence_base with start_any_period set, otherwise it is not allowed. It indicates what period number to start at."
|
|
]
|
|
},
|
|
"recurrence_label": {
|
|
"type": "string",
|
|
"description": [
|
|
"Required if recurrence_counter is set, and otherwise is not allowed. It must be the same as prior fetchinvoice calls for the same recurrence, as it is used to link them together."
|
|
]
|
|
},
|
|
"timeout": {
|
|
"type": "number",
|
|
"description": [
|
|
"If we don't get a reply before this we fail (default, 60 seconds)."
|
|
]
|
|
},
|
|
"payer_note": {
|
|
"type": "string",
|
|
"description": [
|
|
"To ask the issuer to include in the fetched invoice."
|
|
]
|
|
},
|
|
"payer_metadata": {
|
|
"type": "string",
|
|
"description": [
|
|
"Derive the payer_id from the specified payer_metadata. Please be sure that `payer_metdata` can not be derived by anyone, so put some secret into it."
|
|
],
|
|
"added": "v24.11"
|
|
},
|
|
"dev_reply_path": {
|
|
"hidden": true
|
|
},
|
|
"dev_path_use_scidd": {
|
|
"hidden": true
|
|
}
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"invoice",
|
|
"changes"
|
|
],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"invoice": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT12 invoice we fetched."
|
|
]
|
|
},
|
|
"changes": {
|
|
"type": "object",
|
|
"description": [
|
|
"Summary of changes from offer."
|
|
],
|
|
"additionalProperties": false,
|
|
"required": [],
|
|
"properties": {
|
|
"description_appended": {
|
|
"type": "string",
|
|
"description": [
|
|
"Extra characters appended to the *description* field."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"A completely replaced *description* field."
|
|
]
|
|
},
|
|
"vendor_removed": {
|
|
"type": "string",
|
|
"description": [
|
|
"The *vendor* from the offer, which is missing in the invoice."
|
|
]
|
|
},
|
|
"vendor": {
|
|
"type": "string",
|
|
"description": [
|
|
"A completely replaced *vendor* field."
|
|
]
|
|
},
|
|
"amount_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount, if different from the offer amount multiplied by any *quantity* (or the offer had no amount, or was not in BTC)."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"next_period": {
|
|
"type": "object",
|
|
"description": [
|
|
"Only for recurring invoices if the next period is under the *recurrence_limit*."
|
|
],
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"counter",
|
|
"starttime",
|
|
"endtime",
|
|
"paywindow_start",
|
|
"paywindow_end"
|
|
],
|
|
"properties": {
|
|
"counter": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The index of the next period to fetchinvoice."
|
|
]
|
|
},
|
|
"starttime": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp that the next period starts."
|
|
]
|
|
},
|
|
"endtime": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp that the next period ends."
|
|
]
|
|
},
|
|
"paywindow_start": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of the earliest time that the next invoice can be fetched."
|
|
]
|
|
},
|
|
"paywindow_end": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of the latest time that the next invoice can be fetched."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"errors": [
|
|
"The following error codes may occur:",
|
|
"",
|
|
"- -1: Catchall nonspecific error.",
|
|
"- 1002: Offer has expired.",
|
|
"- 1003: Cannot find a route to the node making the offer.",
|
|
"- 1004: The node making the offer returned an error message.",
|
|
"- 1005: We timed out trying to fetch an invoice."
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-sendinvoice(7)",
|
|
"lightning-pay(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
],
|
|
"examples": [
|
|
{
|
|
"request": {
|
|
"id": "example:fetchinvoice#1",
|
|
"method": "fetchinvoice",
|
|
"params": {
|
|
"offer": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrcgqgn3qzs2ge5hx6pqwdskcefpzcssytfzxcs2xkdy0lml0tzy0jzugmyj8kjn8zfzrgq9fsgurc72x82e",
|
|
"payer_note": "Thanks for the fish!"
|
|
}
|
|
},
|
|
"response": {
|
|
"invoice": "lni1qqg9g04gczk9ntk4gsjg3aptwykk2q3qqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy8ssq38zq9q53nfwd5zqumpd3jjz93pqgkjyd3q5dv6gllh77kygly9c3kfy0d9xwyjyxsq2nq3c83u5vw4j5pqqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy84sggztuesttnr6atmya7afycpsvcg0wnzprn58n54lfhf2ragp0jq0e04j9z5dpsku6mnypnx7u3qw35x2grxd9eksgdqnqpz6g3kyz34nfrl7lm6c3rushzxey3a55ecjgs6qp2vz8q78j336kgr6euj6p39a209zw5kpkftk7h9te69vlmjg0arceagpaajague0zsszqk96htpgqn2wsznaas0zfdtf8v97ryz29jrn7rwgs5687ghgq5jusqr99dtx4jdj9nqpep5zxmynegrg6e7rm2l53ur8043h2yqzldyl5vh08h8ssaeq5jrvw9y24kztlwvc4nwagsuqqqqqqqqqqqqqqq9qqqqqqqqqqqqq8fykt06c5sqqqqqpfqyv65yfedgyqrp2s7qpxpjse8q8796qcrr5xwgfkqjue3urd6rs2rt2f68tk0vl2szyugtqggz953rvg9rtxj8lalh43z8epwydjfrmffn3y3p5qz5cywpu09rr4vlqsy2n7vmpn67ltzrj70znp70sk4m530j5vceq6jhk97h7ttzn09sh8m9gecarrt27v2tux8z6rr06sj9h60r05p4vhkhzsp0xf9ea4jgg",
|
|
"changes": {}
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:fetchinvoice#2",
|
|
"method": "fetchinvoice",
|
|
"params": {
|
|
"offer": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrcgqv85ysq2qepk7enxv4j3gqg2zcssytfzxcs2xkdy0lml0tzy0jzugmyj8kjn8zfzrgq9fsgurc72x82e",
|
|
"amount_msat": 2000000,
|
|
"quantity": 2
|
|
}
|
|
},
|
|
"response": {
|
|
"invoice": "lni1qqg86u6jfl660zfuk22sexem37r7xq3qqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy8ssqc0gfqq5pjrdanxvet9zsqs593pqgkjyd3q5dv6gllh77kygly9c3kfy0d9xwyjyxsq2nq3c83u5vw4j5pqqc3xu3s3rg94nj40zfsy866mhu5vxne6tcej5878k2mneuvgjy84yqc7sjq9vqgztqssxq2dwgnpqyhz3j68zx5cts28t6aqfgq937wsgvsmfncau3uhz8t05zvqytfzxcs2xkdy0lml0tzy0jzugmyj8kjn8zfzrgq9fsgurc72x82eq2rdjuqaychg3jndvsjrlu6y08aeuh4ytw6f6ak5n24p5n8zmsz2sqgrg3rg89hqfh6n7dfr0fugvq20ehecd3ezc438l6uh4r8epaakn4lsqv4qgr3ks4yxngyflq339lza456xt8uly085umq3gwql3qyfge0ec03dezeg8xulz33ntlj8yd7dcra9564zrsqqqqqqqqqqqqqqq5qqqqqqqqqqqqqayjedltzjqqqqqq9yq3n2s3894qsfwwvj3szk4yplg4fkw68nwzlwyc23457qx6v7xe38znuha72km6a2qv0gfq9syypz6g3kyz34nfrl7lm6c3rushzxey3a55ecjgs6qp2vz8q78j336k0sgz2rxjcsxs6s3lnngq9xeqn9pzy53n50p4ulcdvkx8dye7h8xgxpvjyg928m2txk2knl0zzfl7j82c6lq7xqlx83ey7z4aux9pjp4sp7",
|
|
"changes": {}
|
|
}
|
|
}
|
|
]
|
|
}
|