NAME

lightning-createinvoice -- Low-level invoice creation

SYNOPSIS

createinvoice invstring label preimage

DESCRIPTION

The createinvoice RPC command signs and saves an invoice into the database.

• invstring (string): The bolt11/bolt12 invoice, but the final signature is ignored. Minimal sanity checks are done.

• label (one of): A unique string or number (which is treated as a string, so 01 is different from 1); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice.:

•

preimage (hex): The preimage to supply upon successful payment of the invoice.

RETURN VALUE

(Note: the return format is the same as lightning-listinvoices(7)). On success, an object is returned, containing:

• label (string): The label for the invoice.

• payment_hash (hash): The hash of the payment_preimage which will prove payment.

• status (string) (one of "paid", "expired", "unpaid"): Whether it has been paid, or can no longer be paid.

• description (string): Description extracted from bolt11 or bolt12.

• expires_at (u64): UNIX timestamp of when invoice expires (or expired).

• created_index (u64): 1-based index indicating order this invoice was created in. (added v23.08)

• bolt11 (string, optional): The bolt11 string (always present unless bolt12 is).

• bolt12 (string, optional): The bolt12 string instead of bolt11

• amount_msat (msat, optional): The amount of the invoice (if it has one).

• pay_index (u64, optional): Incrementing id for when this was paid (status paid only).

• amount_received_msat (msat, optional): Amount actually received (status paid only).

• paid_at (u64, optional): UNIX timestamp of when invoice was paid (status paid only).

• paid_outpoint (object, optional): Outpoint this invoice was paid with (status paid only). (added v23.11):

• payment_preimage (secret, optional): The proof of payment: SHA256 of this payment_hash.

• local_offer_id (hex, optional) (always 64 characters): The id of our offer which created this invoice.

• invreq_payer_note (string, optional): The optional invreq_payer_note from invoice_request which created this invoice.

ERRORS

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

The following error codes may occur:

• -1: Catchall nonspecific error.

• 900: An invoice with the given label already exists.

AUTHOR

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

SEE ALSO

lightning-invoice(7), lightning-listinvoices(7), lightning-delinvoice(7), lightning-getroute(7), lightning-sendpay(7), lightning-offer(7)

RESOURCES

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

EXAMPLES

Example 1:

Request:

$ lightning-cli createinvoice -k "invstring"="lnbcrt100n1pnt2bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000" "label"="lbl_l13" "preimage"="0101010101010101010101010101010101010101010101010101010101010101"

{


  "id": "example:createinvoice#1",


  "method": "createinvoice",


  "params": {


    "invstring": "lnbcrt100n1pnt2bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000bolt11invl010300000000",


    "label": "lbl_l13",


    "preimage": "0101010101010101010101010101010101010101010101010101010101010101"


  }
}

Response:

{


  "label": "lbl_l13",


  "bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",


  "payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",


  "amount_msat": 100000,


  "status": "unpaid",


  "description": "l13 description",


  "expires_at": 1739000000,


  "created_index": 7
}