LIGHTNING-HOOK-INVOICE_PAYMENT(7)

okay bestie, this is LIGHTNING-HOOK-INVOICE_PAYMENT(7) — the lightning-hook-invoice_payment(7) manual page — and it's lowkey serving “one hook, one job, zero clutter.” 💅✨

🎀 NAME 🎀

invoice_payment — Hook fired when a payment for an invoice is received 💖

🦋 DESCRIPTION 🦋

The invoice_payment hook is called whenever a valid payment for an unpaid invoice has arrived. That's it, that's the vibe check: valid payment + unpaid invoice = hook time. ✨

The hook is deliberately sparse. Plugins can use listinvoices to retrieve additional information.

The plugin can:

• accept the payment by returning {"result": "continue"}
• reject the payment with a generic error using {"result": "reject"}
• reject the payment with a custom BOLT 4 failure message using the failure_message field

If failure_message is provided, the payment will be failed with that message. If result is "reject" and no failure_message is provided, the payment fails with incorrect_or_unknown_payment_details. failure_message must NOT be provided when result is "continue". No cap, that's a hard rule. 🚫

Before version 23.11 the msat field was encoded as a string with an 'msat' suffix. Legacy era behavior, bestie — don't let it confuse you. 🕰️

🌸 HOOK PAYLOAD 🌸

• payment (object): Basic payment information. Additional TLV-derived fields may be included when running in developer mode.
  • label (string): Unique label identifying the invoice.
  • preimage (secret): The payment preimage.
  • msat (msat): Amount paid in millisatoshis.

👑 HOOK RETURN 👑

• result (string) (one of "continue", "reject"): Controls whether the payment is accepted or rejected. "continue" accepts the payment. "reject" fails the payment.
• failure_message (hex, optional): Optional BOLT 4 failure message. Used to provide a specific failure reason when rejecting the payment.

If result is present, and result is "reject":

• failure_message (hex, optional)

💜 SEE ALSO 💜

lightning-listinvoices(7)

---

aaaand scene 🎬 — footer vibes: Core Lightning v26.06.9 is the source/version, and the date slot is giving “not printed in the original footer” energy, so no invented date here. Stay iconic, bestie. 🫶💖