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.

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".

Before version 23.11 the msat field was encoded as a string with an 'msat' suffix.

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)