2021-01-07 19:45:47 +01:00
lightning-fetchinvoice -- Command for fetch an invoice for an offer
===================================================================
SYNOPSIS
--------
2021-01-14 04:36:59 +01:00
**(WARNING: experimental-offers only)**
2021-01-07 19:45:47 +01:00
2022-01-26 18:18:49 +01:00
**fetchinvoice** *offer* [*msatoshi*] [*quantity*] [*recurrence_counter*] [*recurrence_start*] [*recurrence_label*] [*timeout*] [*payer_note*]
2021-01-07 19:45:47 +01:00
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.
2021-07-01 06:28:57 +02:00
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` .
2021-01-07 19:45:47 +01:00
The offer must not contain *send_invoice* ; see lightning-sendinvoice(7).
*msatoshi* is required if the *offer* does not specify
an amount at all, otherwise it is not allowed.
*quantity* is is required if the *offer* specifies
*quantity_min* or *quantity_max* , otherwise it is not allowed.
*recurrence_counter* is 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* is 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* is 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* is an optional timeout; if we don't get a reply before this
we fail (default, 60 seconds).
2021-09-03 21:09:11 +02:00
*payer_note* is an optional payer note to include in the fetched invoice.
2021-01-07 19:45:47 +01:00
RETURN VALUE
------------
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
2022-09-05 23:33:09 +02:00
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **invoice** (string): The BOLT12 invoice we fetched
- **changes** (object): Summary of changes from offer:
2022-09-05 23:45:06 +02:00
- **description\_appended** (string, optional): extra characters appended to the *description* field.
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **description** (string, optional): a completely replaced *description* field
2022-09-05 23:45:06 +02:00
- **vendor\_removed** (string, optional): The *vendor* from the offer, which is missing in the invoice
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **vendor** (string, optional): a completely replaced *vendor* field
2022-09-05 23:45:06 +02:00
- **amount\_msat** (msat, optional): 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** (object, optional): Only for recurring invoices if the next period is under the *recurrence_limit* :
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **counter** (u64): the index of the next period to fetchinvoice
- **starttime** (u64): UNIX timestamp that the next period starts
- **endtime** (u64): UNIX timestamp that the next period ends
2022-09-05 23:45:06 +02:00
- **paywindow\_start** (u64): UNIX timestamp of the earliest time that the next invoice can be fetched
- **paywindow\_end** (u64): UNIX timestamp of the latest time that the next invoice can be fetched
2021-09-03 12:07:59 +02:00
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.
We also add a test for getlog, since it was never called by the
testsuite.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
2021-01-07 19:45:47 +01:00
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 >
2022-09-05 23:45:06 +02:00
[comment]: # ( SHA256STAMP:003592ea0876d08b2109a0daa5e10328e049013f8e44d3eccc5805885a16a375)
