lightning-waitinvoice -- Command for waiting for specific payment

SYNOPSIS

waitinvoice label

DESCRIPTION

The waitinvoice RPC command waits until a specific invoice is paid, then returns that single entry as per listinvoices.

• label (one of): Unique label of the invoice waiting to be paid.:
  • (string)
  • (integer)

RETURN VALUE

On success, an object is returned, containing:

• label (string): Unique label supplied at invoice creation.
• payment_hash (hash): The hash of the payment_preimage which will prove payment.
• status (string) (one of "paid", "expired"): Whether it's paid or expired.
• expires_at (u64): UNIX timestamp of when it will become / became unpayable.
• created_index (u64): 1-based index indicating order this invoice was created in. (added v23.08)
• description (string, optional): Description used in the invoice.
• amount_msat (msat, optional): The amount required to pay this invoice.
• bolt11 (string, optional): The BOLT11 string (always present unless bolt12 is).
• bolt12 (string, optional): The BOLT12 string (always present unless bolt11 is).
• updated_index (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation). (added v23.08)

If status is "paid":

• pay_index (u64): Unique incrementing index for this payment.
• amount_received_msat (msat): The amount actually received (could be slightly greater than amount_msat, since clients may overpay).
• paid_at (u64): UNIX timestamp of when it was paid.
• payment_preimage (secret): Proof of payment.
• paid_outpoint (object, optional): Outpoint this invoice was paid with. (added v23.11):
  • txid (txid): ID of the transaction that paid the invoice. (added v23.11)
  • outnum (u32): The 0-based output number of the transaction that paid the invoice. (added v23.11)

ERRORS

On error the returned object will contain code and message properties, with code being one of the following:

• -32602: If the given parameters are wrong.
• -1: If the invoice is deleted while unpaid, or the invoice does not exist.
• 903: If the invoice expires before being paid, or is already expired.

AUTHOR

Christian Decker <[email protected]> is mainly responsible.

SEE ALSO

lightning-waitanyinvoice(7), lightning-listinvoices(7), lightning-delinvoice(7), lightning-invoice(7)

RESOURCES

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

lightning-cli waitinvoice -k "label"="inv2"

{
  "id": "example:waitinvoice#1",
  "method": "waitinvoice",
  "params": {
    "label": "inv2"
  }
}

{
  "label": "inv2",
  "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv01010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "payment_hash": "paymenthashwaitinv0101010101010101010101010101010101010101010101",
  "amount_msat": 2000,
  "status": "paid",
  "pay_index": 5,
  "amount_received_msat": 2000,
  "paid_at": 1738500000,
  "payment_preimage": "paymentpreimagewaitinv0010101010101010101010101010101010101010101",
  "description": "inv2",
  "expires_at": 1739000000,
  "created_index": 13,
  "updated_index": 5
}

lightning-cli waitinvoice "inv3"

{
  "id": "example:waitinvoice#2",
  "method": "waitinvoice",
  "params": [
    "inv3"
  ]
}

{
  "label": "inv3",
  "bolt11": "lnbcrt222n1pnt3005720bolt11wtinv02020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
  "payment_hash": "paymenthashwaitinv0202020202020202020202020202020202020202020202",
  "amount_msat": 3000,
  "status": "paid",
  "pay_index": 6,
  "amount_received_msat": 3000,
  "paid_at": 1738500000,
  "payment_preimage": "paymentpreimagewaitinv0020202020202020202020202020202020202020202",
  "description": "inv3",
  "expires_at": 1739000000,
  "created_index": 14,
  "updated_index": 6
}