NAME

lightning-invoicerequest -- Command for offering payments

SYNOPSIS

invoicerequest amount description [issuer] [label] [absolute_expiry] [single_use]

DESCRIPTION

Command added in v22.11.

The invoicerequest RPC command creates an invoice_request to send payments: it automatically enables the processing of an incoming invoice, and payment of it. The reader of the resulting invoice_request can use lightning-sendinvoice(7) to collect their payment.

• amount (msat): A positive value in millisatoshi precision; it can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc.

• description (string): A short description of purpose of the payment, e.g. ATM withdrawl. This value is encoded into the resulting invoice_request and is viewable by anyone you expose it to. It must be UTF-8, and cannot use \u JSON escape codes.

• issuer (string, optional): Who is issuing it (i.e. you) if appropriate.

• label (string, optional): An internal-use name for the offer, which can be any UTF-8 string.

• absolute_expiry (u64, optional): The time the offer is valid until, in seconds since the first day of 1970 UTC. If not set, the invoice_request remains valid (though it can be deactivated by the issuer of course). This is encoded in the invoice_request.

• single_use (boolean, optional): Indicates that the invoice_request is only valid once; we may attempt multiple payments, but as soon as one is successful no more invoices are accepted (i.e. only one person can take the money). The default is True.

RETURN VALUE

On success, an object is returned, containing:

• invreq_id (hash): The SHA256 hash of all invoice_request fields less than 160.

• active (boolean) (always true): Whether the invoice_request is currently active.

• single_use (boolean): Whether the invoice_request will become inactive after we pay an invoice for it.

• bolt12 (string): The bolt12 string starting with lnr.

• used (boolean) (always false): Whether the invoice_request has already been used.

• label (string, optional): The label provided when creating the invoice_request.

ERRORS

On failure, an error is returned and no invoice_request is created. If the lightning process fails before responding, the caller should use lightning-listinvoicerequests(7) to query whether it was created or not.

•

-1: Catchall nonspecific error.

AUTHOR

Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO

lightning-listinvoicerequests(7), lightning-disableinvoicerequest(7)

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

$ lightning-cli invoicerequest -k "amount"=1000000 "description"="Simple test"

{


  "id": "example:invoicerequest#1",


  "method": "invoicerequest",


  "params": {


    "amount": 1000000,


    "description": "Simple test"


  }
}

Response:

{


  "invreq_id": "invreqid01010101010101010101010101010101010101010101010101010101",


  "active": true,


  "single_use": true,


  "bolt12": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",


  "used": false
}

Example 2:

Request:

$ lightning-cli invoicerequest -k "amount"="10000sat" "description"="Requesting for invoice" "issuer"="clightning store"

{


  "id": "example:invoicerequest#2",


  "method": "invoicerequest",


  "params": {


    "amount": "10000sat",


    "description": "Requesting for invoice",


    "issuer": "clightning store"


  }
}

Response:

{


  "invreq_id": "invreqid02020202020202020202020202020202020202020202020202020202",


  "active": true,


  "single_use": true,


  "bolt12": "lno1qgsq000bolt240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000240002400024000",


  "used": false
}