LIGHTNING-CREATEINVOICE(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 LIGHTNING-CREATEINVOICE(7): createinvoice, low-level invoice creation 💖

okay bestie, welcome to the group chat for createinvoice — low-level invoice creation, no cap. this is LIGHTNING-CREATEINVOICE(7), and we're keeping every single fact exactly while making it make sense. ✨

🌸 NAME 🌸

createinvoice -- Low-level invoice creation

✨ SYNOPSIS ✨

createinvoice invstring label preimage

💅 DESCRIPTION 💅

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

  • 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.:
    • (string)
    • (integer)
  • 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):
    • txid (txid) — ID of the transaction that paid the invoice (status paid only). (added v23.11)
    • outnum (u32) — The 0-based output number of the transaction that paid the invoice (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. main character energy, fr fr 👑

🦋 SEE ALSO 🦋

go read these bestie:

🌈 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
}

bye bestie — this LIGHTNING-CREATEINVOICE(7) page is serving Core Lightning v26.06.9 source/version energy; the footer date isn't listed here, so no invented numbers 💜✨

📦 where this page comes from