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 by returning only the failure_message field (i.e. without result)

If only 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 is ignored if result is provided.

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, optional) (one of "continue", "reject"): Controls whether the payment is accepted or rejected.
  "continue" accepts the payment.
  "reject" fails the payment with incorrect_or_unknown_payment_details.
• failure_message (hex, optional): Optional BOLT 4 failure message.
  Only used when result is absent: the payment is rejected with this failure message.
  Ignored if result is present.

SEE ALSO

lightning-listinvoices(7)